Voice agents

A voice agent is a program of yours that takes phone calls to your numbers over a WebSocket, instead of your callback URL deciding each call. You describe the agent to Sent once with POST /v3/voice/agents: whether it works in text or in audio, how the caller is spoken to, what it may do to a call, and where it may transfer one. Then you bind a number to it. Every call to that number reaches your agent as a session, and the call.* webhooks and GET /v3/voice/calls report it like any other call.

This guide covers the agent record. How the agent connects, and what it exchanges with Sent while a call is on, is in Connect a voice agent and the voice agent protocol.

Prerequisites

Phone calls must be enabled for your account. This is set by Sent: contact support@sent.dm to request it. You can create agents before that, but no call reaches them and no agent can connect until calls are on.

You also need:

• A number with calls turned on. See Voice in the channels guide.
• A webhook subscribed to call events, so you learn when an agent takes a call and when the call ends. See the call events.
• A WebSocket client in the language your agent is written in. The protocol is JSON frames, plus binary messages for audio, so no SDK is needed. The sample agents in the protocol repository show the frames in use.

All requests authenticate with the x-api-key header. Agent ids look like agent_9f2ab000-0000-4000-8000-000000000001. Anything else in the path is refused with 400.

Text or audio

Every agent has a session_type, which decides what travels between Sent and the agent while a call is on.

A text agent carries speech and may carry a greeting. An audio agent carries audio. Sending the other type's settings is refused with 400.

Create an agent

POST /v3/voice/agents creates an agent and returns it with its signing secret:

curl -X POST "https://api.sent.dm/v3/voice/agents" \
  -H "x-api-key: $SENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Receptionist",
    "session_type": "text",
    "websocket_url": "wss://agent.example.com/calls",
    "greeting": "Thanks for calling Example. How can I help?",
    "tools": ["hangup", "transfer"],
    "transfer_targets": [{ "kind": "number", "value": "+12125550100" }],
    "fallback": { "kind": "number", "value": "+12125550100" }
  }'

Only name and session_type are required. Every other field has a default.

The response is the agent as stored, every default filled in, plus signing_secret:

{
  "success": true,
  "data": {
    "id": "agent_9f2ab000-0000-4000-8000-000000000001",
    "name": "Receptionist",
    "session_type": "text",
    "websocket_url": "wss://agent.example.com/calls",
    "speech": { "setting": "standard", "voice": "emma", "language": "en-US" },
    "audio": null,
    "greeting": "Thanks for calling Example. How can I help?",
    "tools": ["transfer", "hangup"],
    "transfer_targets": [{ "kind": "number", "value": "+12125550100" }],
    "fallback": { "kind": "number", "value": "+12125550100" },
    "limits": { "max_call_seconds": 3600, "max_concurrent_calls": 10, "allowed_countries": null },
    "transcripts": { "store": false, "retention_days": 30 },
    "signing_secret": "whsec_MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDA=",
    "created_at": "2026-10-23T12:00:00+00:00",
    "updated_at": null
  },
  "error": null,
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-10-23T12:00:00+00:00",
    "version": "v3"
  }
}

id is also what the agent connects to Sent as. tools comes back as a set in one fixed order, whatever order you sent, so two bodies naming the same tools read the same.

What is refused

A 400 carries details keyed by the path of each field at fault, so one response reports every problem:

{
  "success": false,
  "status": 400,
  "error": {
    "code": "VALIDATION_001",
    "message": "The agent is invalid",
    "details": {
      "tools[1]": ["Must be one of transfer, hangup, send_dtmf, hold."],
      "transfer_targets": ["Required when tools includes transfer: name at least one target."]
    },
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-10-23T12:00:00+00:00",
    "version": "v3"
  }
}

The rules, by field:

