External ID
Pass an External ID when starting a conversation to link it to a CRM record, support ticket, or another record in your system.
Overview
The External ID is:
- Available as
{system_external_id}in the Assistant's instructions - Stored on the Exchange entity and returned in API responses
- Usable as an Exchange filter when retrieving conversation data
Setting the External ID
With a SIP Channel
Set either SIP header to pass the External ID:
X-External-IDcustom header: a dedicated custom SIP header.User-to-User(UUI) header: the standard UUI header with the keyexternal-id, using a semicolon-delimitedkey:valueformat.
Using the X-External-ID header
Code
Using the User-to-User (UUI) header
The User-to-User header follows a key:value format, with multiple pairs separated by semicolons.
Code
If both headers are present, X-External-ID takes priority over the UUI external-id value.
With a WebRTC Channel
From your backend, include externalId in the POST /calls/{channelId} request body when requesting a WebRTC connection token.
Request
Code
Using External ID in instructions
Reference the External ID with {system_external_id} in the Assistant's instructions.
Example
For these Assistant instructions:
Code
An External ID of ticket-12345 produces:
Code
Propagation to Exchange
The External ID automatically propagates to the Exchange entity. This response excerpt shows the relevant fields:
Code
You can filter Exchanges by externalId using the where query parameter:
Code