Questions we get asked

The ones that arrive before the first call is placed. Anything that comes up after you have integrated has a page of its own, and this page links to it rather than answering it twice.

Getting started

Question	Answer
What do I need before I can place a call?	An account, an API key you make yourself in the portal, and — for calls to a telephone — a number provisioned on your account. Browser calls need no number at all, so you can build and test the whole integration before one is assigned. See get an API key.
How long does the first working call take?	About fifteen minutes if you follow the six numbered steps. The first three get you a call that connects.
Is there a sandbox or a test number?	Use a browser call to your own machine, and place real calls to your own phone. There is no simulated telephone: a call that does not use a real carrier does not tell you what you need to know about a real one.
Can I try it without writing code?	Yes — the portal creates agents and places test calls. The command line covers the rest without a program.

Languages and voices

Question	Answer
Which languages can an agent speak?	Every one on language and voice, which is generated from this deployment rather than written out — so it is the real list.
Can one agent speak more than one language?	Yes. Each is an entry in `languages` with its own voice, greeting and prompt, and `language_detection: "follow"` moves the agent into whichever one the caller speaks.
Can I use my own recorded voice?	For the fixed lines — the greeting, a menu, a disclaimer — yes, by uploading the audio. See voice lines. The conversational parts are synthesised.
Can I clone a voice?	Voice cloning belongs to the synthesis vendor rather than to this platform. Clone it with the vendor, then use the id it gives you in the language entry's `voices` map. See vendors.

Telephony

Question	Answer
Can I bring my own carrier account?	Yes, for Twilio, Plivo and Vobiz. Your credentials go on your account and your existing numbers become usable. See numbers and carriers.
Can I connect a SIP trunk directly?	Not today. Terminate the trunk on one of the supported carriers and connect that account. Tell us if the trunk itself is the requirement.
Can the agent transfer a caller to a person?	Yes — a cold transfer to one number you configure. Warm transfer, where all three are on the line, is not available. See transfers and endings.
Why did the caller's number arrive without a country code?	It did not, in what we store. Some carriers deliver a national-format number, and it is normalised to E.164 before the call record is written — so what you read back is consistent even where the carrier's own dashboard is not.

Capacity and cost

Question	Answer
How many calls can run at once?	A ceiling provisioned on your account, plus a separate allowance for inbound callers waiting. Past both, a caller hears the busy line. See concurrency.
Why did a batch of calls fail with `at_capacity`?	They were fired faster than your ceiling allows, so most were never dialled. Use a campaign, which paces itself, or put a gap in your loop.
How do I stop one team spending everybody's budget?	A project with a monthly budget. Note that a budget stops inbound calls too, so put a support line in its own project.
Where do I see what it cost?	Analytics, over any window, sliced by agent or project. Cost per connected call is the number worth watching.

Building agents

Question	Answer
The agent is confidently wrong about our prices. What fixes it?	A knowledge base. No prompt fixes this — you are asking a model to recall something it never knew.
It does the steps in the wrong order.	A flow. Each step becomes a node and the model is only ever asked to do one step's worth of work.
Can it call our API during the call?	Yes. Tools against your own endpoints are provisioned per account today rather than created through this API — see tools and functions.
How do I get structured data out of every call?	Extractions: typed fields filled from the transcript after the call. Test them against a pasted transcript before placing thirty calls.
Why is `summary` empty in my webhook?	You are reading it on `call.ended`. It is written a few seconds later and arrives on `call.analysed`. This is the most common integration bug against this API.

Running it

Question	Answer
Can we run this in our own infrastructure?	Dedicated and in-region deployments exist. Talk to us before you build against assumptions about where data sits.
Can we keep transcripts off third-party models?	The model chain speaks the OpenAI wire format and several presets are self-hosted runtimes, so the model can be one you run. See vendors.
How long are recordings kept?	On a retention window agreed with your account, and only if you turned recording on. See security and data.
Is there a status page?	Getting help has where to look and what to send us.

The shortest possible answer to "how do I start?"

Two requests, to your own telephone. Everything else on this site is detail around these.

Shell

AGENT=$(curl -s -X POST https://voice.sphoro.com/v1/agents \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"First agent","languages":[{"code":"en-IN","greeting":"Hello, this is a test.","system_prompt":"You are testing a phone line. Be brief and friendly."}]}' \
  | jq -r .id)

curl -s -X POST https://voice.sphoro.com/v1/calls \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"agent_id\":\"$AGENT\",\"to\":\"$YOUR_OWN_NUMBER\"}"

Not answered here?

The glossary covers the terms this documentation uses in a narrower sense than the industry does, and getting help is where to ask a person. The search box at the top of this site reads every page, including the ones this FAQ points at.