Update an agent
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Request
Attach a knowledge base (kb_… id, must belong to the workspace) so hosted-AI turns answer from its documents. Empty string detaches.
AI backend. Use GET /admin/ai/providers to see available
providers (typically gemini or openai). Set to byom to
switch to your own webhook; also supply webhook_url in the same
PATCH. New calls use the new mode immediately; in-flight calls
keep the mode they started with.
Model ID for the chosen provider. Must be an active model in the
platform catalogue (validated against voicebip_v1.ai_models).
Omit or leave unchanged to keep the current value; field is
ignored when ai_provider is byom.
The voice the agent speaks with. Pass a voice_id from GET /v1/voice/models (e.g. aura-asteria-en). Validated at save time (unknown id → 400). Omit to leave unchanged; send an empty string to reset to the platform-default voice.
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.
URL of a hosted WAV to play as the greeting instead of greeting_text. Must be 8 kHz mono 16-bit linear-PCM (telephony format); validated and stored at save time, so a bad URL or wrong format fails this request, never mid-call. Send an empty string to clear it. Omit to leave it unchanged (omitting avoids a needless re-fetch + re-upload).
JSON array of OpenAI-compatible tool definitions. Defaults to ’[]’.
Whether a DTMF consent prompt is played before recording starts. Audit-logged on every change.
BYOM only. Enable/disable the synchronous pre-greeting call.screening webhook for inbound calls.
Screening failure policy: false = fail-open (allow on webhook error), true = fail-closed (reject).
Response
The voice the agent speaks with. This is a voice_id from GET /v1/voice/models (e.g. aura-asteria-en). Null/absent means the platform-default voice.
The source URL of a hosted WAV played as the greeting instead of greeting_text. Set via UpdateAgent; validated and stored at save time. The system-managed storage key is never returned.
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 ”[]”.
Attached knowledge base (RAG). When set, hosted-AI turns answer from this KB’s documents. Empty/absent = none.
Earliest permitted outbound call time (HH:MM, 24hr). CBN compliance.
Latest permitted outbound call time (HH:MM, 24hr). CBN compliance.
CBN requirement: spoken announcement at start of call identifying the sponsoring institution.
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.
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.
BYOM only. When true, inbound calls trigger a synchronous call.screening webhook (to the agent’s webhook_url) BEFORE the greeting so you can allow/reject the caller and optionally override the greeting. See the BYOM guide.
Screening failure policy. false (default) = fail-open (allow the call if the screening webhook errors/times out); true = fail-closed (reject).