For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Log inSign up
Support
  • Core
    • Overview
    • Authorization
    • Base URL
    • Data formats
    • Paging
    • Error codes
    • Permissions
  • Calling
      • POSTSend call commands
  • Datasphere
  • Logs
  • Messaging
  • Phone Number Management
  • Platform
  • Resource Management
LogoLogoSignalWire Docs
Log inSign up
Support
CallingCalls

Send call commands

|View as Markdown|Open in Claude|
POST
https://{your_space_name}.signalwire.com/api/calling/calls
POST
/api/calling/calls
$curl -X POST https://{your_space_name}.signalwire.com/api/calling/calls \
>     -H "Content-Type: application/json" \
>     -u "<project_id>:<api_token>" \
>     -d '{
>  "command": "dial",
>  "params": {
>    "from": "+15551234567",
>    "to": "+15559876543",
>    "caller_id": "+15551234567",
>    "status_url": "https://example.com/status_callback",
>    "status_events": [
>      "answered",
>      "ended"
>    ],
>    "codecs": [
>      "PCMU",
>      "PCMA"
>    ],
>    "timeout": 30,
>    "max_price_per_minute": 0.05,
>    "url": "https://example.com/swml"
>  }
>}'
1{
2  "id": "0e9c80d7-a149-4917-892d-420043709f45",
3  "from": "+12069708643",
4  "to": "+15550198765",
5  "direction": "outbound-api",
6  "source": "realtime_api",
7  "url": null,
8  "charge": 0,
9  "created_at": "2024-05-06T12:20:00Z",
10  "charge_details": [
11    {
12      "description": "Outbound Voice",
13      "charge": 0.004
14    }
15  ],
16  "status": "queued",
17  "duration": null,
18  "duration_ms": null,
19  "billing_ms": null,
20  "type": "relay_pstn_call",
21  "parent_id": null
22}
Unified JSON-RPC style endpoint for executing call methods through command-based dispatch. Send a request with the appropriate `command` field to invoke the desired call operation. All async-safe RELAY methods can be sent through this endpoint without a WebSocket connection. ## Supported Commands Use one of the following commands in the `command` field of the request body to perform the corresponding action on an active call. For more details on each command, refer to the individual API reference documentation linked below. | Command | Description | |---------|-------------| | `dial` | Create and initiate a new outbound call | | `update` | Modify an active call's dialplan in real-time | | `calling.end` | Terminate an active call immediately | | `calling.transfer` | Transfer a call to a new destination (SIP URI, phone number, or inline SWML) | | `calling.disconnect` | Disconnect bridged calls without hanging up either leg | | `calling.play` | Play audio, TTS, silence, or ringtone to a call | | `calling.play.pause` | Pause active playback | | `calling.play.resume` | Resume paused playback | | `calling.play.stop` | Stop active playback | | `calling.play.volume` | Adjust playback volume | | `calling.record` | Start recording a call | | `calling.record.pause` | Pause active recording | | `calling.record.resume` | Resume paused recording | | `calling.record.stop` | Stop active recording | | `calling.collect` | Collect DTMF or speech input | | `calling.collect.stop` | Stop active collection | | `calling.collect.start_input_timers` | Start input timers on active collect | | `calling.detect` | Start a detector (answering machine, fax, or digit) | | `calling.detect.stop` | Stop active detector | | `calling.tap` | Tap call audio to an RTP or WebSocket endpoint | | `calling.tap.stop` | Stop active tap | | `calling.transcribe` | Start background transcription of a call | | `calling.transcribe.stop` | Stop active transcription | | `calling.stream` | Stream call audio to a WebSocket endpoint | | `calling.stream.stop` | Stop active stream | | `calling.denoise` | Start noise reduction on a call | | `calling.denoise.stop` | Stop noise reduction | | `calling.ai_hold` | Place an AI call on hold | | `calling.ai_unhold` | Resume an AI call from hold | | `calling.ai_message` | Inject a message into an active AI conversation | | `calling.ai.stop` | Stop an active AI session | | `calling.live_transcribe` | Start, stop, or summarize real-time transcription | | `calling.live_translate` | Start, stop, summarize, or inject real-time translation | | `calling.send_fax.stop` | Stop active fax send | | `calling.receive_fax.stop` | Stop active fax receive | | `calling.refer` | Transfer a SIP call via SIP REFER | | `calling.user_event` | Fire a custom user event on the call | #### Permissions The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Voice_. [Learn more about API scopes](/docs/platform/your-signalwire-api-space).
Was this page helpful?
Previous

