# 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](https://voice.sphoro.com/docs/api-keys): Create your first API key in the portal, choose the role it carries, and store it where it cannot leak.
- [Use your API key](https://voice.sphoro.com/docs/authentication): The base URL, the Authorization header, a first request that proves the key works, and every error the API can answer with.
- [Make a call](https://voice.sphoro.com/docs/calls): Create an agent, place a call to a phone number, follow it live, and read the transcript and recording afterwards.
- [Language and voice](https://voice.sphoro.com/docs/voices): Every language an agent can speak, how to set it per agent or per call, and the voice, speed and pitch that carry it.
- [Webhooks](https://voice.sphoro.com/docs/webhooks): Receive signed, retried events when a call starts, ends or fails — with verification code you can paste in.
- [Talk from a browser](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/concepts): The objects the platform is made of — agent, persona, call, knowledge base, flow, journey, project — and which one owns what.
- [Kinds of agent](https://voice.sphoro.com/docs/agent-types): 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](https://voice.sphoro.com/docs/call-lifecycle): Everything between your request and the finished record: dialling, answer, the turn loop, barge-in, hang-up, and the analysis afterwards.
- [Latency](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/agents): Every field an agent accepts, what it changes, and what it defaults to — the whole configuration surface in one table.
- [Writing the prompt](https://voice.sphoro.com/docs/prompting): 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](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/behaviours): 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](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/keypad): 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](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/post-call): 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](https://voice.sphoro.com/docs/telephony): 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](https://voice.sphoro.com/docs/inbound): 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](https://voice.sphoro.com/docs/outbound): 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](https://voice.sphoro.com/docs/transfers): 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](https://voice.sphoro.com/docs/capacity): 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](https://voice.sphoro.com/docs/journeys): Automation across many calls and days: call, branch on the outcome, wait, retry, fall back to a message. Drafts, versions and executions.
- [Campaigns](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/providers): 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](https://voice.sphoro.com/docs/projects): Cost centres inside your account: attribute calls to one, give it a monthly budget, and decide what happens when it runs out.
- [Analytics](https://voice.sphoro.com/docs/analytics): The numbers behind the calls: volume, duration, outcomes, cost and CSAT, over any window, sliced by agent or project.
- [Recordings and transcripts](https://voice.sphoro.com/docs/recordings): 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](https://voice.sphoro.com/docs/realtime): 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](https://voice.sphoro.com/docs/sdks): Node, Python, Go, Java and the browser client: what to install, what each one wraps, and the behaviour they all share.
- [Command line](https://voice.sphoro.com/docs/cli): Drive the platform from a terminal: sign in once, then create agents, place calls, read transcripts and search the docs.
- [Build with AI](https://voice.sphoro.com/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](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/security): 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](https://voice.sphoro.com/docs/faq): Pricing, phone numbers, languages, concurrency, dedicated deployments — the questions that arrive before the first call is placed.
- [Getting help](https://voice.sphoro.com/docs/support): 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](https://voice.sphoro.com/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](https://voice.sphoro.com/docs/api-keys) 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](https://voice.sphoro.com/docs/authentication)), what language the agent holds the conversation in ([step 4](https://voice.sphoro.com/docs/voices)), and how you hear that a call finished ([step 5](https://voice.sphoro.com/docs/webhooks)).

## 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.

**Base URL**

```
https://voice.sphoro.com
```

Every endpoint sits under `/v1`, every request carries a bearer token, and every body is JSON. [Step 2](https://voice.sphoro.com/docs/authentication) covers all three, along with pagination, rate limits and the full list of errors.

> **These docs are served by the API they describe.** Every example on every page points at `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](https://voice.sphoro.com/openapi.json), and [llms.txt](https://voice.sphoro.com/docs/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.

**The whole site, as text**

```bash
curl -s https://voice.sphoro.com/docs/llms.txt
curl -s https://voice.sphoro.com/docs/calls.md
```