Custom Object Mapping in Chat Webhooks
This article explains how to use the Response Mapping feature within the Trigger Webhook action. Response Mapping allows you to capture data from an external API’s response and use it directly within your workflow.
With Response Mapping, you can:
- Capture data directly from any JSON-based API response.
- Extract specific values using the flexible JSONata query language.
- Save the extracted data into temporary fields (e.g., new_conversation_id).
- Use these temporary fields in subsequent workflow actions, such as updating fields or dynamically configuring dropdown options.
Step 1: Configure the webhook call
Before you can map a response, you must first configure the webhook with all the necessary details to successfully call the external API. This initial setup defines the endpoint you want to interact with and how you will communicate with it.
The information to be included are as follows:
General details
| Header | Description |
|---|---|
| Name | A descriptive name for the webhook (e.g., “License Details”). |
| Description (Optional) | A more detailed explanation of what the webhook does. |
| Request Type | The HTTP method for the call. For sending new data, this is typically POST. For updating existing data, it might be PUT or PATCH. |
| Destination URL | The complete HTTPS URL of the external API endpoint that will receive the data. You can use placeholders to make this URL dynamic. |
| Authentication (Optional) | If the API requires authentication, enable and configure the necessary credentials, such as an API Key or a username/password. |
| Signing (Optional) | You will need to provide a Secret Key that is shared with the receiving application to validate the authenticity of the webhook. |
| Custom Headers (Optional) | Add any required HTTP headers that your destination API needs to process the request. |
Payload details
The data you send to the destination API. This section provides powerful options to structure the body of your request.
- Content Type: Select the format of the payload. For most modern APIs, this should be set to JSON.
- Body Content: Choose how to build the payload’s content. It’s divided into two categories as follows.
-
Default: Select this option to send data from the available chat fields in a standard format. You have two choices here:
- Include all fields in the payload: Enable to send every available chat field.
- Select specific fields: Use the dropdown menu to select only the chat fields you need to send (e.g., Requester, products). This is useful for sending a smaller, more targeted set of data. -
Advanced: Select this option to build a fully custom JSON object from scratch. This is the most flexible method and is ideal when the destination API requires a specific nested structure. An editor will appear where you can write your JSON and insert placeholders for dynamic data.
Default payload structure
When using the Default option, the system automatically builds a well-structured JSON payload with a predefined format:
- System Fields: Either primitive structure or Organized into their own nested JSON objects (e.g.,
requester,agent,brand, etc.). - Custom Fields: All fields prefixed with
cf_are grouped under a singlechatCustomFieldsobject. - Temporary Fields: All fields prefixed with
tf_are grouped under a singlechatTempFieldsobject.
| Field Type | Structure | Example |
|---|---|---|
| System Fields (Primitive) | Key-value pairs directly in the root payload | { "conversationId": "a8191b20-8615-4ef0-836a-44fae4f72f51", "createdOn": "2025-09-12T08:54:59.000Z" } |
| System Fields (Object) | Nested objects with id and name |
"brand": { "id": 1, "name": "" } |
| Chat Custom Fields | Grouped under chatCustomFields object with keys prefixed by cf_ |
"chatCustomFields": { "cf_text": "Sample text", "cf_multiselect": [ { "id": 1, "name": "" } ], "cf_appointment_date_time": "2025-09-12T08:54:59.000Z", "cf_dropdown": { "id": 1, "name": "" } } |
| Workflow Temporary Fields | Grouped under chatTempFields object with keys prefixed by tf_ |
"chatTempFields": { "tf_userType": "", "tf_licenseType": "" } |
If you select Include all fields in the payload, the same structure is followed but will simply include all available fields.
After filling in these essential configuration details, click Next to proceed to the testing stage.
Step 2: Execute a test call to get a live response
To run a test call, you will need to provide the following details:
Provide the payload
In the Payload section, provide the actual data required by the destination API. This data will be sent in your test call.
Execute the test
Click the Test API Call button. This will lead to the following actions:
* Sends a live request to the destination URL with your test payload.
* After the call, the API Response section will show the exact data sent back by the external service.
Confirm a successful response
- You must get a valid JSON response body to proceed with the response mapping step.
- If the test fails, you cannot proceed to the mapping step. You must correct your URL, headers, or payload until the test call succeeds.
Placeholders are not supported in the URL or payload when making a test API call.
Map the API response to temporary fields
There are two ways to create response mappings:
Method 1: Using save query
- In the Try your own query section, write a JSONata query to extract data from the API response.
- Click Execute Query to run the query. The result will appear in the Query Result section.
- Once confirmed that the output matches your expectations, you can click Save Query.
- You’ll be prompted to assign the query to a temporary Response Field Name.
- Click Add to finalize the process.
Method 2: Through the response mapping section
- Once you are done with step 2 above, click Next to proceed to the Response Mapping section.
- For each mapping, enter:
- A Temporary Field Name to store the extracted value (e.g.,userType)
- A JSONata Query that targets the desired data in the API response (e.g.,userType) - Click Add to save the mapping.
- Repeat the process to define as many mappings as needed.
After confirming that all mappings are added, save your webhook configuration. The temporary fields you define will be available for use in later stages of your workflow.
