Skip to main content

Voice API

Outbound and inbound voice calling, transcripts, and analytics Base path: /api/v1/voice Endpoint count: 17

List agent-guided call scripts for a queue

GET /api/v1/voice/queues/{id}/scripts
Returns every active script attached to the queue, ordered by name ascending. Used by the agent console at call-bridge time to render the scripted-prompts panel.
string
required

Get one queue script with its sections

GET /api/v1/voice/queues/{id}/scripts/{scriptId}
Returns the script row plus the full section tree (sorted by sort_order). The agent console renders this client-side at call-bridge time.
string
required
string
required

List tenant skill catalog

GET /api/v1/voice/skill-catalog
Returns every active skill in the tenant’s catalog ordered by slug. Drives the softphone autocomplete + queue + agent edit forms. Use ?includeInactive=true for the admin catalog editor’s tombstone view.
string (enum: true|false)
When true, includes soft-deleted (is_active=false) rows. Default false.

List department voicemail boxes

GET /api/v1/voice/voicemail-boxes/
Returns a page of department voicemail boxes owned by the caller’s organization, ordered by name ascending. Each box carries its member roster and optional inbound_route_id back-ref. The list is cursor-paginated: a request returns at most limit boxes (default 50), and meta.pagination reports whether more pages remain.
string
Opaque cursor for the next page. Pass meta.pagination.cursor from the previous response to fetch the next page; omit for the first page.
integer
default:"50"
Maximum boxes to return per page (1–100, default 50).
string | null
Cursor to pass as cursor to fetch the next page. null on the final page.
boolean
true when more boxes remain beyond this page (fetch the next page with cursor); false on the final page.

Get one department voicemail box

GET /api/v1/voice/voicemail-boxes/{id}
Returns the box identified by :id when it belongs to the caller’s organization. 404 if the id does not exist or belongs to another org.
string
required

Mint a short-lived transcript SSE ticket

POST /api/v1/voice/calls/{callId}/transcript/ticket
Returns a 60s single-use ticket bound to (tenant, call_id) that the SSE client passes as ?ticket= on /transcript/stream. Removes the need to put a long-lived API key on the SSE URL.
string
required

Generate AI call summary

POST /api/v1/voice/calls/{id}/summary
AI-generated structured summary; cached after first invocation.
string
required

Align a transcript to a call recording

POST /api/v1/voice/calls/{id}/recording/align
Aligns a ground-truth transcript you supply against the stored call recording and returns exact word- and character-level timestamps, without re-running speech recognition. Use this to sync subtitles, time an audiobook or dubbing script, or build a redaction map against text you already know is correct — it will not drift from your wording the way a fresh transcript could. Returns 404 if the call has no stored recording.
string
required
string
required
Ground-truth transcript to align against the recording (up to 100,000 characters).

Create a queue script

POST /api/v1/voice/queues/{id}/scripts
Creates a new script optionally with its initial section tree. Sections are full-replace on subsequent PATCHes — there is no per-section CRUD surface.
string
required
string
required
string | null
boolean
object[]

Create a tenant skill catalog row

POST /api/v1/voice/skill-catalog
Creates a new skill row. Returns 201 with the created row. A second insert of the same active slug returns 409 SKILL_SLUG_ALREADY_EXISTS.
string
required
Lowercased + trimmed at the Zod boundary. UNIQUE per (org, slug) where is_active=TRUE — a duplicate active slug returns 409 SKILL_SLUG_ALREADY_EXISTS.
string
required
string

Create a department voicemail box

POST /api/v1/voice/voicemail-boxes/
Creates a new department voicemail box scoped to the caller’s organization. name MUST be unique within the org and is slug-shaped. Every members[*] id is validated against the org’s user roster — leaked ids from other tenants are rejected with 422. Returns 201 with the created row.
string
required
Slug-shape name; UNIQUE within the org.
string
required
string[]
Initial roster of subscribed user ids (max 50).
integer | null

Update a department voicemail box

PUT /api/v1/voice/voicemail-boxes/{id}
Partial update — only fields supplied in the body are written. members (when supplied) replaces the roster (not delta-merged); every id is re-validated against the org. Returns the persisted row.
string
required
string
string
string[]
integer | null

Update softphone in-call notes

PATCH /api/v1/voice/calls/{id}/notes
Saves operator-typed notes onto call_logs.metadata.notes. Auto-saved by the softphone widget every 5s and on hangup.
string
required
string
required

Update queue script metadata and sections

PATCH /api/v1/voice/queues/{id}/scripts/{scriptId}
Partial update — only fields supplied are written. When sections is supplied it FULLY REPLACES the existing section tree (delete + insert in one transaction). Empty patch (no fields) returns 400.
string
required
string
required
string
string | null
boolean
object[]

Update a tenant skill catalog row

PATCH /api/v1/voice/skill-catalog/{id}
Partial update of label, description, isActive. At least one field MUST be present. description: null clears the field; omission preserves it. Setting isActive: false soft-deletes the row.
string
required
string
string | null
boolean

Delete a queue script

DELETE /api/v1/voice/queues/{id}/scripts/{scriptId}
Hard-deletes the script row (CASCADEs to sections via the FK). Returns 204 with no body on success; 404 if the script id does not belong to the queue.
string
required
string
required

Soft-delete a tenant skill catalog row

DELETE /api/v1/voice/skill-catalog/{id}
Soft-deletes the skill by setting is_active=false. The historical row is preserved for analytics + audit; future writes referencing the slug will fail assertSkillsRegistered. Operators may re-create the slug with a fresh row (the partial unique excludes tombstones).
string
required

Delete a department voicemail box

DELETE /api/v1/voice/voicemail-boxes/{id}
Removes the box. Captured voicemails with box_id pointing at this row are NOT deleted — they surface under the dashboard’s Archived / orphan box group (matches user-deletion semantics for assigned_user_id). Returns 204 on success.
string
required