Call Control API

Use Blocx Call Control to place outbound calls, answer inbound calls, connect two answered calls, speak text and send keypad digits. Calls and commands run asynchronously: an API response acknowledges the request, while call events report progress. The Calls dashboard shows the same call history and controls.

For dashboard setup, see Programmable Calling. This reference covers server-side integrations. The current controls do not provide browser microphone audio, recording, transcription or conference management.

Before you start

Your account needs an active plan or trial, approved identity verification, phone-service access and a configured calling rate. Prepaid accounts need sufficient available balance. Use a number owned by your account with Programmable calling enabled. An incoming call rings until your application or a team member answers it, or it times out.

Create credentials under Developer → API Keys. Grant only the permissions your integration needs:

Task Permission
List numbers and read their settings numbers.read
Enable or disable programmable calling numbers.write
List calls and retrieve a call calls.read
Place calls and send commands calls.write
Create or update event subscriptions through the API webhooks.write

Phone and call endpoints also check the account's sms capability and identity verification. Existing API keys may need their permission sets updated to include calls. Credentials can only access calls and numbers in their own account.

Authentication and endpoints

Use https://api.otterblocx.com as the base URL, or your deployment's Blocx API address. Every request includes these headers:

x-access-key-id: YOUR_ACCESS_KEY_ID
x-secret-access-key: YOUR_SECRET_ACCESS_KEY
Content-Type: application/json

Keep credentials on your server. The shell examples below read BLOCX_ACCESS_KEY_ID and BLOCX_SECRET_ACCESS_KEY from your environment. Phone numbers and UUIDs are examples; replace them before making a new call. Save each request body and UUID so an interrupted request can be retried unchanged.

Method and path Purpose Success response
PUT /phone-numbers/{id}/calling Change a number's calling mode 200, calling settings
POST /calls Request an outbound call 202, call object
GET /calls List call history 200, paginated calls
GET /calls/{id} Retrieve a call 200, call object
POST /calls/{id}/actions Submit or check a command 202, command receipt

phoneNumberId and the number configuration path use numeric number IDs. Call paths and bridge targets use the UUID returned in a call's id field. A request ID identifies a dial operation; it is not the call ID.

Enable a number

Find the number's numeric ID with GET /phone-numbers, then enable calling:

curl -i -X PUT 'https://api.otterblocx.com/phone-numbers/123/calling' \
  -H "x-access-key-id: $BLOCX_ACCESS_KEY_ID" \
  -H "x-secret-access-key: $BLOCX_SECRET_ACCESS_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"enabled":true}'

The response is {"enabled":true}. Send {"enabled":false} to disable this mode. Disable call forwarding first: forwarding and programmable calling cannot be enabled together. End live calls before changing a number's calling mode. An incompatible mode or live call returns 409.

Subscribe to call events before activating inbound calling. GET /phone-numbers?callControlEnabled=true lists numbers with programmable calling enabled.

Place an outbound call

curl -i -X POST 'https://api.otterblocx.com/calls' \
  -H "x-access-key-id: $BLOCX_ACCESS_KEY_ID" \
  -H "x-secret-access-key: $BLOCX_SECRET_ACCESS_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "requestId": "d0c27165-ad68-496f-83b7-ce23c034c20d",
    "phoneNumberId": 123,
    "to": "+14155550123",
    "timeoutSeconds": 30
  }'
Field Required Meaning
requestId Yes UUID created once for this dial operation. Reuse it for retries.
phoneNumberId Yes Positive integer ID of your calling-enabled number. This selects the caller number.
to Yes Destination in E.164 format, including + and country code. It must differ from the caller number.
timeoutSeconds No Unanswered-call timeout, an integer from 5 to 120 seconds. Defaults to 30.

An initial 202 response can look like this:

{
  "id": "35a4be1e-8ebe-4630-b9bd-971c3e921388",
  "phoneNumberId": 123,
  "direction": "outbound",
  "from": "+14155550100",
  "to": "+14155550123",
  "status": "initiating",
  "durationSeconds": 0,
  "amountMicros": "0",
  "rateMicros": "20000",
  "createdAt": "2026-11-20T10:00:00.000Z",
  "answeredAt": null,
  "endedAt": null
}

The example rate is illustrative, not a published price. Save the returned call id. Status may already have advanced by the time you receive the response. Repeating a saved dial request returns that call's current state, including completed or failed; 202 does not mean a second call was placed.

Call state and history

Status Meaning
initiating The dial request is recorded, but call progress has not yet been confirmed. An interrupted response can leave a call in this state.
ringing The call has started and is waiting to be answered.
active An answer has been observed. Speech, digits and bridging are available.
completed An end event has been observed. The call may have been answered or unanswered. Usage can still be awaiting delayed information.
failed The dial was rejected, or its outcome remained unconfirmed beyond the recovery window. Inspect history before intentionally creating a replacement.

