--- title: "Create a voice agent" method: POST path: "/v3/voice/agents" tags: ["Voice"] --- # Create a voice agent `POST /v3/voice/agents` ## Request - Base URL: `https://api.sent.dm` - URL: `https://api.sent.dm/v3/voice/agents` - Auth: one of: - API key in header `x-api-key` - HTTP bearer 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. ## Headers - `Idempotency-Key` string - `x-profile-id` string, uuid ## Request body - SentDmServicesEndpointsCustomerAPIv3VoiceAgentsRequestsCreateVoiceAgentRequest: 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` string, nullable: A name for your own reference, 1 to 100 characters. - `session_type` string, nullable: 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` string, nullable: 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` SentDmServicesCommonServicesVoiceVoiceAgentSpeechSpec - `setting` string, nullable: standard, Sent's speech. Other settings are not available yet. - `voice` string, nullable: A voice name from GET /v3/voice/voices. Default: the catalogue's default voice. - `language` string, nullable: The language spoken and listened for, a BCP 47 tag from GET /v3/voice/voices. Default en-US. - `audio` SentDmServicesCommonServicesVoiceVoiceAgentAudioSpec - `sample_rate` integer, nullable: Samples per second of the audio exchanged: 8000, 16000 or 24000. Default 16000. - `greeting` string, nullable: 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` string[], nullable: 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` SentDmServicesCommonServicesVoiceVoiceAgentPartySpec[], nullable: 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. - `kind` string, nullable: number, user or agent. - `value` string, nullable: The E.164 number, the app user's identity, or the agent id (agent_…). - `fallback` SentDmServicesCommonServicesVoiceVoiceAgentPartySpec - `kind` string, nullable: number, user or agent. - `value` string, nullable: The E.164 number, the app user's identity, or the agent id (agent_…). - `limits` SentDmServicesCommonServicesVoiceVoiceAgentLimitsSpec - `max_call_seconds` integer, nullable: The longest a call may last, 60 to 14,400 seconds. Default 3,600. - `max_concurrent_calls` integer, nullable: How many calls the agent may have going at once, from 1. Default 10. - `allowed_countries` string[], nullable: ISO 3166-1 alpha-2 codes of the countries the agent may call or transfer to. Omit it to allow every country. Stored now, applied when the agent places calls. - `transcripts` SentDmServicesCommonServicesVoiceVoiceAgentTranscriptsSpec - `store` boolean, nullable: Whether Sent keeps the call's transcript. Default false. Stored now, applied when transcripts land. - `retention_days` integer, nullable: How long a stored transcript is kept, 1 to 365 days. Default 30. ## Response `201` The agent as stored, with signing_secret - SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfVoiceAgentResponse: Standard API response envelope for all v3 endpoints - `success` boolean: Indicates whether the request was successful - `data` SentDmServicesCommonServicesVoiceContractsVoiceAgentResponse: A voice agent as stored: what was written with every default filled in, plus the signing secret the one time it is shown (on create, and on rotate). The one shape every read of an agent answers with, on /v3/voice/agents and on the admin API the dashboard uses, so the two cannot drift. - `id` string: The agent's id, agent_ and a UUID. It is also what the agent connects to the gateway as. - `name` string - `session_type` string: text or audio. - `websocket_url` string, nullable: Where the gateway dials the agent; null when the agent dials in with your API key. - `speech` SentDmServicesCommonServicesVoiceVoiceAgentSpeech - `setting` string - `voice` string - `language` string - `audio` SentDmServicesCommonServicesVoiceVoiceAgentAudio - `sample_rate` integer - `greeting` string, nullable - `tools` string[] - `transfer_targets` SentDmServicesCommonServicesVoiceVoiceAgentParty[] - `kind` string - `value` string - `fallback` SentDmServicesCommonServicesVoiceVoiceAgentParty - `kind` string - `value` string - `limits` SentDmServicesCommonServicesVoiceVoiceAgentLimits - `max_call_seconds` integer - `max_concurrent_calls` integer - `allowed_countries` string[], nullable - `transcripts` SentDmServicesCommonServicesVoiceVoiceAgentTranscripts - `store` boolean - `retention_days` integer - `signing_secret` string, nullable: The whsec_ secret the gateway signs its handshake to websocket_url with. Present on create and after a rotate-secret; absent on every other read. Store it now. - `created_at` string, date-time - `updated_at` string, date-time, nullable - `error` SentDmServicesEndpointsCustomerAPIv3SharedApiError: Error information - `code` string: Machine-readable error code (e.g., "RESOURCE_001") - `message` string: Human-readable error message - `details` object, nullable: Additional validation error details (field-level errors) - `doc_url` string, nullable: URL to documentation about this error - `meta` SentDmServicesEndpointsCustomerAPIv3SharedApiMeta: Request and response metadata - `request_id` string: Unique identifier for this request (for tracing and support) - `timestamp` string, date-time: Server timestamp when the response was generated - `version` string: API version used for this request ## Other responses - `202`: Sandbox: the request is valid and this is what would have been written, with a secret nothing stores - `400`: A field is missing or out of range; details name each field - `401`: Unauthorized - Invalid API credentials - `403`: Forbidden - `409`: The account already holds as many voice agents as it may - `500`: Internal server error ## Changes - **2026-10-28** `41acb2ceb84d`: 1 info - endpoint added [Operation history](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/changes/v3/voice/agents/post.md) --- [API](https://skmtc.dev/sentdm/apis/sent-dm-api-v3.md) - [All operations](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/revisions/bdcca958cac7?raw)