Pre-connect requests

When a call arrives on your agent’s number, the platform can call your HTTPS endpoint with the caller’s number before answering, and use what you return to greet the caller by name, give the agent their record, or decline the call. It is configured on the agent record; the only code you write is the endpoint.

Telephony only. WebSocket and browser sessions never trigger pre-connect requests.

How it works

A call arrives on the agent’s number. Before answering, the platform runs the agent’s pre_connect_requests in order, at most two.
For each entry it makes one HTTPS request to your URL, carrying the values named in sends, such as caller_number.
Your endpoint replies with JSON within the timeout, 800 ms at most. The platform reads the values named in returns off the response by dotted path.
The platform answers the call. If your response included a greeting and the entry allows it, that greeting is spoken. Otherwise the agent’s greeting is spoken, with any {{name}} placeholders filled from the captured values.
The captured values are placed at the top of the conversation, so the model knows them from the first turn.

Every step fails open. A timeout, a non-2xx status, an unparseable body or a missing value means the call is answered as if the lookup had never run. The one exception is a response of {"reject": true}, which ends the call unanswered.

Add it to your agent

pre_connect_requests is a field on the agent record. Add it with PUT /v1/agents/{id} on an agent you already have, or include it in the body of POST /v1/agents when you create one. This update asks a CRM for the patient behind the caller’s number, greets them by name, and keeps their record id for the conversation:

curl -X PUT https://agents.assemblyai.com/v1/agents/$AGENT_ID \
  -H "Authorization: $ASSEMBLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "greeting": "Thanks for calling Northside Dental, {{patient_name}}. How can I help?",
    "system_prompt": "You are the front desk for Northside Dental. The pre-connect context contains the caller'"'"'s patient_id; use it when you look up appointments and do not ask for it.",
    "pre_connect_requests": [
      {
        "http": {
          "url": "https://example.com/voice/lookup",
          "http_method": "POST",
          "headers": [{ "name": "Authorization", "value": "Bearer crm-service-token" }]
        },
        "sends": ["caller_number"],
        "returns": [
          { "name": "patient_name", "path": "patient.first_name", "default": "there" },
          { "name": "patient_id", "path": "patient.id" }
        ],
        "timeout_ms": 600,
        "allow_overrides": ["greeting"]
      }
    ]
  }'

# pip install requests
import os
import requests

resp = requests.put(
    f"https://agents.assemblyai.com/v1/agents/{os.environ['AGENT_ID']}",
    headers={"Authorization": os.environ["ASSEMBLYAI_API_KEY"]},
    json={
        "greeting": "Thanks for calling Northside Dental, {{patient_name}}. How can I help?",
        "system_prompt": (
            "You are the front desk for Northside Dental. The pre-connect context "
            "contains the caller's patient_id; use it when you look up appointments "
            "and do not ask for it."
        ),
        "pre_connect_requests": [
            {
                "http": {
                    "url": "https://example.com/voice/lookup",
                    "http_method": "POST",
                    "headers": [{"name": "Authorization", "value": "Bearer crm-service-token"}],
                },
                "sends": ["caller_number"],
                "returns": [
                    {"name": "patient_name", "path": "patient.first_name", "default": "there"},
                    {"name": "patient_id", "path": "patient.id"},
                ],
                "timeout_ms": 600,
                "allow_overrides": ["greeting"],
            }
        ],
    },
)
resp.raise_for_status()
print(resp.json()["pre_connect_requests"])

// Node 18+ has fetch built in
const res = await fetch(`https://agents.assemblyai.com/v1/agents/${process.env.AGENT_ID}`, {
  method: "PUT",
  headers: {
    Authorization: process.env.ASSEMBLYAI_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    greeting: "Thanks for calling Northside Dental, {{patient_name}}. How can I help?",
    system_prompt:
      "You are the front desk for Northside Dental. The pre-connect context contains the caller's patient_id; use it when you look up appointments and do not ask for it.",
    pre_connect_requests: [
      {
        http: {
          url: "https://example.com/voice/lookup",
          http_method: "POST",
          headers: [{ name: "Authorization", value: "Bearer crm-service-token" }],
        },
        sends: ["caller_number"],
        returns: [
          { name: "patient_name", path: "patient.first_name", default: "there" },
          { name: "patient_id", path: "patient.id" },
        ],
        timeout_ms: 600,
        allow_overrides: ["greeting"],
      },
    ],
  }),
});
const agent = await res.json();
console.log(agent.pre_connect_requests);

The response echoes the configuration. Header values are write-only and come back as the header name and when it was last set. Attach a phone number as in Connect to Twilio, and the lookup runs on every inbound call to that number.

