Skip to main content
Glama

Wixzel Voice SDKs

npm pub.dev npm MIT

Public source for the packages Wixzel Voice publishes, for building AI agents that place and answer real phone calls over your own SIP trunk.

Package

Registry

Source

wixzel-voice

npm

packages/sdk-ts

wixzel_voice

pub.dev

packages/sdk-dart

wixzel-voice-mcp

npm

apps/mcp

Up to 0.3.0 these were published as wixzel-phone, wixzel_phone and wixzel-phone-mcp. Those versions keep working; each package's changelog says what to change to move across.

The two SDKs cover every /v1 endpoint under one shared method table, page through cursor lists, send idempotency keys on the paths that spend money, retry rate limits honouring Retry-After, and raise errors carrying the API's stable code, request_id and doc_url. The MCP server puts the same surface in front of Claude Code, claude.ai and Claude Desktop.

Running the tests

docs/openapi.json is the API's own OpenAPI document, copied here because each package's coverage test reads it and asserts that every operation has a method and every method names a real operation.

npm install
npm test                       # the TypeScript SDK and the MCP server
cd packages/sdk-dart && dart test

Related MCP server: AgentPhone MCP Server

About this repository

This is a mirror. The packages are developed in the Wixzel Voice monorepo alongside the API they wrap, so that a change to an endpoint and the change to its client land together, and are synced here on release.

Issues and pull requests are welcome and are read. A pull request will be applied upstream and appear here on the next sync rather than merged directly, so it may arrive under a different commit.

Licence

MIT for everything in this repository. Wixzel Voice itself is a hosted service; see voice.wixzel.com for its terms.

Available Tools

56 tools
check_sip_trunk_statusCheck a SIP trunkA
Read-onlyIdempotent
Inspect

Diagnose a trunk: Asterisk's own qualify result and a live network probe, side by side. Where they disagree is the diagnosis. A carrier that ignores unauthenticated OPTIONS shows probe.reachable false while Asterisk reports it healthy; that is normal. Read-only and free. Use this first when calls fail with carrier rejections.

Requires scope sip_trunks:read.

Inputs: id (required).

create_agentCreate an agentAInspect

Create a voice agent. Pick models with list_engines first: an unavailable or mistyped model is rejected with unsupported_model. voice is either a composed pipeline {stt, llm, tts} or a single {realtime} model, never both.

Requires scope agents:write.

Inputs: name (required), voice (required), system_prompt (required), opening_message (required), +4 more.

create_api_keyCreate an API keyAInspect

Mint a new scoped key. The secret is returned ONCE in the result and cannot be retrieved again: hand it to the user immediately and do not log it elsewhere. A key cannot grant scopes the calling key does not hold (scope_escalation). Grant only what the integration needs; billing:write authorises spending money.

Requires scope api_keys:write.

Inputs: name (required), scopes (required), expires_at, spend_limit_micros.

create_appointmentCreate an appointmentBInspect

Book an appointment against a lead and agent.

Requires scope appointments:write.

Inputs: lead_id (required), agent_id (required), date_time (required), phone_number (required), +3 more.

create_campaignCreate a campaignAInspect

Create a campaign that will call every listed lead with an agent. Creating does NOT dial anyone: call start_campaign when the user is ready to spend. Without scheduled_at the campaign is ready to start immediately.

Requires scope campaigns:write.

Inputs: name (required), agent_id (required), lead_ids (required), scheduled_at.

create_knowledge_baseCreate a knowledge baseAInspect

Create a knowledge base of facts and FAQs an agent can draw on during calls.

Requires scope knowledge_bases:write.

Inputs: name (required), faqs, basic_info, other_info, +1 more.

create_leadCreate a leadAInspect

Create one lead. For many at once use import_leads.

Requires scope leads:write.

Inputs: name (required), phone_number (required), tags, fields.

create_phone_numberRegister a phone numberAInspect

Register a number you already own with your carrier, on one of your SIP trunks. Wixzel does not sell numbers. Set inbound_agent_id to have an agent answer calls to it; without it inbound calls are rejected. For inbound to ring at all, the carrier must also be pointed at the trunk's origination_uri (see get_sip_trunk).

Requires scope phone_numbers:write.

Inputs: phone_number (required), sip_trunk_id (required), name, inbound_agent_id.

create_sip_trunkCreate a SIP trunkAInspect

Connect the user's own carrier (Twilio, Telnyx, Plivo, any SIP provider). Wixzel does not resell telephony. After creating, tell the user to allowlist the returned platform_ip with their carrier (for outbound) and to set the carrier's origination URI to origination_uri (for inbound). Then run check_sip_trunk_status.

