Flows
Your first call, end to end
Every call in order, from a test key to a call record you can read back.
Nothing here costs money or rings a phone. See Quickstart for the same path with the responses shown.
| # | Call | Why |
|---|---|---|
| 1 | GET /v1/limits | Confirms the key works and shows your budgets |
| 2 | POST /v1/agents | Creates the agent — always as a draft |
| 3 | POST /v1/numbers | Allocates a free sandbox number |
| 4 | PATCH /v1/numbers/{id} | Binds the agent, so the number has an answer |
| 5 | POST /v1/calls | Places the call. Runs the compliance gate |
| 6 | GET /v1/calls/{id} | Reads the outcome |
Where it goes wrong
| Symptom | Cause |
|---|---|
401 on step 1 | Wrong key, or it was revoked |
403 insufficient_scope on step 2 | The key was minted read-only. Scopes cannot be widened — mint a new key |
400 validation_error on the voice | The (ttsModel, ttsVoice) pair does not exist. See Voices |
422 on step 5 | agentId sent for a BYO number, or omitted for an agent number |
403 blocked_* on step 5 | The gate refused. error.details.checkType says which check |
Call ended with no transcript | Normal in test mode unless you dialled a magic number that answers |
Publishing
Step 2 leaves a draft. A draft can be dialled outbound, which is why this flow works without publishing — but it will not answer inbound calls. Publish before you expect the number to work in both directions:
curl "$TONE_API/v1/agents/$AGENT/publish" -X POST -H "Authorization: Bearer $TONE_KEY"Then stop polling
Step 6 is fine while you are exploring, and wrong in production. Register a
webhook endpoint and subscribe to call.completed — see
Webhooks.
Was this page helpful?