Phone numbers

Your numbers

Every number lives in your workspace’s own Plivo subaccount, which Vaakyo creates the first time your workspace needs one. A number gets there in one of two ways:

• The Vaakyo team assigns it. A number the platform bought (or already had) is moved into your workspace’s subaccount and pointed at that subaccount’s Vaakyo application (voxa-<subaccount id>), so its calls reach Vaakyo with no setup in Plivo’s console.
• You buy it. On Phone numbers in the console, search Plivo’s numbers by country, type and digits, and buy one. It is rented straight into your subaccount and routed to Vaakyo the same way. Buying needs the numbers.manage permission and must be enabled for your workspace (can_buy in the list below).

List your numbers (needs agents.view):

curl https://api.vaakyo.com/api/v1/numbers -H "X-API-Key: $VAAKYO_API_KEY"

{
  "public_base_url": "https://api.vaakyo.com",
  "numbers": [
    {
      "number": "+918035001234",
      "provider": "plivo",
      "country": "India",
      "voice_enabled": true,
      "agent_id": "1b81a241c0e44f5c9d1f0e2a7c3b9d10",
      "agent_name": "Front desk",
      "rented": false,
      "billed": true,
      "monthly_price_paise": 50000,
      "paid_until": "2026-11-02T10:15:00+00:00",
      "past_due_since": null,
      "purchase_status": ""
    }
  ],
  "can_buy": true,
  "errors": {}
}

Field	What it means
provider	Always plivo.
agent_id, agent_name	The agent that answers the number. Empty: not connected, so it does not answer.
rented	true if your workspace bought the number itself (you can release it).
billed	true when the number’s monthly fee is charged to your workspace.
monthly_price_paise	The monthly fee last charged for this number, in paise.
paid_until	When the paid month ends and the next fee is due.
past_due_since	Set when a fee could not be paid; null otherwise.
purchase_status	Plivo’s status for a bought number, for example pending while Plivo finishes setting it up.
can_buy	Whether your workspace can buy numbers in the console.
errors	Set if Plivo could not list the numbers right now, with the reason.

Connect a number to an agent on Phone numbers (or POST /api/v1/numbers/{number}/connect); see Inbound calls.

Monthly fee

Every number in your workspace costs a monthly fee, taken from your credits: ₹500 a month by default, unless the Vaakyo team has set a different fee for your workspace. A number you bought yourself costs at least Plivo’s rent for it (at today’s exchange rate) plus a small margin, so an expensive number can cost more than the default. Plans that include phone numbers (Growth 1, Scale 2) waive the monthly fee of that many of your numbers, oldest first; see Plans.

• The first month is charged when the number arrives (when it is assigned to you or you buy it). A number you buy also charges Plivo’s setup price, if any.
• After that the fee is charged every 30 days. It shows as a number row in your credit ledger.
• If your credits don’t cover a fee, the number is marked past due (past_due_since) and keeps working. If it is still unpaid after the grace period (7 days by default), a number you bought is released on Plivo, and a number the Vaakyo team assigned is taken back. Either way the agent using it stops answering it.

Buying a number

Search what you can buy with GET /api/v1/numbers/search (needs numbers.manage; filters country_iso, type, pattern, region, offset). Prices are in paise, with your workspace’s monthly fee already applied:

GET /api/v1/numbers/search?country_iso=IN&type=local

{
  "items": [
    {"number": "+918035009876", "country": "India", "country_iso": "IN", "region": "Karnataka", "city": "Bangalore", "type": "local", "restriction_text": "", "monthly_price_paise": 50000, "setup_price_paise": 0, "cost_floor_paise": 9000}
  ],
  "more": false
}

Buy one with POST /api/v1/numbers/buy and {"number": "+918035009876", "country_iso": "IN"}. Setup and the first month are taken from your credits at once (the response’s charged_paise); if your credits don’t cover them you get 402, and a number someone else just took returns 409. Release a number you bought with DELETE /api/v1/numbers/{number}: there is no refund for the current month, and it cannot be undone.

API keys don’t have numbers.manage, so buying, releasing and connecting numbers is done in the console (or with a signed-in user’s token).

Calls on a number

The Vaakyo number on the call is the caller ID of an outbound call (from_number, else the agent’s phone_number) or the dialled number of an inbound call. Vaakyo places, routes and hangs up the call with your subaccount’s credentials. The call records provider: "plivo" (web for browser calls), its providers.telephony says the same once the call ends, and phone minutes are charged at Plivo’s rate.

If the Vaakyo team turns Plivo off for your workspace, calls are refused with 422 Plivo is not available to this workspace.

Only your workspace’s own numbers can be used: as an agent’s phone_number and as a call’s or campaign’s from_number. Any other number is refused with 422 that number is not on this workspace, and an inbound call to a number reaches only the agent in the workspace that holds it. Plivo’s requests to Vaakyo are signed and checked, so nobody else can start a call on your agents.

Calls that never connect

Plivo reports calls that never connected, and Vaakyo ends them with these statuses:

Plivo says	Call status
No answer	no-answer
Busy	busy
Failed (bad number, refused, carrier error)	failed
Canceled before it was answered	canceled

hangup_reason holds Plivo’s hang-up cause, and call.ended carries it in data.plivo. A call that connected is ended by its agent session (see hangup_by).

Campaigns

Campaigns dial from the campaign’s from_number (or the agent’s number), which must be one of your workspace’s numbers. Retries, calling hours and results work the same as for single calls.