• name: 1 to 100 characters after trimming.
• session_type: text or audio, matched ignoring case.
• websocket_url: an absolute URL with the wss scheme, no username or password, at most 2,048 characters, on a public host. A literal private, loopback or link-local address is refused here. A hostname is accepted here and judged when Sent connects, so a name that resolves to a private address fails the call, not the request.
• speech.setting: standard. speech.voice and speech.language: a voice name and a language from GET /v3/voice/voices, matched ignoring case. speech on an audio agent is refused.
• audio.sample_rate: 8000, 16000 or 24000. audio on a text agent is refused.
• greeting: 1 to 4,096 characters, text agents only.
• tools[i]: one of the four tools. A tool named twice counts once.
• transfer_targets: at most 20 entries. kind is number, user or agent. A number is written in E.164 and must be in a country Sent allows calls to. A user is an identity: letters, digits, - and _. An agent is an agent id of one of your own agents, and not the agent being written. A party listed twice counts once.
• fallback: kind is number only, with the same number rules.
• limits.max_call_seconds: 60 to 14,400. limits.max_concurrent_calls: from 1 up to a cap on your account. limits.allowed_countries: at least one ISO 3166-1 alpha-2 code when the field is sent, a code listed twice counts once.
• transcripts.retention_days: 1 to 365.

Voices and languages

GET /v3/voice/voices lists the names a text agent's speech.voice and speech.language accept:

curl "https://api.sent.dm/v3/voice/voices" \
  -H "x-api-key: $SENT_API_KEY"

{
  "success": true,
  "data": {
    "voices": [
      {
        "name": "emma",
        "language": "en-US",
        "description": "US English, female. The voice a call uses when the agent names none.",
        "default": true
      },
      {
        "name": "joanna",
        "language": "en-US",
        "description": "US English, female.",
        "default": false
      }
    ],
    "languages": ["en-US"]
  },
  "error": null
}

The catalogue grows as voices are added, and a name is never removed without notice, so read it rather than hard-coding a list. The names are Sent's own. An audio agent uses none of this, because it runs its own speech.

Connect in, or be connected to

An agent reaches Sent in one of two ways, decided by websocket_url. The frames are the same either way.

Choose the first when your agent is a service you run that can hold a connection open. Choose the second when you'd rather be called, for example from a serverless platform that accepts WebSockets. The handshake, the frames and how a session survives a lost connection are in Connect a voice agent.

Tools and transfer targets

tools says what the agent may do to a call, beyond talking. The agent asks with a tool.call frame, and Sent answers with a tool.result.

A tool the agent isn't allowed answers tool_not_allowed, and a transfer to a party that isn't listed answers target_not_allowed. Keep tools to what the agent needs. An agent that only answers questions needs ["hangup"], the default.

transfer_targets is the whole list of where the agent may send a call:

{
  "tools": ["hangup", "transfer"],
  "transfer_targets": [
    { "kind": "number", "value": "+12125550100" },
    { "kind": "user", "value": "support-desk" },
    { "kind": "agent", "value": "agent_4c1d2e3f-0000-4000-8000-000000000002" }
  ]
}

Only a number target connects a transfer. List a user or an agent when you want the agent to know about them, and have the agent treat a failed result as the caller still being on the line.

An agent that lists another agent as a target holds that agent: the other one can't be deleted until it's removed from the list. See Delete an agent.

Fallback

fallback is who takes a call to the agent's number when the agent can't. It's a phone number. A call goes there when:

• the agent connects in and isn't connected when the call arrives,
• the agent is connected to and the connection to websocket_url fails or isn't accepted in time,
• the agent's connection is lost during a call and the session isn't resumed within the resume window.

Without a fallback, such a call ends as FAILED with reason agent_unreachable, and you receive call.failed. A fallback leg to a phone number costs money for as long as it runs, like any other phone leg, and needs a balance that affords it. The call record names the number in connected_number and is billed for both legs, listed in legs. See The Call Record. A call the agent refuses for being over max_concurrent_calls doesn't go to the fallback: it fails with agent_busy.

Limits

Transcripts

transcripts.store and transcripts.retention_days are stored on the agent: whether Sent keeps the transcript of every call the agent takes, and for how many days, 1 to 365. They default to false and 30. No endpoint reads a transcript, so an agent that needs a record of a call keeps its own: a text agent sees every utterance as user.said and agent.say frames.

Bind a number to the agent

A call reaches the agent through one of your voice numbers. Bind the number with agent_id on PATCH /v3/channels/voice/{number}, or on POST /v3/channels/voice when you turn calls on for the number:

curl -X PATCH "https://api.sent.dm/v3/channels/voice/%2B12125550100" \
  -H "x-api-key: $SENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "agent_9f2ab000-0000-4000-8000-000000000001" }'

