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.
Idempotency-Key?stringUnique 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.
^[a-zA-Z0-9_-]+$length <= 255x-profile-id?stringProfile 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.
uuidapplication/json- 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?booleanSandbox 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?|nullText sessions only: how the caller is spoken to and listened to.
audio?|nullAudio 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?|nullWho takes the call when the agent cannot: a phone number (kind: number). Omit it and such a call hangs up.
limits?|nulltranscripts?|nullThe agent as stored, with signing_secret
application/json- response
Standard API response envelope for all v3 endpoints
success?booleanIndicates whether the request was successful
data?|nullThe response data (null if error)
error?|nullError details (null if successful)
meta?Metadata about the request and response
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}'{ "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" }}Remove every participant from a call DELETE
Removes every participant from the conference room a live call is in, the call itself included. Every leg ends and is reported through call.completed like any other call. A room that is already empty answers 204 as well. A call that has ended answers 409, as does a call that is not in a conference.
List your voice agents GET
Your voice agents, newest first. `page` and `page_size` (1 to 100, default 20) page the list. Signing secrets are never listed.