API ReferenceAgents

Update an agent

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

agent_idstringRequired

Request

This endpoint expects an object.
display_namestringOptional
descriptionstringOptional
languagestringOptional
ai_providerenumOptional

AI backend. Set to byom to switch to your own webhook. When changing to byom, also supply webhook_url in the same PATCH. New calls use the new mode immediately; in-flight calls keep the mode they started with.

Allowed values:
ai_modelstringOptional
system_promptstringOptional
webhook_urlstringOptional
Required when `ai_provider` is `byom`. This single URL receives both BYOM turn requests (`BYOMVoiceWebhookRequest`) and lifecycle events (`call.initiated`, `call.transcription`, `call.completed`). Detect lifecycle events by the presence of `event_type` in the body and return `{"received": true}`; for turn requests return a `BYOMVoiceWebhookResponse`. See the [BYOM guide](/guides/byom).
greeting_textstringOptional
Custom greeting played via TTS when a call connects
tool_definitionsstringOptional

JSON array of OpenAI-compatible tool definitions. Defaults to ’[]’.

shareablebooleanOptional
Enable or disable the public 'try my agent' shareable link
call_window_startstringOptional
call_window_endstringOptional
call_window_timezonestringOptional
pre_call_announcementstringOptional
recording_enabledbooleanOptional
Enable or disable call recording for this agent.
consent_requiredbooleanOptional

Whether a DTMF consent prompt is played before recording starts. Audit-logged on every change.

statusenumOptional
Allowed values:

Response

Agent updated
agent_idstring
workspace_idstring
display_namestring
descriptionstring
languagestring
ai_providerstring
ai_modelstring
system_promptstring
webhook_urlstring
greeting_textstring
Custom greeting played via TTS when a call connects. If null, a default greeting is used.
tool_definitionsstringDefaults to []

JSON array of OpenAI-compatible function/tool definitions. The AI can invoke these tools during voice calls. Built-in tools: hang_up, transfer_call, hold_call, resume_call. Custom tools are dispatched to the agent’s webhook_url. Defaults to ”[]”.

shareableboolean

When true, enables a public ‘try my agent’ link for browser-based test calls.

call_window_startstringDefaults to 08:00

Earliest permitted outbound call time (HH:MM, 24hr). CBN compliance.

call_window_endstringDefaults to 20:00

Latest permitted outbound call time (HH:MM, 24hr). CBN compliance.

call_window_timezonestringDefaults to Africa/Lagos
IANA timezone for call window evaluation.
pre_call_announcementstring

CBN requirement: spoken announcement at start of call identifying the sponsoring institution.

recording_enabledboolean

Whether call recording is enabled for this agent. Workspace-level recording must also be enabled via POST /v1/workspace/recording for calls to be recorded.

consent_requiredboolean

When true (default), the caller hears a consent prompt before recording starts. When false, recording begins immediately. Only disable if you have an independent legal basis under NDPR.

statusenum
created_atdatetime
updated_atdatetime

Errors

404
Update Agent Request Not Found Error