Use GET /calls/{id} to retrieve the current call object. answeredAt and endedAt are nullable ISO 8601 timestamps. An inbound caller whose number is unavailable may appear as Anonymous in from. durationSeconds represents settled answered duration, not a live timer. amountMicros and rateMicros are integer strings in microdollars: 1000000 equals USD 1.

List history with optional filters:

curl 'https://api.otterblocx.com/calls?page=1&limit=25&status=active&phoneNumberId=123' \
  -H "x-access-key-id: $BLOCX_ACCESS_KEY_ID" \
  -H "x-secret-access-key: $BLOCX_SECRET_ACCESS_KEY"

page defaults to 1 and must be positive. limit defaults to 25 and accepts 1–100. status accepts one state from the table above; phoneNumberId accepts one positive integer. Omit a filter to include all matching calls in your account. Results are ordered newest first.

{
  "data": [],
  "page": 1,
  "limit": 25,
  "count": 0,
  "canControl": true
}

count is the total matching record count, not just the current page size. canControl indicates whether your credentials grant calls.write; account access, balance and call-state checks still apply to each command.

Control a call

Send commands to POST /calls/{id}/actions. Each command requires a UUID commandId, created once for that action and reused on retries. Request bodies reject fields that do not belong to the selected action.

For example, end a call:

curl -i -X POST 'https://api.otterblocx.com/calls/35a4be1e-8ebe-4630-b9bd-971c3e921388/actions' \
  -H "x-access-key-id: $BLOCX_ACCESS_KEY_ID" \
  -H "x-secret-access-key: $BLOCX_SECRET_ACCESS_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"action":"hangup","commandId":"08ce437e-24e8-4c72-a17f-9df730c25b12"}'

The following bodies use the same endpoint, substituting the call you want to control.

Answer

Only a ringing inbound call can be answered. Wait for call.answered before sending speech, digits or a bridge command.

{
  "action": "answer",
  "commandId": "6bdfe6a3-048d-48cc-a273-fdb17691908f"
}

Hang up

End a live call. A call still being initialized may return 409 until it is available for control. A completed call also returns 409 for a new hangup command.

{
  "action": "hangup",
  "commandId": "08ce437e-24e8-4c72-a17f-9df730c25b12"
}

Authenticated hangup requests remain available during maintenance and when paid access, phone-service access or verification is revoked. Call ownership and calls.write are always required; accounts being deleted cannot send commands.

Speak text

Speak plain text on an active call. text is trimmed and must contain 1–3,000 characters. voice is female (default) or male. language supports en-US only and defaults to that value. Treat the content as plain text; SSML is not supported. Completion is reported through call.speech-ended.

{
  "action": "speak",
  "commandId": "a975cdbd-e435-44fa-ab39-0d09a73be84b",
  "text": "Hello, thank you for calling. Press one for sales.",
  "voice": "female",
  "language": "en-US"
}

Send keypad digits

Send a sequence of 1–64 characters on an active call. Supported characters are 0–9, uppercase A–D, *, #, w (half-second pause) and W (one-second pause). Spaces are not accepted. This sends tones to the other end of the call; call.digits-received reports tones received from the caller.

{
  "action": "send-digits",
  "commandId": "b13ed331-1f42-45a6-b3f5-2a5179f1d99c",
  "digits": "1w23#"
}

Bridge two calls

Both calls must be active and belong to your account. Send the command to the first call's actions endpoint and put the second call's Blocx UUID in callId. A call cannot bridge to itself. Each answered leg is billed separately.

{
  "action": "bridge",
  "commandId": "f866e109-deb6-4b30-92e5-ce095362b529",
  "callId": "2ba6ebbf-3b4e-46f5-9889-e03c4ee51f78"
}

Command receipts

Commands return 202 with a receipt:

{
  "commandId": "a975cdbd-e435-44fa-ab39-0d09a73be84b",
  "status": "accepted"
}
Receipt status Meaning and next step
accepted The command was submitted. Use events and call state to observe the result.
pending A receipt exists, but submission was interrupted or is still in progress. Inspect call state and reuse the original body to check the receipt.
failed The command was rejected. Resolve the cause before intentionally creating a new command.

Check a receipt by repeating POST /calls/{id}/actions with the same body. There is no separate receipt lookup endpoint. A pending receipt is not evidence that the action failed; contact support if its outcome remains unclear.

Safe retries

