Send call commands

Creates a new outbound call from from to to, handled by the SWML you supply — fetched from url or provided inline as swml. The response returns the new call immediately; the lifecycle events selected in status_events are delivered to status_url as the call progresses. This is the only command that does not take a call id.

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.

Ends the call. The optional reason selects the hangup cause reported for the call; omitted, the call ends as a normal hangup. To disconnect only the peer leg of a connected call and keep this leg up, use calling.disconnect instead.

Disconnects the peer leg of a connected call — for example, one joined by the SWML connect method — while keeping this call leg active. The call must currently be connected. Otherwise, the HTTP response is still 200; the command failure is recorded asynchronously in the call event log with error code 409, rather than delivered to a status webhook. To end the call itself, use calling.end.

Places a call that is on a live AI agent session on hold. The optional prompt is spoken to the caller before hold begins, and timeout limits how long the hold lasts. Requires an active AI agent on the call; resume with calling.ai_unhold.

Takes a call off AI hold and resumes the conversation with the AI agent. Takes no parameters; the call is addressed by id alone.

Injects a message into the conversation of the AI agent on the call — as the system, user, or assistant role — or resets the conversation state via reset. Requires an active AI agent session on the call.

Stops the AI agent running on the call. The call itself stays up — use it to take over with other call commands, or calling.end to hang up entirely.

Attaches a real-time AI observer (a sidecar) to an answered call. The sidecar listens to the conversation and streams advice to your application as webhook callbacks; it never speaks on the call. A call has at most one sidecar, addressed by id alone.

Asks the attached sidecar a one-off question without affecting the live conversation. The HTTP response returns the call object and does not include an ask_id. If the sidecar was started with a callback url, the first callback for the request is ask_request, which carries the generated ask_id. The later ask_answer callback and any request, thought, tool_call, or tool_result callbacks triggered by the ask repeat that ID.

Requests an internal snapshot of the attached sidecar’s activity counters. The HTTP response returns the call object and does not expose the requested snapshot. If the sidecar was started with a callback url, its final callback provides end-of-session totals such as tool calls, insights, and token usage; see the SWML ai_sidecar callback types.

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.

Pauses playback started by calling.play, addressed by its control_id. Resume it with calling.play.resume.

Resumes playback previously paused with calling.play.pause, addressed by its control_id.

Stops playback started by calling.play, addressed by its control_id. A finished state is delivered to the play operation’s status_url webhook.

Adjusts the volume of an active play operation, in dB, addressed by its control_id.

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.

Pauses an active recording, addressed by its control_id. behavior selects whether the paused span is omitted from the file or kept as silence. Resume with calling.record.resume.

Resumes a recording previously paused with calling.record.pause, addressed by its control_id.

Stops an active recording, addressed by its control_id. The finished recording’s URL is delivered to the record operation’s status_url webhook.

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

At least one of digits or speech must be provided. 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.

Stops an active collect operation, addressed by its control_id — including a continuous collect, which otherwise restarts after each result.

Starts the initial-timeout clock for a collect that was started with start_input_timers: false — for example, once a prompt has finished playing and the caller should now respond.

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.

Stops an active detect operation before its timeout elapses, addressed by its control_id.

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.

Stops an active tap, addressed by its control_id, ending delivery of the call’s audio to the external RTP or WebSocket destination.

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. Stop it with calling.transcribe.stop using the same control_id before starting another.

Stops the background transcription started by calling.transcribe, addressed by its control_id, without waiting for the call to end.

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.

Stops an active audio stream, addressed by its control_id, closing delivery to the WebSocket endpoint. The call itself continues.

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.

Disables the noise-reduction filter enabled by calling.denoise. Takes no parameters; denoise is per-call, addressed by id alone.

Controls real-time transcription on the call. The action starts a session, requests an on-demand summary, or stops the session; transcription events and summaries are delivered to the webhook configured on the action. To transcribe the whole call in the background instead, use calling.transcribe.

Controls real-time translation on the call. The action starts a session between two languages, requests an on-demand summary, injects a message to be translated and spoken, or stops the session; translation events are delivered to the configured webhook.

Transfers the call to a new destination. Whatever the call is doing stops immediately and the destination’s SWML takes over; the call keeps the same id, and further commands can still be sent while it remains active.

Stops an in-progress fax send on the call, addressed by its control_id.

Stops an in-progress fax receive on the call, addressed by its control_id.

Sends a SIP REFER on the call, asking the remote SIP endpoint to take the call to a new SIP destination. Available only on SIP calls, with one REFER in progress at a time; refer lifecycle events are delivered to status_url.

Fires a custom JSON event on the call, delivered to the connected client — for example, a Browser SDK client on the call. Use it to trigger client-side behavior; the client-side contract matches the SWML user_event method.