Create queue

Next
Built with

Unified JSON-RPC style endpoint for executing call methods through command-based dispatch. Send a request with the appropriate command field to invoke the desired call operation. All async-safe RELAY methods can be sent through this endpoint without a WebSocket connection.

Supported Commands

Use one of the following commands in the command field of the request body to perform the corresponding action on an active call. For more details on each command, refer to the individual API reference documentation linked below.

CommandDescription
dialCreate and initiate a new outbound call
updateModify an active call’s dialplan in real-time
calling.endTerminate an active call immediately
calling.transferTransfer a call to a new destination (SIP URI, phone number, or inline SWML)
calling.disconnectDisconnect bridged calls without hanging up either leg
calling.playPlay audio, TTS, silence, or ringtone to a call
calling.play.pausePause active playback
calling.play.resumeResume paused playback
calling.play.stopStop active playback
calling.play.volumeAdjust playback volume
calling.recordStart recording a call
calling.record.pausePause active recording
calling.record.resumeResume paused recording
calling.record.stopStop active recording
calling.collectCollect DTMF or speech input
calling.collect.stopStop active collection
calling.collect.start_input_timersStart input timers on active collect
calling.detectStart a detector (answering machine, fax, or digit)
calling.detect.stopStop active detector
calling.tapTap call audio to an RTP or WebSocket endpoint
calling.tap.stopStop active tap
calling.transcribeStart background transcription of a call
calling.transcribe.stopStop active transcription
calling.streamStream call audio to a WebSocket endpoint
calling.stream.stopStop active stream
calling.denoiseStart noise reduction on a call
calling.denoise.stopStop noise reduction
calling.ai_holdPlace an AI call on hold
calling.ai_unholdResume an AI call from hold
calling.ai_messageInject a message into an active AI conversation
calling.ai.stopStop an active AI session
calling.live_transcribeStart, stop, or summarize real-time transcription
calling.live_translateStart, stop, summarize, or inject real-time translation
calling.send_fax.stopStop active fax send
calling.receive_fax.stopStop active fax receive
calling.referTransfer a SIP call via SIP REFER
calling.user_eventFire a custom user event on the call

Permissions

The API token used to authenticate must have the following scope(s) enabled to make a successful request: Voice.

Learn more about API scopes.

Authentication

AuthorizationBasic
SignalWire Basic Authentication using Project ID and API Token. The client sends HTTP requests with the Authorization header containing the word Basic followed by a space and a base64-encoded string of project_id:token. The project ID will be used as the username and the API token as the password. Example: ``` Authorization: Basic base64(project_id:token) ```

Request

This endpoint expects an object.
dialobjectRequired
OR
updateobjectRequired

Update a call in progress — cancel, complete, or redirect the SWML flow.

State-transition rules:

  • status: canceled is only valid while the leg is queued or ringing.
  • status: completed is only valid while the leg is answered (or in-progress).
  • Supplying url or swml (redirect) is only valid while the leg is answered.
  • Calls in terminal states (busy, failed, no-answer, canceled, completed) cannot be updated.
OR
calling.endobjectRequired
OR
calling.disconnectobjectRequired
OR
calling.ai_holdobjectRequired
OR
calling.ai_unholdobjectRequired
OR
calling.ai_messageobjectRequired
OR
calling.ai.stopobjectRequired
OR
calling.playobjectRequired