Requires scope sip_trunks:write.

Inputs: host (required), name (required), port, password, +7 more.

create_topupAdd creditAInspect

Start a top-up. Returns a checkout_url that a HUMAN must open to pay; credit lands once payment settles, not when this returns. Never open the URL or attempt payment yourself. Confirm the amount with the user first.

Requires scope billing:write.

Inputs: amount_usd (required), return_url, idempotency_key.

delete_agentDelete an agentA
DestructiveIdempotent
Inspect

Permanently delete an agent. Phone numbers and campaigns pointing at it stop working. Not reversible.

Requires scope agents:write.

Inputs: id (required).

delete_appointmentDelete an appointmentA
DestructiveIdempotent
Inspect

Permanently delete an appointment. To cancel but keep the record, update its status to canceled instead. Not reversible.

Requires scope appointments:write.

Inputs: id (required).

delete_callDelete a call recordA
DestructiveIdempotent
Inspect

Remove a call log with its transcript and recording, as a caller's erasure request needs. The usage rows that billed it are kept (they carry no content). A call still in progress cannot be deleted; hang it up first. Not reversible.

Requires scope calls:write.

Inputs: id (required).

delete_campaignDelete a campaignA
DestructiveIdempotent
Inspect

Permanently delete a campaign. Pause it first if it is running. Not reversible.

Requires scope campaigns:write.

Inputs: id (required).

delete_knowledge_baseDelete a knowledge baseA
DestructiveIdempotent
Inspect

Permanently delete a knowledge base. Agents referencing it lose that context. Not reversible.

Requires scope knowledge_bases:write.

Inputs: id (required).

delete_leadDelete a leadA
DestructiveIdempotent
Inspect

Permanently delete a lead. Not reversible.

Requires scope leads:write.

Inputs: id (required).

delete_phone_numberDelete a phone numberA
DestructiveIdempotent
Inspect

Remove a phone number from the account. Agents using it as their outbound number can no longer place calls. Not reversible.

Requires scope phone_numbers:write.

Inputs: id (required).

delete_sip_trunkDelete a SIP trunkA
DestructiveIdempotent
Inspect

Remove a SIP trunk. Phone numbers on it can no longer make or take calls. Not reversible.

Requires scope sip_trunks:write.

Inputs: id (required).

get_agentRetrieve an agentA
Read-onlyIdempotent
Inspect

Fetch one agent by id, including its full voice configuration and prompt.

Requires scope agents:read.

Inputs: id (required).

get_appointmentRetrieve an appointmentA
Read-onlyIdempotent
Inspect

Fetch one appointment by id.

Requires scope appointments:read.

Inputs: id (required).

get_balanceRetrieve the balanceA
Read-onlyIdempotent
Inspect

The account's prepaid credit: balance_micros, held_micros (reserved by live calls) and available_micros. Micro-USD: 1,000,000 = $1.00. Check this before placing calls or starting campaigns.

Requires scope billing:read.

Inputs: no named parameters.

get_callRetrieve a callA
Read-onlyIdempotent
Inspect

The full call record: status, duration, cost_micros, recording_url, summary, transcript, transfers, and any provider errors. If the call did not connect, failure_code (a Q.850 cause: 17 busy, 19 no answer, 21 rejected by carrier, 34 congestion, 102 timeout) and failure_reason say what to do about it.

Requires scope calls:read.

Inputs: id (required).

get_call_transcriptRetrieve a call transcriptA
Read-onlyIdempotent
Inspect

Just the transcript of a call, as a list of {role, content, timestamp} turns.

Requires scope calls:read.

Inputs: id (required).

get_campaignRetrieve a campaignA
Read-onlyIdempotent
Inspect

Fetch one campaign by id.

Requires scope campaigns:read.

Inputs: id (required).

get_knowledge_baseRetrieve a knowledge baseA
Read-onlyIdempotent
Inspect

Fetch one knowledge base with its full content.

Requires scope knowledge_bases:read.

Inputs: id (required).

get_leadRetrieve a leadA
Read-onlyIdempotent
Inspect

Fetch one lead by id.

Requires scope leads:read.

Inputs: id (required).

get_phone_numberRetrieve a phone numberA
Read-onlyIdempotent
Inspect

Fetch one phone number record by id.

Requires scope phone_numbers:read.

Inputs: id (required).

get_sip_trunkRetrieve a SIP trunkA
Read-onlyIdempotent
Inspect

