# Data Injection

Pass call-specific values, such as a customer name or order number, when starting a conversation. Reference each value with `{key}` in the Assistant's instructions, first message, or another supported templated field.

## Overview

Choose the injection method for your Channel:

| Channel type | Injection method                                                  |
| ------------ | ----------------------------------------------------------------- |
| WebRTC       | `injectedData` field in the `POST /calls/:channelId` request body |
| SIP          | Custom key-value pairs in the `User-to-User` (UUI) SIP header     |

If the data you need is not known to the caller's service at initiation, a [Startup Request](/docs/startup-request) lets Reecall fetch it from your own API at the start of the conversation instead.

## Injecting data via WebRTC Channels

From your backend, pass `injectedData` in the `POST /calls/:channelId` request body. Use the returned `wsUrl` and `token` to [connect a LiveKit client](/docs/webrtc-channel#connecting-with-livekit-client).

### Request

```http
POST /calls/497dcba3-ecbf-4587-a2dd-5eb0665e6880
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "injectedData": {
    "customername": "Jane Doe",
    "orderid": "ORD-789",
    "accounttier": "premium"
  }
}
```

**Response:**

```json
{
  "wsUrl": "wss://rtc.reecall.io",
  "token": "eyJhbGciOiJIUzI1NiIs..."
}
```

The `injectedData` object must be a flat JSON object. All values are coerced to strings internally, so `123` becomes `"123"`.

***

## Injecting data via SIP Channels

For SIP Channels, include custom key-value pairs in the `User-to-User` (UUI) header. Each pair follows the `key:value` format, with multiple pairs separated by semicolons.

### UUI header format

```
INVITE sip:+33123456789@trunk.reecall.io SIP/2.0
User-to-User: external-id:ext123;customername:Jane Doe;orderid:ORD-789;accounttier:premium
```

In this example, three custom fields are injected: `customername`, `orderid`, and `accounttier`. The `external-id` key is a reserved system key and is not treated as injected data.

:::info{title="Note"}

SIP UUI keys are case-insensitive. A key like `customerName` is normalised to `customername` during parsing. Use lowercase keys in your SIP headers and in your `{placeholder}` references to ensure consistent resolution.

:::

### Reserved UUI keys

The following UUI keys are reserved for system use and are excluded from injected data:

| Key           | Purpose                                                          |
| ------------- | ---------------------------------------------------------------- |
| `external-id` | Links the conversation to an external identifier in your systems |

***

## Using injected data in Assistant instructions

Injected keys are available directly as `{key}` placeholders.

### Example

For these Assistant instructions:

```
Hello {customername}! I can see your order {orderid}.
As a {accounttier} customer, how can I help you today?
```

The injected data in the examples above produces:

```
Hello Jane Doe! I can see your order ORD-789.
As a premium customer, how can I help you today?
```

The same substitution applies to the first message and other supported templated fields.

***

## Variable resolution priority

When the same key exists at multiple levels, the highest-priority source wins. Injected data takes priority over Project-level Variables, allowing per-conversation overrides.

| Priority    | Source                                                            | Scope                                             |
| ----------- | ----------------------------------------------------------------- | ------------------------------------------------- |
| 1 (lowest) | Project Variables | Shared across all conversations in a Project |
| 2 | **Injected data** | **Supplied at call initiation** |
| 3 | Startup data, when configured | Fetched at Assistant startup |
| 4 | Assistant config fields (`timezone`, `language`, `first_message`) | Core Assistant configuration |
| 5 (highest) | Protected call identity | System fields derived from the connection |

### Override example

If a Project Variable `customername` is `"Default Customer"` and the call injects `customername: "Jane Doe"`, `{customername}` resolves to `"Jane Doe"`. Higher-priority sources can still override that value.

:::info{title="Note"}

Protected system keys (`assistant_id`, `project_id`, `channel_id`, `connection_type`, `trace_id`, `caller_phone_number`, `called_phone_number`, `external_id`, `exchange_id`, `sip_call_id`) cannot be overridden by injected data. Any attempt to inject these keys is ignored.

:::

***

## Limitations

| Constraint                        | Detail                                                                                                 |
| --------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Values are strings                | All injected values are coerced to strings. Objects and arrays are not supported.                      |
| Flat structure only               | The `injectedData` object (WebRTC) must be a single-level key-value map.                               |
| SIP keys are lowercased           | UUI keys are normalised to lowercase during parsing.                                                   |
| Protected system keys             | A set of system keys cannot be overridden by injected data.                                            |
| No server-side validation of keys | Unused keys are accepted and may still be recorded in Exchange resources; they do not change templates that do not reference them. |

<br />
