Developers · Your AI
Your own AI, connected to your phone system.
Give a coding assistant the guide it needs to build on the API, with the rules that keep its code safe. Have your AI agent call a customer from your own software, with the reason and what to say in the request, inside its calling hours.
Docs written for the assistant that writes your code.
Point Claude Code, Cursor or ChatGPT at the guide and the OpenAPI file, and paste the rules below, so the code it writes is safe the first time.
You are writing code against the Vocatech API.
Read https://vocatech.com/developers/guide.md and https://vocatech.com/developers/openapi.yml first.
- Call the API from a server only. It sends no CORS headers. Keep the key in an environment variable, never in a browser, an app or a repository.
- Send a text or a fax with "test": true first. Without it, a real one goes out.
- On a 429, wait the seconds in Retry-After. Each kind of request has its own counter.
- Check X-Vocatech-Signature on the raw body of every webhook, and answer within five seconds.
- Send an Idempotency-Key with every AI agent call, so a retry never places a second call.
- Dates you ask for are read in New York time unless you send a timezone. Every time comes back in UTC.
- The API reads and sends. It never changes call settings, so do not look for a route that does.From your own software
One request, and the agent calls.
Your software names the person, the number, the reason and what to say, and the agent calls inside its calling hours. One call per request, never an emergency or a foreign number, and at most fifty a day for each agent.
- 01
Turn on outgoing calls
On the agent’s Persona tab in the portal, switch on Outgoing calls and set its calling hours.
- 02
Send one request
POST /v1/agents/{id}/calls with the number, the reason in a line, and up to 2,000 characters of instructions for this one call.
- 03
Hear how it went
The agent calls, works with the jobs it has, and reports through its message delivery, marked with your reference.
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: appt-2291-confirm" \
-d '{
"to": "7185550142",
"person_name": "Rachel Stein",
"purpose": "Confirm the Friday 10 AM appointment",
"instructions": "If Friday no longer works, offer Monday at 9 AM or Tuesday at 2 PM, and file the change with the Appointments job.",
"job": "Appointments",
"reference": "appt-2291"
}'{
"call": {
"call_sid": "c7d2e9a4-1f3b-4c8e-9a6d-0b5e2f7c1a93",
"agent_id": 7,
"from": "7185550100",
"to": "7185550142",
"state": "trying",
"kind": "notice",
"purpose": "Confirm the Friday 10 AM appointment",
"reference": "appt-2291"
}
}Questions about AI and the API.
“Can Claude or ChatGPT read our calls?”
Not through a connector of our own yet. A developer can hand an assistant the API and the guide, and Ask AI inside the portal answers plain questions about your own account, on its own.
“Can the AI agent call a list of people?”
No. One call per request, on purpose, and at most fifty a day for each agent. It is for reminders, confirmations and callbacks, never a campaign, and every call keeps the agent’s calling hours.
“When does the agent call?”
Between 8 AM and 9 PM in the agent’s time zone, unless its Persona tab sets other hours. A request from your software outside them is refused, unless it asks to place the call anyway with allow_quiet_hours.
“Which numbers will it never dial?”
No emergency or service code such as 911 or 988, no premium number, and no area code that belongs to another country. US and Canadian numbers and your own extensions only.
“How do we try it without calling a customer?”
Have the agent call you first, from its Testing tab or with your own number in the request, and listen to how it opens. A message taken on that call is real, so treat it as one.
“What does a call cost?”
The agent’s minutes while it is on the line, the same as on any call it answers, and nothing for the request itself. The pricing page has the price of the line and of the minute.
The AI backs up the team
The guide first. A person when needed.
The AI does the looking. A person does the answering. Call or text 718.395.1550 and the people who built the API pick up.