Fetch one SIP trunk by id. The password is never returned.

Requires scope sip_trunks:read.

Inputs: id (required).

get_sip_trunk_logsRecent SIP eventsA
Read-onlyIdempotent
Inspect

The SIP engine's recent events for this account: registration, call setup, and carrier rejections with their cause. A live in-memory ring buffer, not an audit trail. Poll with since_id set to the last_id of the previous response to get only new entries.

Requires scope sip_trunks:read.

Inputs: id (required), limit, since_id.

get_usage_summarySummarise usageA
Read-onlyIdempotent
Inspect

Total spend over a period, broken down by component, provider and model. total_micros is micro-USD; total_display is human-readable.

Requires scope usage:read.

Inputs: end, start.

hangup_callEnd a call in progressA
Idempotent
Inspect

Hang up a live call. Billing stops when the call ends. Returns the updated call record.

Requires scope calls:write.

Inputs: id (required).

import_leadsImport many leadsAInspect

Create up to 1,000 leads in one request. Rows are validated individually: malformed rows come back in errors with their index, and the rest are still created. Check failed_count in the result.

Requires scope leads:write.

Inputs: leads (required).

list_agentsList agentsA
Read-onlyIdempotent
Inspect

List the voice agents on this account. Cursor-paginated: pass next_cursor as starting_after for the next page.

Requires scope agents:read.

Inputs: limit, ending_before, starting_after.

list_api_keysList API keysA
Read-onlyIdempotent
Inspect

List the account's API keys with their scopes, spend limits and last use. Secrets are never returned, only a prefix and last four characters.

Requires scope api_keys:read.

Inputs: limit, ending_before, starting_after.

list_appointmentsList appointmentsA
Read-onlyIdempotent
Inspect

List appointments booked by agents or created directly, with status scheduled, completed or canceled.

Requires scope appointments:read.

Inputs: limit, ending_before, starting_after.

list_callsList callsA
Read-onlyIdempotent
Inspect

List calls in summary form (no transcript). Filter by status, direction, agent, campaign, engine, phone number or time window. Use get_call for the full record of one call.

Requires scope calls:read.

Inputs: limit, engine, status, agent_id, +8 more.

list_campaignsList campaignsA
Read-onlyIdempotent
Inspect

List outbound calling campaigns with their status (idle, scheduled, running, completed, stopped, paused) and lead_count.

Requires scope campaigns:read.

Inputs: limit, ending_before, starting_after.

list_enginesList available engines and modelsA
Read-onlyIdempotent
Inspect

What the platform can serve right now, with per-unit prices in micro-USD. Each engine is composed (needs stt + llm + tts models) or realtime (one model). Call this before create_agent rather than guessing model ids: an engine whose provider is degraded disappears from this list before calls start failing. No scope needed beyond a valid key.

Inputs: no named parameters.

list_knowledge_basesList knowledge basesA
Read-onlyIdempotent
Inspect

List knowledge bases. Attach one to an agent with knowledge_base_id on create_agent or update_agent.

Requires scope knowledge_bases:read.

Inputs: limit, ending_before, starting_after.

list_leadsList leadsA
Read-onlyIdempotent
Inspect

List leads (contacts). Filter by tag or free-text search. Cursor-paginated.

Requires scope leads:read.

Inputs: tag, limit, search, ending_before, +1 more.

list_ledger_entriesList ledger entriesA
Read-onlyIdempotent
Inspect

Every movement on the account (topup, usage, refund, adjustment, promo, overage, chargeback), with balance_after_micros. Balances reconcile exactly.

Requires scope billing:read.

Inputs: limit, ending_before, starting_after.

list_phone_numbersList phone numbersA
Read-onlyIdempotent
Inspect

List the phone numbers registered on this account, with the SIP trunk each rides on and the agent (if any) answering inbound calls.

Requires scope phone_numbers:read.

Inputs: limit, ending_before, starting_after.

list_sip_trunksList SIP trunksA
Read-onlyIdempotent
Inspect

List the account's SIP trunks. Each carries platform_ip (allowlist it with the carrier for outbound) and origination_uri (point the carrier at it for inbound).

Requires scope sip_trunks:read.

Inputs: limit, ending_before, starting_after.

list_usage_eventsList usage eventsA
Read-onlyIdempotent
Inspect

Every billable line, itemised. Filter by session_id (from a call record) to see exactly what one call cost and why: the sum of a call's events equals what was debited.

Requires scope usage:read.

Inputs: end, limit, start, component, +3 more.

pause_campaignPause a campaignA
Idempotent
Inspect

