Case data enrichment

Plans and permissions:

• Add-on: AI agents or Copilot, billed separately
• Set up case data enrichment for a chat agent: Admin, Manager, or Team Lead role, or a custom role with Chat agent settings set to Can edit chat agent settings
• Set up case data enrichment for the email agent: Admin role, or a custom role with Email agent set to Can edit email agent settings
• Create the API endpoint: Admin role, or a custom role with Tools and connectors set to Can edit tools and connectors settings
• Test with sample user data: Admin, Manager, or Team Lead role, or a custom role with Chat agent settings set to Can edit chat agent settings or Can view chat agent settings

Use case data enrichment to pull customer details from your own systems, such as an account balance, a membership renewal date, or recent orders, before the AI agent replies. Assembled calls one of your API endpoints with details about the customer, saves the response in smart fields, and the AI agent uses them to give a specific answer instead of asking the customer or handing off.

To set it up for chat, go to AI support > Chat agent, select a chat agent, and open the Setup tab. The email agent has the same setting in AI support > Email agent, on the Pre-automation tab, and Copilot has one in its settings.

How case data enrichment works

Enrichment has three parts:

• User data mapping: on chat, your website sends details about the visitor with each chat, such as metadata.organization_id, and you map these to smart fields. For the fields your website can send, see Identify signed-in users.
• The API endpoint: an endpoint in Configure > Tools and connectors that looks up the customer, such as /api/external/v1/customer/{{identifier}}, with an output mapping that saves parts of the response to smart fields.
• The enrichment mapping: which customer data to send to each of the endpoint’s variables.

How it behaves:

• In a live chat, the values come from the user data your website sends. In a test, you enter them yourself.
• Assembled calls the endpoint again for each customer message, and each time a support team member uses Copilot, so the data is current.
• The smart fields it fills can be used in workflow conditions, Guide steps, and replies.

Set up case data enrichment for chat

Before you start, you need a chat agent, an API endpoint that returns the customer’s data, and the credentials your API requires.

1. Create the smart fields you want to fill, in Configure > Smart fields. See Smart fields.
2. Create the API endpoint in Configure > Tools and connectors. In its Output mapping, map each JSON path in the response, such as account.balance, to a Smart field. See Custom API endpoints.
3. Go to AI support > Chat agent, select the chat agent, and open the Setup tab.
4. In User data mapping, select Add variable. Enter the JSON path of a value your website sends, such as metadata.organization_id, and choose the Smart field to store it in. Repeat for each value.
5. In Case data enrichment, select Enable case data enrichment and choose the API endpoint.
6. Under Enter JSON paths to send to the API, enter a JSON path for each of the endpoint’s variables, such as the path to the customer’s ID.
7. Check Smart fields returned from API, which lists what the endpoint fills in.
8. Select Save changes.

From the next chat, Assembled calls the endpoint and fills those smart fields. To turn it off, clear Enable case data enrichment and save.

Handle arrays in API responses

When your API returns a list, such as several receipts, transactions, or incidents, you can map it in two ways.

To decide, consider how often you’ll refer to a specific value, whether a workflow needs to branch on it, and how many places use it.

Test case data enrichment

Test before you go live, so you can catch a wrong JSON path or a failing API call early. In a test there’s no real visitor, so you enter the user data yourself.

1. Go to AI quality > AI agent testing and open Settings.
2. Under Chat agent, choose the chat agent you set up.
3. Under Impersonate a customer, turn on Enable impersonation. Choose Enter details and fill in the fields, adding any custom fields your mapping uses, or choose Paste JSON and paste a sample of the user data your website sends.
4. Select Save. If a conversation is open, select Reset and apply settings to start a new one.
5. Ask questions that need the enriched data, such as “What’s my current balance?”.
6. In the conversation’s activity, open Customer context to see the request sent to your API and its response.

Start with a value you know, so you can check the result against your own system. Test conversations are saved, so you can review them later in AI quality > QA review by selecting Test cases.

Note: When you test a chat workflow from its Test button, select Apply user data under Test with user data to enter values the same way. View details then shows the request body, the response body, and the response status.

Common issues

To see the request and the response for a test, open Customer context in the test conversation’s activity.

• The test shows a response status other than 200: Check that the endpoint is reachable from the internet and that its credentials are valid. To test the endpoint on its own, use Preview endpoint in Configure > Tools and connectors.
• The request has the wrong values: Check the JSON paths in User data mapping and in Enter JSON paths to send to the API against the user data your website sends.
• The response looks right, but the smart fields stay empty: Check that the endpoint’s Output mapping uses the JSON paths in the actual response.