> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.lumenia.net/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.lumenia.net/_mcp/server. # 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. > **Info** > > **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`](/documentation/core-concepts/workspaces#chat-modes) 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](/documentation/core-concepts/workspaces) and [Documents & knowledge base](/documentation/core-concepts/documents). Tools attached to the workspace are available for the voice assistant to call — see [Tools](/documentation/core-concepts/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. > **Info** > > **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.