Reecall

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 typeInjection method
WebRTCinjectedData field in the POST /calls/:channelId request body
SIPCustom 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
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:

JSONCode
{ "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

Code
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.

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:

KeyPurpose
external-idLinks 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
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:

Code
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.

PrioritySourceScope
1 (lowest)Project VariablesShared across all conversations in a Project
2Injected dataSupplied at call initiation
3Startup data, when configuredFetched at Assistant startup
4Assistant config fields (timezone, language, first_message)Core Assistant configuration
5 (highest)Protected call identitySystem 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

ConstraintDetail
Values are stringsAll injected values are coerced to strings. Objects and arrays are not supported.
Flat structure onlyThe injectedData object (WebRTC) must be a single-level key-value map.
SIP keys are lowercasedUUI keys are normalised to lowercase during parsing.
Protected system keysA set of system keys cannot be overridden by injected data.
No server-side validation of keysUnused keys are accepted and may still be recorded in Exchange resources; they do not change templates that do not reference them.

Last modified on