Phone numbers

A Phone number answers inbound Calls with the Agent it routes to, and is the caller ID of the outbound Calls an Agent places. A Vocal operator provisions the numbers of an Organization; the API lists them, routes them and dials from them.

On the Phase 0 host. Served: routing and the dial policy since contracts 1.22.0, outbound Calls since 1.16.0. Phone Calls are live Calls; the test environment has no Phone numbers.

Route a number to an Agent

GET /v1/phone-numbers lists the Organization's numbers, newest first, with their status and capabilities (inbound, outbound). PATCH /v1/phone-numbers/{phone_number_id} sets the routing at the revision If-Match names:

{ "agent_id": "agt_...", "agent_version": null }

With agent_version null each inbound Call runs the Agent's active version as it stands at admission; a number pins a published version by naming it. A Call in progress keeps its version, and the next inbound Call takes the new routing. The update needs telephony:write and a live key or a Member; a test key is refused with forbidden. An inbound Call to a number that routes to no Agent ends with the reason refused_no_route.

Place an outbound Call

curl -X POST "$VOCAL_API/v1/calls" \
  -H "Authorization: Bearer $VOCAL_LIVE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"transport": "phone", "direction": "outbound", "agent_id": "agt_...", "to": "+15555550100"}'

to is the number to dial in E.164 form, and from_number_id names the number to dial from; without it the setting outbound.default_from, and then the Organization's earliest active number with the outbound capability, decide. The answer's client is null, because no browser joins. The number dialled is write-only: no answer, list, log or Audit event repeats it, and the Call carries a destination_hint only.

Before any dial, admission checks the Organization's dial policy and refuses with 403 dial_not_allowed and a reason: live_environment_required for a test key, number_not_outbound_capable or no_from_number for the number to dial from, country_not_allowed for a destination outside allowed_countries, premium_rate while block_premium_rate is on, and outbound_cap_reached at max_concurrent_outbound open outbound Calls. On the Phase 0 host an operator's allowlist of destinations is a second gate, refusing any other number with the reason not_on_environment_allowlist. A Call the callee does not answer ends no_answer; a dial the carrier refuses ends dial_failed.

The dial policy is part of the Organization: PATCH /v1/organization changes it, from the owner in a Member session only.

Not built

Automated provisioning, the free number, the fallback line, SIP trunks of your own and keypad input are planned.