Field	Type	Description
`http.url`	string, required	Your endpoint. Must be `https://`, and its hostname must resolve in public DNS when the agent is saved.
`http.http_method`	string	`POST` (default), `PUT`, `PATCH`, `GET` or `DELETE`. Sent values travel in the JSON body for `POST`, `PUT` and `PATCH`, and as query parameters for `GET` and `DELETE`.
`http.headers`	array	Headers to send, each `{ "name", "value" }`. Use one to authenticate your endpoint. Values are stored encrypted and never returned.
`sends`	array of strings	What to send: any of the call facts below, and any name an earlier entry captured. Nothing is sent unless you name it.
`returns`	array	Values to capture from the response. Each has a `name` you choose, a dotted `path` into the JSON, and an optional `default` used when the path does not resolve.
`timeout_ms`	integer	Shortens this entry’s timeout, from 1 to 800. Every entry has a ceiling of 800 ms; omit this for the full ceiling.
`allow_overrides`	array of strings	Agent fields the response may replace. The only value today is `"greeting"`. Without it, a `greeting` in the response is ignored.

What your endpoint receives

The request carries only what sends names. The platform supplies five call facts that any entry may send:

Name	Value
`caller_number`	The caller’s number in E.164 form, for example `+14155550100`.
`dialed_number`	The agent’s number the caller dialled, in E.164 form.
`direction`	`"inbound"` or `"outbound"`.
`agent_id`	The id of the agent handling the call.
`session_id`	The id of the session being created, the same id you will see in session history and webhooks.

With "sends": ["caller_number", "dialed_number", "direction"] a POST endpoint receives:

{
  "caller_number": "+14155550100",
  "dialed_number": "+14155550199",
  "direction": "inbound"
}

A GET endpoint receives the same values as query parameters: ?caller_number=%2B14155550100&dialed_number=%2B14155550199&direction=inbound. A fact the platform does not have is left out, not sent blank. When the caller withholds their number, caller_number is missing from the request; treat that as an unknown caller, and the default on each capture applies. The request is a plain HTTPS call with the headers you configured. There is no signature; authenticate it with a header value only you and the platform know.

What your endpoint returns

Respond with 200 and a JSON object within the timeout.

In the response	Effect
A value at each `returns[].path`	Captured under `returns[].name`. Strings are taken as is; numbers and booleans become text; objects and arrays are ignored. Values over 512 characters are dropped. Paths are dotted: `patient.first_name`, or `results.0.id` to index an array.
Top-level `"greeting": "..."`	Spoken instead of the agent’s greeting on this call, if the entry lists `"greeting"` in `allow_overrides`.
Top-level `"reject": true`	The call is not answered.
Anything else	Ignored.

A response that is not JSON, not a 2xx, larger than 8 KB, or later than the timeout counts as no response. The platform does not retry. For the clinic agent above, the CRM might answer:

{
  "patient": { "id": "pt_48213", "first_name": "Maria", "last_visit": "2026-07-02" }
}

The platform captures patient_name as Maria and patient_id as pt_48213, and the caller hears “Thanks for calling Northside Dental, Maria. How can I help?”

Use the captured values

In the greeting

Write {{name}} in the agent’s greeting for any name in returns. The platform fills it from the captured value, or from that capture’s default when the lookup returned nothing. An unknown caller to the clinic agent hears “Thanks for calling Northside Dental, there. How can I help?”, so pick a default that reads well in the sentence. Every placeholder has to end up with a non-empty value. If any {{name}} has neither a value nor a default, or resolves to an empty string, the platform speaks the agent’s greeting exactly as written, braces included. An empty default is not a way to make a placeholder disappear. Only names in returns are substituted. To speak the caller’s number back, have your endpoint return it and capture it.

As a greeting your endpoint writes

When your endpoint should decide the wording, return a top-level greeting and list "greeting" in the entry’s allow_overrides:

{
  "patient": { "id": "pt_48213", "first_name": "Maria" },
  "greeting": "Thanks for calling Northside Dental, Maria. Are you calling about your appointment on Thursday?"
}

A returned greeting takes precedence over the agent’s templated greeting.

In the conversation

The platform puts the captured values at the top of the transcript as the result of a platform tool named aai_pre_connect_context:

{ "variables": { "patient_name": "Maria", "patient_id": "pt_48213" } }

You do not add this tool; the platform inserts the result whenever a pre-connect entry captured anything. The model treats the values as established facts, so it can pass patient_id to a tool without asking the caller for it. Tell the model in the system_prompt what the names mean, as the clinic agent does. If you connect your own LLM, the same tool result appears in the messages your endpoint receives.

Chain two lookups

A second entry can send what the first captured. Here the first request resolves the caller to a patient id and the second fetches that patient’s next appointment:

