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

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/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"
  }
}
{
  "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"
  }
}
{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_001",
    "message": "The agent is invalid",
    "details": {
      "tools[1]": [
        "Must be one of transfer, hangup, send_dtmf, hold."
      ]
    },
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-10-28T15:46:43.7684734+00:00",
    "version": "v3"
  }
}
Empty
Empty
{
  "success": true,
  "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"
  }
}
{
  "success": true,
  "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.