Change a voice agent

Changes the fields you name and answers with the agent as stored, the same shape GET returns.

A key left out is left alone. A key sent as null clears an optional field (websocket_url makes the agent dial in, greeting and fallback go, speech, audio, tools, limits and transcripts return to their defaults). A key sent with a value replaces that field whole: send the whole limits object, not one of its keys. Changing session_type drops speech, audio and greeting unless the body sends them, since the other type cannot carry them. The result is checked like a new agent, and a body that changes nothing is 400.

With sandbox: true nothing is written: the request is validated against the stored agent and the agent is reported with 200 as it would read after the change.

PATCH
/v3/voice/agents/{id}

Path Parameters

id*string

The agent id, such as agent_9f2ab000-0000-4000-8000-000000000001

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

Changes some of a voice agent's fields. Partial: a key left out is left alone, a key sent as null clears an optional one, and a key sent with a value replaces that field whole (an object such as limits is replaced, not merged). A body that changes nothing is refused.

sandbox?boolean

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

name?string

A new name, 1 to 100 characters.

session_type?string

text or audio. Changing it drops the settings the other type cannot have (speech, audio, greeting) unless the body sends them.

websocket_url?|

A new wss:// URL, or null for an agent that dials in.

speech?|null

Text sessions: { setting, voice, language }, replaced whole; null restores the defaults.

audio?|null

Audio sessions: { sample_rate }; null restores the default.

greeting?|

A new greeting, or null for none.

tools?array<string>|

The whole list of tools; null restores the default.

transfer_targets?array<>|

The whole list of parties; null clears it.

fallback?|null

A new fallback party, or null for none.

limits?|null

The whole limits object; null restores the defaults.

transcripts?|null

The whole transcripts object; null restores the defaults.

Response Body

The agent as stored after the change

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 PATCH 'https://api.sent.dm/v3/voice/agents/string' \  -H 'Idempotency-Key: req_abc123_retry1' \  -H 'Content-Type: application/json' \  -d '{}'
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"  }}