{
  "pre_connect_requests": [
    {
      "http": {
        "url": "https://example.com/voice/lookup",
        "http_method": "POST",
        "headers": [{ "name": "Authorization", "value": "Bearer crm-service-token" }]
      },
      "sends": ["caller_number"],
      "returns": [
        { "name": "patient_id", "path": "patient.id" },
        { "name": "patient_name", "path": "patient.first_name", "default": "there" }
      ]
    },
    {
      "http": { "url": "https://example.com/voice/next-appointment", "http_method": "GET" },
      "sends": ["patient_id"],
      "returns": [
        { "name": "next_appointment", "path": "appointment.spoken_date", "default": "no upcoming appointment" }
      ]
    }
  ]
}

Entries run in order, each with its own 800 ms ceiling, so two entries can hold the call for up to about 1.6 s before the greeting. If the first entry fails, the second still runs, but patient_id is not sent because nothing captured it. If an earlier entry captures a value under the same name as a call fact, a later entry that sends that name sends your value, not the platform’s.

Limits and validation

The API checks the configuration when you save the agent and returns 422 naming the failing field:

Rule	Error
At most two entries	`pre_connect_requests: at most 2 pre-connect requests are supported; got 3`
`timeout_ms` from 1 to 800	`pre_connect_requests[0].timeout_ms: ... must be an integer between 1 and 800 ms`
`sends` names a call fact or an earlier capture	`pre_connect_requests[0].sends[0]: 'customer_tier' is neither a call fact nor captured by an earlier pre-connect request`
`allow_overrides` contains only `greeting`	`pre_connect_requests[0].allow_overrides[0]: 'voice' is not an overridable field; allowed: greeting`
`http.url` is HTTPS	`pre_connect_requests[0].http.url: webhook URL must use https://`
`http.url` host resolves in public DNS	`pre_connect_requests[0].http.url: webhook URL host 'crm.example.com' does not resolve`
`returns[].path` is a dotted path of `[A-Za-z0-9_-]+` segments, at most 10 deep and 256 characters	`pre_connect_requests[0].returns[0].path: 'patient..id' is not a valid dotted path`
Capture names are unique across all entries	`pre_connect_requests[1].returns[0].name: 'patient_id' is already captured by an earlier pre-connect request`

At call time: each entry has 800 ms, responses are read up to 8 KB, and each captured value is kept up to 512 characters.

Test it

You can watch what the platform sends without writing any code. Point an entry at a request-capture service, name every call fact in sends, attach a number, and call it:

{
  "pre_connect_requests": [
    {
      "http": { "url": "https://webhook.site/your-unique-id", "http_method": "POST" },
      "sends": ["caller_number", "dialed_number", "direction", "agent_id", "session_id"]
    }
  ]
}

The request appears the moment the call arrives, before the greeting.

Troubleshooting

The request body is empty. The entry’s sends is empty or missing. The platform sends nothing you did not name; add "sends": ["caller_number"] and save the agent again. The request never arrives. Check that the number is attached to this agent on the same regional host you created it on; agent ids are not shared between agents.assemblyai.com and agents.us.assemblyai.com. Then check your endpoint answers 200 within the timeout to a POST carrying your headers. A 401 from your own auth layer looks the same as a lookup that never ran, because the platform fails open either way. The greeting did not change. A greeting in the response needs "allow_overrides": ["greeting"] on that entry. A templated greeting needs every {{name}} to resolve to a non-empty value, from the response or from its default. The number is missing on some calls. The caller withheld their number. The platform omits caller_number rather than sending a placeholder. The model does not use the values. Name them in the system_prompt and say what to do with them.

Next steps

Connect to Twilio

Attach a phone number so calls reach this agent.

Tools

Let the agent act on the caller’s record during the call.

Webhooks

Get the call’s from_number and outcome after it ends.

Getting started

Create & manage agents

Agent behavior

Conversational experience

Deploy

Telephony

Test

After a session

Reference

API reference

Pre-connect requests

How it works

Add it to your agent

What your endpoint receives

What your endpoint returns

Use the captured values

In the greeting

As a greeting your endpoint writes

In the conversation

Chain two lookups

Limits and validation

Test it

Troubleshooting

Next steps

Connect to Twilio

Tools

Webhooks

​How it works

​Add it to your agent

​What your endpoint receives

​What your endpoint returns

​Use the captured values

​In the greeting

​As a greeting your endpoint writes

​In the conversation

​Chain two lookups

​Limits and validation

​Test it

​Troubleshooting

​Next steps

Connect to Twilio

Tools

Webhooks

How it works

Add it to your agent

What your endpoint receives

What your endpoint returns

Use the captured values

In the greeting

As a greeting your endpoint writes

In the conversation

Chain two lookups

Limits and validation

Test it

Troubleshooting

Next steps