Voice integration & routing numbers

A voice integration turns a workspace into a phone assistant: callers dial a number, and the workspace’s assistant answers, talks, consults its knowledge base, and calls its tools. A workspace has at most one voice integration.

Routing numbers

Voice calls are delivered through routing numbers — a pool of phone numbers LumenOne owns and manages.

When you create a voice integration, a number is auto-assigned from the available pool. There is no number picker.
Callers can dial the assigned number directly and reach the assistant, but the recommended setup is for the customer to keep advertising their existing business line and forward it to the routing number. Inbound calls to their line are forwarded to the routing number and land on the assistant.
The assigned number is returned in full (unmasked) as voice.phoneNumber — it is a LumenOne-owned destination the customer needs to see in order to set up forwarding, not customer PII.

Why forward instead of advertising the routing number directly? The routing number is owned by LumenOne, not the customer, and re-creating voice can hand back a different routing number once the previous one has been released. If the customer forwards their own line, they just re-point the forward at the new voice.phoneNumber and their public-facing number never changes. Give the customer the routing number and forwarding instructions once voice is created.

Configuring the assistant

Create the integration with POST /v1/workspaces/{workspaceId}/integrations/voice. Every body field is optional — an empty body creates a fully-defaulted assistant. The main fields:

Field	What it controls
`firstMessage`	The greeting the assistant speaks first.
`prompt`	The system prompt for the live voice conversation.
`voice`	The text-to-speech voice (`provider`, `voiceId`, and `model` where required).
`transcriber`	The speech-to-text engine (`provider`, `model`, `language`).
`fallbackVoices` / `fallbackTranscribers`	Ordered fallbacks used if the primary fails.

Build the body from the options catalog:

GET /v1/integrations/voice/options

This catalog is the source of truth for allowed providers and their valid values (Vapi voice ids, ElevenLabs voice models, transcriber models and their per-model languages). It is static and identical for every account, so it needs no X-Account-Id.

Two prompts: live conversation vs. knowledge base

A voice assistant draws on two different prompts, which is a common point of confusion:

voice.prompt — governs the live spoken conversation (persona, tone, flow).
The workspace chat.prompt — is the system prompt used to synthesize answers from the knowledge base. The workspace’s knowledgeSearch settings (top results, similarity threshold) also apply to those knowledge-base answers.

A voice assistant’s knowledge-base lookups always run in query mode, whatever the workspace’s chat.mode is set to: they answer strictly from the embedded documents and return the workspace’s refusal message when nothing relevant is found.

So to change how the assistant talks, edit the voice prompt; to change how it answers from your documents, embed documents and tune the workspace chat/knowledgeSearch settings. See Workspaces and Documents & knowledge base.

Tools attached to the workspace are available for the voice assistant to call — see Tools.

Lifecycle

Action	Endpoint	Notes
Create	`POST /v1/workspaces/{workspaceId}/integrations/voice`	Auto-assigns a routing number. Returns `409` if a voice integration already exists (remove it first, or PATCH to edit) or if no routing numbers are available in the pool.
Read	`GET /v1/workspaces/{workspaceId}/integrations/voice`	Redacted assistant config; `{ connected: false }` when not set up.
Update	`PATCH /v1/workspaces/{workspaceId}/integrations/voice`	Edit any subset of the fields above.
Remove	`DELETE /v1/workspaces/{workspaceId}/integrations/voice`	Disconnects voice and starts releasing the number (see below).

What happens to the number on disconnect

Disconnecting voice (or deleting the workspace) does not immediately return the routing number to the pool. It is marked pending release: the LumenOne team confirms the customer has removed call forwarding, then releases the number back to the available pool. This prevents a freshly reassigned number from receiving another customer’s forwarded calls.

Re-creating voice on the same workspace keeps the same number — while it is still pending release. If you POST a new voice integration for a workspace whose previous number has not yet been released, assignment prefers that workspace’s own pending-release number and hands it straight back, so existing call forwarding keeps working. A different number is drawn only once the old one has already been released to the pool.