Docs/Voice API
Voice API
Place an outbound call from your agent's phone number with one request. You send the number to call, a goal, the facts the agent may use and the script to follow. The agent holds the conversation and you get the transcript and outcome back.
How it works
One POST /v1/voice/calls places the call. Your agent dials the number, opens the conversation, works toward the goal using only the facts you sent, and ends the call. When the call ends you can fetch the result by its ID, or have it pushed to your server with a signed call.ended webhook.
- Base URL:
https://api.talktomyagent.io - Format: JSON in, JSON out. Errors are RFC 7807
application/problem+json. - Full reference: every endpoint, schema and error code is in the interactive API reference (OpenAPI at /v1/openapi.json).
Authentication
Create an API key on the API keys page of your dashboard and limit it to the agent that owns the phone number you will call from. Keys look like mbn_live_... and go in a Bearer header on every request.
| Scope | Lets the key |
|---|---|
voice:call | Place outbound calls and configure the call.ended webhook. |
voice:read | List and read calls, fetch recordings, read the webhook settings. |
Every request other than a GET also needs an Idempotency-Key header: 8 to 100 characters from A-Z a-z 0-9 . _ ~ -. A UUID is ideal. Retrying with the same key and the same body within 24 hours returns the original response instead of placing a second call. The same key with a different body is refused with 422. A 4xx answer other than 429 is stored with its key too, so after fixing a rejected request, send it with a new key. 5xx and 429 answers are forgotten, so a retry with the same key after a server error or a rate limit runs again.
Authorization: Bearer mbn_live_YOUR_KEY
Content-Type: application/json
Idempotency-Key: 3f6c1a52-8a0e-4c4f-9a8e-2b7d61c0e9f4
Place your first call
The from number identifies your agent: it must be one of the agent's active numbers, and the key must be scoped to that agent or be account-wide. Start with a one-line purpose to your own phone.
export TTMA_KEY=mbn_live_YOUR_KEY
curl -X POST https://api.talktomyagent.io/v1/voice/calls \
-H "Authorization: Bearer $TTMA_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"from": "+1YOUR_AGENT_NUMBER",
"to": "+1YOUR_OWN_NUMBER",
"triggeredBy": "first-test",
"purpose": "Test call. Say hello, confirm the integration works, then say goodbye."
}'
A successful request returns 200:
{
"data": {
"callControlId": "v3:abcDef123...",
"expectedDialAt": "2026-11-02T15:04:05.000Z",
"warnings": []
}
}
callControlId is the ID of this call. Use it to fetch the result, the recording, and to match the webhook delivery. warnings is reserved for non-fatal notices and is empty today.
Request body
Send exactly one of purpose or task. Sending both, or neither, is a 400.
| Field | Notes |
|---|---|
from | Required. String. Your agent's number in E.164, for example +16475550100. The call is placed from this number. |
to | Required. String. Number to call, E.164. |
triggeredBy | Required. String. Who or what placed the call, up to 200 characters. Written to the audit log, never spoken. |
purpose | String. One free-text instruction, up to 500 characters. Fine for simple calls. |
task | Object. The structured brief: goal, facts, script, escalation. See below. |
targetName | String. Name of the person you are calling, up to 200 characters. The agent is told who it is calling. |
firstMessage | String. The exact opening line, up to 500 characters. Overrides the agent's default outbound greeting for this call. |
maxDurationSecs | Integer. Conversation length cap, 60 to 1800. Default 600. The agent wraps up and says goodbye as the cap approaches. |
script | String. Script name for a purpose call. With task, use task.script instead. |
The task object
The task is the brief the agent works from on this one call.
| Field | Rules |
|---|---|
goal (required) | 1 to 500 characters. What a successful call achieves, in one or two sentences. |
facts | Flat object, up to 30 keys. Keys match ^[a-z][a-z0-9_]{0,40}$. Values are strings (up to 500 characters), numbers or booleans; no nested objects or arrays. The whole object must be 4096 characters or less as JSON. The agent is told these are the only confirmed facts. |
script | Name of a script set up for your agent, 1 to 64 characters from a-z A-Z 0-9 _ -. |
escalation | Up to 500 characters. A plain-English rule for when to hand off, for example "If they dispute the amount, email the billing team a one-line summary and end the call politely." The agent acts on it with the tools it has, such as emailing your team. |
"task": {
"goal": "Confirm Maria's Thursday 10:30 cleaning, or note a preferred new time.",
"script": "appointment_confirmation",
"facts": {
"patient_name": "Maria",
"appointment_date": "Thursday, November 12",
"appointment_time": "10:30 AM",
"office_phone": "+16475559876"
},
"escalation": "If she has a clinical question, tell her the office will call back and end the call."
}
goal, facts and escalation are read by the agent as part of its brief. Text that looks like prompt injection is stripped, but no filter catches every phrasing. Build them on your server from your own data; never pass end-user input straight through.Scripts
A script tells the agent how to run a type of call: how to open, what to ask, how to handle each answer, what it must never do, and how to close. You write a script once and reuse it on every call of that type; the facts change per call.
- Agents with published scripts (the Scripts tab of your agent in the dashboard):
task.scriptmust name a published script that allows outbound calls, and every fact the script marks as required must be present. Otherwise the request fails with400and a message naming the problem, before anyone is called. - Agents without published scripts: the name refers to a
#### namesection of the agent's voice playbook. An unknown name is not an error; the agent falls back to its general outbound guidance.
Our team writes the first scripts with you during the build. The use-case guides show what a good script covers: appointment reminders, sales follow-ups, notifications and payment reminders.
Get the result
Fetch the call by its callControlId with a voice:read key:
curl https://api.talktomyagent.io/v1/voice/calls/v3:abcDef123... \
-H "Authorization: Bearer $TTMA_KEY"
While the call is ringing or live, status is "in_progress". Once the call ends and the agent reports it, status is "completed" and the response carries durationSeconds, endedReason, transcript, the task you sent, and an outcome (completed, not_completed, dropped or unknown, with a short summary) once the post-call evaluation has run. The transcript needs the Ship Transcripts setting on, which is the default.
Other read endpoints:
GET /v1/voice/callslists calls, newest first, withlimit,cursor,after,before, and one ofdirectionorendedReason.GET /v1/voice/calls/{id}/recordingreturns{ "data": { "url", "expiresAt" } }: an MP3 link that expires after 5 minutes.404when recording is off or there is none.
Rather than polling, register a call.ended webhook and receive the same call object, signed, when the call ends.
Errors
Errors are application/problem+json with type, title, status, detail, instance and requestId. Match on the last segment of type; detail is human-readable and can change. Quote requestId when you contact us.
| Status | Type | Meaning |
|---|---|---|
| 400 | validation-failed | Bad number format, a missing field, both or neither of purpose and task, a fact over its limit, an unknown published script, a missing required fact, or text that was empty after injection filtering. |
| 400 | missing-idempotency-key | No Idempotency-Key header. |
| 400 | voice-self-call | to is one of the agent's own numbers. |
| 401 | missing-credentials, invalid-credentials | No key, or an unknown key. |
| 403 | insufficient-scope | The key lacks the scope the route needs: voice:call to place calls, voice:read to read them. |
| 403 | voice-country-blocked | The destination country is not on the agent's outbound list. |
| 403 | voice-direction-disabled | The agent is set to inbound only. |
| 403 | voice-line-suspended | The line is suspended and cannot place calls. |
| 404 | not-found | No agent with this from number among the agents the key may use. |
| 409 | voice-not-provisioned | The agent has no number yet, or its gateway connection is not registered. |
| 409 | agent-offline | The agent's gateway has stopped checking in. |
| 409 | idempotency-in-flight | A request with this key is still being processed. Retry shortly. |
| 422 | idempotency-key-mismatch | The key was already used with a different body. |
| 429 | rate-limit-exceeded | A call limit below was hit, or the key's own request limit (60 per minute by default); detail says which. |
| 502 | dial-failed | The carrier refused the dial. Retry later. |
Limits
| Limit | Value |
|---|---|
| Calls to the same number | 5 per hour, per agent |
| Outbound calls | 30 per hour and 100 per day, per agent |
| Simultaneous calls | 2 per agent by default, inbound and outbound together; raised on request |
| Call length | 60 to 1800 seconds via maxDurationSecs, default 600 |
| Destination countries | Activating a number allows that number's own country plus the United States. Add other supported countries in the Outbound countries setting of your agent. |
200 with a call ID, and the call is then hung up as soon as the dial starts, before it reaches the person. Send at most as many calls at once as your agent has lines, and start the next one when a call ends.Premium-rate destinations are always refused.
Before you go live
- Consent. Outbound calling rules depend on where you and the person you call are. In the US, for example, the FCC treats AI-generated voices as artificial voices under the TCPA, which generally means calls to mobile numbers need the person's prior consent. Check with your counsel.
- Opt-outs and calling hours. The API does not check do-not-call lists or local time. Your system decides who to call and when.
- Recording notice. Calls are recorded by default. Where the law requires a notice, put it in
firstMessageor the script's opening line. - Audit. Every placed call is written to an audit log with its
triggeredByvalue and task.