Reecall
Data Injection

Startup Request

Configure a Startup Request to fetch call context from your API before the Assistant resolves its instructions and greeting. Reference response values with {key} in supported templated fields.

Overview

The request runs once each time a conversation enters the configured Assistant, including after an Assistant transfer. Return a JSON object from your endpoint. Each top-level key becomes a variable available to the Assistant.

Use injected data when your service already knows the values at call initiation. Use a Startup Request to look them up from call context, such as the caller's phone number.


Configuring a Startup Request

Set the startupRequest field on an Assistant via a partial update.

Code
PATCH /data_next/conversational/assistants/{your-assistant-id} Authorization: Bearer {your-api-key} Content-Type: application/json
JSONCode
{ "startupRequest": { "url": "https://crm.example.com/lookup", "method": "GET", "headers": { "Authorization": "Bearer {crm_api_key}" }, "queryParams": { "phone": "{system_caller_phone_number}" }, "timeout": 5 } }

The startupRequest object accepts the following fields.

FieldTypeRequiredDefaultDescription
urlstringYesEndpoint to call. Must start with https://, or with a { placeholder.
methodstringNoGETMethod used to call your endpoint: GET, POST, PUT, PATCH, or DELETE.
headersobjectNo{}Request headers as string key-value pairs. Supports {variable} resolution.
bodyobjectNoJSON request body. Use an object for compatibility with the voice worker. Supports {variable} resolution.
queryParamsobjectNoQuery string parameters. Values may be a string, number, or boolean. Supports {variable} resolution.
timeoutnumberNo10Request timeout in seconds. Must be greater than 0 and at most 10.

The object is validated strictly: any field not listed above is rejected, and the update fails with a descriptive error. To disable the feature, set startupRequest to null.


Templating the request

Use {variable} placeholders in string values in url, headers, body, and queryParams. Reecall resolves them before sending the request using Project Variables, injected data, and system fields. Use these values to pass call context and credentials to your endpoint.

JSONCode
{ "startupRequest": { "url": "https://crm.example.com/customers", "method": "POST", "headers": { "Authorization": "Bearer {crm_api_key}" }, "body": { "phone": "{system_caller_phone_number}", "channel": "{channel_id}" }, "timeout": 5 } }

{crm_api_key} resolves from a Project-scoped Secret Variable. {system_caller_phone_number} supplies the caller's phone number.

See Variables and Data Injection for the values available at resolution time.

Unresolved variables

If no source supplies a placeholder's value, it resolves to an empty string. In a request field, this does not stop Reecall from attempting the request.


The initial Assistant's Startup Request runs before the Exchange is registered, so {system_exchange_id} is empty in that request. It becomes available to instructions and the first message after registration succeeds.

Using the response

Your endpoint must return a JSON object. Each top-level key becomes a dynamic variable available as {key} wherever variables are resolved.

For this response:

JSONCode
{ "name": "Bob", "accountTier": "premium" }

For these Assistant instructions:

Code
You are speaking with {name}, a {accountTier} customer.

Reecall resolves the instructions to:

Code
You are speaking with Bob, a premium customer.

All values are coerced to strings. A nested object or array in the response is stringified rather than flattened, so design your endpoint to return a single-level object.


Variable resolution priority

When several sources supply the same key, the highest-priority source wins. Startup data overrides injected data and Project Variables. Assistant configuration and protected call identity take priority over startup data.

PrioritySourceScope
1 (lowest)Project VariablesShared across all conversations in a Project
2Injected dataSupplied at call initiation
3Startup dataFetched from your API
4Assistant config fields (timezone, language, first_message)Core Assistant configuration
5 (highest)Protected call identitySystem fields derived from the connection

Protected and system keys

Startup data cannot overwrite assistant_id, project_id, channel_id, connection_type, trace_id, caller_phone_number, called_phone_number, external_id, exchange_id, or sip_call_id. Reecall ignores these keys in the response. System variables such as {system_time} are recomputed at resolution time, so a same-named startup key has no effect.


Failure behaviour

The Assistant waits for the Startup Request before resolving its instructions and greeting, so the request can delay the start of the conversation or an Assistant transfer. If the request fails, the conversation continues without its data. A placeholder resolves to an empty string only if no other variable source supplies its value.

The request contributes nothing in each of these cases:

  • The endpoint returns a non-2xx status.
  • The request times out or the network fails.
  • The response is not a JSON object (for example it is an array, a string, or a number). Nested values inside an object are stringified.

A malformed startupRequest configuration is treated as if the feature were off, so the rest of the Assistant loads normally.


Limitations

ConstraintDetail
Object responseThe top-level response must be an object. Nested objects and arrays are stringified.
Values are stringsAll response values are coerced to strings.
URL prefixA literal url must start with https://; templated URLs can start with a { placeholder.
Timeout ceilingtimeout is capped at 10 seconds.
No caching or retryThe request runs once per Assistant entry. There is no caching, retry, or circuit-breaking.

What's next

Last modified on