Voice Callback Contract

When a call arrives on one of your voice numbers, or a caller presses a key on a menu, Sent POSTs a signed question to that number's callback URL and follows your answer. This page is the reference for both sides of that exchange: the question Sent sends and the answer your backend returns. For the flow around it, including signature verification, deadlines and retries, see Answering Calls.

How the contract is used

Every exchange is one HTTP request from Sent to you. The body is a question, sent as application/json. Your response body is an answer: optional instructions to run in order, then exactly one action that decides where the call goes. A menu chains by answering a call.input question with another playMenu or a connect action. The same contract drives the test question from POST /v3/channels/voice/{number}/test, so a backend that passes the test answers real calls the same way. Worked examples are in Voice Recipes.

The envelope

Every question carries these fields. Keys are camelCase and null values are left out.

Questions

call.request

A new call, asking your backend what should happen to it.

An app user calling a phone number:

{
  "type": "call.request",
  "version": "1",
  "callId": "call_9f2ab000-0000-4000-8000-000000000001",
  "number": "+38349111222",
  "timestamp": "2026-07-22T12:00:00+00:00",
  "direction": "outbound",
  "from": { "kind": "user", "identity": "agent-42" },
  "to": { "kind": "number", "number": "+14155551234" }
}

Someone dialing one of your numbers:

{
  "type": "call.request",
  "version": "1",
  "callId": "call_9f2ab000-0000-4000-8000-000000000001",
  "number": "+38349111222",
  "timestamp": "2026-07-22T12:05:00+00:00",
  "direction": "inbound",
  "from": { "kind": "number", "number": "+38344555666" },
  "to": { "kind": "number", "number": "+38349111222" }
}

A caller who withheld their number:

{
  "type": "call.request",
  "version": "1",
  "callId": "call_9f2ab000-0000-4000-8000-000000000001",
  "number": "+38349111222",
  "timestamp": "2026-07-22T12:06:00+00:00",
  "direction": "inbound",
  "from": { "kind": "anonymous" },
  "to": { "kind": "number", "number": "+38349111222" }
}

call.input

What the caller pressed on a menu, asking what to do next. Menus chain by answering this with another playMenu or a connect action.

A later setCookie with the same key replaces the earlier value, and every later question carries the whole set. Cookies live for the life of the call.

{
  "type": "call.input",
  "version": "1",
  "callId": "call_9f2ab000-0000-4000-8000-000000000001",
  "number": "+38349111222",
  "timestamp": "2026-07-22T12:00:07+00:00",
  "digits": "1"
}

With cookies stored by an earlier answer:

{
  "type": "call.input",
  "version": "1",
  "callId": "call_9f2ab000-0000-4000-8000-000000000001",
  "number": "+38349111222",
  "timestamp": "2026-07-22T12:00:07+00:00",
  "digits": "1",
  "cookies": { "step": "greeted", "department": "sales" }
}

Addresses

from and to are addresses, told apart by kind. Identities and room names are bare: the account prefix never reaches your backend.

Answers

Your response body is one JSON object:

{ "instructions": [], "action": {} }

Answer with a 2xx status. A 4xx status tells Sent you refuse the call. On a call.request the call ends FAILED with reason rejected; on a call.input the call was already answered, so it is hung up and ends COMPLETED. For what happens on a timeout, a 5xx or an invalid answer, see Answering Calls.

Actions

connectToUser

Rings an app user of your account.

{ "action": { "action": "connectToUser", "identity": "ben", "record": false } }

connectToNumber

Dials a phone number. The leg runs for at most what your balance affords at the destination's per-minute rate, but never less than one minute, and never longer than four hours. A leg to an app user or a room has no such limit, because it costs nothing.

{
  "action": {
    "action": "connectToNumber",
    "number": "+38349123456",
    "callerId": "+14155551234",
    "dialTimeoutSeconds": 30,
    "record": false
  }
}

connectToConference

Puts the call into a conference room belonging to your account. A call in a room can take participants through POST /v3/calls/{id}/participants.

{ "action": { "action": "connectToConference", "name": "daily-standup", "record": false } }

playMenu

Plays a menu and collects keypresses. The digits come back as a call.input question, which is how menus chain.

{
  "action": {
    "action": "playMenu",
    "prompt": { "text": "Press 1 for sales, 2 for support" },
    "maxDigits": 1,
    "timeoutSeconds": 5,
    "repeats": 2
  }
}

