# Sphoro Voice documentation

> Place automated voice calls from a plain JSON API over HTTPS. Six steps from an API key to a call that connects and reports back.

Every page below is also served as HTML at the same address without the `.md` suffix. The base URL for the API these pages describe is https://voice.sphoro.com.

## Documentation

- [Overview](https://voice.sphoro.com/docs/index.md): Place automated voice calls from a plain JSON API over HTTPS. Six steps from an API key to a call that connects and reports back.
- [1. Get an API key](https://voice.sphoro.com/docs/api-keys.md): Create your first API key in the portal, choose the role it carries, and store it where it cannot leak.
- [2. Use your API key](https://voice.sphoro.com/docs/authentication.md): The base URL, the Authorization header, a first request that proves the key works, and every error the API can answer with.
- [3. Make a call](https://voice.sphoro.com/docs/calls.md): Create an agent, place a call to a phone number, follow it live, and read the transcript and recording afterwards.
- [4. Language and voice](https://voice.sphoro.com/docs/voices.md): Every language an agent can speak, how to set it per agent or per call, and the voice, speed and pitch that carry it.
- [5. Webhooks](https://voice.sphoro.com/docs/webhooks.md): Receive signed, retried events when a call starts, ends or fails — with verification code you can paste in.
- [6. Talk from a browser](https://voice.sphoro.com/docs/browser.md): 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.
- [Platform concepts](https://voice.sphoro.com/docs/concepts.md): 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.md): 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.md): 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.md): 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.md): Every term this documentation uses that does not mean the obvious thing, defined once, in one place.
- [Agent reference](https://voice.sphoro.com/docs/agents.md): 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.md): 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.md): 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.md): 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.md): 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.md): 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.md): 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.md): 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.md): 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.md): 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.md): 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.md): 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.md): The summary and the typed fields written onto every finished call, how to write an extraction that answers reliably, and how to test one.
- [Numbers and carriers](https://voice.sphoro.com/docs/telephony.md): 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.md): 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.md): 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.md): 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.md): How many calls run at once, what happens to the ones that do not fit, hold queues for inbound, and paced dialling for outbound.
- [Journeys](https://voice.sphoro.com/docs/journeys.md): 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.md): 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.md): Six step types that do the work after the conversation — book, update a CRM, send an email, call a webhook, query, set a value.
- [The portal](https://voice.sphoro.com/docs/portal.md): 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.md): 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.md): 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.md): 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.md): 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.md): 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.md): 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.md): 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.md): 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.md): Every endpoint this deployment serves, generated from the running server: method, path, what it takes and what it answers with.
- [Compliance](https://voice.sphoro.com/docs/compliance.md): 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.md): 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.md): 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.md): Where to ask, what to include so the first reply is useful, and the two identifiers that let us find your call in seconds.

## Machine-readable

- [OpenAPI (JSON)](https://voice.sphoro.com/openapi.json): every endpoint, including the ones this guide leaves out.
- [OpenAPI (YAML)](https://voice.sphoro.com/openapi.yaml): the same description, as YAML.