--- 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. Only the commands listed below are supported. Most operate on an already-active call; `dial` creates a new one. All commands are sent over HTTP (no persistent WebSocket connection required) and return immediately; operations that continue asynchronously deliver their results to your `status_url` webhooks. ## 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.ai_sidecar` | Attach a real-time AI observer (sidecar) to a call, or summarize the conversation | | `calling.ai_sidecar.poke` | Send a message to the sidecar and prompt an immediate response | | `calling.ai_sidecar.ask` | Ask the sidecar a one-off question (answered via an `ask_answer` callback) | | `calling.ai_sidecar.stop` | Stop and detach the AI sidecar | | `calling.ai_sidecar.status` | Get a snapshot of the sidecar's activity counters | | `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. Only the commands listed here are supported. Most operate on an already-active call; `dial` creates a new one. Commands return immediately; operations that continue asynchronously deliver their results to your `status_url` webhooks. - 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. - `username` string — SIP authentication username, forwarded to the destination when `to` is a SIP URI. Ignored for PSTN and WebRTC/Verto destinations. Write-only — never returned in the call response. - `password` string — SIP authentication password, forwarded to the destination when `to` is a SIP URI. Ignored for PSTN and WebRTC/Verto destinations. Write-only — never returned in the call response. - `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[] - `custom_variables` object — Your own key/value string pairs to attach to the call. They become environment variables on the call's SWML document, where you can reference them as `${envs.}` — for example, to carry an order or case number through to your call logic. When SignalWire fetches your SWML document from a URL, the same pairs are also included in the `envs` object of that request. If a key here matches a variable you've already set at the account or project level, the value you pass on the request takes precedence — but only when the keys match exactly, including case. Keys are case-sensitive, so two keys that differ only in case are kept as separate variables. Each value must be a non-empty string of at most 1024 bytes. You can send at most 20 pairs. Each key must start with a letter or underscore and contain only letters, numbers, and underscores, and cannot begin with the reserved prefixes `signalwire_`, `sw_`, `rtc_`, or `internal_` (case-insensitive). - `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. - `username` string — SIP authentication username, forwarded to the destination when `to` is a SIP URI. Ignored for PSTN and WebRTC/Verto destinations. Write-only — never returned in the call response. - `password` string — SIP authentication password, forwarded to the destination when `to` is a SIP URI. Ignored for PSTN and WebRTC/Verto destinations. Write-only — never returned in the call response. - `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[] - `custom_variables` object — Your own key/value string pairs to attach to the call. They become environment variables on the call's SWML document, where you can reference them as `${envs.}` — for example, to carry an order or case number through to your call logic. When SignalWire fetches your SWML document from a URL, the same pairs are also included in the `envs` object of that request. If a key here matches a variable you've already set at the account or project level, the value you pass on the request takes precedence — but only when the keys match exactly, including case. Keys are case-sensitive, so two keys that differ only in case are kept as separate variables. Each value must be a non-empty string of at most 1024 bytes. You can send at most 20 pairs. Each key must start with a letter or underscore and contain only letters, numbers, and underscores, and cannot begin with the reserved prefixes `signalwire_`, `sw_`, `rtc_`, or `internal_` (case-insensitive). - `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 - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.ai_sidecar', required — The `calling.ai_sidecar` command attaches a real-time AI observer (a sidecar) to an answered call. The sidecar listens to the conversation and streams advice for the agent to your application as webhook callbacks; it never speaks on the call. - `params` SWMLCallingAISidecarObject, required - `prompt` union - string - SWMLCallingAISidecarPromptText - `text` string, required — The operator prompt as a single block of text. - SWMLCallingAISidecarPromptPom - `pom` SWMLCallingPOM[], required — The operator prompt as a Prompt Object Model (POM) — a structured array of sections that SignalWire renders into a markdown document before sending it to the model. - union — Regular section that requires either body or bullets. - … - SWMLCallingAISidecarPromptFile - `file` string, required — Path to a server-side file whose contents are used as the operator prompt. - `lang` string, required — The conversation language as a single BCP-47 tag. Sets the speech recognition language and is shared with the model as a hint. - `model` union — The model used for the sidecar's advice and its end-of-call summaries. Suggested values: `gpt-4o-mini`, `gpt-4.1-mini`, `gpt-4.1-nano`. **Default:** `gpt-4o-mini`. - 'gpt-4o-mini' | 'gpt-4.1-mini' | 'gpt-4.1-nano' - string - `direction` SWMLCallingTranscribeDirection[] — The call legs to observe. Both legs are required — a single-leg value is rejected. When omitted, both legs are observed. **Default:** both legs (`remote-caller` and `local-caller`). - `customer_role` 'remote-caller' | 'local-caller' - `url` string, uri — The webhook URL the sidecar POSTs its callbacks to. Receives both transcription events and sidecar callbacks. When unset, callbacks are published only on the relay topic and no webhook POST is made. Basic auth can be embedded in the URL in the format `username:password@url`. - `SWAIG` SWMLCallingAISidecarSWAIG - `defaults` SWMLCallingAISidecarSWAIGDefaults - `web_hook_url` string — Default webhook URL for functions that do not set their own `web_hook_url`. Basic auth can be embedded as `username:password@url`. - `web_hook_auth_user` string — Default basic-auth username for the function webhook. - `web_hook_auth_password` string — Default basic-auth password for the function webhook. - `functions` SWMLCallingAISidecarSWAIGFunction[] — An array of functions the model can call during the conversation. - `function` string, required — The name of the function. This is the only required field; the model calls the function by this name. - `description` string — A description of what the function does, sent to the model so it knows when to call it. - `purpose` string — Fallback for `description` — used only when `description` is not set. - `parameters` SWMLCallingAISidecarFunctionParameters - `type` 'object', required — The container type for the function's arguments. Always `object`. - `properties` object, required — The properties the function accepts, keyed by property name. Each property allows only `type`, `description`, `enum`, and `default` — additional validation keywords such as `pattern`, `format`, `minimum`, and `maximum` are not accepted; express those constraints in the property `description` and validate them server-side. - `required` string[] — The names of the required properties. - `web_hook_url` string — Webhook URL for this function. Falls back to `defaults.web_hook_url`. Basic auth can be embedded as `username:password@url`. - `web_hook_auth_user` string — Basic-auth username for this function's webhook. Falls back to `defaults.web_hook_auth_user`. - `web_hook_auth_password` string — Basic-auth password for this function's webhook. Falls back to `defaults.web_hook_auth_password`. - `mcp_servers` SWMLCallingMCPServer[] — An array of MCP (Model Context Protocol) servers whose tools and resources are made available to the model. - `url` string, required — The MCP (Model Context Protocol) server URL. Required. - `headers` object — HTTP headers sent to the MCP server. Authorization tokens go here — there is no separate auth field. Header values support variable expansion (for example, `Bearer ${global_data.token}`). - `resources` boolean — Whether to fetch the server's resources into `global_data`, when the server advertises resource support. **Default:** `false`. - `resource_vars` object — Template variables passed to the MCP server when fetching resources, typically using variable expansion such as `${global_data.customer_id}`. Used only when `resources` is enabled. - `permissions` SWMLCallingAISidecarPermissions - `swaig_allow_swml` boolean — Whether SWAIG tools may run SWML on the call. **Default:** `true`. - `swaig_allow_settings` boolean — Whether SWAIG tools may change the sidecar's settings, such as the model. **Default:** `true`. - `swaig_set_global_data` boolean — Whether SWAIG tools may set the sidecar's global data. **Default:** `true`. - `global_data` SWMLCallingGlobalData — A key-value object for data that persists throughout an AI or sidecar session. - `hints` string[] — Hints that improve speech recognition of specific terms, such as product names, competitor names, jargon, or customer names. Strongly recommended. - `params` SWMLCallingAISidecarParams - `idle_timeout_ms` integer — How long the customer can be silent, in milliseconds, after they finish speaking before the sidecar evaluates the conversation. Lower values make the sidecar react faster. Range: 50-5000. **Default:** `200`. - `min_interval_ms` integer — The minimum time, in milliseconds, between evaluations — a throttle that limits how often the sidecar runs on a busy call. Range: 0-60000. **Default:** `0`. - `max_iters_per_tick` integer — The maximum number of tool calls the sidecar will chain within a single evaluation before it must produce its advice. Range: 1-20. **Default:** `5`. - `max_history_tokens` integer — The token budget for the sidecar's running conversation history. When the history grows past this, the oldest messages are dropped. Range: 1000-200000. **Default:** `8000`. - `act_on_channel` boolean — Whether actions returned by your tools (such as transferring or hanging up the call) take effect on the call, or are only reported as callbacks. **Default:** `true`. - `final_summary` boolean — Whether to generate a closing summary of the sidecar's session when the call ends. The result is included in the final callback. **Default:** `false`. - `ai_summary` boolean — Whether to generate an end-of-call summary of the conversation itself, distinct from `final_summary` (which summarizes the sidecar's session). **Default:** `false`. - `ai_summary_prompt` string — A custom prompt for the end-of-call conversation summary. - `summary_model` union — The model used for the end-of-call conversation summary, distinct from `model` (the sidecar's own model). Suggested values: `gpt-4o-mini`, `gpt-4.1-mini`, `gpt-4.1-nano`. **Default:** `gpt-4o-mini`. - 'gpt-4o-mini' | 'gpt-4.1-mini' | 'gpt-4.1-nano' - string - `live_events` boolean — Whether to emit a callback for each utterance the speech recognizer produces. **Default:** `false`. - `verbose_utterances` boolean — Whether each utterance callback includes full speech-recognition detail, such as word timings and alternatives. This increases the callback size, so leave it off unless you need it. **Default:** `false`. - `speech_engine` 'deepgram' | 'google' — Speech recognition engine options. - `speech_timeout` integer — How long, in milliseconds, the recognizer waits before finalizing speech. Range: 0-600000. `0` uses the speech engine's own default. - `vad_silence_ms` integer — The amount of silence, in milliseconds, used to detect the end of speech. Range: 0-60000. `0` uses the speech engine's own default. - `vad_thresh` integer — How sensitively the recognizer detects speech. Range: 0-10000. `0` uses the speech engine's own default. - `debug_level` integer — Speech-engine debug verbosity. Range: 0-100. **Default:** `0`. - `debug` boolean — Whether to enable verbose logging for the sidecar. **Default:** `false`. - `transcribe_prompt` string — A bias prompt passed to the speech recognizer to improve accuracy on expected terms, such as product or company names. This is distinct from the operator `prompt`. - `action` SWMLCallingAISidecarSummarizeAction - `summarize` object, required — Generate a one-off summary of the conversation, instead of starting a sidecar, and send it to a webhook. - `webhook` string — The webhook URL the summary is sent to. Defaults to the sidecar's configured `url`. - `prompt` string — The prompt used to write the summary. Defaults to the configured `ai_summary_prompt`. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.ai_sidecar.poke', required — The `calling.ai_sidecar.poke` command sends a message to the sidecar and prompts it to respond right away, without waiting for the next customer turn. - `params` object, required — An object of parameters that will be utilized by the active command. - `text` string, required — The message to send to the sidecar. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.ai_sidecar.ask', required — The `calling.ai_sidecar.ask` command asks the sidecar a one-off question without affecting the live conversation. The response returns an `ask_id` right away, and the answer arrives later as an `ask_answer` webhook callback carrying the same `ask_id`. - `params` object, required — An object of parameters that will be utilized by the active command. - `text` string, required — The question for the sidecar to answer. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.ai_sidecar.stop', required — The `calling.ai_sidecar.stop` command stops and detaches the AI sidecar from the call. - `params` object, required — The `calling.ai_sidecar.stop` command takes no parameters — the sidecar is addressed by `id` (the call ID) alone. - object - `id` string, uuid, required — Universal Unique Identifier. - `command` 'calling.ai_sidecar.status', required — The `calling.ai_sidecar.status` command returns a snapshot of the sidecar's activity counters. The result is a single `+OK` line of `key=value` counters (`running`, `ticks`, `insights`, `skips`, `tools`, `errors`, `in_tokens`, `out_tokens`, `history_size`, `event_log_bytes`) rather than a JSON object. - `params` object, required — The `calling.ai_sidecar.status` command takes no parameters — the sidecar is addressed by `id` (the call ID) alone. - 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. --- [API](https://skmtc.net/signalwire/apis/signalwire-rest-api.md) · [All operations](https://skmtc.net/signalwire/apis/signalwire-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/signalwire/signalwire-rest-api/versions/05c5164b85c7/schema)