# 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](/docs/data-injection) 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.

<Mermaid chart={`sequenceDiagram
    participant Caller
    participant Assistant
    participant API as Your API

    Caller->>Assistant: Conversation starts
    Assistant->>Assistant: Load Assistant config (startupRequest known)
    Assistant->>API: GET /lookup?phone={system_caller_phone_number}
    API-->>Assistant: { "name": "Bob" }
    Note over Assistant: Merge response into variables
    Assistant->>Assistant: Resolve "My name is {name}" -> "My name is Bob"`} />

***

## Configuring a Startup Request

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

```http title="HTTP Request"
PATCH /data_next/conversational/assistants/{your-assistant-id}
Authorization: Bearer {your-api-key}
Content-Type: application/json
```
```json title="Payload"
{
  "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.

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

```json title="Payload"
{
  "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](/docs/variables) and [Data Injection](/docs/data-injection) for the values available at resolution time.

:::info{title="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:

```json title="Response"
{
  "name": "Bob",
  "accountTier": "premium"
}
```

For these Assistant instructions:

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

Reecall resolves the instructions to:

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

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

:::info{title="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. |

<br />

## What's next

- [Data Injection](/docs/data-injection)
- [Variables](/docs/variables)
- [HTTP request tool](/docs/send-http-request)
