Call control

Answer, hang up, and disconnect active call sessions. These commands are sent to the session command endpoint and do not have their own rate-limit group.

Note

All session commands share one base path: POST /api/v1/sessions/{uuid}/commands/{command}. The {uuid} must match an active session owned by your application.

Common response format

All session commands return 202 Accepted with a deferred operation envelope:

{
  "operation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "in_progress",
  "timeout_ms": 2000
}

The final result is delivered asynchronously via a command.result webhook.

Common request fields

Field	Type	Required	Description
command_uid	string	optional	Caller-supplied idempotency key. Auto-generated UUID if omitted. Max 128 chars, ^[a-zA-Z0-9._-]+$.

Answer

Answer an incoming call. The result arrives asynchronously via webhook after the underlying execute completes (deferred response, 2 s timeout).

POST /api/v1/sessions/{uuid}/commands/answer Copy

curl -X POST https://gateway.example.com/api/v1/sessions/{uuid}/commands/answer \
  -H "X-App-ID: YOUR_APP_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Request body — no additional fields beyond the optional command_uid.

Triggered webhooks

• call.answered — fired on execute-complete confirmation.
• command.result — deferred; fires on execute complete or after the 2 s timeout.

Hangup

Hang up a call with an optional Q.850 cause code. The command.result webhook fires immediately (fire-and-forget). A separate call.hangup lifecycle webhook fires later, when the channel is fully torn down.

POST /api/v1/sessions/{uuid}/commands/hangup Copy

curl -X POST https://gateway.example.com/api/v1/sessions/{uuid}/commands/hangup \
  -H "X-App-ID: YOUR_APP_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cause": "USER_BUSY"}'

Request body

Field	Type	Required	Description
cause	string	optional	Q.850 hangup cause code. Defaults to NORMAL_CLEARING. Max 64 chars, ^[A-Z_]+$.

Triggered webhooks

• command.result — immediate; fires right after command dispatch.
• call.hangup — deferred lifecycle event; fires when channel teardown completes.

Disconnect

Disconnect the session and return control to the dialplan. Typically results in the call being hung up shortly after. The command.result webhook fires immediately.

POST /api/v1/sessions/{uuid}/commands/disconnect Copy

curl -X POST https://gateway.example.com/api/v1/sessions/{uuid}/commands/disconnect \
  -H "X-App-ID: YOUR_APP_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Request body — no additional fields beyond the optional command_uid.

Triggered webhooks

• command.result — immediate; fires right after command dispatch.