# Wixzel Voice - [Wixzel Voice documentation: API, SDKs and MCP server](https://docs.voice.wixzel.com/index.md): Wixzel Voice docs: the voice AI API for building AI agents that place and answer real phone calls over your own SIP trunk, with SDKs and an MCP server. - [Get started with Wixzel Voice: account, key, credit and trunk](https://docs.voice.wixzel.com/get-started.md): Get started with Wixzel Voice: sign up, create an API key, add prepaid credit and connect your own SIP trunk before your agent places its first call. - [Quickstart: place your first AI voice agent phone call with the API](https://docs.voice.wixzel.com/quickstart.md): Four requests from nothing to a ringing phone: connect a SIP trunk, register a number, create an AI voice agent and place a real call with the API. - [Build an AI voice agent with the API: prompt, voice and call handling](https://docs.voice.wixzel.com/agents.md): An agent is a prompt plus a voice engine, with a mascot for its face. Create one with POST /v1/agents or from a website, test it with a real call, and set human transfer. - [Give your voice agent a face: the agent's mascot](https://docs.voice.wixzel.com/mascots.md): Every agent has a mascot, an animated face drawn from a small spec. Change its look, generate one from a website, share it, or draw it in your own web or Flutter app. - [Callers: who called your agent, and blocking them](https://docs.voice.wixzel.com/callers.md): A caller is one person as one agent sees them, across all their calls. List them, look one up, and block or unblock them. - [Give your AI phone agent a knowledge base](https://docs.voice.wixzel.com/knowledge-bases.md): Teach a voice agent about your business: write a knowledge base by hand, draft one from your website or a document, add PDFs and Word files the agent searches during calls, then give it to an agent. An agent generated from a website gets one made for it. - [Give your AI phone agent tools: webhooks and app actions](https://docs.voice.wixzel.com/tools.md): Let a voice agent take actions during a call: a webhook tool calls your server (on phone and web calls), a client tool runs in the caller's app or on your website. Create them with /v1/tools and attach them with tool_ids. - [Clone a voice for your AI phone agent](https://docs.voice.wixzel.com/voice-cloning.md): Make a cloned voice from your own recordings with POST /v1/voices, preview it, and give it to an agent. ElevenLabs clones speak on the classic and Deepgram engines; Sarvam clones speak Indian languages, including Malayalam. - [Put your AI agent on WhatsApp](https://docs.voice.wixzel.com/whatsapp.md): Connect a WhatsApp business number through Meta, let an agent answer its chats and voice notes, and let agents send WhatsApp messages, files, booking confirmations and reminders during and after phone calls. - [Wixzel Voice API keys: scopes, rotation and revocation](https://docs.voice.wixzel.com/api-keys.md): Create scoped Wixzel Voice API keys, rotate them with a 24-hour overlap, revoke them at once, and find the keys that AI clients hold through OAuth. - [Prepaid credits: what an AI phone call costs, billed per second](https://docs.voice.wixzel.com/credits.md): Add prepaid credit from $5, billed per second of actual usage. What an AI phone call costs on each voice engine, and what happens when the credit runs out. - [SIP trunks: connect any carrier to Wixzel Voice](https://docs.voice.wixzel.com/sip-trunks.md): Connect a SIP trunk from Twilio, Telnyx, Plivo, Vonage or any carrier, buy a number on your own carrier account, then fix calls that fail to connect. - [Wixzel Voice SDKs for TypeScript and Dart (Flutter)](https://docs.voice.wixzel.com/sdks.md): The wixzel-voice npm package and the wixzel_voice Dart package cover every endpoint. wixzel-voice/mascot and wixzel_voice_flutter draw an agent's mascot in your app. - [Call the Wixzel Voice API from cURL, Node.js and Python](https://docs.voice.wixzel.com/integrate.md): Place an AI phone call with plain HTTP from cURL, Node.js and Python, build a reusable client, page through usage and pin an API version. No SDK needed. - [Wixzel Voice MCP server: connect Claude Code, Codex, Cursor or any MCP client](https://docs.voice.wixzel.com/mcp-server.md): The Wixzel Voice MCP server lets Claude Code, Codex, Cursor or any MCP client build voice agents and place real phone calls over your own SIP trunk. - [Let a voice agent use other apps' MCP servers during a call](https://docs.voice.wixzel.com/mcp-integrations.md): Connect HubSpot, Cal.com, GoHighLevel, Stripe and 30 other apps, or any remote MCP server, choose which tools are allowed, and attach them to an agent. During a call the agent looks things up and makes changes in those apps. - [Webhooks for AI phone calls: signed events and a delivery log](https://docs.voice.wixzel.com/webhooks.md): Receive a signed webhook when a call arrives, is placed, completes or is transferred. Verify the signature, handle retries, and check whether one fired. - [Realtime API: connect a web or Flutter app to an agent over WebSocket](https://docs.voice.wixzel.com/realtime.md): Put an AI voice agent you build in a web page, a Flutter app or a kiosk over a WebSocket, with no SIP trunk or phone number. Audio is G.711 µ-law at 8 kHz. - [Meetings: send an AI voice agent into Zoom, Google Meet or Teams](https://docs.voice.wixzel.com/meetings.md): Your agent joins a Zoom, Google Meet or Microsoft Teams meeting as a named participant, hears everyone and speaks into the meeting, through your own Attendee account. - [Compose a voice AI pipeline: speech-to-text, LLM and text-to-speech](https://docs.voice.wixzel.com/composing.md): Name the speech-to-text, language model and text-to-speech models yourself, from Deepgram, OpenRouter, ElevenLabs or Sarvam, and see what each costs. - [Self-host Wixzel Voice on your own server](https://docs.voice.wixzel.com/self-hosting.md): A self-host license runs the Wixzel Voice API, MCP server, console and SIP stack on your server, with your own provider keys and no orchestration fee. - [Twilio Elastic SIP Trunking: console steps for Wixzel Voice](https://docs.voice.wixzel.com/carriers/twilio.md): Connect Twilio Elastic SIP Trunking to Wixzel Voice for AI phone calls: allowlist the platform IP, set the Origination URI, and use a Twilio caller ID. - [Telnyx SIP Connection: console steps for Wixzel Voice](https://docs.voice.wixzel.com/carriers/telnyx.md): Connect a Telnyx SIP Connection to Wixzel Voice for AI phone calls: IP authentication, the platform IP under Outbound, an inbound region and a transport. - [Plivo Zentrunk: console steps for Wixzel Voice](https://docs.voice.wixzel.com/carriers/plivo.md): Connect Plivo Zentrunk to Wixzel Voice for AI phone calls: an outbound trunk with an IP ACL, and an inbound trunk whose Primary URI points at Wixzel Voice. - [Vonage Programmable SIP: console steps for Wixzel Voice](https://docs.voice.wixzel.com/carriers/vonage.md): Connect a Vonage Programmable SIP trunk to Wixzel Voice for AI phone calls: the SIP Dashboard's outbound and inbound settings, and the ACL entry to add. - [Bandwidth SIP trunk: console steps for Wixzel Voice](https://docs.voice.wixzel.com/carriers/bandwidth.md): Connect a Bandwidth SIP trunk to Wixzel Voice for AI phone calls: the platform IP on a location, termination and origination, or SIP credentials instead. - [Exotel vSIP trunk: console steps for Wixzel Voice](https://docs.voice.wixzel.com/carriers/exotel.md): Connect Exotel Virtual SIP Trunking (vSIP) to Wixzel Voice for AI calls on Indian numbers: TCP transport, the IP whitelist and the Destination URI. - [Vobiz SIP trunk: console steps for Wixzel Voice](https://docs.voice.wixzel.com/carriers/vobiz.md): Connect a Vobiz SIP trunk to Wixzel Voice for AI phone calls: the per-trunk SIP domain as host, IP ACL or credentials, and what Vobiz calls origination. - [Mobily SIP trunk: setup for Wixzel Voice](https://docs.voice.wixzel.com/carriers/mobily.md): Connect a Mobily SIP Trunk in Saudi Arabia to Wixzel Voice for AI phone calls: your SBC on the Mobily link, the platform IP, G.711 A-law and the inbound route. - [Voice engines: STT, LLM and TTS pipelines or one realtime model](https://docs.voice.wixzel.com/voice-engines.md): Every voice engine behind one API key: compose speech-to-text, a language model and text-to-speech, or hand the whole turn to one realtime voice model. - [Wixzel Voice billing: per-second metering, itemised usage](https://docs.voice.wixzel.com/billing.md): How Wixzel Voice reserves credit before a call, meters it per second of actual usage, freezes prices per call, and itemises every charge in usage events. - [Authenticate to the Wixzel Voice API with scoped bearer keys](https://docs.voice.wixzel.com/authentication.md): Send a scoped API key as a bearer token, tell live from test keys, rotate without downtime, pin an API version, and see where OAuth fits for MCP clients. - [Wixzel Voice API errors: types, codes and request ids](https://docs.voice.wixzel.com/errors.md): Every Wixzel Voice API error carries a type, a stable machine-readable code and a request id. Match on the code, not the message, and see the notable ones. - [Pagination: walking list endpoints with cursors](https://docs.voice.wixzel.com/pagination.md): Every Wixzel Voice list endpoint returns the same cursor envelope. How to walk the pages, why cursors are opaque, and why the API has no offset parameter. - [Idempotency keys: retry an AI phone call without paying twice](https://docs.voice.wixzel.com/idempotency.md): Wixzel Voice requires an Idempotency-Key on calls, test calls, number purchases and top-ups, so a retry after a network timeout never places a second call or charges twice. - [Wixzel Voice rate limits and concurrent call limits](https://docs.voice.wixzel.com/rate-limits.md): Wixzel Voice allows 10 requests per second per API key with a burst of 20, and 5 concurrent calls per account by default. What the rate-limit headers mean. - [List agents](https://docs.voice.wixzel.com/api-reference/agents/list-agents.md): Cursor-paginated. Requires `agents:read`. - [Create an agent](https://docs.voice.wixzel.com/api-reference/agents/create-an-agent.md): Requires `agents:write`. - [Retrieve an agent](https://docs.voice.wixzel.com/api-reference/agents/retrieve-an-agent.md) - [Delete an agent](https://docs.voice.wixzel.com/api-reference/agents/delete-an-agent.md) - [Update an agent](https://docs.voice.wixzel.com/api-reference/agents/update-an-agent.md): Only the fields you send are changed. - [Place a test call](https://docs.voice.wixzel.com/api-reference/agents/place-a-test-call.md): Ring a number and have the agent speak one phrase, then hang up. A probe rather than a conversation: it answers "is my trunk configured and does this agent sound right" in a few seconds, without anyone having to hold a conversation with it. For a real conversation use POST /v1/calls. - [Generate an agent](https://docs.voice.wixzel.com/api-reference/agents/generate-an-agent.md): Makes an agent from a `website_url` (its pages become the agent's knowledge base, its colour and tone the mascot), a `description`, or both, and the `role` it plays. Answers at once with the agent, whose `mascot.status` is `building`; it can already talk, with a generic prompt. Poll `GET /v1/agents/… - [Update an agent's mascot](https://docs.voice.wixzel.com/api-reference/agents/update-an-agents-mascot.md): Replace its look with an edited spec (normalised like a new one), change its speech bubble, or change `sharing`. Turning on the share link or the website widget lets anyone talk to the agent on your credit, within the caps in `sharing`, so `sharing` also needs `calls:write`. Requires `agents:write`. - [Generate a new mascot look](https://docs.voice.wixzel.com/api-reference/agents/generate-a-new-mascot-look.md): A new look for the agent's mascot from a `website_url`, a `description`, or both; send neither for a random one. The agent's prompt never changes. Its knowledge base is rewritten from the website only with `refresh_knowledge`, and one is made from the website only if it has none. Answers at once wit… - [Change a mascot's share id](https://docs.voice.wixzel.com/api-reference/agents/change-a-mascots-share-id.md): Gives the agent's mascot a new `public_id`. Its old share link and embed code stop working at once. Requires `agents:write` and `calls:write`. - [Create a realtime session](https://docs.voice.wixzel.com/api-reference/realtime/create-a-realtime-session.md): Mint a one-minute, single-use `client_secret` that lets a browser or app talk to one of your agents over `wss://api.voice.wixzel.com/v1/realtime` — no SIP trunk, no phone number. Call this from your server; the API key must never reach the client. - [List leads](https://docs.voice.wixzel.com/api-reference/leads/list-leads.md): Cursor-paginated. Requires `leads:read`. - [Create a lead](https://docs.voice.wixzel.com/api-reference/leads/create-a-lead.md): Requires `leads:write`. - [Retrieve a lead](https://docs.voice.wixzel.com/api-reference/leads/retrieve-a-lead.md) - [Delete a lead](https://docs.voice.wixzel.com/api-reference/leads/delete-a-lead.md) - [Update a lead](https://docs.voice.wixzel.com/api-reference/leads/update-a-lead.md): Only the fields you send are changed. - [Import many leads](https://docs.voice.wixzel.com/api-reference/leads/import-many-leads.md): Creates up to 1,000 leads in one request. Rows are validated individually and partial success is the contract: a malformed row is reported in `errors` with its index, and the rest are still created. Synchronous, which is why the array is bounded — larger imports belong in a job rather than a request… - [Start a campaign](https://docs.voice.wixzel.com/api-reference/campaigns/start-a-campaign.md): Begins calling every lead on the campaign. Separate from creating one on purpose: starting spends money on each lead, and that should never be a side effect of the request that also built it. Returns 402 when the balance cannot cover the run. - [Pause a campaign](https://docs.voice.wixzel.com/api-reference/campaigns/pause-a-campaign.md): Stops placing new calls and hangs up any the campaign still has in flight. - [List campaigns](https://docs.voice.wixzel.com/api-reference/campaigns/list-campaigns.md): Cursor-paginated. Requires `campaigns:read`. - [Create a campaign](https://docs.voice.wixzel.com/api-reference/campaigns/create-a-campaign.md): Requires `campaigns:write`. - [Retrieve a campaign](https://docs.voice.wixzel.com/api-reference/campaigns/retrieve-a-campaign.md) - [Delete a campaign](https://docs.voice.wixzel.com/api-reference/campaigns/delete-a-campaign.md) - [List knowledge bases](https://docs.voice.wixzel.com/api-reference/knowledge-bases/list-knowledge-bases.md): Cursor-paginated. Requires `knowledge_bases:read`. - [Create a knowledge base](https://docs.voice.wixzel.com/api-reference/knowledge-bases/create-a-knowledge-base.md): Requires `knowledge_bases:write`. - [Retrieve a knowledge base](https://docs.voice.wixzel.com/api-reference/knowledge-bases/retrieve-a-knowledge-base.md) - [Delete a knowledge base](https://docs.voice.wixzel.com/api-reference/knowledge-bases/delete-a-knowledge-base.md) - [Update a knowledge base](https://docs.voice.wixzel.com/api-reference/knowledge-bases/update-a-knowledge-base.md): Only the fields you send are changed. - [Draft a knowledge base from a website](https://docs.voice.wixzel.com/api-reference/knowledge-bases/draft-a-knowledge-base-from-a-website.md): Reads a website (its home page and up to three linked pages) and writes a draft: what the business is and does, up to 15 questions callers ask with their answers, and other facts such as prices and policies. Nothing is saved; review the draft, then create it with `POST /v1/knowledge-bases`. Takes 10… - [Draft a knowledge base from a file](https://docs.voice.wixzel.com/api-reference/knowledge-bases/draft-a-knowledge-base-from-a-file.md): Reads one document (PDF, DOCX, TXT, MD, CSV or HTML, up to 10 MB), uploaded as multipart `file` or fetched from JSON `{ url }`, and writes a draft of the three fields, like the website import. Nothing is saved. To make a whole document searchable instead, add it to a knowledge base with `POST /v1/kn… - [List a knowledge base’s files](https://docs.voice.wixzel.com/api-reference/knowledge-bases/list-a-knowledge-base’s-files.md): Newest first, with each one’s status. Requires `knowledge_bases:read`. - [Add files to a knowledge base](https://docs.voice.wixzel.com/api-reference/knowledge-bases/add-files-to-a-knowledge-base.md): Upload up to 5 documents as multipart `files`, or send JSON `{ url }` to fetch one. Each comes back `processing`; it is read in the background (usually seconds) and becomes `ready`, after which agents using this knowledge base can search it during calls with the built-in `search_knowledge` tool. The… - [Retrieve a knowledge base file](https://docs.voice.wixzel.com/api-reference/knowledge-bases/retrieve-a-knowledge-base-file.md): Poll this until `status` is `ready` or `failed`. Requires `knowledge_bases:read`. - [Remove a knowledge base file](https://docs.voice.wixzel.com/api-reference/knowledge-bases/remove-a-knowledge-base-file.md): Removes the file and its passages; agents stop finding what was in it. Requires `knowledge_bases:write`. - [List phone numbers](https://docs.voice.wixzel.com/api-reference/phone-numbers/list-phone-numbers.md): Cursor-paginated. Requires `phone_numbers:read`. - [Create a phone number](https://docs.voice.wixzel.com/api-reference/phone-numbers/create-a-phone-number.md): Requires `phone_numbers:write`. - [Retrieve a phone number](https://docs.voice.wixzel.com/api-reference/phone-numbers/retrieve-a-phone-number.md) - [Delete a phone number](https://docs.voice.wixzel.com/api-reference/phone-numbers/delete-a-phone-number.md) - [Update a phone number](https://docs.voice.wixzel.com/api-reference/phone-numbers/update-a-phone-number.md): Only the fields you send are changed. - [List the numbers on a carrier account](https://docs.voice.wixzel.com/api-reference/phone-numbers/list-the-numbers-on-a-carrier-account.md): Every number on the carrier account behind this trunk, marked with whether the carrier already sends its calls here (`attached`) and whether it is registered with Wixzel Voice. Register one with `POST /v1/phone-numbers`; on this kind of trunk that also points it at us at the carrier. A trunk added b… - [Search for numbers to buy](https://docs.voice.wixzel.com/api-reference/phone-numbers/search-for-numbers-to-buy.md): Numbers the trunk's carrier will sell, with the carrier's own prices in its own currency. Searching is free and changes nothing. Supported on Twilio, Telnyx, Plivo, Vobiz and Vonage (`can_buy_numbers` on the trunk says so); other carriers answer `400 carrier_cannot_buy`. Requires `phone_numbers:read… - [Buy a number](https://docs.voice.wixzel.com/api-reference/phone-numbers/buy-a-number.md): Buys the number on the customer's own carrier account, points it at the trunk, and registers it, with `inbound_agent_id` answering it. **The carrier charges that account** at its own price; Wixzel Voice sells no numbers and adds nothing. Confirm the number and the price with the person before callin… - [List sip trunks](https://docs.voice.wixzel.com/api-reference/sip-trunks/list-sip-trunks.md): Cursor-paginated. Requires `sip_trunks:read`. - [Create a SIP trunk](https://docs.voice.wixzel.com/api-reference/sip-trunks/create-a-sip-trunk.md): Requires `sip_trunks:write`. - [Retrieve a SIP trunk](https://docs.voice.wixzel.com/api-reference/sip-trunks/retrieve-a-sip-trunk.md) - [Delete a SIP trunk](https://docs.voice.wixzel.com/api-reference/sip-trunks/delete-a-sip-trunk.md) - [Update a SIP trunk](https://docs.voice.wixzel.com/api-reference/sip-trunks/update-a-sip-trunk.md): Only the fields you send are changed. - [Check a SIP trunk](https://docs.voice.wixzel.com/api-reference/sip-trunks/check-a-sip-trunk.md): Asterisk's own qualify result and a live network probe, reported side by side rather than reduced to one boolean, because where they disagree IS the diagnosis. A provider that ignores unauthenticated OPTIONS shows `probe.reachable: false` while Asterisk reports it healthy — that is normal and Asteri… - [Test a SIP trunk](https://docs.voice.wixzel.com/api-reference/sip-trunks/test-a-sip-trunk.md): Sends a TCP connect or an unauthenticated SIP OPTIONS to the provider from this server and records the outcome on the trunk. A write scope because it mutates `last_tested_at` and puts traffic on a third party. A negative result is not proof the trunk is broken — plenty of carriers drop unauthenticat… - [Recent SIP events](https://docs.voice.wixzel.com/api-reference/sip-trunks/recent-sip-events.md): The SIP engine's recent events for your account — registration, call setup, and carrier rejections with their cause. An in-memory ring buffer, so it is a live diagnostic rather than an audit trail: it does not survive a restart and old entries fall off. Poll with `since_id` set to the `last_id` of y… - [List mcp servers](https://docs.voice.wixzel.com/api-reference/mcp-servers/list-mcp-servers.md): Cursor-paginated. Requires `mcp_servers:read`. - [Create an MCP server](https://docs.voice.wixzel.com/api-reference/mcp-servers/create-an-mcp-server.md): Requires `mcp_servers:write`. - [Retrieve an MCP server](https://docs.voice.wixzel.com/api-reference/mcp-servers/retrieve-an-mcp-server.md) - [Delete an MCP server](https://docs.voice.wixzel.com/api-reference/mcp-servers/delete-an-mcp-server.md) - [Update an MCP server](https://docs.voice.wixzel.com/api-reference/mcp-servers/update-an-mcp-server.md): Only the fields you send are changed. - [Refresh an MCP server’s tools](https://docs.voice.wixzel.com/api-reference/mcp-servers/refresh-an-mcp-server’s-tools.md): Connects to the server and reads its tools again. Answers 200 even when the server cannot be reached: `status` and `last_error` are the result. Tools the server no longer offers are removed from the allowlist. Requires `mcp_servers:write`. - [Connect an OAuth MCP server](https://docs.voice.wixzel.com/api-reference/mcp-servers/connect-an-oauth-mcp-server.md): Starts signing in to a server whose `auth.type` is `oauth`. Open `authorization_url` in a browser; when the provider sends the browser back, the server is connected and its tools are read. The link is single-use and expires after ten minutes. Any stored sign-in is replaced. Requires `mcp_servers:wri… - [List tools](https://docs.voice.wixzel.com/api-reference/tools/list-tools.md): Cursor-paginated. Requires `tools:read`. - [Create a tool](https://docs.voice.wixzel.com/api-reference/tools/create-a-tool.md): Requires `tools:write`. - [Retrieve a tool](https://docs.voice.wixzel.com/api-reference/tools/retrieve-a-tool.md) - [Delete a tool](https://docs.voice.wixzel.com/api-reference/tools/delete-a-tool.md) - [Update a tool](https://docs.voice.wixzel.com/api-reference/tools/update-a-tool.md): Only the fields you send are changed. - [Test a webhook tool](https://docs.voice.wixzel.com/api-reference/tools/test-a-webhook-tool.md): Runs a webhook tool once with the arguments you give and answers with what the agent would hear. The request is exactly what a call sends, signature included, with `X-Wixzel-Call-Id: test`. Client tools run in your app, so they are tested from a call instead. Requires `tools:write`. - [List voices](https://docs.voice.wixzel.com/api-reference/voices/list-voices.md): Your cloned voices. Cursor-paginated. Requires `voices:read`. - [Clone a voice](https://docs.voice.wixzel.com/api-reference/voices/clone-a-voice.md): Makes a cloned voice from recordings of one person speaking, and charges the one-off fee in the price book (`voice_clone`). `consent` must be `true`. Send the recordings as `files` in a multipart request, or as `audio_urls` in JSON. The recordings are passed to the provider and not stored. Put the r… - [Retrieve a voice](https://docs.voice.wixzel.com/api-reference/voices/retrieve-a-voice.md): Requires `voices:read`. - [Delete a voice](https://docs.voice.wixzel.com/api-reference/voices/delete-a-voice.md): Deletes the clone at the provider too. Refused with 409 `voice_in_use` while an agent speaks in it. The cloning fee is not refunded. Requires `voices:write`. - [Update a voice](https://docs.voice.wixzel.com/api-reference/voices/update-a-voice.md): Rename it or change its description. Only the fields you send are changed. Requires `voices:write`. - [Preview a voice](https://docs.voice.wixzel.com/api-reference/voices/preview-a-voice.md): The voice saying a short line, as mp3. Made the first time it is asked for in a language and kept after that. Not charged. Requires `voices:read`. - [List appointments](https://docs.voice.wixzel.com/api-reference/appointments/list-appointments.md): Cursor-paginated. Requires `appointments:read`. - [Create an appointment](https://docs.voice.wixzel.com/api-reference/appointments/create-an-appointment.md): Requires `appointments:write`. - [Retrieve an appointment](https://docs.voice.wixzel.com/api-reference/appointments/retrieve-an-appointment.md) - [Delete an appointment](https://docs.voice.wixzel.com/api-reference/appointments/delete-an-appointment.md) - [Update an appointment](https://docs.voice.wixzel.com/api-reference/appointments/update-an-appointment.md): Only the fields you send are changed. - [List callers](https://docs.voice.wixzel.com/api-reference/callers/list-callers.md): Who has called your agents, newest first, one per person per agent: by Google sign-in, app account, phone number or browser. Filter by `agent_id`, or `blocked=true` for an agent's blocklist. Cursor-paginated. Requires `calls:read`. - [Retrieve a caller](https://docs.voice.wixzel.com/api-reference/callers/retrieve-a-caller.md): Their latest location and platform, and how many calls they made. Their calls: `GET /v1/calls?caller_id=`. Requires `calls:read`. - [Block or unblock a caller](https://docs.voice.wixzel.com/api-reference/callers/block-or-unblock-a-caller.md): A blocked caller cannot call that agent again: not from its share link, its website widget, the app, or by phone. They are told only that they cannot call. Requires `calls:write`. - [List calls](https://docs.voice.wixzel.com/api-reference/calls/list-calls.md) - [Place a call](https://docs.voice.wixzel.com/api-reference/calls/place-a-call.md): Dials over your SIP trunk and connects the agent. Credit is reserved before the call is placed; an underfunded account is refused with `402` and no resources are allocated. - [Retrieve a call](https://docs.voice.wixzel.com/api-reference/calls/retrieve-a-call.md): Returns the full record, including the transcript, the recording, and any provider errors recorded while the call was running. The list endpoint returns the summary shape instead — a transcript on every row of a page is megabytes nobody asked for. When a call did not connect, `failure_code` and `fai… - [Delete a call record](https://docs.voice.wixzel.com/api-reference/calls/delete-a-call-record.md): Removes the call log, its transcript and its recording — what a caller's erasure request needs. The usage rows that billed the call are kept: they carry components and quantities, never content, and the ledger has to keep adding up. A call still in progress cannot be deleted; hang it up first. - [Retrieve a transcript](https://docs.voice.wixzel.com/api-reference/calls/retrieve-a-transcript.md) - [End a call in progress](https://docs.voice.wixzel.com/api-reference/calls/end-a-call-in-progress.md) - [List usage events](https://docs.voice.wixzel.com/api-reference/usage/list-usage-events.md): Every billable line, itemised. Filter by `session_id` to see exactly what one call cost and why — the sum of a call's events always equals what was debited. - [Summarise usage](https://docs.voice.wixzel.com/api-reference/usage/summarise-usage.md) - [Retrieve your balance](https://docs.voice.wixzel.com/api-reference/billing/retrieve-your-balance.md) - [List ledger entries](https://docs.voice.wixzel.com/api-reference/billing/list-ledger-entries.md): Every movement on the account, oldest cursor first. Balances reconcile exactly. - [Add credit](https://docs.voice.wixzel.com/api-reference/billing/add-credit.md): Returns a checkout URL. Credit lands once payment settles, not when this returns. - [List API keys](https://docs.voice.wixzel.com/api-reference/api-keys/list-api-keys.md): Secrets are never returned — only a prefix and last four characters. - [Create an API key](https://docs.voice.wixzel.com/api-reference/api-keys/create-an-api-key.md): The secret is returned **once**. It cannot be retrieved again. - [Rotate an API key](https://docs.voice.wixzel.com/api-reference/api-keys/rotate-an-api-key.md): Issues a replacement and keeps the old key working for 24 hours, so a deploy can roll out without a window where neither key is valid. - [Revoke an API key](https://docs.voice.wixzel.com/api-reference/api-keys/revoke-an-api-key.md): Immediate. In-flight requests using it will fail. - [List available engines and models](https://docs.voice.wixzel.com/api-reference/engines/list-available-engines-and-models.md): What the platform can actually serve right now, with per-unit prices. Use this rather than hardcoding model ids: an engine whose provider is degraded disappears from this list before calls start failing. - [List an engine's languages](https://docs.voice.wixzel.com/api-reference/engines/list-an-engines-languages.md): Which languages an engine can hold a conversation in. A composed engine lists a language only when both its speech-to-text and its text-to-speech serve it — one that is transcribed but cannot be spoken back is not a language the engine supports end to end. Use a `code` from here as the agent's `lang… - [List an engine's speaker voices](https://docs.voice.wixzel.com/api-reference/engines/list-an-engines-speaker-voices.md): The voices an engine can speak as. Use an `id` from here as `voice.tts.voice` (composed engines) or `voice.realtime.voice` (realtime engines). Sarvam and Gemini publish fixed rosters; the ElevenLabs-backed engines are fetched and cached for an hour, and if ElevenLabs cannot be reached the last good… - [Retrieve the webhook endpoint](https://docs.voice.wixzel.com/api-reference/webhooks/retrieve-the-webhook-endpoint.md): One endpoint per account. Returns null for `url` until you set one, and never returns the signing secret — only whether one exists. Requires `webhooks:read`. - [Update the webhook endpoint](https://docs.voice.wixzel.com/api-reference/webhooks/update-the-webhook-endpoint.md): Only the fields you send are changed, except `events`, which replaces the subscription entirely. The URL must resolve to a public address — one pointing at loopback, link-local or private space is refused here and again at delivery time. Enabling without a URL is refused rather than saved. Requires… - [Rotate the signing secret](https://docs.voice.wixzel.com/api-reference/webhooks/rotate-the-signing-secret.md): Mints a new signing secret and returns it once. The old secret stops verifying immediately, so your receiver will reject events until it has the new one — rotate deliberately, not as part of a routine update. Requires `webhooks:write`. - [Send a test event](https://docs.voice.wixzel.com/api-reference/webhooks/send-a-test-event.md): POSTs one sample payload to your URL right now and hands back what came back. It goes through the same delivery path as a real event — same headers, same signature, and it is recorded in the delivery list — but it deliberately ignores `enabled` and your event subscription, because the question it an… - [List delivery attempts](https://docs.voice.wixzel.com/api-reference/webhooks/list-delivery-attempts.md): One record per POST we made, newest first — so an event delivered on its third try is three records and a flapping receiver is visible as such. `response_status` is null when nothing answered at all, which is what separates "never arrived" from "arrived and your handler threw". Cursor-paginated. Req… - [List WhatsApp numbers](https://docs.voice.wixzel.com/api-reference/whatsapp/list-whatsapp-numbers.md): The WhatsApp business numbers connected to this account. Cursor-paginated. Requires `whatsapp:read`. - [Connect a WhatsApp number](https://docs.voice.wixzel.com/api-reference/whatsapp/connect-a-whatsapp-number.md): Connect a number with a token from your own Meta app (WhatsApp > API Setup): its phone number id, its WhatsApp Business Account id, a permanent access token and the app secret. The number is checked with Meta, and your app is subscribed to its webhooks. - [Retrieve a WhatsApp number](https://docs.voice.wixzel.com/api-reference/whatsapp/retrieve-a-whatsapp-number.md): Requires `whatsapp:read`. - [Disconnect a WhatsApp number](https://docs.voice.wixzel.com/api-reference/whatsapp/disconnect-a-whatsapp-number.md): Stops Wixzel Voice using the number: its webhooks are unsubscribed, agents sending from it stop, and the chats, contacts and scheduled messages Wixzel Voice kept for it are deleted. The number itself stays yours in WhatsApp Manager. Requires `whatsapp:write`. - [Update a WhatsApp number](https://docs.voice.wixzel.com/api-reference/whatsapp/update-a-whatsapp-number.md): Change which agent answers it (`inbound_agent_id`, or null for none) and how. Only the fields you send change. Requires `whatsapp:write`. - [Refresh a WhatsApp number](https://docs.voice.wixzel.com/api-reference/whatsapp/refresh-a-whatsapp-number.md): Read the number’s name, quality rating and messaging limit from Meta again, and subscribe to its webhooks again. Requires `whatsapp:write`. - [List message templates](https://docs.voice.wixzel.com/api-reference/whatsapp/list-message-templates.md): A number’s message templates, as last synced from WhatsApp Manager. Templates are written and approved there; only `APPROVED` ones can be sent. Requires `whatsapp:read`. - [Create a message template](https://docs.voice.wixzel.com/api-reference/whatsapp/create-a-message-template.md): Write a template and submit it to Meta for review. It starts `PENDING`; Meta approves or rejects it, usually within minutes, and the status updates by itself. Only an `APPROVED` template can be sent. Number the body’s values `{{1}}`, `{{2}}`, … and give one example value for each. Requires `whatsapp… - [Sync message templates](https://docs.voice.wixzel.com/api-reference/whatsapp/sync-message-templates.md): Copy the number’s templates from WhatsApp Manager now. Status changes also arrive by webhook. Requires `whatsapp:write`. - [Delete a message template](https://docs.voice.wixzel.com/api-reference/whatsapp/delete-a-message-template.md): Delete one template, in one language, from WhatsApp Manager and from Wixzel Voice. Agents that name it stop finding it. Requires `whatsapp:write`. - [Send a WhatsApp message](https://docs.voice.wixzel.com/api-reference/whatsapp/send-a-whatsapp-message.md): Send one message from a connected number: `text`, a knowledge-base file (`knowledge_file_id`), or an approved `template`. Text and files can only be sent within 24 hours of the person’s last message to the number; outside that window, send a template. Set `send_at` to schedule it instead. - [List WhatsApp conversations](https://docs.voice.wixzel.com/api-reference/whatsapp/list-whatsapp-conversations.md): Chats agents have had on your numbers, newest first. Cursor-paginated. Requires `whatsapp:read`. - [Retrieve a WhatsApp conversation](https://docs.voice.wixzel.com/api-reference/whatsapp/retrieve-a-whatsapp-conversation.md): One conversation with its messages, oldest first, and what it cost. Requires `whatsapp:read`. - [List scheduled WhatsApp messages](https://docs.voice.wixzel.com/api-reference/whatsapp/list-scheduled-whatsapp-messages.md): Reminders, follow-ups and scheduled sends, newest first. Cursor-paginated. Requires `whatsapp:read`. - [Cancel a scheduled WhatsApp message](https://docs.voice.wixzel.com/api-reference/whatsapp/cancel-a-scheduled-whatsapp-message.md): Only a message that has not started sending can be canceled. Requires `whatsapp:write`. - [Retrieve the meeting integration](https://docs.voice.wixzel.com/api-reference/meetings/retrieve-the-meeting-integration.md): Your Attendee connection: its URL, the last four characters of the key, and whether a webhook secret is stored. 404 until one is connected. Requires `calls:read`. - [Connect Attendee](https://docs.voice.wixzel.com/api-reference/meetings/connect-attendee.md): Store the Attendee account your agents join meetings through: `https://app.attendee.dev` with a key from your project there, or your own Attendee install. The key is checked against Attendee first and stored encrypted; it is never returned. Calling this again replaces what is stored. - [Disconnect Attendee](https://docs.voice.wixzel.com/api-reference/meetings/disconnect-attendee.md): Forget the stored Attendee URL and key. Meetings already running carry on. Requires `calls:write`. - [List meetings](https://docs.voice.wixzel.com/api-reference/meetings/list-meetings.md): Meetings your agents were sent to, newest first. Cursor-paginated. Requires `calls:read`. - [Send an agent to a meeting](https://docs.voice.wixzel.com/api-reference/meetings/send-an-agent-to-a-meeting.md): Your agent joins a Zoom, Google Meet or Microsoft Teams meeting as a named participant, through your Attendee account (connect it first with POST /v1/meetings/integration). It hears everyone and speaks into the meeting, with the same voice, tools and knowledge as on a call. - [Retrieve a meeting](https://docs.voice.wixzel.com/api-reference/meetings/retrieve-a-meeting.md): Where the bot is (joining, waiting room, in the meeting) or how it ended. The transcript is on GET /v1/calls/{id}. Requires `calls:read`. - [Leave a meeting](https://docs.voice.wixzel.com/api-reference/meetings/leave-a-meeting.md): The agent leaves now. A bot still joining or waiting is called off. A meeting that already ended is returned as it is. Requires `calls:write`. ## OpenAPI Specs - [openapi](/openapi.json) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.