Play media (audio files, text-to-speech, silence, or ringtones) on an active call.

The HTTP response confirms the command was accepted. Playback lifecycle is delivered asynchronously via the status_url webhook, with payloads of the form {control_id, call_id, node_id, state} where state is one of playing, paused, finished, or error.

OR
calling.play.pauseobjectRequired
OR
calling.play.resumeobjectRequired
OR
calling.play.stopobjectRequired
OR
calling.play.volumeobjectRequired
OR
calling.recordobjectRequired

Starts recording an active call. The HTTP response returns the call leg — the recording URL is not included. Recording runs asynchronously; provide status_url to receive a webhook when the recording finishes (with the final URL), or query the call’s events endpoint.

OR
calling.record.pauseobjectRequired
OR
calling.record.resumeobjectRequired
OR
calling.record.stopobjectRequired
OR
calling.collectobjectRequired

Collect user input (DTMF digits, speech, or both) on an active call.

At least one of digits or speech must be provided; requests missing both return 400. Results are delivered asynchronously via the status_url webhook. Digit events have the shape {control_id, call_id, node_id, result: {type:"digit", params: {digits, terminator}}} and speech events {..., result: {type:"speech", params: {text, confidence}}}.

When start_input_timers is false, the initial_timeout clock does not start until you send calling.collect.start_input_timers for the same control_id.

OR
calling.collect.stopobjectRequired
OR
calling.collect.start_input_timersobjectRequired
OR
calling.detectobjectRequired

Start detection (answering machine, fax tone, or DTMF digits) on an active call.

Detection runs asynchronously up to timeout seconds. Results are delivered via the status_url webhook.

OR
calling.detect.stopobjectRequired
OR
calling.tapobjectRequired

Capture audio from an active call and stream it to an external destination.

Audio is streamed via RTP (to a public IP/port) or WebSocket (to a ws:///wss:// URI). Stop the tap with calling.tap.stop using the same control_id.

OR
calling.tap.stopobjectRequired
OR
calling.transcribeobjectRequired

Transcribe the entire call in the background.

The transcription covers the whole call and completes when the call ends. For real-time transcription, use calling.live_transcribe. Only one transcription can be active on a call at a time; starting another while one is running returns a 409 conflict. Stop it with calling.transcribe.stop using the same control_id.

OR
calling.transcribe.stopobjectRequired
OR
calling.streamobjectRequired

Stream call audio to an external WebSocket endpoint.

Audio is sent to a wss:// URL; custom_parameters pass through to the endpoint as connection metadata. Stream lifecycle webhooks are delivered to status_url (default method POST). Stop the stream with calling.stream.stop using the same control_id.

OR
calling.stream.stopobjectRequired
OR
calling.denoiseobjectRequired

Enable noise reduction on an active call. Denoise is per-call (no control_id); a call has at most one active denoise filter. Use calling.denoise.stop to disable it.

OR
calling.denoise.stopobjectRequired
OR
calling.live_transcribeobjectRequired
OR
calling.live_translateobjectRequired
OR
calling.transferobjectRequired
OR
calling.send_fax.stopobjectRequired
OR
calling.receive_fax.stopobjectRequired
OR
calling.referobjectRequired
OR
calling.user_eventobjectRequired

Response

The request has succeeded.
Call Legobject
Returned when the call is a standard PSTN, SIP, or WebRTC call.
OR
Fabric Subscriber Device Legobject

Returned when the call is a Fabric subscriber device leg. The status field is always null for this type.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
422
Unprocessable Entity Error
500
Internal Server Error

SignalWire Basic Authentication using Project ID and API Token.

The client sends HTTP requests with the Authorization header containing the word Basic followed by a space and a base64-encoded string of project_id:token. The project ID will be used as the username and the API token as the password.

Example:

Authorization: Basic base64(project_id:token)