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

01

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.

02

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.

03

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.

04

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.

05

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.

06

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.

  1. 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>.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

AreaDetail
AgentsCreate, list, fetch and update voice agents
Phone numbersRegister, list, assign, unassign and remove numbers
CallsStart an outbound call from one of your numbers
CampaignsCreate and manage recipient campaigns, with pause, resume, cancel and retry
ConversationsList calls, fetch one with its record, or terminate a call in progress
Webhookscall.started, call.answered, transcription.update, tool.executed, call.ended — delivered over HTTPS
ConfigurationKnowledge bases, web tools (HTTP and MCP), voice dictionaries and project secrets
AnalyticsOverview, performance and satisfaction, plus conversation exports and call logs
AuthenticationA secret key in the Authorization header of every request, as Token <key>

Use cases

What teams build on the agents API

01

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.

02

CRM that stays current

call.ended webhooks carry outcomes into your CRM the moment calls finish — no polling, no manual logging.

03

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.

04

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

Partner ecosystem

Trusted Across the
Technology Ecosystem

Hamsa works with leading technology companies, integrators, and solution providers to bring enterprise Voice AI to organizations across the region.