# 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:

1. **`X-External-ID` custom header**: a dedicated custom SIP header.
2. **`User-to-User` (UUI) header**: the standard UUI header with the key `external-id`, using a semicolon-delimited `key:value` format.

#### Using the `X-External-ID` header

```
INVITE sip:+33123456789@trunk.reecall.io SIP/2.0
X-External-ID: ticket-12345
```

#### Using the `User-to-User` (UUI) header

The `User-to-User` header follows a `key:value` format, with multiple pairs separated by semicolons.

```
INVITE sip:+33123456789@trunk.reecall.io SIP/2.0
User-to-User: external-id:ticket-12345
```

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.

<Mermaid chart={`sequenceDiagram
    participant App as Your Service
    participant API as Reecall API
    participant Assistant as Assistant

    App->>API: POST /calls/{channelId}<br/>{ "externalId": "ticket-12345" }
    API-->>App: { wsUrl, token }
    App->>Assistant: Connect with token
    Note over Assistant: {system_external_id} = "ticket-12345"`} />

#### Request

```
POST /calls/{channelId}
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "externalId": "<your-external-id>"
}
```

## Using External ID in instructions

Reference the External ID with `{system_external_id}` in the Assistant's instructions.

### Example

For these Assistant instructions:

```
You are handling support ticket {system_external_id}. 
Reference this ticket number when the user asks about their case.
```

An External ID of `ticket-12345` produces:

```
You are handling support ticket ticket-12345. 
Reference this ticket number when the user asks about their case.
```

## Propagation to Exchange

The External ID automatically propagates to the Exchange entity. This response excerpt shows the relevant fields:

```json
{
  "status": "completed",
  "type": "voice",
  "externalId": "ticket-12345",
  "traceId": "b8c31b19-ed4b-46bb-ba48-88d20c49b64d"
}
```

You can filter Exchanges by `externalId` using the `where` query parameter:

```
GET /data_next/conversational/exchanges?where={"externalId":"<your-external-id>"}
```
