Skip to content
VoxaDocs
Navigation
Open console →

Calls

Inbound calls

When someone dials a phone number connected to one of your agents, that agent answers; this page explains how numbers are set up and how Voxa decides whether to take the call.

Phone numbers

Voxa uses Plivo for phone calls. The Voxa team assigns Plivo numbers to your workspace. You then connect each number to an agent.

List your numbers (needs agents.view):

curl https://voxa.abhinavyadav.in/api/v1/numbers -H "X-API-Key: $VOXA_API_KEY"
{
  "public_base_url": "https://voxa.abhinavyadav.in",
  "numbers": [
    {"number": "+918035001234", "agent_id": "1b81a241c0e44f5c9d1f0e2a7c3b9d10", "agent_name": "Front desk", "...": "..."},
    {"number": "+918035005678", "agent_id": "", "agent_name": "", "...": "..."}
  ]
}

A number with an empty agent_id is not connected and does not answer.

Connect a number to an agent

In the console, open Phone numbers and pick an agent for the number. The matching endpoint is POST /api/v1/numbers/{number}/connect with the body {"agent_id": "..."}.

Connecting does two things:

  1. It points the number’s Plivo answer URL at Voxa.
  2. It sets the agent’s phone_number to this number, and clears it from any other agent that had it.

This needs the numbers.manage permission, which owners and admins have. API keys don’t, so connect numbers in the console. You can still set phone_number on an agent with an API key (see Webhook and number); that changes which agent answers, but only works once the number has been connected at least once.

How Voxa answers

When a call comes in, Plivo asks Voxa what to do. Voxa looks up the dialled number and checks, in order:

CheckIf it fails
An agent with status: "active" has this numberThe call is rejected. Paused agents don’t answer.
The workspace is activeRejected.
The workspace has credits (balance above ₹0)Rejected.
A call slot is free (live calls below the concurrency limit)Rejected. Inbound calls are not queued.

A rejected call is hung up straight away and no call record is created.

If every check passes, Voxa creates a call with direction: "inbound" and status: "in-progress", and the agent’s session starts on the audio stream:

  • from_number is the caller’s number, to_number is your number;
  • user_data is empty, so only {caller_phone} (the caller’s number) is filled among the agent’s variables;
  • calling hours are ignored;
  • the call is limited by max_duration_seconds and by your balance, like any call.

The welcome message plays first. If the agent has no welcome message, it waits for the caller to speak.

Personalising inbound calls

Inbound calls have no user_data, so the agent knows only the caller’s number. To greet known callers by name, give the agent a tool that looks up the caller, and say in the prompt to call it first:

At the start of the call, call lookup_customer. If it finds the caller, greet them by name.

Your tool receives the caller’s number in _call.from.

Following inbound calls

curl "https://voxa.abhinavyadav.in/api/v1/calls?direction=inbound&limit=20" -H "X-API-Key: $VOXA_API_KEY"

Webhooks fire for inbound calls the same way as for outbound ones, starting with call.started (there is no call.queued or call.placed).

Esc