Agent Number

POST /voice/dial

Place an outbound voice call

Description

Dials a destination number from one of the bearer's owned numbers. Returns a `call_id` and a `stream_url` (WebSocket) that the agent opens to send/receive 16 kHz PCM audio frames. The destination phone is ringing by the time this returns. Close the stream WS to hang up.

Authentication

Bearer required. Send Authorization: Bearer <token>.

Code samples

Pick your runtime. Every sample is in the page source — switching tabs is for your eyes.

curl https://agentnumber.really.com/voice/dial \
  --request POST \
  --header 'Authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --data '{
  "phone_number": "+15555550123",
  "to": "+15555550199"
}'

Request body

FieldTypeDescription
phone_number required string An E.164 phone number this bearer's subscription owns. The call is placed FROM this number.
Example: +15555550123
to required string E.164 destination.
Example: +15555550199

Example body

{
  "phone_number": "+15555550123",
  "to": "+15555550199"
}

Responses

200 Call placed; open the WebSocket at `stream_url` for audio.

{
  "call_id": "call_example_0000000000000000000000",
  "stream_url": "wss://agentnumber.really.com/voice/stream/call_example_0000000000000000000000",
  "direction": "outbound",
  "caller": "+15555550199",
  "phone_number": "+15555550123"
}

401 Missing, invalid, revoked, or expired bearer token.

{
  "error": "unauthorized",
  "message": "invalid bearer token"
}

403 Bearer doesn't own the requested `phone_number`.

{
  "error": "forbidden",
  "message": "phone_number not owned by this token"
}

404 `phone_number` not found or has no active subscription owned by this bearer.

{
  "error": "phone_number_not_found"
}

409 Subscription isn't yet bound to a hardware slot — provisioning is still in progress.

{
  "error": "subscription_not_bound",
  "message": "subscription isn't bound to a (device_id, sim_number) slot"
}

502 Mac phone-node unreachable, or it returned a non-2xx for the dial request.

{
  "error": "mac_unreachable",
  "message": "phone node returned 503"
}