Callsv4

Place a call

POST/calls

Call to from one of the organization's Blooio Voice numbers. The call starts ringing; when the callee answers, handler takes its audio and call.answered fires. With an agent handler, the Blooio agent that owns from talks to the callee. OAuth apps need calls:write.

Headers

AuthorizationRequiredstring

Your API key, sent as a bearer token: Authorization: Bearer <api_key>. Editing this stays in sync with the API key box on the right.

Bearer

Body parameters

JSON

fromRequiredstring

One of the organization's Blooio Voice numbers, in E.164 format.

toRequiredstring

The number to call, in E.164 format.

handlerRequiredCallHandlerRequest

Who takes the call's audio once it's answered. stream: Blooio opens a WebSocket to url and speaks the Blooio media stream protocol (base64 PCMU at 8 kHz both ways; see the Blooio Voice guide); a socket that closes or sends a frame the protocol doesn't define ends the call with handler_disconnected. agent: the Blooio agent that owns the call's number talks to the caller. softphone: the dashboard user making the request takes it in their browser (dashboard only).

typeRequiredstring

"stream""agent""softphone"

urloptionalstring

stream only, required: a wss:// URL.

auth_tokenoptionalstring

stream only: sent as Authorization: Bearer <auth_token> when Blooio connects to url. Kept with the live call only and never returned.

Returns

dataoptionalCall

call_idRequiredstring

Call id (call_...).

channel_idRequiredstring

The Blooio Voice channel (ch_...) the call is on.

directionRequiredstring

"inbound""outbound"

fromRequiredstring

Caller, in E.164 format. A withheld caller ID is the carrier's text instead, such as anonymous, with no contact_id.

toRequiredstring

Callee, in E.164 format.

contact_idRequiredstring | null

The contact on the other end (ct_...).

statusRequiredstring

queued while the dial is placed, ringing, in_progress once answered, then completed. A call that ends unanswered is missed; one whose dial was refused is failed.

"queued""ringing""in_progress""completed""missed""failed"

handlerRequiredCallHandler | null

Who has the call's audio; null until it's answered, and while a call the agent handed off waits for a teammate.

CallHandler

typeRequiredstring

"stream""softphone""agent""phone"

urloptionalstring

stream only: the WebSocket URL the audio streams to.

tooptionalstring

phone only: the number the call was transferred to.

null

answered_by_user_idRequiredstring | null

The dashboard user holding the call on their softphone.

hangup_causeRequiredstring | null

The carrier's hangup cause, e.g. normal_clearing.

errorRequiredCallError | null

CallError

codeRequiredstring

messageRequiredstring

null

created_atRequiredinteger

Epoch ms.

answered_atRequiredinteger | null

Epoch ms.

ended_atRequiredinteger | null

Epoch ms.

Response codes

201The call

400`invalid_body`, or `invalid_field` (with the `field`) for a bad `from`, `to`, or `handler`.

401Your API key is missing or invalid. Pass it as a bearer token.

403`feature_not_enabled`: Blooio SMS and Blooio Voice aren't enabled on this organization.

404`voice_number_not_found`: `from` isn't one of the organization's Blooio Voice numbers.

409`agent_unavailable`: no live Blooio agent owns `from`.

422`call_rejected`: the carrier refused the call. The call is recorded as `failed`.

502`upstream_unavailable`: the carrier network couldn't be reached. Retry with backoff.

503`telephony_unavailable`: Blooio Voice isn't configured.

Sends a live request with your values and shows the real response below. Your key is stored only in this browser.

Request

curl -X POST https://api.blooio.com/v4/calls \

  -H "Authorization: Bearer bl_live_..." \  -H "Content-Type: application/json" \  -d '{    "from": "+14155550123",    "to": "+15551234567",    "handler": {      "type": "stream",      "url": "wss://voice.example.com/calls",      "auth_token": "secret-token"    }  }'

Body object

{  "from": "+14155550123",  "to": "+15551234567",  "handler": {    "type": "stream",    "url": "wss://voice.example.com/calls",    "auth_token": "secret-token"  }}

Response objectexample

{  "data": {    "call_id": "obj_a1b2c3d4",    "channel_id": "ch_a1b2c3d4",    "direction": "inbound",    "from": "+15551234567",    "to": "+15551234567",    "contact_id": "ct_a1b2c3d4",    "status": "queued",    "handler": {      "type": "stream",      "url": "https://example.com",      "to": "+15551234567"    },    "answered_by_user_id": "obj_a1b2c3d4",    "hangup_cause": "string",    "error": {      "code": "string",      "message": "Hello from Blooio!"    },    "created_at": 0,    "answered_at": 0,    "ended_at": 0  }}