Stop placing new calls and hang up any the campaign still has in flight.

Requires scope campaigns:write.

Inputs: id (required).

place_callPlace an outbound callAInspect

Dial a real phone number over the account's SIP trunk and connect the agent. THIS SPENDS MONEY AND MAKES A PHONE RING: confirm with the user before calling it. Credit is reserved up front; an underfunded account is refused with insufficient_credits and nothing is dialled. Returns the call record immediately with status queued or ringing; poll get_call for progress, transcript and cost. Needs an agent (create_agent), a SIP trunk (create_sip_trunk) and a phone number on it (create_phone_number), either as from_number_id or as the agent's outbound_phone_number_id.

Requires scope calls:write.

Inputs: to (required), agent_id (required), lead_id, metadata, +3 more.

revoke_api_keyRevoke an API keyA
DestructiveIdempotent
Inspect

Revoke immediately, with no grace period. Anything still using it starts failing at once, including this MCP server if it is the key in use. Not reversible.

Requires scope api_keys:write.

Inputs: id (required).

rotate_api_keyRotate an API keyAInspect

Issue a replacement secret. The old key keeps working for 24 hours so a deploy can roll over without a gap. The new secret is returned once; hand it to the user immediately.

Requires scope api_keys:write.

Inputs: id (required).

start_campaignStart a campaignAInspect

Begin calling every lead on the campaign. THIS SPENDS MONEY AND MAKES REAL PHONES RING, one call per lead: confirm with the user before calling it. Refused with insufficient_credits when the balance cannot cover the run.

Requires scope campaigns:write.

Inputs: id (required).

test_sip_trunkTest a SIP trunkA
Idempotent
Inspect

Send a TCP connect or unauthenticated SIP OPTIONS to the carrier from the platform and record the outcome on the trunk. Puts traffic on a third party. A negative result is not proof the trunk is broken: many carriers drop unauthenticated probes. Prefer check_sip_trunk_status.

Requires scope sip_trunks:write.

Inputs: id (required).

update_agentUpdate an agentAInspect

Change an agent. Only the fields you send are changed; omit the rest. Sending voice replaces the whole voice object.

Requires scope agents:write.

Inputs: id (required), name, voice, language, +5 more.

update_appointmentUpdate an appointmentAInspect

Reschedule or annotate an appointment. Only the fields you send are changed.

Requires scope appointments:write.

Inputs: id (required), notes, status, lead_id, +5 more.

update_knowledge_baseUpdate a knowledge baseAInspect

Change a knowledge base. Only the fields you send are changed. Sending faqs replaces the whole list.

Requires scope knowledge_bases:write.

Inputs: id (required), faqs, name, basic_info, +2 more.

update_leadUpdate a leadAInspect

Change a lead. Only the fields you send are changed.

Requires scope leads:write.

Inputs: id (required), name, tags, fields, +1 more.

update_phone_numberUpdate a phone numberBInspect

Change a phone number's label, trunk or inbound agent. Only the fields you send are changed.

Requires scope phone_numbers:write.

Inputs: id (required), name, phone_number, sip_trunk_id, +1 more.

update_sip_trunkUpdate a SIP trunkAInspect

Change a SIP trunk. Only the fields you send are changed.

Requires scope sip_trunks:write.

Inputs: id (required), host, name, port, +8 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 56 tools

    Disambiguation4/5

    Tools are organized into clear resource families (agents, calls, leads, campaigns, trunks, numbers, billing) and the verb+resource naming makes most selections obvious. The only mild ambiguities are the SIP diagnostics (check_sip_trunk_status vs test_sip_trunk) and the several billing/usage views, but their descriptions explicitly differentiate them.

    Naming Consistency5/5

    All tools follow a consistent lowercase snake_case verb_noun convention: list_/get_ for reads and create_/update_/delete_ for writes, plus domain verbs like start_, pause_, place_, hangup_, check_, and rotate_. Minor variants like import_leads or create_topup still fit the same predictable pattern.

    Tool Count1/5

    At 56 tools, this is beyond the rubric's 50+ extreme-mismatch threshold and far too large a surface for an agent to navigate efficiently. Although the tools are well structured, this is more like a full REST API than a scoped MCP server.

    Completeness4/5

    Most resources have full CRUD coverage plus domain-specific operations: calls, SIP diagnostics, billing views, API key lifecycle, and bulk lead import. The main gap is the campaign lifecycle: there is no update_campaign, stop_campaign, or explicit resume_campaign, so agents must delete/recreate or improvise with pause/start.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers