Recipes
Place an AI agent call
Written beside the API’s code, and read from it every hour.
Have one of your AI agents call one person, for a reminder, a confirmation, a callback or a notice. To have it call a company for one of your people, see Call a company for someone.
- Pick an agent.
GET /v1/agentslists them. It must beactive, withoutgoing_callson (the Outgoing calls switch on the agent's Persona tab). - Place the call with who to call and why. The answer is
202once the call is placed. Send anIdempotency-Keyheader, your own id for the request, so a retry after a timeout gets the same call instead of placing a second one. - Get the outcome. The agent greets, says the purpose, and handles the answer with its own jobs. It reports how it went the way it reports every message, through the message delivery and message action set on the agent in the portal, marked with your
reference.
# 1. Find an agent that may place calls
curl https://api.vocatech.com/v1/agents \
-H "Authorization: Bearer $VOCATECH_API_KEY"
# 2. Have it call one person (the Idempotency-Key makes a retry safe)
curl -X POST https://api.vocatech.com/v1/agents/7/calls \
-H "Authorization: Bearer $VOCATECH_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: visit-20260925-0900" \
-d '{
"to": "7185550142",
"purpose": "confirm the Friday 9 AM visit",
"person_name": "Jordan Reyes",
"reference": "visit-20260925-0900"
}'import { vt } from './vocatech.mjs';
// 1. An agent that is on and may place calls
const { agents } = await vt('GET', '/v1/agents');
const agent = agents.find((a) => a.active && a.outgoing_calls);
// 2. One call, to one person
const { call } = await vt('POST', `/v1/agents/${agent.id}/calls`, {
to: '7185550142',
purpose: 'confirm the Friday 9 AM visit',
person_name: 'Jordan Reyes',
reference: 'visit-20260925-0900',
});
console.log(call.call_sid, call.state); // 202: placedfrom vocatech import vt
# 1. An agent that is on and may place calls
agents = vt("GET", "/v1/agents")["agents"]
agent = next(a for a in agents if a["active"] and a["outgoing_calls"])
# 2. One call, to one person
call = vt("POST", f"/v1/agents/{agent['id']}/calls", {
"to": "7185550142",
"purpose": "confirm the Friday 9 AM visit",
"person_name": "Jordan Reyes",
"reference": "visit-20260925-0900",
})["call"]
print(call["call_sid"], call["state"]) # 202: placed<?php
require __DIR__ . '/vocatech.php';
// 1. An agent that is on and may place calls
$agents = vt('GET', '/v1/agents')['agents'];
$agent = current(array_filter($agents, fn ($a) => $a['active'] && $a['outgoing_calls']));
// 2. One call, to one person
$call = vt('POST', "/v1/agents/{$agent['id']}/calls", [
'to' => '7185550142',
'purpose' => 'confirm the Friday 9 AM visit',
'person_name' => 'Jordan Reyes',
'reference' => 'visit-20260925-0900',
])['call'];
echo $call['call_sid'], ' ', $call['state'], PHP_EOL; // 202: placedGET /v1/agents response200 OK
{
"agents": [
{
"id": 7,
"name": "Front desk",
"extension": "850",
"active": true,
"outgoing_calls": true,
"provisioned": true
}
],
"meta": { "total": 1 }
}POST /v1/agents/7/calls response202 Accepted
{
"call": {
"call_sid": "5d7e9a1c-3b2f-4c8e-a6d0-9f1b2c3d4e5f",
"agent_id": 7,
"from": "7185550100",
"to": "7185550142",
"state": "trying",
"kind": "notice",
"purpose": "confirm the Friday 9 AM visit",
"reference": "visit-20260925-0900"
}
}- One call per request. This is not a bulk dialer.
- The agent calls inside its calling hours only, 8 AM to 9 PM in the agent's time zone, unless you changed them on its Persona tab. Outside them the call is refused with
422. Send"allow_quiet_hours": trueto place it anyway. tois a 10-digit US or Canadian number, or an extension of 2 to 6 digits.- It never dials 911 or another N11 service code, 933 or 988, a premium number (900 or 976), or an area code that belongs to another country, such as those in the Caribbean. US territories are fine.
- Each key may place 10 agent calls a minute and 500 a day, and an agent places 50 a day unless a cap is set on it.
