Voice agents
AI agents that answer a phone number, and the calls they take.
List voice agents
Returns the workspace's voice agents and the numbers they answer on.
Requires the module-voice-agent license feature. Without it the request is refused with 403 license_required — see plans and modules.
query Parameters
cursor^[A-Za-z0-9_-]+$limitoffsetsort^-?[a-z0-9_]+$Headers
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
List voice agents › Responses
Success
has_moreWhether more rows exist past this page.
next_cursorPass back as cursor for the next page. Null on the last page.
Create a voice agent
Creates the agent and its configuration. It has no phone number until you request one.
Requires the module-voice-agent license feature. Without it the request is refused with 403 license_required — see plans and modules.
Headers
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Create a voice agent › Request Body
vag_namevag_agentvag_configvag_limitsCreate a voice agent › Responses
Created
vag_idvag_activevag_createdvag_updatedvag_created_byvag_keyvag_namevag_agentvag_configvag_limitsvag_provider_refGet a voice agent
Returns the voice agent with the AI agent behind it and, if one is provisioned, its phone number.
Requires the module-voice-agent license feature. Without it the request is refused with 403 license_required — see plans and modules.
path Parameters
idHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Get a voice agent › Responses
Success
vag_idvag_activevag_createdvag_updatedvag_created_byvag_keyvag_namevag_agentvag_configvag_limitsvag_provider_refDelete a voice agent
Soft delete: the agent stops answering and stops being listed. Its call history is kept, and a phone number it still holds is not released — release it first if you are done paying for it.
Requires the module-voice-agent license feature. Without it the request is refused with 403 license_required — see plans and modules.
path Parameters
idHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Delete a voice agent › Responses
Success. No content.
Update a voice agent
Applies the vag_-prefixed fields present in the body. Changes reach the telephony provider on the next call, not retroactively.
Requires the module-voice-agent license feature. Without it the request is refused with 403 license_required — see plans and modules.
path Parameters
idHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Update a voice agent › Request Body optional
vag_namevag_activevag_agentvag_configvag_limitsUpdate a voice agent › Responses
Success
vag_idvag_activevag_createdvag_updatedvag_created_byvag_keyvag_namevag_agentvag_configvag_limitsvag_provider_refGet call statistics
Call count, total duration and credits consumed over the last days (30 by default).
Requires the module-voice-agent license feature. Without it the request is refused with 403 license_required — see plans and modules.
path Parameters
idquery Parameters
daysHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Get call statistics › Responses
Success
List calls
Returns the calls this agent took, newest first, with how each one ended.
Requires the module-voice-agent license feature. Without it the request is refused with 403 license_required — see plans and modules.
path Parameters
idquery Parameters
cursor^[A-Za-z0-9_-]+$limitoffsetsort^-?[a-z0-9_]+$vcall_createdvcall_statusHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
List calls › Responses
Success
has_moreWhether more rows exist past this page.
next_cursorPass back as cursor for the next page. Null on the last page.
Get one call
Returns the call with its transcript, summary and analysis. Details are refreshed from the telephony provider as they are read, so a call that just ended fills in rather than staying empty.
Requires the module-voice-agent license feature. Without it the request is refused with 403 license_required — see plans and modules.
path Parameters
call_ididHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Get one call › Responses
Success
vcall_idvcall_createdvcall_typevcall_fromvcall_tovcall_statusvcall_ended_reasonvcall_startedvcall_endedvcall_duration_secondsvcall_creditsvcall_summaryvcall_analysisvcall_has_recordingvcall_has_transcriptStream a call recording
Streams the audio rather than handing back a provider URL. The provider's own links are raw bucket endpoints or expiring presigned URLs and are not reliably playable in a browser, so this resolves a working source per request. Responds with audio, not JSON.
Requires the module-voice-agent license feature. Without it the request is refused with 403 license_required — see plans and modules.
path Parameters
call_ididHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Stream a call recording › Responses
Success
Assign a phone number
Rents a number and points it at this agent. This starts a recurring third-party charge.
Pick the country with country (US by default) and optionally an areaCode where the country supports one. An agent may hold one number at a time: asking again while it has one returns 400, so release the current number before requesting a different one.
Requires the module-voice-agent license feature. Without it the request is refused with 403 license_required — see plans and modules.
path Parameters
idHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Assign a phone number › Request Body optional
countryareaCode^\d{3}$Assign a phone number › Responses
Success
Release the phone number
Gives the number back to the provider and stops the charge. The number is gone — you will not get the same one back, so anything advertising it needs updating first.
Requires the module-voice-agent license feature. Without it the request is refused with 403 license_required — see plans and modules.
path Parameters
idHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Release the phone number › Responses
Success