Sphoro Voice documentation
Place automated voice calls from your own software. An agent answers or dials, holds the conversation in the language you choose, and reports back when it is done. It is a plain JSON API over HTTPS — if your language can make an HTTP request, you are ready.
The whole setup, in six steps
Do them in order. Each page picks up exactly where the last one left off, and every command on every page is complete — paste it and run it.
Get an API key
Create your first API key in the portal, choose the role it carries, and store it where it cannot leak.
2Use your API key
The base URL, the Authorization header, a first request that proves the key works, and every error the API can answer with.
3Make a call
Create an agent, place a call to a phone number, follow it live, and read the transcript and recording afterwards.
4Language and voice
Every language an agent can speak, how to set it per agent or per call, and the voice, speed and pitch that carry it.
5Webhooks
Receive signed, retried events when a call starts, ends or fails — with verification code you can paste in.
6Talk from a browser
Put the agent on your website or in your app: mint a call token on your server, drop in the widget or the SDK, and never ship an API key to a page.
How it works
What the pieces are and what happens on a call. Read after step 3, when every word below names something you have watched happen.
Platform concepts
The objects the platform is made of — agent, persona, call, knowledge base, flow, journey, project — and which one owns what.
Kinds of agent
Four modes an agent can run in: a conversation, a keypad menu, a plain forwarding line, and a browser-to-browser call. How to pick one.
How a call runs
Everything between your request and the finished record: dialling, answer, the turn loop, barge-in, hang-up, and the analysis afterwards.
Latency
Where the time in a spoken reply goes, the budget each stage gets, what we measure per call, and the settings that actually move the number.
Glossary
Every term this documentation uses that does not mean the obvious thing, defined once, in one place.
Building an agent
The six steps take an afternoon. This is the part you are in for the weeks afterwards — the prompt, the tools it can call, the documents it answers from, and what gets written down when the call ends.
Agent reference
Every field an agent accepts, what it changes, and what it defaults to — the whole configuration surface in one table.
Writing the prompt
How to write a system prompt that survives a real phone call: structure, length, refusals, numbers read aloud, and the failures to write against.
Variables
Put your own data into a call with call_variables, and the eight variables the platform fills in for you — dates, times and the caller's number.
Conversation behaviour
Barge-in, how long a silence runs before the agent speaks, maximum call duration, and what to do when an answering machine picks up.
Knowledge base
Ground answers in your own documents: ingest text, files and URLs, attach a base to an agent, and check what it retrieves before a caller does.
Tools and functions
Let the agent call your API mid-conversation: the built-in tools, defining your own, argument validation, and what the caller hears while it runs.
Conversation flows
For conversations one prompt cannot hold: nodes the call moves between, the four kinds of edge that move it, and variables captured on the way.
Keypad and IVR
Press-1 menus that answer in milliseconds without a model, in-band and signalled digits, and how a menu hands over to a conversation.
Personas
The idea an agent deploys — prompt, voice, knowledge, flow — kept apart from the telephone, so one idea can run a line, a campaign and a widget.
Agent groups
Settings shared across a fleet of agents: what a group holds, why joining one changes nothing on its own, and how defaults are adopted.
Agent templates
Start from a working agent instead of an empty one. Every template we ship, what each is for, and how to create one and then change it.
Voice lines
Fixed lines rendered once and replayed instead of synthesised on every call — cheaper, instant, and the place to upload your own recordings.
Post-call analysis
The summary and the typed fields written onto every finished call, how to write an extraction that answers reliably, and how to test one.
Telephony
Numbers, carriers, and what happens at the two edges of a call.
Numbers and carriers
The carriers this platform dials through, how a number is attached to an agent, caller ID, and what each carrier does and does not support.
Receiving calls
Point a number at an agent, ring before you answer, identify or block the caller, and route a call to a person instead.
Placing calls
One call, a list of calls, retries that respect the do-not-call list, and the pacing that stops a campaign melting your carrier.
Transfers and endings
Hand a live call to a person or another number, end one deliberately, and read the end reason that says which of nine ways it finished.
Concurrency
How many calls run at once, what happens to the ones that do not fit, hold queues for inbound, and paced dialling for outbound.
Automation
When one call stops being the unit of work: many calls, over days, branching on how each one went.
Journeys
Automation across many calls and days: call, branch on the outcome, wait, retry, fall back to a message. Drafts, versions and executions.
Campaigns
Run a journey over a list of contacts: upload entries, start, pause, resume and abort, and read the report while it is still running.
Workflows
Six step types that do the work after the conversation — book, update a CRM, send an email, call a webhook, query, set a value.
Platform
The machinery under the conversation — the vendors behind the voice, where the money goes, the wire protocols, and the tools you drive it all with.
The portal
Every screen of the console, control by control: the agent builder's eight tabs, the calls, the numbers, the money, and what each page's states mean.
Speech and language vendors
Every transcriber, voice and model this platform can reach, how a chain falls through when one refuses, and how to pin the ones you want.
Projects and budgets
Cost centres inside your account: attribute calls to one, give it a monthly budget, and decide what happens when it runs out.
Analytics
The numbers behind the calls: volume, duration, outcomes, cost and CSAT, over any window, sliced by agent or project.
Recordings and transcripts
Turn recording on, fetch the audio and the turn-by-turn transcript, and know how long each is kept before it is deleted.
Realtime protocol
The WebSocket wire format behind live audio and the live event feed: frames in both directions, heartbeats, and what a client must get right.
SDKs
Node, Python, Go, Java and the browser client: what to install, what each one wraps, and the behaviour they all share.
Command line
Drive the platform from a terminal: sign in once, then create agents, place calls, read transcripts and search the docs.
Build with AI
Give a coding assistant hands on this platform: the MCP server and its tools, the skills pack, and the machine-readable copies of this site.
API reference
Every endpoint this deployment serves, generated from the running server: method, path, what it takes and what it answers with.
And the ones that are not steps
Read before you dial a list rather than after, and read again every time a call did not go out.
Compliance
The checks every outbound call passes before the phone rings: the do-not-call list, consent, and the calling window where the number actually is.
Security and data
Where your data lives, how long each kind is kept, what isolates one account from another, and what we never store at all.
Questions we get asked
Pricing, phone numbers, languages, concurrency, dedicated deployments — the questions that arrive before the first call is placed.
Getting help
Where to ask, what to include so the first reply is useful, and the two identifiers that let us find your call in seconds.
Before you start
Three things, and only the first is required to get through step 3.
| You need | Where it comes from |
|---|---|
| An account on this deployment | Sign in at the portal. If you do not have a login yet, whoever set up your organisation's account can invite you. |
| An API key | You create it yourself, in the portal — step 1 walks through it. |
| A phone number, for outbound calls | Provisioned on your account by Sphoro Voice. Web calls from a browser need no number at all, so you can test the whole integration before one is assigned. |
The two things you will create
The API has exactly two objects on the path to a working call, and it is worth being clear about which is which before the commands start.
| Object | What it is | How long it lives |
|---|---|---|
Agent agt_… | The configuration that decides how the conversation goes: what it says first, the instructions it follows, the language and voice it speaks in. | Long-lived. Create it once, use it for every call. |
Call call_… | One conversation, running that agent — dialled out to a phone number, or connected from a browser. | Minutes. It carries its own transcript, recording and end reason afterwards. |
Everything else on this site is about those two: how to authenticate the requests that create them (step 2), what language the agent holds the conversation in (step 4), and how you hear that a call finished (step 5).
Your base URL
Every path on this site is relative to one origin. It is the deployment you are reading these docs from, so the examples are already pointed at the right place.
https://voice.sphoro.comEvery endpoint sits under /v1, every request carries a bearer token, and every
body is JSON. Step 2 covers all three, along with pagination,
rate limits and the full list of errors.
https://voice.sphoro.com — the same process answering this page
answers those requests, so there is no second copy of the documentation to drift out of date. The
machine-readable description of every endpoint is at openapi.json, and
llms.txt is the same site in plain Markdown, for feeding to a
model.Reading this anywhere else
Every page here is also served as Markdown — the same words, no markup — at the page's own
address with .md on the end. Paste one into a model, diff it between releases, or
read the whole site from a terminal.
curl -s https://voice.sphoro.com/docs/llms.txt
curl -s https://voice.sphoro.com/docs/calls.md