Calling uses requestId and commandId in the JSON body. The messaging API's Idempotency-Key header does not replace these fields.

  1. Generate and persist a UUID and request body before the first submission.
  2. On a timeout, network interruption or 5xx response, retry the same endpoint with the same UUID and body.
  3. Inspect the returned call or receipt. A stored dial or command is not submitted again by a retry.
  4. Create a new UUID only for an intentional new call or action, after resolving any uncertain earlier outcome.

Dial request IDs are scoped to your account. Command IDs are scoped to the call. Reusing a recorded ID with different parameters returns 409. Authentication and validation errors can occur before a request is recorded, so resolve the reported cause; do not use a new ID to bypass an uncertain result. Retain IDs with your own calling records and never recycle them for unrelated work.

Receive call events

Create an HTTPS endpoint under Developer → Webhooks, select the events you need and save its signing secret. Configuring Webhooks explains signature verification and delivery handling.

Event Meaning
call.initiated An inbound or outbound call started.
call.answered The call was answered.
call.ended The call ended, including unanswered calls.
call.bridged Two call legs were connected.
call.speech-ended Spoken text finished playing.
call.digits-received A keypad digit was received; data.digit contains the digit.

Example delivery:

{
  "id": "evt_51fcfe65-10ad-4832-a076-8d94ea09d6c4",
  "type": "call.ended",
  "createdAt": "2026-11-20T10:01:12.000Z",
  "data": {
    "occurredAt": "2026-11-20T10:01:11.000Z",
    "call": {
      "id": "35a4be1e-8ebe-4630-b9bd-971c3e921388",
      "phoneNumberId": 123,
      "direction": "outbound",
      "from": "+14155550100",
      "to": "+14155550123",
      "status": "completed",
      "durationSeconds": 61,
      "amountMicros": "40000",
      "rateMicros": "20000",
      "createdAt": "2026-11-20T10:00:00.000Z",
      "answeredAt": "2026-11-20T10:00:10.000Z",
      "endedAt": "2026-11-20T10:01:11.000Z"
    }
  }
}

Verify Blocx-Signature over the raw body before trusting an event. Blocx-Event identifies its type and Blocx-Event-Id matches its id. Deduplicate durably by event ID, store or queue the event, and respond promptly with a 2xx status. Keep command IDs stable when a redelivered event triggers an action.

Events can arrive more than once, late or out of order. data.occurredAt is the event time; top-level createdAt is the notification creation time. data.call is a snapshot and may already include a later state. Use GET /calls/{id} when you need the latest state. An ended event may initially contain zero usage if answer information has not arrived yet.

Example inbound workflow

  1. Receive and verify call.initiated. Check data.call.direction is inbound and the call is still ringing.
  2. Persist an answer command UUID for that call, then submit answer.
  3. On call.answered, submit a speak command with its own persisted UUID.
  4. On call.digits-received, use data.digit to select the next step. To connect an agent, dial the agent and wait until both legs are active before bridging them.
  5. On call.ended, close the conversation in your application and retrieve the latest usage when needed.

Billing and limits

Each answered call leg is charged per started minute at the rate captured when it starts:

charge in microdollars = ceil(durationSeconds / 60) × rateMicros

A 61-second leg is billed for two minutes. Two bridged legs each accrue their own answered duration. Unanswered calls have no usage charge. The call's rate and prepaid or postpaid billing mode are retained if its account changes plans while the call is in progress.

Usage is settled after the call ends and answer information is available. Until then, zero duration or charge does not establish that the call was free. Completed usage remains payable if other activity has depleted a prepaid balance. Billing history describes this usage as Calling.

Your deployment sets the concurrent-call limit and maximum call duration. A new dial over the concurrent limit returns 429. timeoutSeconds controls unanswered outbound ringing; it does not change the maximum answered-call duration. Contact support for your account's rate and deployment limits.

Error handling

Errors include an error message; validation errors may also include a fields object. Account restrictions may include a code.

HTTP status Common cause Next step
400 Invalid UUID, destination, command fields or unsupported speech options Correct the input using the field limits above.
401 Missing or invalid credentials Check both authentication headers.
402 Account access, phone-service capability or available balance is insufficient Resolve the specific restriction in Billing or contact support.
403 Missing permission or identity verification Update the permission set or complete verification.
404 The call or calling-enabled number is unavailable to your account; a bridge target may also be inactive Check the Blocx ID, ownership and target state.
409 Wrong call state, conflicting number mode or reuse of an ID with different parameters Retrieve current state; preserve the original request body when retrying.
429 Concurrent-call limit reached End or wait for a live call before dialing again.
502 The calling service could not complete or confirm the request Retry with the same UUID and body, then inspect the call or receipt.
503 Calling or pricing is not configured, or maintenance is in progress Follow Retry-After when present or contact support. Preserve request IDs.

Related guides