{
  "success": true,
  "data": {
    "number": "+12125550100",
    "status": "ACTIVE",
    "default_for_app_calls": true,
    "callback_url": "https://example.com/voice",
    "agent_id": "agent_9f2ab000-0000-4000-8000-000000000001",
    "routes_to": "agent_pending",
    "created_at": "2026-07-22T12:00:00+00:00",
    "updated_at": "2026-10-23T12:00:00+00:00"
  },
  "error": null
}

routes_to says who answers calls to the number:

Calls follow the change within about an hour, both ways: a call to the number in that hour may still reach your callback, or be declined, and after an unbind may still reach the agent. routes_to says what Sent has recorded, not which calls have moved yet, so bind a number before you need it and test with a call.

The agent wins over callback_url for calls to the number. Calls your app places from the number, with a voice token bound to it, still go through your callback, so one number can serve both. Send "agent_id": null to unbind the agent, after which callback_url answers again. An agent_id that isn't one of your agents is 404. A number the provider couldn't move to or from the agent is 502 with BUSINESS_027, and nothing is written, so repeat the request. The rest of the number's settings are in Managing channels.

List and read agents

GET /v3/voice/agents lists your agents, newest first, in pages of page_size (1 to 100, default 20) starting at page 1:

curl "https://api.sent.dm/v3/voice/agents?page=1&page_size=20" \
  -H "x-api-key: $SENT_API_KEY"

The response carries the page under agents and a pagination object, as every paginated list does. GET /v3/voice/agents/{id} reads one agent, in the shape the create returned. Neither carries signing_secret: it's never on a read. An agent that isn't yours is 404, not 403.

Change an agent

PATCH /v3/voice/agents/{id} changes the fields you name and answers with the agent as stored, the same shape GET returns:

curl -X PATCH "https://api.sent.dm/v3/voice/agents/agent_9f2ab000-0000-4000-8000-000000000001" \
  -H "x-api-key: $SENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "greeting": null,
    "tools": ["hangup", "transfer", "hold"],
    "limits": { "max_call_seconds": 1800, "max_concurrent_calls": 10 }
  }'

The result is checked by the same rules as a new agent, so a PATCH that leaves transfer in tools while emptying transfer_targets is 400. A body that changes nothing is 400 too, and so is a body that names no field at all. The signing secret is never touched here. A change reaches calls that start after it. Calls already on the agent keep the settings they started with.

With sandbox: true nothing is written: the request is validated against the stored agent and the agent is reported with 200 as it would read after the change.

Rotate the signing secret

POST /v3/voice/agents/{id}/rotate-secret generates a new signing_secret and returns it:

curl -X POST "https://api.sent.dm/v3/voice/agents/agent_9f2ab000-0000-4000-8000-000000000001/rotate-secret" \
  -H "x-api-key: $SENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "success": true,
  "data": {
    "signing_secret": "whsec_MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDA="
  },
  "error": null
}

The previous secret stops signing the moment the response is returned, so install the new one on your agent straight after the call. Handshakes in between fail verification: rotate at a quiet moment, and let the verifier accept both secrets while the switch is under way if calls can't wait. The secret only matters to an agent Sent connects to. An agent that connects in authenticates with your API key, and rotating its secret changes nothing it uses. With sandbox: true a secret is generated and returned with 202, and nothing is written.

Delete an agent

DELETE /v3/voice/agents/{id} removes the agent. The response is 204. Calls it already took keep their agent_id, so your call history stays readable.

An agent that something still points at isn't deleted:

To delete it, first unbind each number with PATCH /v3/channels/voice/{number} and "agent_id": null, and take the agent out of the other agents' transfer_targets or delete them. With sandbox: true nothing is written: the agent is looked up and the answer is the one a real delete would give.

Calls an agent answers

A call to a number bound to an agent is a call like any other, with two more facts on it. The call record and every call.* event carry mode, which is agent for a call an agent answers and inapp for a call your callback decides, and an agent call carries agent_id as well. A call.agent_connected event is sent once the agent's session starts, after call.answered. Filter your calls with GET /v3/voice/calls?mode=agent&agent_id=agent_....

POST /v3/voice/calls/{id}/hangup and POST /v3/voice/calls/{id}/recordings on a live agent call answer 409 with CONFLICT_015. The agent ends its own calls with the hangup tool. See Calls, recordings, and participants.

Next steps