Create a voice agent

Creates an agent that answers phone calls through the Sent Voice Gateway. session_type says whether Sent carries the call as text (the caller's speech recognised for the agent, the agent's text spoken) or as audio. With websocket_url the gateway dials your agent for each call and signs the handshake with the signing_secret this response returns; without it, your agent dials in with your API key and this agent's id.

tools, transfer_targets, fallback and limits say what the agent may do on a call. Voices and languages for text sessions come from GET /v3/voice/voices. Calls reach the agent once a number is bound to it on /v3/channels/voice.

signing_secret is shown here and on POST /v3/voice/agents/{id}/rotate-secret only; store it now. With sandbox: true the request is validated and the agent reported with 202; nothing is written.

POST
/v3/voice/agents

Header Parameters

Idempotency-Key?string

Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.

Match^[a-zA-Z0-9_-]+$
Lengthlength <= 255
x-profile-id?string

Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.

Formatuuid

Request Body

application/json
  1. body

Creates a voice agent: what it takes for your agent to answer phone calls through the Sent Voice Gateway. Only name and session_type are required; every other field has a default.

sandbox?boolean

Sandbox flag - when true, the operation is simulated without side effects Useful for testing integrations without actual execution

name?|

A name for your own reference, 1 to 100 characters.

session_type?|

text: Sent turns the caller's speech into text and the agent's text into speech, so the agent exchanges text frames. audio: the agent receives and sends the sound itself.

websocket_url?|

Where the gateway connects to the agent for each call: an absolute wss:// URL on a public host, at most 2,048 characters. The handshake is signed with the agent's signing_secret. Leave it out and the agent dials in instead, connecting to the gateway with your API key.

speech?|null

Text sessions only: how the caller is spoken to and listened to.

audio?|null

Audio sessions only: the sound format.

greeting?|

Text sessions only: what the caller hears as soon as the call is answered, before the agent's first turn. 1 to 4,096 characters. Omit it and the agent speaks first.

tools?array<string>|

What the agent may do to the call: any of transfer, hangup, send_dtmf and hold. Default ["hangup"]. transfer needs at least one transfer_targets entry.

transfer_targets?array<>|

Where the agent may transfer a call to, up to 20 parties: a phone number (kind: number, E.164), one of your app users (kind: user, the identity) or another of your agents (kind: agent, its id). The agent can only transfer to a party listed here.

fallback?|null

Who takes the call when the agent cannot: a phone number (kind: number). Omit it and such a call hangs up.

limits?|null
transcripts?|null

Response Body

The agent as stored, with signing_secret

application/json
  1. response

Standard API response envelope for all v3 endpoints

success?boolean

Indicates whether the request was successful

data?|null

The response data (null if error)

error?|null

Error details (null if successful)

meta?

Metadata about the request and response

Example Request
curl -X POST 'https://api.sent.dm/v3/voice/agents' \  -H 'Idempotency-Key: req_abc123_retry1' \  -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"    }  ],  "sandbox": false}'
Example Response
{  "success": true,  "data": {    "id": "string",    "name": "string",    "session_type": "string",    "websocket_url": "string",    "speech": {      "setting": "string",      "voice": "string",      "language": "string"    },    "audio": {      "sample_rate": 0    },    "greeting": "string",    "tools": [      "string"    ],    "transfer_targets": [      {        "kind": "string",        "value": "string"      }    ],    "fallback": {      "kind": "string",      "value": "string"    },    "limits": {      "max_call_seconds": 0,      "max_concurrent_calls": 0,      "allowed_countries": [        "string"      ]    },    "transcripts": {      "store": true,      "retention_days": 0    },    "signing_secret": "string",    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z"  },  "error": {    "code": "string",    "message": "string",    "details": {      "property1": [        "string"      ],      "property2": [        "string"      ]    },    "doc_url": "string"  },  "meta": {    "request_id": "string",    "timestamp": "2019-08-24T14:15:22Z",    "version": "string"  }}