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
Code
The startupRequest object accepts the following fields.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
url | string | Yes | Endpoint to call. Must start with https://, or with a { placeholder. | |
method | string | No | GET | Method used to call your endpoint: GET, POST, PUT, PATCH, or DELETE. |
headers | object | No | {} | Request headers as string key-value pairs. Supports {variable} resolution. |
body | object | No | JSON request body. Use an object for compatibility with the voice worker. Supports {variable} resolution. | |
queryParams | object | No | Query string parameters. Values may be a string, number, or boolean. Supports {variable} resolution. | |
timeout | number | No | 10 | Request 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.
Code
{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:
Code
For these Assistant instructions:
Code
Reecall resolves the instructions to:
Code
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.
| Priority | Source | Scope |
|---|---|---|
| 1 (lowest) | Project Variables | Shared across all conversations in a Project |
| 2 | Injected data | Supplied at call initiation |
| 3 | Startup data | Fetched from your API |
| 4 | Assistant config fields (timezone, language, first_message) | Core Assistant configuration |
| 5 (highest) | Protected call identity | System 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
| Constraint | Detail |
|---|---|
| Object response | The top-level response must be an object. Nested objects and arrays are stringified. |
| Values are strings | All response values are coerced to strings. |
| URL prefix | A literal url must start with https://; templated URLs can start with a { placeholder. |
| Timeout ceiling | timeout is capped at 10 seconds. |
| No caching or retry | The request runs once per Assistant entry. There is no caching, retry, or circuit-breaking. |