> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes. # dial > Initiate a new outbound call via REST. Initiate a new outbound call. Provide either a `url` pointing to a SWML document or an inline `swml` object to control the call flow. ## **Request** ### Schema (`dial`) ```yaml components: schemas: CallingCallCreateParamsUrlToScript: oneOf: - type: string - type: object additionalProperties: description: Any type description: >- Inline [Calling SWML document](/docs/swml/reference/calling) (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. title: CallingCallCreateParamsUrlToScript CallingCallCreateParamsUrlStatusEventsItems: type: string enum: - created - ringing - answered - ended title: CallingCallCreateParamsUrlStatusEventsItems CallingCallCreateParamsUrlUrlMethod: type: string enum: - GET - POST default: POST description: HTTP method used when requesting the `url`. Defaults to `POST`. title: CallingCallCreateParamsUrlUrlMethod Calling.OutboundCallCodec: type: string enum: - OPUS - OPUS@48000H@20I - OPUS@24000H@20I - OPUS@16000H@20I - OPUS@8000H@20I - G722 - PCMU - PCMA - G729 - VP8 - H264 description: >- Codec offered on an outbound call. For PSTN, `PCMU`/`PCMA` are widely supported. `OPUS@H@I` variants pin the OPUS sample rate (Hz) and packetization time (ms). title: Calling.OutboundCallCodec CallingCallCreateParamsUrlCodecs0: type: array items: $ref: '#/components/schemas/Calling.OutboundCallCodec' title: CallingCallCreateParamsUrlCodecs0 CallingCallCreateParamsUrlCodecs: oneOf: - $ref: '#/components/schemas/CallingCallCreateParamsUrlCodecs0' - type: string description: >- 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. title: CallingCallCreateParamsUrlCodecs CallingCallCreateParamsUrlRegion: oneOf: - type: string - type: array items: type: string description: >- 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. title: CallingCallCreateParamsUrlRegion CallingCallCreateParamsUrlCustomVariables: type: object properties: {} description: >- 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). title: CallingCallCreateParamsUrlCustomVariables Calling.CallCreateParamsURL: type: object properties: from: type: string description: >- 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: type: string description: >- 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: type: string description: >- 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: type: string description: >- 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: $ref: '#/components/schemas/CallingCallCreateParamsUrlToScript' description: >- Inline [Calling SWML document](/docs/swml/reference/calling) (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. caller_id: type: string description: >- Caller ID displayed to the destination. E.164 for PSTN; short caller-id token or SIP URI for SIP/Verto. fallback_url: type: string description: Fallback URL that returns SWML if the primary `url` fails. status_url: type: string format: uri description: >- HTTP or HTTPS URL that receives call lifecycle webhooks for events listed in `status_events`. status_events: type: array items: $ref: '#/components/schemas/CallingCallCreateParamsUrlStatusEventsItems' default: - ended description: Call lifecycle events that will be delivered to `status_url`. url_method: $ref: '#/components/schemas/CallingCallCreateParamsUrlUrlMethod' default: POST description: HTTP method used when requesting the `url`. Defaults to `POST`. codecs: $ref: '#/components/schemas/CallingCallCreateParamsUrlCodecs' description: >- 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. timeout: type: integer minimum: 1 maximum: 600 description: Ring timeout in seconds. Must be between 1 and 600. max_price_per_minute: type: number format: double minimum: 0 description: >- Maximum per-minute price (in dollars). If the computed billing route exceeds this value, the call is rejected. send_digits: type: string description: >- DTMF digits to send after the call is answered. Allowed characters: `0-9`, `A-D`, `*`, `#`, `w` (wait), `,` (pause). region: $ref: '#/components/schemas/CallingCallCreateParamsUrlRegion' description: >- 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. custom_variables: $ref: '#/components/schemas/CallingCallCreateParamsUrlCustomVariables' description: >- 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: type: string description: >- 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. required: - from - url description: '`dial` parameters for a call whose handling SWML is fetched from `url`.' title: Calling.CallCreateParamsURL CallingCallCreateParamsSwmlToScript: oneOf: - type: string - type: object additionalProperties: description: Any type description: >- Inline [Calling SWML document](/docs/swml/reference/calling) (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. title: CallingCallCreateParamsSwmlToScript CallingCallCreateParamsSwmlStatusEventsItems: type: string enum: - created - ringing - answered - ended title: CallingCallCreateParamsSwmlStatusEventsItems CallingCallCreateParamsSwmlUrlMethod: type: string enum: - GET - POST default: POST description: HTTP method used when requesting the `url`. Defaults to `POST`. title: CallingCallCreateParamsSwmlUrlMethod CallingCallCreateParamsSwmlCodecs0: type: array items: $ref: '#/components/schemas/Calling.OutboundCallCodec' title: CallingCallCreateParamsSwmlCodecs0 CallingCallCreateParamsSwmlCodecs: oneOf: - $ref: '#/components/schemas/CallingCallCreateParamsSwmlCodecs0' - type: string description: >- 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. title: CallingCallCreateParamsSwmlCodecs CallingCallCreateParamsSwmlRegion: oneOf: - type: string - type: array items: type: string description: >- 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. title: CallingCallCreateParamsSwmlRegion CallingCallCreateParamsSwmlCustomVariables: type: object properties: {} description: >- 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). title: CallingCallCreateParamsSwmlCustomVariables CallingCallCreateParamsSwmlSwml: type: object properties: {} description: >- Inline [Calling SWML document](/docs/swml/reference/calling) containing instructions for handling the call. Either `url` or `swml` must be included for a new call. title: CallingCallCreateParamsSwmlSwml Calling.CallCreateParamsSWML: type: object properties: from: type: string description: >- 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: type: string description: >- 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: type: string description: >- 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: type: string description: >- 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: $ref: '#/components/schemas/CallingCallCreateParamsSwmlToScript' description: >- Inline [Calling SWML document](/docs/swml/reference/calling) (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. caller_id: type: string description: >- Caller ID displayed to the destination. E.164 for PSTN; short caller-id token or SIP URI for SIP/Verto. fallback_url: type: string description: Fallback URL that returns SWML if the primary `url` fails. status_url: type: string format: uri description: >- HTTP or HTTPS URL that receives call lifecycle webhooks for events listed in `status_events`. status_events: type: array items: $ref: '#/components/schemas/CallingCallCreateParamsSwmlStatusEventsItems' default: - ended description: Call lifecycle events that will be delivered to `status_url`. url_method: $ref: '#/components/schemas/CallingCallCreateParamsSwmlUrlMethod' default: POST description: HTTP method used when requesting the `url`. Defaults to `POST`. codecs: $ref: '#/components/schemas/CallingCallCreateParamsSwmlCodecs' description: >- 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. timeout: type: integer minimum: 1 maximum: 600 description: Ring timeout in seconds. Must be between 1 and 600. max_price_per_minute: type: number format: double minimum: 0 description: >- Maximum per-minute price (in dollars). If the computed billing route exceeds this value, the call is rejected. send_digits: type: string description: >- DTMF digits to send after the call is answered. Allowed characters: `0-9`, `A-D`, `*`, `#`, `w` (wait), `,` (pause). region: $ref: '#/components/schemas/CallingCallCreateParamsSwmlRegion' description: >- 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. custom_variables: $ref: '#/components/schemas/CallingCallCreateParamsSwmlCustomVariables' description: >- 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: $ref: '#/components/schemas/CallingCallCreateParamsSwmlSwml' description: >- Inline [Calling SWML document](/docs/swml/reference/calling) containing instructions for handling the call. Either `url` or `swml` must be included for a new call. required: - from - swml description: >- `dial` parameters for a call whose handling SWML is provided inline in `swml`. title: Calling.CallCreateParamsSWML CallingCallRequestDiscriminatorMappingDialParams: oneOf: - $ref: '#/components/schemas/Calling.CallCreateParamsURL' - $ref: '#/components/schemas/Calling.CallCreateParamsSWML' description: An object of parameters that will be utilized by the active command. title: CallingCallRequestDiscriminatorMappingDialParams Calling.CallCreateRequest: type: object properties: params: $ref: >- #/components/schemas/CallingCallRequestDiscriminatorMappingDialParams description: An object of parameters that will be utilized by the active command. required: - params title: Calling.CallCreateRequest ``` ## **Response** ### Schema (`Calling.CallResponse`) ```yaml components: schemas: uuid: type: string format: uuid description: Universal Unique Identifier. title: uuid Calling.CallDirection: type: string enum: - inbound - outbound - outbound-api description: The direction of the call. title: Calling.CallDirection CallingCallLegSource: type: string enum: - realtime_api description: Source of this call. title: CallingCallLegSource Calling.ChargeDetails: type: object properties: description: type: string description: Description for this charge. charge: type: number format: double description: Charged amount. required: - description - charge description: One itemized charge applied to the call. title: Calling.ChargeDetails Calling.CallResponseStatus: type: string enum: - queued - initiated - created - ringing - answered - ending - ended - failed - canceled - completed description: The status of the call throughout its lifecycle. title: Calling.CallResponseStatus CallingCallLegType0: type: string enum: - relay_pstn_call title: CallingCallLegType0 CallingCallLegType1: type: string enum: - relay_sip_call title: CallingCallLegType1 CallingCallLegType2: type: string enum: - relay_webrtc_call title: CallingCallLegType2 CallingCallLegType: oneOf: - $ref: '#/components/schemas/CallingCallLegType0' - $ref: '#/components/schemas/CallingCallLegType1' - $ref: '#/components/schemas/CallingCallLegType2' description: Type of this call. title: CallingCallLegType Calling.CallLeg: type: object properties: id: $ref: '#/components/schemas/uuid' description: >- The unique identifier of the call on SignalWire. This can be used to update the call programmatically. from: type: string description: The origin number or address. to: type: string description: The destination number or address. direction: $ref: '#/components/schemas/Calling.CallDirection' description: The direction of the call. source: $ref: '#/components/schemas/CallingCallLegSource' description: Source of this call. url: type: - string - 'null' description: The URL associated with this call. charge: type: number format: double description: Total charge for this call. created_at: type: string format: date-time description: The date and time when the call was created. charge_details: type: array items: $ref: '#/components/schemas/Calling.ChargeDetails' description: Details on charges associated with this call. status: oneOf: - $ref: '#/components/schemas/Calling.CallResponseStatus' - type: 'null' description: The status of the call. duration: type: - integer - 'null' description: The duration of the call in seconds. duration_ms: type: - integer - 'null' description: The duration of the call in milliseconds. billing_ms: type: - integer - 'null' description: The billable duration of the call in milliseconds. type: $ref: '#/components/schemas/CallingCallLegType' description: Type of this call. parent_id: oneOf: - $ref: '#/components/schemas/uuid' - type: 'null' description: The parent call ID if this is a child call. required: - id - from - to - direction - source - url - charge - created_at - charge_details - status - duration - duration_ms - billing_ms - type - parent_id description: Returned when the call is a standard PSTN, SIP, or WebRTC call. title: Calling.CallLeg CallingFabricDeviceLegSource: type: string enum: - realtime_api description: Source of this call. title: CallingFabricDeviceLegSource CallingFabricDeviceLegType: type: string enum: - fabric_subscriber_device_leg description: Type of this call. title: CallingFabricDeviceLegType Calling.FabricDeviceLeg: type: object properties: id: $ref: '#/components/schemas/uuid' description: >- The unique identifier of the call on SignalWire. This can be used to update the call programmatically. from: type: string description: The origin number or address. to: type: string description: The destination number or address. direction: $ref: '#/components/schemas/Calling.CallDirection' description: The direction of the call. source: $ref: '#/components/schemas/CallingFabricDeviceLegSource' description: Source of this call. url: type: - string - 'null' description: The URL associated with this call. charge: type: number format: double description: Total charge for this call. created_at: type: string format: date-time description: The date and time when the call was created. charge_details: type: array items: $ref: '#/components/schemas/Calling.ChargeDetails' description: Details on charges associated with this call. status: description: >- The status of the call. Always null for Fabric subscriber device legs. type: $ref: '#/components/schemas/CallingFabricDeviceLegType' description: Type of this call. required: - id - from - to - direction - source - url - charge - created_at - charge_details - status - type description: >- Returned when the call is a Fabric subscriber device leg. The `status` field is always null for this type. title: Calling.FabricDeviceLeg Calling.CallResponse: oneOf: - $ref: '#/components/schemas/Calling.CallLeg' - $ref: '#/components/schemas/Calling.FabricDeviceLeg' title: Calling.CallResponse ``` ## **Example** ```typescript {9} import { RestClient } from "@signalwire/sdk"; const client = new RestClient({ project: "your-project-id", token: "your-api-token", host: "your-space.signalwire.com" }); const result = await client.calling.dial("+15551234567", "+15559876543", { url: "https://example.com/call-handler", }); console.log(result); // { id: "call-id-xxx", ... } ``` > Initiate a new outbound call via REST.