Case Enrichment - FAQ

What is Case Enrichment?

Case enrichment is a feature that allows customers to enhance their chat conversations by pulling in external data from APIs to provide richer context and improved responses.

What Can Customers Do with Case Enrichment?

Case enrichment enables customers to:

• Configure custom APIs to enrich chat conversations with external data
• Define how ticket/case data maps to those APIs using JSON path mapping
• Leverage returned data to improve chat responses and provide more contextual information
• Test their configuration in real-time before going live

Key Components of Case Enrichment Setup

1. User Data Mapping

• Set up how incoming user data will be parsed and mapped to reusable smart fields
• Configure JSON paths (e.g., metadata.organization_id) to map to smart fields
• These mappings allow the system to extract relevant user information from chat sessions

2. API Endpoint Configuration

• Define the external API endpoint that will be called for enrichment
• Configure the HTTP method (GET, POST, etc.) and endpoint path
• Example: /api/external/v1/assembled_ai/customer/{{identifier}}

3. Smart Fields from API Response

The system can extract various data points from API responses, including:

• Account information (balance, approval status, ID)
• Personal details (first name, last name)
• Account status (order active, flex score)
• Membership details (renewal date, rejection reason)
• Historical data and incidents

4. Handling Arrays in Smart Fields

You have two main approaches to handle arrays from API responses:

Option 1: Map Entire Array to One Smart Field

• Create a single smart field that contains the entire array
• The system can parse the array and use the data without explicit sub-value smart fields
• Useful when you want the LLM to process the full array context

Option 2: Map Individual Array Elements to Separate Smart Fields

• Extract specific values from array elements into individual smart fields
• Depends on your workflow needs and how you want to use the sub-values
• Useful when you need to reference specific array elements in conditions or workflows

Example Scenarios for Array Usage:

• If you need to condition a workflow based on a specific array element, create a dedicated smart field for that sub-value
• If you're using array data frequently across multiple places, consider creating individual smart fields for easier reference
• For simple array processing where the LLM just needs access to the data, mapping the entire array to one smart field may be sufficient

5. Field Mapping

• Map JSON paths from the API response to specific variables
• Example: JSON path → API variable

How to Test Case Enrichment

Key Testing Concepts

Automatic vs Manual Variable Input:

• In real chat scenarios, variables are gathered automatically from user information
• For testing purposes, you need to manually input the variable value to simulate having that data
• This allows you to test with specific user data scenarios without requiring an actual user session

Step-by-Step Testing Process

1. Navigate to the Testing Interface

2. Configure Test User Data

3. Begin Testing

Using the Chat Testing Interface

1. Access the Testing Panel: Navigate to AI Support > Chat testing in the left sidebar
2. Select Chat Profile: Choose the chat profile with case enrichment configured
3. Test with User Data: The system will show if user data was successfully retrieved
4. Review API Calls: Check the "User data details" panel to see:

Testing Workflow

1. Configure Test Variables: Set up the user data variables you want to test with
2. Start a Test Conversation: Use the chat interface to ask questions
3. Monitor Data Enrichment: Check if user data is successfully pulled
4. Verify API Responses: Review the detailed request/response information
5. Test Agent Responses: See how the AI agent uses the enriched data (e.g., "Your Flexscore is 996")
6. Save Test Cases: Each conversation is recorded and saved for QA review

Why is Testing Important?

Setting up case enrichment can be complex and error-prone, especially when dealing with:

• Custom APIs with various configurations
• Different data mapping requirements
• Integration troubleshooting

Our new testing panel addresses these challenges by allowing users to:

• Preview how case enrichment behaves in real-time
• Identify configuration issues early in the setup process
• Troubleshoot problems much faster and easier
• Validate API connections and data mapping before going live
• Review detailed request/response logs for debugging

Do we Always Need to Manually Input Variables for Testing?

For testing purposes: Yes. While in real chat scenarios variables like are gathered automatically from user information (like phone numbers), for testing you need to manually input the variable value. This allows you to:

• Test with specific user data scenarios
• Simulate different user profiles
• Validate API responses without requiring actual user sessions

How Does Variable Gathering Work in Production vs Testing?

Production: Variables are automatically extracted from user information (e.g., phone number lookup, user account data) Testing: Variables must be manually configured using the "Apply user data" feature to simulate having that information available

How should I handle arrays in my API response?

When your API returns arrays (like multiple receipts, transactions, or records), you have options:

Single Smart Field Approach: Map the entire array to one smart field. The LLM can parse and use the array data directly without needing individual sub-fields.

Individual Smart Field Approach: Create separate smart fields for specific array elements if you need to:

• Use array elements in workflow conditions
• Reference specific array values frequently
• Apply different logic to different array elements

Decision Factors:

• How often will you reference specific array elements?
• Do you need to condition workflows on array sub-values?
• Will you use the array data in multiple places?

How Often Does Case Data Enrichment Occur?

Fresh data for every interaction: Case data enrichment makes a fresh API call for each customer message/copilot button press, not just once per ticket. This ensures that:

• Customer data is always up-to-date
• Any changes in external systems are reflected immediately
• Each interaction has access to the most current information

What Happens After I Apply User Data?

Once you apply user data with the configured variable:

• The system makes the API call with that variable
• You can see the full JSON response body
• The chat agent can then use this enriched data to provide personalized responses
• All API request/response details are logged for review

Technical Requirements

To use case enrichment testing, customers must have:

• A chat profile set up in the system
• A case data enrichment endpoint properly configured
• Appropriate API access and credentials
• Proper JSON path mapping configured for user data

Troubleshooting Common Issues

User Data Not Successful

• Check if the API endpoint is accessible
• Verify the JSON path mappings are correct
• Ensure the API credentials are valid
• Review the request/response details in the testing panel

API Response Issues

• Check the response status (should be 200)
• Verify the API is returning the expected JSON structure
• Ensure the smart field mappings match the actual API response structure

Getting Started with Case Enrichment Testing

Based on feedback from our Solutions team, here's how to get started:

Initial Setup Steps

1. Navigate to the testing panel: Go to https://app.assembledhq.com/quality/chat-testing
2. Select your chat profile: Make sure Case data enrichment is enabled in your Chat profile Setup
3. Validate your API setup: Use the testing interface to confirm your API is returning the expected data structure

Testing Best Practices

• Start with simple test cases: Use known variable values to validate your API connection
• Review the complete JSON response: Check that all expected fields are being returned
• Test array handling: If your API returns arrays, determine whether you need individual smart fields or can use the entire array
• Validate smart field mapping: Ensure your JSON paths correctly map to the returned data structure

Getting Help

If you encounter issues or have questions about case enrichment configuration:

• Use the detailed testing panel to diagnose API connection issues
• Review the request/response logs for specific error messages
• Contact the engineering team for technical assistance
• Reach out to the PM team for design-related questions
• Reference this FAQ for common troubleshooting steps

QA Review Process

• Test conversations are automatically saved as test cases
• Navigate to the QA review page to evaluate past conversations
• Use "Start reviewing" to begin the QA process for test cases
• Click "Reset conversation" to start new test cases