SEsentdm
Voice

Create a voice agent

Changed on

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

Request

  • Base URL
    https://api.sent.dm
  • URL
    https://api.sent.dm/v3/voice/agents
  • Auth
    • API key in header x-api-key
    • or HTTP bearer

Headers

Idempotency-Keystring

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.

x-profile-idstring uuid

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.

Request body

sandboxboolean

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

namestring nullable

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

session_typestring 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_urlstring 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.

greetingstring 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.

toolsstring[] 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.

Example request

{
  "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
}

Response

The agent as stored, with signing_secret

successboolean

Indicates whether the request was successful

Changes