---
title: "Change a voice agent"
method: PATCH
path: "/v3/voice/agents/{id}"
tags: ["Voice"]
---

# Change a voice agent

`PATCH /v3/voice/agents/{id}`

## Request

- Base URL: `https://api.sent.dm`
- URL: `https://api.sent.dm/v3/voice/agents/{id}`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

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.

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string
- `x-profile-id` string, uuid

## Request body

- SentDmServicesEndpointsCustomerAPIv3VoiceAgentsRequestsPatchVoiceAgentRequest: 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` string, nullable: A new wss:// URL, or null for an agent that dials in.
  - `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: A new greeting, or null for none.
  - `tools` string[], nullable: The whole list of tools; null restores the default.
  - `transfer_targets` SentDmServicesCommonServicesVoiceVoiceAgentPartySpec[], nullable: The whole list of parties; null clears it.
    - `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 `200`

The agent as stored after the change

- 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

- `400`: id is not an agent id, a field is out of range (details name each), or the body changes nothing
- `401`: Unauthorized - Invalid API credentials
- `403`: Forbidden
- `404`: This account has no such agent

## Changes

- **2026-10-28** `41acb2ceb84d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/changes/v3/voice/agents/:id/patch.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)