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 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.
Request
Code
Response:
Code
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
Code
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.
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:
Code
The injected data in the examples above produces:
Code
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.
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. |