Outbound calling
Make the call while it still matters. Straight from your systems.
Your application or automation places a call through the Voice API with one request: who to call, the goal, the facts the agent may use and the script to follow. The agent holds the conversation from your agent's number, and the outcome and transcript come back when the call ends.
A call reaches people. When a message would not.
Use voice for the moments that are urgent, valuable or too nuanced for another automated message: right after a form is submitted, when an appointment is missed, when a delivery runs into a problem. Your system decides when a call is worth making.
The agent starts informed. It is told why it is calling, who it is calling and which facts are confirmed, so it does not interrogate the person for things you already know.
Example call, with sample data
One request. A whole conversation.
The API returns a call ID straight away, so your workflow stays responsive while the agent talks.
- 1
Your system triggers it
One
POST /v1/voice/callswith your agent's number, the number to call, who triggered it, and a one-line purpose or a structured task. - 2
The agent gets the brief
The task carries the goal, up to 30 facts, the name of the script to follow and an optional escalation rule.
- 3
The conversation adapts
The agent answers questions, confirms details, uses the tools you approved, and wraps up politely before the call's length limit.
- 4
The result comes back
Fetch the call by its ID, or receive it with a signed webhook: status, duration, transcript, outcome and the task you sent.
The brief, as your system sends it.
Facts are a flat list of values your server builds from your own data. The agent is told these are the only confirmed facts. Build them on your server; never pass a caller's or user's text straight through.
Full request referencePOST https://api.talktomyagent.io/v1/voice/calls
{
"from": "+16475550100",
"to": "+16475550134",
"triggeredBy": "reminder-scheduler",
"targetName": "Maria",
"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"
},
"escalation": "If she has a clinical question, tell her the office will call back and end the call."
}
}Production control. At every step.
Your software decides who gets a call, when, and what the agent may do. The platform enforces the limits around it.
- Scoped API keysSeparate scopes to place calls and to read them, and a key can be limited to one agent. Keep keys on your server. Rotate or revoke a key without touching the agent.
- Safe retriesEvery request carries an idempotency key. Retrying with the same key within 24 hours returns the first answer instead of placing a second call.
- Your own numberCalls go out from one of your agent's active numbers.
- Rate limitsPer agent: 5 calls an hour to the same number, 30 calls an hour and 100 a day.
- Allowed countriesActivating a number allows that number's own country plus the United States. Other supported countries can be added in the agent's outbound settings. Premium-rate numbers are always refused.
- Planned capacityTwo simultaneous calls per agent by default, inbound and outbound together, raised on request.
- Audit trailEvery placed call is logged with who triggered it and the task it carried.
Calls worth automating first.
Each guide shows what a good script for that call covers.
Appointment confirmations
Confirm, or take a preferred new time, before the slot is lost.
Read the guide →Lead follow-ups
Call a new lead back while their request is still fresh.
Read the guide →Notifications
Service changes, delivery problems and other news a person should hear.
Read the guide →Payment reminders
Renewals and overdue balances, with the escalation rule you choose.
Read the guide →Questions.
Can our own server start a call?
Yes. Your backend, or an automation tool such as n8n, sends an authenticated request to the Voice API and gets the call's ID back straight away.
What can we tell the agent about the call?
A goal, up to 30 facts, the script to follow, an escalation rule, the name of the person you are calling, and optionally the exact opening line. Keep the brief specific: what success looks like, what is known, and where the agent should stop.
How do we get the result?
Fetch the call by its ID, or register a signed call.ended webhook. The record carries the status, duration, how the call ended, the transcript when transcript shipping is on, whether a recording is available, the task, and the outcome once it has been evaluated.
What happens if we send more calls than the agent has lines?
The simultaneous-call limit is checked by the agent when the dial starts, not by the API: the API still returns a call ID, and a call placed while every line is busy is 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.
Does the API check do-not-call lists or calling hours?
No. Your system decides who to call and when. Calling rules depend on where you and the person you call are; in the US, for example, AI-generated voices count as artificial voices under the TCPA. Check with your counsel. Where the law requires a recording notice, your project can play an approved notice at the start of every outgoing call, or you can put it in the opening line.
Which call should your agent take first?
Tell us which requests your team handles most often. We'll suggest a practical place to start.