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.

ScopeLets the key
voice:callPlace outbound calls and configure the call.ended webhook.
voice:readList 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
Keep the key server-sideAn API key can place calls from your number. Never ship it in a browser, a mobile app or a public repository.

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.

FieldNotes
fromRequired. String. Your agent's number in E.164, for example +16475550100. The call is placed from this number.
toRequired. String. Number to call, E.164.
triggeredByRequired. String. Who or what placed the call, up to 200 characters. Written to the audit log, never spoken.
purposeString. One free-text instruction, up to 500 characters. Fine for simple calls.
taskObject. The structured brief: goal, facts, script, escalation. See below.
targetNameString. Name of the person you are calling, up to 200 characters. The agent is told who it is calling.
firstMessageString. The exact opening line, up to 500 characters. Overrides the agent's default outbound greeting for this call.
maxDurationSecsInteger. Conversation length cap, 60 to 1800. Default 600. The agent wraps up and says goodbye as the cap approaches.
scriptString. 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.

FieldRules
goal (required)1 to 500 characters. What a successful call achieves, in one or two sentences.
factsFlat 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.
scriptName of a script set up for your agent, 1 to 64 characters from a-z A-Z 0-9 _ -.
escalationUp 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."
}
These fields become instructionsgoal, 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.script must name a published script that allows outbound calls, and every fact the script marks as required must be present. Otherwise the request fails with 400 and a message naming the problem, before anyone is called.
  • Agents without published scripts: the name refers to a #### name section 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/calls lists calls, newest first, with limit, cursor, after, before, and one of direction or endedReason.
  • GET /v1/voice/calls/{id}/recording returns { "data": { "url", "expiresAt" } }: an MP3 link that expires after 5 minutes. 404 when 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.

StatusTypeMeaning
400validation-failedBad 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.
400missing-idempotency-keyNo Idempotency-Key header.
400voice-self-callto is one of the agent's own numbers.
401missing-credentials, invalid-credentialsNo key, or an unknown key.
403insufficient-scopeThe key lacks the scope the route needs: voice:call to place calls, voice:read to read them.
403voice-country-blockedThe destination country is not on the agent's outbound list.
403voice-direction-disabledThe agent is set to inbound only.
403voice-line-suspendedThe line is suspended and cannot place calls.
404not-foundNo agent with this from number among the agents the key may use.
409voice-not-provisionedThe agent has no number yet, or its gateway connection is not registered.
409agent-offlineThe agent's gateway has stopped checking in.
409idempotency-in-flightA request with this key is still being processed. Retry shortly.
422idempotency-key-mismatchThe key was already used with a different body.
429rate-limit-exceededA call limit below was hit, or the key's own request limit (60 per minute by default); detail says which.
502dial-failedThe carrier refused the dial. Retry later.

Limits

LimitValue
Calls to the same number5 per hour, per agent
Outbound calls30 per hour and 100 per day, per agent
Simultaneous calls2 per agent by default, inbound and outbound together; raised on request
Call length60 to 1800 seconds via maxDurationSecs, default 600
Destination countriesActivating a number allows that number's own country plus the United States. Add other supported countries in the Outbound countries setting of your agent.
Pace your batchesThe simultaneous-call limit is enforced by the agent when the dial starts, not by the API. A request placed while both lines are busy still returns 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 firstMessage or the script's opening line.
  • Audit. Every placed call is written to an audit log with its triggeredBy value and task.

Which call should your agent take first?

Tell us which requests your team handles most often. We'll suggest a practical place to start.

Tell us about your calls