Saperly MCP Integration for AI Agents

List the active phone numbers (lines) provisioned in this workspace.

Fetch one phone number by its Saperly id.

Search available inventory for numbers available to provision, priced for this workspace.

Order a new phone number and add it to this workspace. Charges the prepaid balance. The first number needs no card; provisioning a SECOND number requires a saved payment method on file (otherwise it fails with PaymentMethodRequired).

Release a phone number and stop billing it.

Attach a connection (the handler that answers calls) to a number — i.e. configure the line.

Set (or clear) a line’s alphanumeric SMS sender name — the 1–11 letter/number label recipients see as the “from” on INTERNATIONAL SMS only. US & Canada carriers don’t allow alphanumeric senders, so US/Canada recipients always see the phone number. It is one-way (recipients can’t reply to a name). Pass an empty string or null to clear it (revert to sending from the phone number). A bad value returns InvalidSmsSenderId. Line-reconfiguration, so a number-scoped key is bounded to its allow-list.

Set (or clear) a line’s outbound CALLER ID NAME — the 1–15 letter/number/space display name (CNAM) shown alongside the number on the called party’s phone. Unlike the SMS sender name this is NOT free per-call text: it’s a listing registered to the number, so display is best-effort (the recipient’s carrier decides via a CNAM dip; mainly US & Canada, and it takes time to propagate — many mobile carriers may not show it). Pass an empty string or null to clear it (show the bare number). A bad value returns InvalidCallerIdName. Line-reconfiguration, so a number-scoped key is bounded to its allow-list.

List stock voices and ready private voices. Pass an id as voiceId to create_connection or update_connection. Upload recordings in the dashboard or POST /custom-voices (multipart); private voices are hosted-only.

List this workspace’s private voices and their processing status. Upload recordings through the dashboard or multipart POST /custom-voices. Only active voices can be selected.

List the connections (call/message handlers) configured in this workspace.

Fetch one connection by its Saperly id.

Create a connection. hosted = an in-network AI assistant; manual = your own brain via BYO-LLM.

Update a connection’s name, instructions, compliance/disclosure — or switch its mode between hosted (an in-network AI assistant) and manual (your own brain via BYO-LLM). A mode switch reconciles automatically.

Delete a connection.

Reconcile a connection — create/update its assistant and mint its manual-mode secret.

Dial an outbound call from one of your numbers. The connection answers it.

Fetch one call record by its Saperly id.

List the calls in this workspace.

Blind-transfer a live call to another destination — an E.164 phone number or a sip: URI. A Call Control action (signaling only): the carrier re-bridges the leg to the destination; Saperly never touches the audio (the no-media rule). Works across every backend — hosted, manual, and openai_realtime — because it acts on the call’s bound carrier leg. Returns CallStartFailed if the call has no live leg or the carrier transfer fails.

Speak a line into a live call. NOTE: out-of-band speech injection is not available — the carrier owns the in-network audio loop and only pulls the brain on a caller turn. In manual mode the agent speaks by REPLYING on its turn (the BYO-LLM / agent-as-channel path); Saperly never holds the media path.

Send an SMS from one of your numbers.

List SMS messages in this workspace, optionally filtered to one number.

Summarize calls, messages, and the current balance for this workspace.