Phonic

View saved version →

---
name: phonic
description: Choose a Phonic voice integration and find the relevant implementation skill. Use when starting a Phonic integration or deciding between phone calls, browser voice, and server audio.
license: MIT
---

# Build voice agents on Phonic

SDKs: `npm install phonic` / `pip install phonic`. Entry points: `new PhonicClient({ apiKey })` (Node), `Phonic(api_key=...)` / `AsyncPhonic(...)` (Python). REST base: `https://api.phonic.ai/v1` with `Authorization: Bearer $PHONIC_API_KEY`. Always use the `.ai` domain for API and docs URLs — `phonic.co` addresses still resolve for backward compatibility, but all new code should use `phonic.ai`.

Fetch live docs rather than from memory: use the index at [llms.txt](https://docs.phonic.ai/llms.txt). For the REST API, see [openapi.json](https://docs.phonic.ai/openapi.json). For the WebSocket protocol, see [asyncapi.json](https://docs.phonic.ai/asyncapi.json). If an endpoint does not appear in these docs, it doesn't exist, do not invent one.

## Choosing a conversation surface

- **Outbound phone call**: `client.conversations.outboundCall({ to_phone_number, config })`
- **Inbound phone number**: create/update the agent with `phone_number: "assign-automatically"`
- **Voice in a browser or mobile app**: direct STS WebSocket `wss://api.phonic.ai/v1/sts/ws?session_token=...`
- **Bridge your own telephony/audio server-side**: `client.conversations.connect()`
- **Watch a live conversation (read-only)**: `wss://api.phonic.ai/v1/conversations/{id}/live/ws`

Mistakes to avoid when picking:

- Don't open the browser STS socket to place a phone call — phone calls are one API call (`outboundCall`); the STS socket streams a user's microphone.
- Don't relay browser audio through your own server on the way to Phonic — it works, but adds a network hop of latency to every utterance; browsers connect directly using a session token. The session-token flow exists because an API key can't live in a browser; your own server holds the key, so server-side code uses `conversations.connect()` directly and never needs session tokens.
- Don't confuse the two WebSockets: `sts/ws` is the live voice conversation; `conversations/{id}/live/ws` is a read-only monitoring feed (`conversation-updated` / `conversation-ended` events only) — it cannot send audio or speak.

## Continue with the relevant skill

Use the matching skill when installed. If it is unavailable, follow the live documentation links above.

| Task | Skill |
| --- | --- |
| Agents, phone calls, prompts, and project operations | [phonic-agents](../phonic-agents/SKILL.md) |
| Browser voice, STS configuration, audio, and reconnects | [phonic-websockets](../phonic-websockets/SKILL.md) |
| Agent tools and human transfers | [phonic-tools](../phonic-tools/SKILL.md) |
| Webhooks, extractions, and conversation evaluations | [phonic-post-call](../phonic-post-call/SKILL.md) |

View saved version →

---
name: phonic-agents
description: Create and configure Phonic agents and phone calls using MCP, SDKs, or REST. Use for saved agents, inbound numbers, outbound calls, prompting, and project operations.
license: MIT
---

# Configure Phonic agents and calls

SDKs: `npm install phonic` / `pip install phonic`. Entry points: `new PhonicClient({ apiKey })` (Node), `Phonic(api_key=...)` / `AsyncPhonic(...)` (Python). REST base: `https://api.phonic.ai/v1` with `Authorization: Bearer $PHONIC_API_KEY`. Always use the `.ai` domain for API and docs URLs — `phonic.co` addresses still resolve for backward compatibility, but all new code should use `phonic.ai`.

Fetch live docs rather than from memory: use the index at [llms.txt](https://docs.phonic.ai/llms.txt). For the REST API, see [openapi.json](https://docs.phonic.ai/openapi.json). For the WebSocket protocol, see [asyncapi.json](https://docs.phonic.ai/asyncapi.json). If an endpoint does not appear in these docs, it doesn't exist, do not invent one.

## SDK surface

- Agents: `client.agents.create/get/list/update/upsert/delete`. `upsert` is create-or-update by name (idempotent). Agents are identified by name.
- Outbound calls: `client.conversations.outboundCall(...)` — greeting goes in `config.welcome_message`.

## MCP calls and saved configuration

Regular outbound calls remain available through `create_outbound_call`. Direct SIP outbound calls and custom SIP phone-number registration are excluded from MCP while saved SIP connections are unsupported; do not invent a connection-ID tool or request SIP credentials in chat.

For external storage, direct the user to [Phonic](https://phonic.ai), select the intended workspace/project, and create or rotate credentials in **Project settings → External storage policies**. Then list saved policies through MCP and reference the policy name or ID supported by the operation. Configure authenticated configuration endpoints on the website; MCP cannot submit their headers.

Do not collect these credentials through chat or an SDK/REST/shell workaround for an excluded MCP operation. When implementing an SDK application, use existing environment variables or a secrets manager without displaying secret values.

## Prompting voice agents

Voice prompts differ from chat prompts (speech formatting, silence handling, naturalness) — use [the prompting guide](https://docs.phonic.ai/docs/build/agents/prompting_guide.md).

## Operations

- **Projects** organize agents/tools/numbers within a workspace; use one project per tenant/product line rather than a new workspace. API keys are workspace-level.
- **Rate limits**: see [the rate limits page](https://docs.phonic.ai/docs/platform/rate_limits.md); high-volume outbound campaigns need client-side concurrency caps.
- **Observability**: per-call outcomes via the webhook events above; live read-only monitoring via the live WebSocket; [audit logs](https://docs.phonic.ai/docs/platform/audit-logs.md).

## Campaign and batch dialers

- **Campaign/batch dialers**: claim each number (durable in-progress state) before dialing and design the claim so a second runner instance can't grab it too — per-run completion state alone doesn't prevent two processes from double-dialing.

View saved version →

---
name: phonic-get-started
description: Get started on phonic.ai via MCP, connect Phonic, and build and run a first voice conversation. Use for Phonic setup, a first conversation, and choosing the next implementation workflow.
license: MIT
---

# Get started with Phonic

When the user says “get started on phonic.ai via MCP,” “connect Phonic,” or “build my first Phonic conversation,” carry the task through connection, agent setup, and a first conversation. Use the user's existing context, make reasonable reversible defaults, and ask only for missing details that block the next step.

## Connect and authenticate

Inspect the client's available tools and MCP configuration before adding anything. Reuse a working Phonic connection. Otherwise configure `https://mcp.phonic.ai/mcp` through the client's supported setup flow; consult the client-specific installation instructions in [the package README](../../README.md). Preserve other MCP entries. Use the client's OAuth flow for sign-in and workspace selection; never ask the user to paste a token into chat.

Perform supported setup steps directly when the environment permits. If a login, client approval, or restart requires the user, give the exact next action and resume from that point when completed. Do not claim connection success until a Phonic tool responds. Installing a skill does not itself connect MCP, and connecting MCP does not install skills; automatic selection depends on the host loading this skill.

Discover the tools actually exposed by the connection; prefixes differ between clients. Use `search_docs` on the same connection for product and API questions. If it is unavailable, use [the documentation index](https://docs.phonic.ai/llms.txt) and check connection status; do not require a separate docs server.

## Set up the first agent

Inspect the connected workspace, projects, and existing agents. Use the user's specified project, or an unambiguous existing project; ask only when the choice is unclear. OAuth selects the workspace for the connection; selecting a project does not switch workspaces.

Use the discovered API tools for account operations. Reuse a suitable agent or create a small demo agent within the user's requested scope. If no use case is given, start with a simple friendly assistant that can hold a short conversation, without business integrations. Use a supported model and available voice from the current schemas/catalog. Avoid making a long questionnaire a prerequisite to trying the product.

## Run the first conversation

Follow the user's requested conversation surface. For an unspecified first demo, prefer a browser or dashboard conversation so a phone number is not required; use current docs to find the supported test interface or implement a minimal browser session if that is the user's task. Use a returned or documented destination rather than inventing a dashboard URL. Keep API keys server-side when building a browser session.

For an outbound call, obtain the user's intended recipient if missing, validate with `dry_run: true`, then place the requested test call once validation succeeds and the task authorizes calling that recipient. A dry run is not a completed conversation. Do not repeat a potentially successful call after an ambiguous error without checking its status.

Verify the conversation from available status/transcript events and invite the user to speak when microphone interaction is required. Report the selected workspace/project, agent, and observed result concisely. If the host cannot capture audio or start the chosen surface, provide the exact action or runnable entry point that lets the user finish, and state that the conversation has not yet been verified. Continue through available steps rather than stopping after a setup plan.

## Specialized tasks

- Use `phonic-improvement-loop` for prompt experiments and Replay or Responses simulations.
- Use `phonic-steering` for context and reply controls during a live conversation.
- Use `p

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: phonic-improvement-loop
description: Run Phonic prompt experiments and conversation simulations with Replay or Responses. Use to debug a conversation, compare prompt changes, or simulate tool-dependent behavior.
license: MIT
---

# Phonic prompt experiments and simulations

Use Replay and Responses to investigate a conversation or compare a proposed prompt change. Read the [Replay API](https://docs.phonic.ai/api-reference/conversation-items/replay.md) or [Responses API](https://docs.phonic.ai/api-reference/responses/create.md) for the selected method.

## Scope the experiment

Identify the behavior being changed, the affected conversations and tool paths, and the consequence of a regression. Match the experiment to that scope:

- **One conversation or a small wording change:** inspect the failure, replay the relevant completed assistant turns, and check a few related cases. A mock server or formal dataset split is unnecessary for a local diagnosis.
- **Broader prompt or tool-use changes:** compare the baseline and candidate on representative conversations, including ordinary cases, known failures, and affected tool paths. For repeated prompt development, separate train (development), validation (candidate selection), and test (final assessment) sets. Keep related conversation turns and synthetic variants in the same split.
- **High-volume or consequential deployments:** consider simulations with varied tool outputs, failures, and rare cases. A mock tool server is useful when tool behavior materially affects the result; scale, tool complexity, and failure impact matter more than an enterprise label. Read [mock-tool simulations](references/mock-tools.md) only when this larger experiment is warranted.

Choose sample counts and a stopping condition from the user's objective, coverage, cost, and available time. Respect a supplied budget; otherwise propose the size and estimated generation count before a substantial batch. There is no fixed iteration limit. Define what a successful reply or tool call looks like before comparing results.

## Choose Replay or Responses

- **Replay:** use `replay_conversation_item` when exposed, or `POST /v1/conversation_items/{id}/replay`, for a completed assistant turn from an ended, transcript-retained conversation. Omit `system_prompt` for the as-recorded baseline; supply it for the candidate. Whole-conversation audio replay is a different operation.
- **Responses:** use the discovered `create_response` tool or `POST /v1/responses` for synthetic or edited histories, alternate tool outputs, and multi-turn simulations. Workspace enablement may be required. Read [Responses simulation requests](references/responses.md) when using this method.

## Run and compare

Keep inputs, configuration, sample counts, and grading criteria consistent between baseline and candidate. Inspect generated text, proposed tool calls, and actions together; check tool names and arguments rather than judging plausible speech alone. A proposed tool call does not prove an external action executed. Text simulations do not measure voice quality, interruptions, or live latency.

For a local experiment, report what the related cases establish and their limits. For broader experiments, develop changes on train cases, select using validation, and assess the chosen prompt on untouched test cases. If test results guide a further edit, use a new test set before making a final generalization claim. If grading criteria change, regrade baseline and candidate consistently.

Stop when the target is met, the agreed resource limit is reached, or further experiments are not justified by the evidence. Separate failed Replay or Responses API requests from poor generated replies and deliberately simulated tool errors. Report attempted, successful, and failed requests, sample sizes, representative failures, and total generations; do not silently drop missing samples. Fix access/eligibility errors before retrying, and bound transient retrie

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: phonic-post-call
description: Handle Phonic conversation webhooks, extractions, and evaluations. Use for post-call processing, analysis results, and webhook receivers.
license: MIT
---

# Process Phonic conversation results

SDKs: `npm install phonic` / `pip install phonic`. Entry points: `new PhonicClient({ apiKey })` (Node), `Phonic(api_key=...)` / `AsyncPhonic(...)` (Python). REST base: `https://api.phonic.ai/v1` with `Authorization: Bearer $PHONIC_API_KEY`. Always use the `.ai` domain for API and docs URLs — `phonic.co` addresses still resolve for backward compatibility, but all new code should use `phonic.ai`.

Fetch live docs rather than from memory: use the index at [llms.txt](https://docs.phonic.ai/llms.txt). For the REST API, see [openapi.json](https://docs.phonic.ai/openapi.json). For the WebSocket protocol, see [asyncapi.json](https://docs.phonic.ai/asyncapi.json). If an endpoint does not appear in these docs, it doesn't exist, do not invent one.

## Webhooks and post-call steps

Webhooks can indicate conversation progress: `conversation.ended`, `conversation.analysis`, `conversation.transferred`. A typical post-call pipeline looks like:

1. **`conversation.ended`** fires when the call ends — log the outcome and kick off your downstream steps from here.
2. **`conversation.analysis`** follows with performance metrics: its `conversation` payload carries `latencies_ms` and `interruptions_count` (also available via `GET /v1/conversations/{id}/analysis`). It does not contain extraction results.
3. **Extractions** turn the transcript into typed fields you define. Create an extraction schema, then run it per conversation with `POST /v1/conversations/{id}/extractions` and read results with the matching GET — typically from your `conversation.ended` handler. Extractions read the transcript, so they fail if transcripts are deleted; run them promptly if you have a retention policy.
4. **Eval prompts** grade calls against plain-language criteria. Create them at the project level (`name` + a criterion like "the assistant made the required disclosure"), evaluate a conversation via the conversation-evals endpoint, and read results per conversation or listed across the project — useful for compliance checks and QA queues.

## Webhook receivers

- **Webhook receivers** — Phonic delivers webhooks via svix, which retries, so the same event can arrive more than once (and concurrently). Build for that:
  1. Verify the svix signature before touching the body.
  2. Durably enqueue the event before returning 2xx; process slow work with a retryable worker.
  3. Store each event id durably (DB unique constraint, not process memory) and skip events you've already processed.
  4. For external side effects, use a stable idempotency key supported by the destination and persist the result. A crash after a side effect but before marking it complete can otherwise duplicate it on retry. A local started/done marker alone does not guarantee exactly-once execution; reconcile ambiguous outcomes before retrying non-idempotent operations.

View saved version →

---
name: phonic-steering
description: Steer a live Phonic voice conversation with system messages, tool availability, and reply controls. Use when adding app context mid-call or controlling when an agent speaks.
license: MIT
---

# Steer a live Phonic conversation

Read the relevant message schemas in [AsyncAPI](https://docs.phonic.ai/asyncapi.json) and the [WebSocket guide](https://docs.phonic.ai/docs/build/with-web-sockets/via-web-sockets.md). Send control messages on the active conversation's STS WebSocket or the application's SDK connection. The inbound API MCP and the read-only live monitoring socket are not substitutes for that connection.

Choose the control matching the user's intent:

- **Add new context or instructions:** `add_system_message`. This is the current message name; there is no `add_system_prompt` message. `update_system_prompt` is deprecated.
- **Change available tools:** `update_tools_subset`, using the documented list shape. Verify which tools remain available before sending the new subset.
- **Request a reply now:** `generate_reply`; adding context and requesting speech are distinct operations.
- **Speak specified text:** `say`, using the current schema rather than assuming it accepts the same fields as a system message.
- **Change future conversations:** update the saved agent configuration instead of treating a live control message as a persistent prompt edit.

For example, after the conversation has been configured:

```json
{
  "type": "add_system_message",
  "system_message": "The user has selected the annual plan in the app. Explain the annual plan if they ask about their selection."
}
```

Only follow that with `generate_reply` when the app should proactively speak. Keep trusted application instructions separate from untrusted user/document text. Do not place API keys or unnecessary personal data in the message.

Verify the intended effect in the transcript and tool events, including what happens if the user is speaking when the update arrives. Keep the audio loop nonblocking. Report the distinction between a successfully sent message and observed agent behavior; sending a control message is not proof the agent followed it.

View saved version →

---
name: phonic-supervisor
description: Build your own supervisor over a Phonic agent as a consult tool the agent calls before risky actions, with a read-only live transcript for context, call cancellation, and post-call review. Use when adding LLM, rules-based, or human oversight, compliance checks, or escalation logic on top of a Phonic agent.
license: MIT
---

# Build a supervisor for Phonic conversations

SDKs: `npm install phonic` / `pip install phonic`. Entry points: `new PhonicClient({ apiKey })` (Node), `Phonic(api_key=...)` / `AsyncPhonic(...)` (Python). REST base: `https://api.phonic.ai/v1` with `Authorization: Bearer $PHONIC_API_KEY`. Always use the `.ai` domain for API and docs URLs — `phonic.co` addresses still resolve for backward compatibility, but all new code should use `phonic.ai`.

Fetch live docs rather than from memory: use the index at [llms.txt](https://docs.phonic.ai/llms.txt). For the REST API, see [openapi.json](https://docs.phonic.ai/openapi.json). For the WebSocket protocol, see [asyncapi.json](https://docs.phonic.ai/asyncapi.json). If an endpoint isn't in these docs, assume it doesn't exist and don't invent one. One exception: the live transcript socket in section 2 (`/v1/conversations/{id}/live/ws`) is a preview documented in the [Live Conversation WebSocket guide](https://docs.phonic.ai/docs/build/with-web-sockets/live_websocket) rather than in the spec, so its contract may change.

A supervisor is your own service (an LLM, a rules engine, or a human console) that reviews what the agent is about to do and tells it what to do instead. Phonic has no supervisor endpoint. Build it as a **tool the agent calls**: this works for phone calls, web sessions, and your own socket alike, and keeps the agent in control of when it speaks.

If the user only wants stronger in-call reasoning rather than their own policy or business checks, suggest trying the agent's `intelligence_level: "high"` before building a supervisor.

## 1. Supervisor as a consult tool

Create a `custom_webhook` tool such as `consult_supervisor(question)` and attach it to the agent (see `phonic-tools`). Phonic POSTs `{ call_info, ...parameters }`, where `call_info.conversation_id` identifies the call; your endpoint runs the supervisor and returns its decision as JSON. The response body goes into the agent's context and is truncated beyond 16,000 characters.

- **Use `execution_mode: "async"` with `wait_for_response: true` and `allow_tool_chaining: false`.** The agent waits for the answer, calls no other tools meanwhile, and then tells the caller the result. `allow_tool_chaining` defaults to `true`, and the API rejects it alongside `wait_for_response`, so set it to `false` explicitly.
- On a POST tool, every parameter needs `location: "request_body"`; the API rejects the tool otherwise.
- Set `endpoint_timeout_ms` (1000–180000, default 5000) to cover the slowest review, including a human queue, and give your handler its own deadline well under it so Phonic always gets a `200` answer.
- Leave `require_speech_before_tool_call: false` unless the caller must hear an acknowledgement before the consult; with `true`, the agent has repeated "checking with my supervisor" before giving the answer. Neither setting silences the agent: with `false` it can still speak on its own, and `wait_for_response` doesn't mean it waits silently.
- Authenticate the endpoint with `endpoint_headers` (a shared secret header). Refuse to start without the secret, and reject requests whose header is missing or wrong.

**Tell the agent when to consult.** The agent only calls the tool when its instructions say to, so be specific in both the tool `description` and the agent's system prompt:

- Name the triggers: "Before issuing a refund, cancelling an account, or transferring the caller, call `consult_supervisor`."
- Say what to send: the situation, what the caller asked for, and the action the agent intends to take.
- Say what to do with the answer: follow `decision`, use `

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: phonic-tools
description: Connect tools to Phonic agents and configure human transfers. Use for webhook, WebSocket, context, MCP, and built-in tools or transfer outcomes.
license: MIT
---

# Connect Phonic tools and transfers

SDKs: `npm install phonic` / `pip install phonic`. Entry points: `new PhonicClient({ apiKey })` (Node), `Phonic(api_key=...)` / `AsyncPhonic(...)` (Python). REST base: `https://api.phonic.ai/v1` with `Authorization: Bearer $PHONIC_API_KEY`. Always use the `.ai` domain for API and docs URLs — `phonic.co` addresses still resolve for backward compatibility, but all new code should use `phonic.ai`.

Fetch live docs rather than from memory: use the index at [llms.txt](https://docs.phonic.ai/llms.txt). For the REST API, see [openapi.json](https://docs.phonic.ai/openapi.json). For the WebSocket protocol, see [asyncapi.json](https://docs.phonic.ai/asyncapi.json). If an endpoint does not appear in these docs, it doesn't exist, do not invent one.

- Tools: `client.tools.create(...)`, then attach by name in agent config `tools: [...]`.

## Tools

Tool types (webhook, websocket, context, built-in transfers, MCP), reserved parameter names, and each type's request/response contract are documented in [the tools docs](https://docs.phonic.ai/docs/build/tools/tools_overview.md) — fetch the page for your tool type before implementing.

- Tool outputs must include every identifier a later tool call needs as a parameter (e.g. return the `job_id` your `update_job` tool expects) — the agent can only pass along values it has been given.
- Tools can be defined inline in the STS config (no pre-created tool): `tools: [{ "type": "custom_websocket", "execution_mode": "sync", "tool_schema": { "type": "function", "function": { ..., "strict": true } } }]` — the `strict: true` inside the function schema is required.
- If you bridge audio server-side, never do blocking I/O in the audio send/receive loop — periodic multi-second stalls in agent audio are almost always blocking code in the bridge.

## Authentication for configured tools

Configure webhook and external MCP-server authentication on [Phonic](https://phonic.ai) in the intended workspace/project, then reference the saved tool or server from the agent configuration. Phonic's MCP cannot submit custom headers, including SIP transfer headers. Do not ask users to paste credentials into chat or use an SDK/REST/shell workaround to submit credentials excluded from MCP. For SDK application development, use existing environment variables or a secrets manager without displaying secret values.

## Transfers

- Transfer to a human is a built-in tool (`built_in_transfer_to_phone_number`, target number in the tool config) attached to the agent — don't hand-roll Twilio call control.
- Targets are preconfigured per transfer tool; the agent chooses among configured transfer tools and cannot dial an arbitrary number returned by another tool mid-call.
- Reading outcomes from conversation data: the transfer tool's output body has `connected: true|false` — `true` means the callee leg answered (human or voicemail); `false` means the transfer failed and the agent tells the caller.
- Voicemail detection: set `detect_voicemail: true` on the transfer tool (tools API). The agent then listens to the answered leg and a system tool call records the judgment — `tool_transfer_hit_voicemail` or `tool_transfer_successful` (= judged human). Without voicemail detection, `tool_transfer_successful` fires immediately on connect and means only "connected". Detection requires the bridged transfer mode (`use_agent_phone_number: true`, the default) — a SIP REFER handoff leaves the call and can't listen.
- The `conversation.transferred` webhook carries `transferred_to`, `call_info`, and the conversation items up to the transfer — the pre-transfer transcript arrives with the event.

View saved version →

---
name: phonic-voices
description: Find, preview, and select Phonic voices for a language, accent, or speaking style. Use when a user wants to hear voice options, configure a voice ID, or randomly allocate voices across conversations.
license: MIT
---

# Find a Phonic voice

Point users to the [voice picker](https://phonic.ai/voices) to browse and listen. Use the [voices reference](https://docs.phonic.ai/docs/build/agents/voices) for voice IDs and descriptions. Use the connected `list_voices` tool (with its required model argument) or current SDK/API to verify availability, and `get_voice` for details when exposed. Tool prefixes and supported model values vary by client; inspect the schema rather than guessing them.

Start with the use case and the person the voice should evoke. Ask only for missing details that change the recommendation:

- What will this person do on the call, and who will they be speaking with?
- Which languages matter most, and which need occasional support?
- What personality, energy, accent, or speaking style fits the intended experience?

Use the language-proficiency ratings to prioritize the important languages, then match style and accent to the desired persona. Offer a small shortlist with verified voice IDs and a brief reason for each. For example, Sandeep can fit a realistic, tired, monotonous customer-support representative; Sabrina can fit a cheerful, chatty persona. Treat these as listening starting points and verify their current availability and target-language suitability.

Preview candidates with the same short, representative sentence in the intended language using `voices_preview` or the voice picker. Include domain terms and numbers when their pronunciation matters. If the client can play returned audio, let the user listen; otherwise point them to the voice picker or voices page. Do not claim to have heard audio that you could not play or inspect.

Set `voice_id` only within the requested agent/application change. Note that choosing a voice and setting the conversation's language are separate settings. For multilingual use, read the [multilingual guide](https://docs.phonic.ai/docs/build/agents/multilingual.md) and preview every important target language before recommending a final choice.

## Allocate voices across conversations

Choose based on the experience callers should have: should they recognize a consistent persona, or hear different members of a team? Use context already provided; ask only if this affects the choice and is unclear.

- **Fixed voice:** fits a recurring persona, such as a front-desk receptionist whom callers expect to recognize across calls.
- **Random voice set:** fits a team experience, such as customer service, where callers may hear a different representative on each call instead of always hearing the same voice. Random selection can still repeat a voice on consecutive calls.

Narrow the candidate set to voices suitable for the required languages and persona first.

Phonic supports equal-probability random allocation: set `voice_id` and `additional_voice_ids` on the agent. Each conversation receives one voice from their combined set. The additional list must exclude `voice_id` and contain no duplicates. Verify the exposed schema against the [agent API](https://docs.phonic.ai/api-reference/agents/create.md) before applying it. For example, a set with `voice_id: "sabrina"` and `additional_voice_ids: ["sandeep"]` selects either voice with equal probability; it does not alternate predictably.

View saved version →

---
name: phonic-websockets
description: Build Phonic browser voice sessions and server audio bridges. Use for STS configuration, audio streaming, transcript events, interruptions, and reconnects.
license: MIT
---

# Build Phonic voice connections

SDKs: `npm install phonic` / `pip install phonic`. Entry points: `new PhonicClient({ apiKey })` (Node), `Phonic(api_key=...)` / `AsyncPhonic(...)` (Python). REST base: `https://api.phonic.ai/v1` with `Authorization: Bearer $PHONIC_API_KEY`. Always use the `.ai` domain for API and docs URLs — `phonic.co` addresses still resolve for backward compatibility, but all new code should use `phonic.ai`.

Fetch live docs rather than from memory: use the index at [llms.txt](https://docs.phonic.ai/llms.txt). For the REST API, see [openapi.json](https://docs.phonic.ai/openapi.json). For the WebSocket protocol, see [asyncapi.json](https://docs.phonic.ai/asyncapi.json). If an endpoint does not appear in these docs, it doesn't exist, do not invent one.

## Config message

Every conversation begins with a `config` message:

- Minimal `config` message: `{ "type": "config", "agent": "my-cool-agent", "input_format": "pcm_44100", "output_format": "pcm_44100" }` (pick the audio formats that match your use case).
- For prototyping, it is possible to send the config without a named agent by carrying `system_prompt`, `welcome_message`, `voice_id`, `tools`, and more inline (see the config schema in [asyncapi.json](https://docs.phonic.ai/asyncapi.json)). However, for long-term projects we recommend creating an agent to be able to track version changes, reuse the agent config across different conversation mediums, and avoid frequent redeployments.
- Unknown fields and out-of-bounds values are rejected with `{"error": {"message": "Invalid parameters"}}` plus a `param_errors` object naming each offending field — read it, and treat a config rejection as fatal (a reconnect loop must not resend the same config). Field bounds are documented on the docs pages, but the served `asyncapi.json` artifact currently omits constraint keywords (`minimum`/`maximum`/`const`) — a field looking unconstrained in the artifact doesn't mean it is.

## Browser voice

This is the recommended pattern for building Phonic into a browser:

1. Server side, exchange the API key for a session token with the SDK — `client.auth.createSessionToken({ ttl_seconds: 300 })` (`POST /v1/auth/session_token`). The API key stays on the server — in Next.js, never put it in a `NEXT_PUBLIC_*` env var (those are compiled into client code).
2. The browser connects directly to `wss://api.phonic.ai/v1/sts/ws?session_token=<token>` (token in the query string — browsers can't set WebSocket headers). Don't add a relay server in between; the direct connection is the supported, lowest-latency pattern.
3. Send the config message (see [Config message](#config-message) above).
4. Send and receive audio as base64 16-bit PCM `audio_chunk` messages. We recommend to use chunks of ~20ms (chunks longer than 40ms are rejected with error); note mic access requires a secure context — HTTPS or localhost.
5. The client can also send messages during the call: `add_system_message`, `update_tools_subset`, `set_external_id`, `mute` / `unmute`, `generate_reply` (force a turn), and `say` — schemas in [asyncapi.json](https://docs.phonic.ai/asyncapi.json). These enable patterns like pushing app state into the conversation or a button that makes the agent speak. Note that `update_system_prompt` is deprecated; use `add_system_message` instead.
6. Turn lifecycle comes from explicit events: `assistant_started_speaking` / `assistant_finished_speaking` and `user_started_speaking` / `user_finished_speaking`. When building a transcript UI, start a new assistant entry on `assistant_started_speaking`, not on the first audio chunk — trailing `audio_chunk`s (often with empty text) can arrive after `assistant_finished_speaking`, and keying entries on chunks creates ghost transcript items. Interrupts 

Preview of the first 4,000 characters. Read full instructions →