Programmable Calling

Blocx calling lets your application place and answer calls, connect two answered calls, speak text and send keypad digits. The Calls page provides these controls alongside your call history. Audio is handled through spoken text and connected phone calls; the dashboard does not use your browser microphone.

For complete endpoint definitions, request and response examples, and retry rules, see the Call Control API reference.

Enable a number

Open Numbers → Manage, select a number and enable Programmable calling. If call forwarding is enabled, disable it first. Incoming calls in programmable mode ring until your application or a team member answers them. Subscribe to call events before enabling a number so your application can respond to incoming calls.

End live calls before changing the number's calling mode. You can disable programmable calling from the same number settings page once those calls have ended.

Calling requires an active plan or trial, verified identity, phone-number access and a configured calling rate. Contact support if calling is unavailable. Changing a number's calling settings requires numbers.write. Reading history requires calls.read; placing and controlling calls requires calls.write. Add these permissions to existing API keys as needed.

Use the dashboard

  1. Open Calls, select your calling-enabled number and enter a destination with + and its country code.
  2. Select Place call. Its status updates as the call progresses.
  3. Select Details in call history. Answer a ringing inbound call, end a live call, or use the controls on an answered call.
  4. To connect two people, place a call to each person, wait for both calls to be answered, then paste the second call's ID into Connect to an answered call on the first call.

Speak text reads your message aloud in US English (en-US), using a female or male voice. Keypad digits sends numbers, * and #, plus A–D tones. Use w for a half-second pause or W for a one-second pause.

The dashboard's speech control uses the female voice; the API also lets you choose male. Speech accepts up to 3,000 characters and keypad sequences accept up to 64 characters. Both controls require an answered call.

History shows call direction and can be filtered by status and paged through. Details shows the call ID, caller and destination, state, settled duration, charge and per-minute rate. Duration and charge are settled figures, not live counters. Team members without calls.write can inspect history when they have calls.read, but cannot place or control calls.

If a response is interrupted, Check call request or Check command receipt checks the original request using its saved ID. Keep checking that request or contact support if its outcome remains unclear. A Command accepted message means the command was submitted; watch the call status to see the result.

Use the API

Authenticate with your Blocx API credentials. Enable a number with PUT /phone-numbers/{id}/calling and {"enabled":true}. Then call POST /calls:

{
  "requestId": "d0c27165-ad68-496f-83b7-ce23c034c20d",
  "phoneNumberId": 123,
  "to": "+14155550123",
  "timeoutSeconds": 30
}

The 202 response contains a Blocx call id. Get current status with GET /calls/{id}, or list your calls with GET /calls. Send commands to POST /calls/{id}/actions:

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

Supported actions are answer, hangup, bridge (with the other Blocx callId), speak and send-digits (with digits). A bridge can only connect answered calls in your own account. An accepted command reports that it was submitted; call events report its outcome.

Always reuse the same requestId or commandId when retrying an interrupted request. Reusing an ID with different parameters returns 409. If a request remains pending, inspect its call status and contact support; submitting a new ID could initiate another call or action.

Call events

In Developer → Webhooks, subscribe to call.initiated, call.answered, call.ended, call.bridged, call.speech-ended and call.digits-received. Each event includes data.call with a Blocx call ID and data.occurredAt. Keypad events also include data.digit.

Events can arrive more than once or out of order. Deduplicate using the event id, compare occurredAt, and retrieve the call when you need its latest status or finalized charge. Follow the standard Blocx webhook signature verification instructions.

Billing and limits

Each answered call leg is billed per started minute at the rate captured when the call starts. A 61-second call is billed for two minutes. Bridging two calls bills both answered legs. Unanswered calls have no usage charge. Duration and charges finalize after the call ends and answer information is received.

Charges appear as Calling in billing history. Account balance is checked before dialing or answering; completed usage is settled even if other activity has depleted the balance. Calls have a maximum duration and accounts have a concurrent-call limit. Unanswered calls also time out. Keep sufficient balance available before calling.

Troubleshooting

What you see What to check
No number in the From list Enable programmable calling on an owned number and confirm you can read its settings.
Calling cannot be enabled Disable forwarding, end live calls, and confirm account access and identity verification. Contact support if the calling rate is not configured.
Speak, Send or Connect is unavailable Wait until the call is active, confirm your calling permissions, and check any pending command receipt.
A call stays at initiating Its outcome may still be unconfirmed. Check the original request and contact support before placing a replacement.
An ended call shows zero duration or charge It may have been unanswered, or answer information may still be arriving. Refresh its details before treating the charge as final.

Related articles