Hamsa Agents · API
AI Phone Agents API
Everything behind the agents dashboard, callable from your backend: create and update agents, connect phone numbers, start calls, run campaigns, and pull every conversation with its transcript — with webhooks pushing call events to you as they happen.
- Agents as REST resources
- Numbers, calls and campaigns
- Conversations with transcripts
- 5 webhook events
- Tools, knowledge and secrets
Capabilities
The phone agent, programmable end to end
Agents as resources
Create, list, fetch and update voice agents through the v2 endpoints. Build the conversation visually in the dashboard, then version and manage it from code.
Numbers under API control
Register numbers, assign one to an agent, unassign it, list what you have and remove what you no longer need — the full lifecycle over REST.
Calls your backend starts
One endpoint places an outbound call from a number. Campaigns take a list of recipients and run it, with pause, resume, cancel and per-recipient retry.
Every conversation, retrievable
List conversations, fetch one with its details, or terminate a call in progress — the records behind the dashboard’s call history are an API.
Events pushed to you
Webhooks deliver call.started, call.answered, transcription.update, tool.executed and call.ended over HTTPS, so your systems follow calls live.
The agent’s surroundings too
Knowledge bases, web tools (HTTP and MCP), pronunciation dictionaries and encrypted secrets all have endpoints, so agent setup is scriptable.
Integration
From API key to a live call
A phone agent integration, in the order it comes together.
- 01
Create a secret key
Create a secret key in the dashboard and keep it on your server. Every request carries it in the Authorization header as Token <key>.
- 02
Create or pick an agent
Create the agent over the v2 endpoint, or design it in the dashboard and fetch it by ID. Attach its tools, knowledge base and secrets by API.
- 03
Connect a number
Register the number, then assign it to the agent. Inbound calls to that line are answered by the agent from then on.
- 04
Start outbound calls
Place a single call from the call endpoint, or create a campaign with recipients and let it dial through the list on your schedule.
- 05
Follow and record outcomes
Webhooks stream events during the call; afterwards, conversation endpoints return the record and analytics endpoints aggregate performance and satisfaction.
Reference
The phone agents API at a glance
Each row links to its page in the API docs — the authoritative reference, with full schemas and runnable code samples.
| Area | Detail |
|---|---|
| Agents | Create, list, fetch and update voice agents |
| Phone numbers | Register, list, assign, unassign and remove numbers |
| Calls | Start an outbound call from one of your numbers |
| Campaigns | Create and manage recipient campaigns, with pause, resume, cancel and retry |
| Conversations | List calls, fetch one with its record, or terminate a call in progress |
| Webhooks | call.started, call.answered, transcription.update, tool.executed, call.ended — delivered over HTTPS |
| Configuration | Knowledge bases, web tools (HTTP and MCP), voice dictionaries and project secrets |
| Analytics | Overview, performance and satisfaction, plus conversation exports and call logs |
| Authentication | A secret key in the Authorization header of every request, as Token <key> |
Use cases
What teams build on the agents API
Calls inside your product
Your app triggers the call endpoint when an order ships or a booking nears, and the agent makes the call in the customer’s dialect.
CRM that stays current
call.ended webhooks carry outcomes into your CRM the moment calls finish — no polling, no manual logging.
Campaigns from your backend
Generate recipient lists from your own data, create the campaign by API, and pause or retry it based on live results.
QA and reporting pipelines
Export conversations and pull analytics on schedule, feeding call quality into the dashboards your team already uses.
FAQ
Questions about the phone agents API
Can I create and manage agents entirely through the API?
+
The v2 endpoints create, list, fetch and update agents. In practice most teams design the conversation in the dashboard — especially flow agents — and use the API to manage, version and operate agents from their backend.
How does my system start a call?
+
For a single call, POST to the phone-number call endpoint with the number and recipient. For lists, create a campaign: it dials recipients on your schedule and exposes pause, resume, cancel and retry per recipient.
How do call results reach my systems?
+
Three ways, by freshness: webhooks push call.started, call.answered, transcription.update, tool.executed and call.ended during the call; conversation endpoints return the full record afterwards; analytics endpoints aggregate and export across calls.
Does the API cover what the agent knows and uses?
+
Yes. Knowledge base items, web tools — plain HTTP or MCP — pronunciation dictionaries and encrypted project secrets each have endpoints, so the agent’s whole setup can live in your deployment scripts.
How is the API authenticated?
+
With a secret key created in the dashboard, sent in the Authorization header as Token <key>. It is shown once and refused from a browser, so keep it on your server. To start calls from a web page or an app, use a public key with the Web SDK instead: it can only start calls.
Keep reading
Hamsa Agents · Phone
AI Phone Agents
Inbound and outbound Arabic voice agents on your Twilio numbers or SIP trunk, with keypad input, transfers and campaigns.
Read →Hamsa API · Speech to Text
Arabic Speech to Text API
Batch, synchronous and WebSocket transcription of Arabic across dialects, with word timestamps, diarization and SRT export.
Read →Hamsa API · Text to Speech
Arabic Text to Speech API
Synchronous, async and streaming Arabic speech generation in 14 dialects plus English, with telephony output and cloned voices.
Read →


