--- title: "Send call commands" method: POST path: "/api/calling/calls" tags: ["Calls"] --- # Send call commands `POST /api/calling/calls` 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). ## Request body - union — Call request union for JSON-RPC style method dispatch. Use the `command` field to specify which call method to invoke. All async-safe RELAY methods can be sent through this endpoint without a WebSocket connection. - object - `command` 'dial', required — The `dial` command is used to create a new call. - `params` union, required — An object of parameters that will be utilized by the active command. - CallingCallCreateParamsURL - `from` string, required — The address that initiates the call. For PSTN destinations, must be an E.164 number; for SIP/Verto destinations may also be a SIP URI (`sip:user@host`) or a short caller-id token. - `to` string — Destination address. Accepts E.164 (`+xxxxxxxxxxx`), SIP URI (`sip:` / `sips:`), Verto URI (`verto:`), client address (`client:`), or a fabric address. Required unless `to_script` is provided. - `to_script` union — Inline SWML document (JSON or YAML string), or an `http(s)://` URL that returns one, executed at the destination end. Useful for directing the call to a RelayBin / external SWML handler. When present, `to` may be omitted. - string - SWMLCallingSWMLObject — A SWML document for handling inbound and outbound calls. Contains a `sections` map where each section holds an array of methods that run sequentially. Execution starts at `sections.main`. See the [Calling SWML reference](/docs/swml/reference/calling) for the full list of available methods. - `version` '1.0.0' - `sections` SWMLCallingSection, required - … - `caller_id` string — Caller ID displayed to the destination. E.164 for PSTN; short caller-id token or SIP URI for SIP/Verto. - `fallback_url` string — Fallback URL that returns SWML if the primary `url` fails. - `status_url` string, uri — HTTP or HTTPS URL that receives call lifecycle webhooks for events listed in `status_events`. - `status_events` string[] — Call lifecycle events that will be delivered to `status_url`. - `url_method` 'GET' | 'POST' — HTTP method used when requesting the `url`. Defaults to `POST`. - `codecs` union — Codecs to offer on the outbound call. May be provided as an array of enum values or a comma-separated string of the same values. If the `to` value is a SIP URI containing `codecs=...`, those take precedence. - CallingOutboundCallCodec[] - string - `timeout` integer — Ring timeout in seconds. Must be between 1 and 600. - `max_price_per_minute` number, double — Maximum per-minute price (in dollars). If the computed billing route exceeds this value, the call is rejected. - `send_digits` string — DTMF digits to send after the call is answered. Allowed characters: `0-9`, `A-D`, `*`, `#`, `w` (wait), `,` (pause). - `region` union — Preferred FreeSWITCH region(s) for call routing. Must be drawn from the project's available regions. Accepts a single region or a priority-ordered array. - string - string[] - `url` string, required — The URL to handle the call. This parameter allows you to specify a webhook or different route in your code containing SWML instructions for handling the call. Either `url` or `swml` must be included for a new call. - CallingCallCreateParamsSWML - `from` string, required — The address that initiates the call. For PSTN destinations, must be an E.164 number; for SIP/Verto destinations may also be a SIP URI (`sip:user@host`) or a short caller-id token. - `to` string — Destination address. Accepts E.164 (`+xxxxxxxxxxx`), SIP URI (`sip:` / `sips:`), Verto URI (`verto:`), client address (`client:`), or a fabric address. Required unless `to_script` is provided. - `to_script` union — Inline SWML document (JSON or YAML string), or an `http(s)://` URL that returns one, executed at the destination end. Useful for directing the call to a RelayBin / external SWML handler. When present, `to` may be omitted. - string - SWMLCallingSWMLObject — A SWML document for handling inbound and outbound calls. Contains a `sections` map where each section holds an array of methods that run sequentially. Execution starts at `sections.main`. See the [Calling SWML reference](/docs/swml/reference/calling) for the full list of available methods. - `version` '1.0.0' - `sections` SWMLCallingSection, required - … - `caller_id` string — Caller ID displayed to the destination. E.164 for PSTN; short caller-id token or SIP URI for SIP/Verto. - `fallback_url` string — Fallback URL that returns SWML if the primary `url` fails. - `status_url` string, uri — HTTP or HTTPS URL that receives call lifecycle webhooks for events listed in `status_events`. - `status_events` string[] — Call lifecycle events that will be delivered to `status_url`. - `url_method` 'GET' | 'POST' — HTTP method used when requesting the `url`. Defaults to `POST`. - `codecs` union — Codecs to offer on the outbound call. May be provided as an array of enum values or a comma-separated string of the same values. If the `to` value is a SIP URI containing `codecs=...`, those take precedence. - CallingOutboundCallCodec[] - string - `timeout` integer — Ring timeout in seconds. Must be between 1 and 600. - `max_price_per_minute` number, double — Maximum per-minute price (in dollars). If the computed billing route exceeds this value, the call is rejected. - `send_digits` string — DTMF digits to send after the call is answered. Allowed characters: `0-9`, `A-D`, `*`, `#`, `w` (wait), `,` (pause). - `region` union — Preferred FreeSWITCH region(s) for call routing. Must be drawn from the project's available regions. Accepts a single region or a priority-ordered array. - string - string[] - `swml` SWMLCallingSWMLObject, required — A SWML document for handling inbound and outbound calls. Contains a `sections` map where each section holds an array of methods that run sequentially. Execution starts at `sections.main`. See the [Calling SWML reference](/docs/swml/reference/calling) for the full list of available methods. - `version` '1.0.0' - `sections` SWMLCallingSection, required - `main` SWMLCallingSWMLMethod[], required - … - object — 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. - `command` 'update', required — The `update` command is used to update a existing call with a new dialplan. - `params` union, required — An object of parameters that will be utilized by the active command. - CallingCallUpdateParamsURL - `id` string, uuid, required — Universal Unique Identifier. - `fallback_url` string — The Fallback URL to handle the call. This parameter allows you to specify a backup webhook or different route in your code containing SWML instructions for handling the call. - `status` 'canceled' | 'completed' — Either `canceled` (to cancel a not yet connected call) or `completed` (to end a call that is in progress). - `status_url` string, uri — A URL to receive call status update callbacks. - `url` string, required — The URL to handle the call. This parameter allows you to specify a webhook or different route in your code containing SWML instructions for handling the call. Either `url` or `swml` must be included for a new call. - CallingCallUpdateParamsSWML - `id` string, uuid, required — Universal Unique Identifier. - `fallback_url` string — The Fallback URL to handle the call. This parameter allows you to specify a backup webhook or different route in your code containing SWML instructions for handling the call. - `status` 'canceled' | 'completed' — Either `canceled` (to cancel a not yet connected call) or `completed` (to end a call that is in progress). - `status_url` string, uri — A URL to receive call status update callbacks. - `swml` SWMLCallingSWMLObject, required — A SWML document for handling inbound and outbound calls. Contains a `sections` map where each section holds an array of methods that run sequentially. Execution starts at `sections.main`. See the [Calling SWML reference](/docs/swml/reference/calling) for the full list of available methods. - `version` '1.0.0' - `sections` SWMLCallingSection, required - `main` SWMLCallingSWMLMethod[], required - … - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.end', required — The `calling.end` command is used to hang up a call. - `params` object, required — An object of parameters that will be utilized by the active command. - `reason` 'hangup' | 'cancel' | 'busy' | 'noAnswer' | 'decline' | 'error' — The reason for hanging up the call. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.disconnect', required — The `calling.disconnect` command is used to disconnect a call leg. - `params` object, required — An object of parameters that will be utilized by the active command. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.ai_hold', required — The `calling.ai_hold` command is used to hold a call. - `params` object, required — An object of parameters that will be utilized by the active command. - `timeout` string — Hold timeout, expressed as a numeric string of seconds. Note: must be sent as a string — integer payloads are rejected. - `prompt` string — A system message added to the AI conversation before placing the caller on hold. The AI will speak this message to the caller before hold music begins. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.ai_unhold', required — The `calling.ai_unhold` command is used to unhold a call. - `params` object, required — An object of parameters that will be utilized by the active command. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.ai_message', required — The `calling.ai_message` command is used to inject a message into the AI conversation. - `params` object, required — An object of parameters that will be utilized by the active command. - `role` 'system' | 'user' | 'assistant' — The role that the message is from. By convention pair with `message_text` (the validator itself does not enforce this). - `system`: Inject instructions or context that modify the AI's behavior mid-conversation without the caller hearing it. - `user`: Inject a message as if the caller said it. The AI will respond as if the caller spoke it. - `assistant`: Inject a message as if the AI said it. Appears as an AI response in the conversation history. - `message_text` string — The text content sent to the AI. Typically required unless `reset` is provided. - `reset` CallingCallAIMessageResetParams — Parameters for resetting the AI conversation state. - `full_reset` boolean — Whether to perform a full reset of the AI conversation, clearing all history. - `user_prompt` string — A new user prompt to set after resetting the conversation. - `system_prompt` string — A new system prompt to set after resetting the conversation. - `global_data` object — Arbitrary JSON data to merge into the AI session's global data store. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.ai.stop', required — The `calling.ai.stop` command stops an active AI session on the call. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string — Reserved field. The handler stops AI on the active session for this call; this value is currently ignored. - object — 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`. - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.play', required — The `calling.play` command is used to play media on an active call. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — Unique identifier for this play operation, used to control it later. Must be unique per active play on this call. - `play` union[], required — Ordered list of media items to play. Items play sequentially. - union - CallingPlayAudioItem — A media item to play on the call. The shape of `params` is determined by `type`. - `type` 'audio' | 'tts' | 'silence' | 'ringtone', required — The type of media to play. - CallingPlayTtsItem — A media item to play on the call. The shape of `params` is determined by `type`. - `type` 'audio' | 'tts' | 'silence' | 'ringtone', required — The type of media to play. - CallingPlaySilenceItem — A media item to play on the call. The shape of `params` is determined by `type`. - `type` 'audio' | 'tts' | 'silence' | 'ringtone', required — The type of media to play. - CallingPlayRingtoneItem — A media item to play on the call. The shape of `params` is determined by `type`. - `type` 'audio' | 'tts' | 'silence' | 'ringtone', required — The type of media to play. - `volume` number, double — Volume adjustment in dB. Must be between -40 and 40. - `direction` 'listen' | 'speak' | 'both' — The direction of audio playback relative to the call participants. - `loop` integer — Number of times the full `play` sequence is repeated. `0` loops forever; `N > 0` plays a total of N times. - `language` string — Default BCP-47 language tag applied to any TTS item that does not set its own `language`. - `voice` string — Default voice applied to any TTS item that does not set its own `voice`. Defaults to the request-level `gender` when unset. - `gender` 'male' | 'female' — Text-to-speech voice gender. - `status_url` string, uri — HTTP or HTTPS URL that receives playback lifecycle webhooks (`playing`, `paused`, `finished`, `error`). - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.play.pause', required — The `calling.play.pause` command pauses an active play operation. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — The control ID of the play operation to pause. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.play.resume', required — The `calling.play.resume` command resumes a paused play operation. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — The control ID of the play operation to resume. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.play.stop', required — The `calling.play.stop` command stops an active play operation. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — The control ID of the play operation to stop. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.play.volume', required — The `calling.play.volume` command adjusts the volume of an active play operation. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — The control ID of the play operation to adjust. - `volume` number, double, required — Volume adjustment in dB. Must be between -40 and 40. - object — 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. - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.record', required — The `calling.record` command starts recording an active call. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — Unique identifier for this record operation, used to control it later. Must be unique among active recordings on the call. - `record` CallingRecordParams, required — Recording configuration wrapper. Currently only audio recording is supported. - `audio` CallingRecordAudioParams, required — Audio recording parameters. - `beep` boolean — Whether to play a beep before recording starts. - `format` 'mp3' | 'wav' | 'mp4' — The audio format for the recording. - `stereo` boolean — Whether to record in stereo (separate channels for each direction). - `direction` 'listen' | 'speak' | 'both' — The direction of audio playback relative to the call participants. - `initial_timeout` number, double — Maximum time in seconds to wait for initial speech before stopping. - `end_silence_timeout` number, double — Time in seconds of silence after speech to stop recording. - `max_length` integer — Maximum recording duration in seconds. Set to `0` for no limit. - `terminators` string — DTMF digits that terminate the recording when pressed. Accepts `0-9`, `A-D` (case insensitive), `*`, and `#`. - `input_sensitivity` number, double — Input sensitivity for voice detection (0.0-100.0). - `status_url` string, uri — Webhook URL invoked with recording events — including a `finished` event that contains the final recording URL. Must begin with `http://` or `https://`. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.record.pause', required — The `calling.record.pause` command pauses an active recording. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — The control ID of the recording to pause. - `behavior` 'skip' | 'silence' — How the paused audio is handled. `skip` omits paused audio from the output file; `silence` replaces it with silence, preserving timing. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.record.resume', required — The `calling.record.resume` command resumes a paused recording. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — The control ID of the recording to resume. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.record.stop', required — The `calling.record.stop` command stops an active recording. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — The control ID of the recording to stop. - object — 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`. - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.collect', required — The `calling.collect` command collects user input (digits or speech) during a call. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — Unique identifier for this collect operation, used to control it later. Must be unique per active collect on this call. - `initial_timeout` number, double — Maximum time in seconds to wait for initial input. Must be positive. Defaults to the server-configured no-input timeout when omitted. - `digits` CallingCollectDigitsParams — Parameters for collecting DTMF digit input. - `max` integer, required — Maximum number of digits to collect. Must be positive. - `terminators` string — DTMF digits that terminate input when pressed. Allowed: `0-9`, `A-D` (case insensitive), `*`, `#`. Empty string disables terminators. - `digit_timeout` number, double — Time in seconds to wait between digit presses. Must be positive. Defaults to the server-configured digit timeout when omitted. - `speech` CallingCollectSpeechParams — Parameters for collecting speech input. - `end_silence_timeout` number, double — Time in seconds of silence after speech to consider input complete. Must be positive. - `speech_timeout` number, double — Maximum time in seconds to wait for speech input. Must be positive. - `language` string — Speech recognition language. Accepts a BCP-47 tag (e.g. `en-US`) or an `engine:tag` override (e.g. `Deepgram:en-US`) to pick a specific engine. Defaults to the server-configured ASR language when omitted. - `hints` string[] — Array of words or phrases to bias the speech recognition. - `model` string — Provider-specific ASR model name (e.g. Deepgram `nova-3`). Freeform string; validation is performed by the selected engine. - `engine` 'Google' | 'Google.V2' | 'Deepgram' — Speech recognition engine for `calling.collect`. Note: values are case-sensitive. - `continuous` boolean — If `true`, the collect restarts after each result until `calling.collect.stop` is called. Continuous events include a `state` field indicating collect state. - `partial_results` boolean — If `true`, partial results are delivered as they are recognized, and events include a `final` field (`false` for partial, `true` for final). - `send_start_of_input` boolean — If `true`, a `start_of_input` webhook event is fired when input is first detected. - `start_input_timers` boolean — If `false`, the initial-timeout clock does not start until `calling.collect.start_input_timers` is called for this `control_id`. - `status_url` string, uri — HTTP or HTTPS URL that receives collect result webhooks. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.collect.stop', required — The `calling.collect.stop` command stops an active collect operation. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — The control ID of the collect operation to stop. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.collect.start_input_timers', required — The `calling.collect.start_input_timers` command starts input timers for an active collect operation. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — The control ID of the collect operation to start input timers for. - object — 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. - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.detect', required — The `calling.detect` command starts detection (machine, fax, or digit) on an active call. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — Unique identifier for this detect operation, used to control it later. Must be unique per active detect on this call. - `detect` union, required — Detection configuration specifying what to detect. - CallingDetectMachineConfig — Detection configuration. The shape of `params` depends on `type`. - `type` 'machine' | 'fax' | 'digit', required — The type of detection to perform. - CallingDetectFaxConfig — Detection configuration. The shape of `params` depends on `type`. - `type` 'machine' | 'fax' | 'digit', required — The type of detection to perform. - CallingDetectDigitConfig — Detection configuration. The shape of `params` depends on `type`. - `type` 'machine' | 'fax' | 'digit', required — The type of detection to perform. - `timeout` number, double — Maximum time in seconds the detection may run before timing out. - `status_url` string, uri — HTTP or HTTPS URL that receives detection result webhooks. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.detect.stop', required — The `calling.detect.stop` command stops an active detection operation. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — The control ID of the detect operation to stop. - object — 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`. - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.tap', required — The `calling.tap` command starts tapping (capturing audio) on an active call. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — Unique identifier for this tap operation, used to control it later. Must be unique per active tap on this call. - `tap` CallingTapConfig, required — Tap configuration — specifies what audio to capture. - `type` 'audio', required — Currently only `audio` is supported. - `params` object, required — Audio tap parameters. - `direction` 'listen' | 'speak' | 'both', required — The direction of audio playback relative to the call participants. - `device` union, required — Device configuration specifying where to stream captured audio. - CallingTapDeviceRtp — Tap device configuration — specifies where to stream captured audio. - `type` 'rtp' | 'ws', required — The type of tap device to stream audio to. - CallingTapDeviceWs — Tap device configuration — specifies where to stream captured audio. - `type` 'rtp' | 'ws', required — The type of tap device to stream audio to. - `status_url` string, uri — HTTP or HTTPS URL that receives tap lifecycle webhooks. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.tap.stop', required — The `calling.tap.stop` command stops an active tap operation. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — The control ID of the tap operation to stop. - object — 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`. - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.transcribe', required — The `calling.transcribe` command starts transcribing an active call in the background. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — Unique identifier for this transcription operation, used to control it later. - `status_url` string, uri — An HTTP or HTTPS URL that receives the status callback when the transcription finishes. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.transcribe.stop', required — The `calling.transcribe.stop` command stops an active transcription operation. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — The control ID of the transcription operation to stop. - object — 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`. - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.stream', required — The `calling.stream` command starts streaming call audio to a WebSocket endpoint. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — Unique identifier for this stream operation, used to control it later. Must be unique per active stream on this call. - `url` string, uri, required — WebSocket URL to stream audio to. Must start with `wss://` (TLS is required; plain `ws://` is rejected). - `name` string — Optional human-readable name to identify the stream at the endpoint. - `codec` string — Audio codec to request. Freeform; endpoint-specific. Common values include `PCMU`, `PCMA`, `OPUS`. - `track` 'inbound_track' | 'outbound_track' | 'both_tracks' — The audio track to stream. - `authorization_bearer_token` string — Bearer token included as `Authorization: Bearer ` when establishing the WebSocket connection. - `custom_parameters` object — Arbitrary JSON object passed through to the WebSocket endpoint as connection metadata. - `status_url` string, uri — HTTP or HTTPS URL that receives stream lifecycle webhooks. - `status_url_method` 'GET' | 'POST' — HTTP method used when invoking the `status_url` webhook. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.stream.stop', required — The `calling.stream.stop` command stops an active audio stream. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — The control ID of the stream operation to stop. - object — 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. - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.denoise', required — The `calling.denoise` command enables noise reduction on an active call. - `params` object, required — An object of parameters that will be utilized by the active command. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.denoise.stop', required — The `calling.denoise.stop` command disables noise reduction on an active call. - `params` object, required — An object of parameters that will be utilized by the active command. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.live_transcribe', required — The `calling.live_transcribe` command is used to control live transcription on an active call. - `params` object, required — An object of parameters that will be utilized by the active command. - `action` union, required — The transcription action to perform: start, stop, or summarize. - CallingLiveTranscribeStartAction - `start` object, required — Starts live transcription of the call. - `lang` string, required — The language to transcribe (e.g., 'en-US', 'es-ES'). - `direction` SWMLCallingTranscribeDirection[], required — The direction(s) of the call to transcribe. - `webhook` string — The webhook URL to receive transcription events. - `live_events` boolean — Whether to send real-time utterance events as speech is recognized. - `ai_summary` boolean — Whether to generate an AI summary when transcription ends. - `ai_summary_prompt` string — The AI prompt that instructs how to summarize the conversation when `ai_summary` is enabled. - `speech_engine` 'deepgram' | 'google' — Speech recognition engine options. - `speech_timeout` integer — Speech timeout in milliseconds. - `vad_silence_ms` integer — Voice activity detection silence time in milliseconds. Default depends on speech engine: `300` for Deepgram, `500` for Google. - `vad_thresh` integer — Voice activity detection threshold (0-1800). - `debug_level` integer — Debug level for logging (0-2). - CallingLiveTranscribeSummarizeAction - `summarize` object, required — Request an on-demand AI summary of the conversation. - `webhook` string — The webhook URL to receive the summary. - `prompt` string — The AI prompt that instructs how to summarize the conversation. - 'stop' — Stops the live transcription session. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.live_translate', required — The `calling.live_translate` command is used to control live translation on an active call. - `params` object, required — An object of parameters that will be utilized by the active command. - `action` union, required — The translation action to perform: start, stop, summarize, or inject. - CallingLiveTranslateStartAction - `start` object, required — Starts live translation of the call. - `from_lang` string, required — The language to translate from (e.g., 'en-US'). - `to_lang` string, required — The language to translate to (e.g., 'es-ES'). - `direction` SWMLCallingTranscribeDirection[], required — The direction(s) of the call to translate. - `from_voice` string — The TTS voice for the source language. - `to_voice` string — The TTS voice for the target language. - `filter_from` union — Translation filter for the source language direction. - … - `filter_to` union — Translation filter for the target language direction. - … - `webhook` string — The webhook URL to receive translation events. - `live_events` boolean — Whether to send real-time translation events. - `ai_summary` boolean — Whether to generate AI summaries in both languages when translation ends. - `ai_summary_prompt` string — The AI prompt that instructs how to summarize the conversation when `ai_summary` is enabled. - `speech_engine` 'deepgram' | 'google' — Speech recognition engine options. - `speech_timeout` integer — Speech timeout in milliseconds. - `vad_silence_ms` integer — Voice activity detection silence time in milliseconds. Default depends on speech engine: `300` for Deepgram, `500` for Google. - `vad_thresh` integer — Voice activity detection threshold (0-1800). - `debug_level` integer — Debug level for logging (0-2). - CallingLiveTranslateSummarizeAction - `summarize` object, required — Request an on-demand AI summary of the translated conversation. - `webhook` string — The webhook URL to receive the summary. - `prompt` string — The AI prompt that instructs how to summarize the conversation. - CallingLiveTranslateInjectAction - `inject` object, required — Inject a message into the conversation to be translated and spoken. - `message` string, required — The text message to inject and translate. - `direction` 'remote-caller' | 'local-caller', required - 'stop' — Stops the live translation session. - `status_url` string, uri — HTTP or HTTPS URL that receives translation-session webhooks. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.transfer', required — The `calling.transfer` command is used to transfer an active call to a new destination. - `params` object, required — An object of parameters that will be utilized by the active command. - `dest` union, required — The destination to transfer the call to. Can be a SIP URI, phone number, SWML URL, or an inline SWML object. - string - SWMLCallingSWMLObject — A SWML document for handling inbound and outbound calls. Contains a `sections` map where each section holds an array of methods that run sequentially. Execution starts at `sections.main`. See the [Calling SWML reference](/docs/swml/reference/calling) for the full list of available methods. - `version` '1.0.0' - `sections` SWMLCallingSection, required - `main` SWMLCallingSWMLMethod[], required - … - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.send_fax.stop', required — The `calling.send_fax.stop` command stops an active fax send operation. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — The control ID of the fax send operation to stop. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.receive_fax.stop', required — The `calling.receive_fax.stop` command stops an active fax receive operation. - `params` object, required — An object of parameters that will be utilized by the active command. - `control_id` string, required — The control ID of the fax receive operation to stop. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.refer', required — The `calling.refer` command performs a SIP REFER on an active call. - `params` object, required — An object of parameters that will be utilized by the active command. - `device` CallingReferDevice, required — Device configuration for SIP REFER. - `type` 'sip', required — The device type. Currently only 'sip' is supported. - `params` CallingReferSipParams, required — SIP REFER device parameters. - `to` string, required — SIP URI to refer the call to (must start with `sip:`). - `from` string — Optional SIP From URI (must start with `sip:` when provided). - `username` string — Optional SIP authentication username. - `password` string — Optional SIP authentication password. - `status_url` string, uri — HTTP or HTTPS URL that receives refer lifecycle webhooks. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.user_event', required — The `calling.user_event` command is used to fire a custom user event on the call. - `params` object, required — An object of parameters that will be utilized by the active command. - `event` object, required — Arbitrary JSON event data to fire on the call. ## Response `200` The request has succeeded. - union — The response varies based on the type of call. A standard call returns a Call Leg, while a Fabric subscriber call returns a Fabric Device Leg. - CallingCallLeg — Returned when the call is a standard PSTN, SIP, or WebRTC call. - `id` string, uuid, required — Universal Unique Identifier. - `from` string, required — The origin number or address. - `to` string, required — The destination number or address. - `direction` 'inbound' | 'outbound' | 'outbound-api', required — The direction of the call. - `source` 'realtime_api', required — Source of this call. - `url` string, nullable, required — The URL associated with this call. - `charge` number, double, required — Total charge for this call. - `created_at` string, date-time, required — The date and time when the call was created. - `charge_details` CallingChargeDetails[], required — Details on charges associated with this call. - `description` string, required — Description for this charge. - `charge` number, double, required — Charged amount. - `status` 'queued' | 'initiated' | 'created' | 'ringing' | 'answered' | 'ending' | 'ended' | 'failed' | 'canceled' | 'completed', required — The status of the call throughout its lifecycle. - `duration` integer, nullable, required — The duration of the call in seconds. - `duration_ms` integer, nullable, required — The duration of the call in milliseconds. - `billing_ms` integer, nullable, required — The billable duration of the call in milliseconds. - `type` union, required — Type of this call. - 'relay_pstn_call' - 'relay_sip_call' - 'relay_webrtc_call' - `parent_id` string, uuid, required — Universal Unique Identifier. - CallingFabricDeviceLeg — Returned when the call is a Fabric subscriber device leg. The `status` field is always null for this type. - `id` string, uuid, required — Universal Unique Identifier. - `from` string, required — The origin number or address. - `to` string, required — The destination number or address. - `direction` 'inbound' | 'outbound' | 'outbound-api', required — The direction of the call. - `source` 'realtime_api', required — Source of this call. - `url` string, nullable, required — The URL associated with this call. - `charge` number, double, required — Total charge for this call. - `created_at` string, date-time, required — The date and time when the call was created. - `charge_details` CallingChargeDetails[], required — Details on charges associated with this call. - `description` string, required — Description for this charge. - `charge` number, double, required — Charged amount. - `status` unknown, required - `type` 'fabric_subscriber_device_leg', required — Type of this call. ## Other responses - `400` — The request is invalid. - `401` — Access is unauthorized. - `404` — The server cannot find the requested resource. - `422` — The request contains invalid parameters. See errors for details. - `500` — An internal server error occurred. ## Changes - **2026-06-03** `548c8bbaf71b` — 2 warning, 12 info - removed the request property `oneOf[subschema #1: dial]/params/anyOf[subschema #1: dial (URL)]/custom_variables` - removed the request property `oneOf[subschema #1: dial]/params/anyOf[subschema #2: dial (Inline SWML)]/custom_variables` - added `calling.transcribe, calling.transcribe.stop` mapping keys to the request discriminator - added `#/components/schemas/Calling.CallTranscribeRequest, #/components/schemas/Calling.CallTranscribeStopRequest` to the request body `oneOf` list - …10 more - …earlier changes not shown [Full history](https://skmtc.dev/signalwire/apis/signalwire-rest-api/changes/api/calling/calls/post.md) --- [API](https://skmtc.dev/signalwire/apis/signalwire-rest-api.md) · [All operations](https://skmtc.dev/signalwire/apis/signalwire-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/signalwire/signalwire-rest-api/revisions/548c8bbaf71b/schema)