Collecting several digits, with a cookie that tells the next question which step the caller is on:

{
  "instructions": [
    { "instruction": "setCookie", "key": "step", "value": "account-number" }
  ],
  "action": {
    "action": "playMenu",
    "prompt": { "text": "Enter your four digit account number" },
    "maxDigits": 4,
    "timeoutSeconds": 8
  }
}

park

Holds the call, playing the hold prompt until the hold runs out. One hold lasts at most 600 seconds, and the call ends when it is reached, so say how long the caller may wait in the prompts.

{
  "action": {
    "action": "park",
    "introPrompt": { "text": "Please hold" },
    "holdPrompt": { "text": "Still with you" },
    "maxDurationSeconds": 600
  }
}

hangup

Ends the call. No fields.

{ "action": { "action": "hangup" } }

reject

Turns the call away without connecting it. On a call.request the call ends FAILED with reason rejected. On a call.input the call was already answered, so it is hung up and ends COMPLETED.

{ "action": { "action": "reject", "reason": "busy" } }

Instructions

Instructions are optional, run in the order given, and never decide where the call goes. Each is told apart by its instruction name.

Every instruction in one answer:

{
  "instructions": [
    { "instruction": "say", "text": "Welcome to Acme", "locale": "en-US" },
    { "instruction": "play", "url": "https://cdn.acme.com/greeting.mp3" },
    { "instruction": "sendDigits", "digits": "1w2" },
    { "instruction": "startRecording" },
    { "instruction": "stopRecording" },
    { "instruction": "answer" },
    { "instruction": "setCookie", "key": "step", "value": "greeted" }
  ],
  "action": { "action": "hangup" }
}

Parsing rules

Sent reads your answer with these rules. An answer that breaks one is invalid, and the reason is reported as described under Answer error reasons.

• Fields the contract does not define are ignored. An unknown action or instruction name is an error.
• An empty body, a body that is not a JSON object, or invalid JSON is malformed_json.
• instructions must be an array. Each item must be an object with an instruction name.
• There must be exactly one action key. None is missing_action. More than one, or an array of two or more, is multiple_actions. An array of one is invalid_field: "'action' must be an object, not a list."
• Strings must be strings. An empty string counts as absent, so a required string that is empty fails with '{property}' is required and must be a non-empty string.
• Integers (dialTimeoutSeconds, maxDigits, timeoutSeconds, repeats, maxDurationSeconds) must be whole numbers from 1 up.
• Booleans must be true or false. Absent means false.
• park.maxDurationSeconds over 600 is park_duration_exceeded: "A single hold can last at most 600 seconds. Answer the next question with another park to keep holding."
• Prompts are { "text": "..." } only. A url key is refused: "Prompts are text only. Use a 'play' instruction to play audio." The text cannot contain ]: "Prompt text cannot contain ']'. Use a 'say' instruction for text that needs one."
• An identity is up to 200 characters of letters, digits, - and _. A room name is up to 27 characters of the same set.
• play.url must be an absolute http or https URL.

Account rules

After parsing, a connectToNumber answer is checked against your account. The other actions have no account rules.

• number must be in E.164 format.
• A destination in a blocked country is destination_blocked: "Calls to this destination are not allowed."
• callerId, when present, must be in E.164 format, otherwise invalid_field. A valid number this account does not own through Sent is caller_id_not_owned: "'callerId' must be a phone number this account owns through Sent." Ownership is read from your number inventory; the caller id does not have to be voice-enabled itself.
• The answer is normalised: number is written in E.164, and a missing callerId is filled in with the call's owning number. The test endpoint returns the normalised answer under answer.
• Connecting to a phone on a call that had no phone destination needs a balance greater than zero. A call refused for balance ends with reason insufficient_balance.

Answer error reasons

The test endpoint reports these in error.reason, with error.path naming the field at fault (such as action.action) and error.message saying what to fix. On a live call an invalid answer is asked for once more. If the second attempt does not produce a usable answer either, a call.request fails with the reason the last attempt produced, invalid_answer for an unusable body, and a call.input is hung up and ends COMPLETED. The call failure reasons are listed in the Error Catalog.

Versioning

Every question carries version: "1", the only version today. Changes within a version are additive: a question may gain fields, so ignore fields you do not know and never rely on key order. A field is never removed or given a new meaning without a new version, and the version is sent on every question so your backend can check it.