<Dial>

import Tabs from @theme/Tabs; import TabItem from @theme/TabItem; The verb connects an existing call to another phone number. will end this new call if: the called number does not answer, the number does not exist, or SignalWire receives a busy signal. You can use the verb with the following nouns: | Noun | | |:-|:| | [](./conference-noun.mdx) | A conference call between two or more callers. | | [](./number-noun.mdx) | A phone number with additional attributes. | | [](./sip-noun.mdx) | A SIP endpoint. | | [](./verto-noun.mdx) | A Verto client. | | [](./queue-noun.mdx) | A line for callers to wait in. The current call will be connected to the call at the front of the queue. | ## Verb Attributes | Attribute | | | --: | - | | action optional | The action attribute takes in an absolute URL. SignalWire will make a GET or POST request to this URL after the dialed call ends. If no action is provided, SignalWire will continue to the next verb in the document. SignalWire will end the call if there are no more verbs following the verb in the document. See [below](#dial_action) for request parameters. | | answerOnBridge optional | If set to true, the inbound call will ring until the number that was dialed answers the call. If the inbound call is a SIP call, SignalWire will send a 180 or 183 to your SIP server as soon as it connects to SignalWire. When the call is connected, a 200 will be sent. Default value is **false**. | | callerId optional | The inbound callers phone number, which is displayed to the number that was dialed. The caller ID must be a valid E.164 number. Note that the number specified here must either be verified or purchased in the SignalWire Dashboard. | | callerName optional | The caller name displayed for Sip calls. This should be an alphanumeric string. Limit is 70 characters. | | hangupOnStar optional | The initiator of the call can hangup on the dialed number by using the * key. Default value is **false**. | | method optional | The method attribute specifies whether the request to action is a GET or a POST. Valid values are GET or POST. Default value is POST. | | record optional | The record attribute allows the ability to record both legs of a call. Recordings are available as **mono-channel** or **dual-channel**. See [below](#record_channels) for a detailed explanation of these channels. Default value is do-not-record. | | recordingStatusCallback optional | The recordingStatusCallback attribute takes in an absolute or relative URL. SignalWire will make a GET or POST request to this URL when recording is available. Default value is POST. See [below](#dial_recordingStatusCallback) for request parameters. | | recordingStatusCallbackEvent optional | The different recording statuses. Possible values are completed, in-progress, and absent. To specify multiple events, separate with a space. Defaults to completed. | | recordingStatusCallbackMethod optional | Whether the request to recordingStatusCallback URL is a GET or a POST. Default is POST. | | recordingStorageUrl optional | The recordingStorageUrl attribute accepts an absolute URL as the destination to send a recording to, if you prefer to host your own recordings and bypass SignalWire storage. The recording files are in .wav format. | | recordingStorageUrlMethod optional | Specifies which HTTP verb to use when sending the recording to the recordingStorageUrl. Available values are: **POST** and **PUT**. Defaults to **POST**. | | recordingTrack optional | Specifies whether to record the inbound audio to SignalWire from the called party or the outbound audio from SignalWire to the called party or both the inbound and outbound audio. Defaults to both. | | ringTone optional | The ability to change the ringback tone played to the caller when dialing a number. Default value is the ringback tone from the carrier. Available values are the following ISO 3166-1 alpha-2 country codes: **at**, **au**, **bg**, **br**, **be**, **ch**, **cl**, **cn**, **cz**, **de**, **dk**, **ee**, **es**, **fi**, **fr**, **gr**, **hu**, **il**, **in**, **it**, **lt**, **jp**, **mx**, **my**, **nl**, **no**, **nz**, **ph**, **pl**, **pt**, **ru**, **se**, **sg**, **th**, **uk**, **us**, **us-old**, **tw**, **ve**, **za**. | | timeLimit optional | Maximum duration, in seconds, for a . Default value is **4 hours**. | | timeout optional | The time, in seconds, that SignalWire will wait for a call to be answered before setting the status of the call to no-answer. Default is **30 seconds**. Minimum value is **5 seconds** and maximum value is **600 seconds**. For some call flows, there may be a 5-second buffer added to the timeout value you provide. | | trim optional | Whether silence in the beginning and end of recordings is removed. Use trim-silence to achieve this behavior. Default value is do-not-trim. |
#### Request parameters for the action URL {#dial_action} You can expect several parameters to be present in the request associated to the action URL. First, you have the [Standard Request Parameters](./index.mdx#request-parameters). Then, you also have the following specific parameters: | Parameter | | | : | - | | DialCallStatus string | The status of the dialed call attempt. See [below](#action_dialCallStatus) for status values. | | DialCallSid string | The unique identifier of the new call leg. | | DialCallDuration integer | The duration, in seconds, of the dialed call. | | RecordingUrl string | The URL of the recorded audio file. This parameter is only present if record is set on a . |
#### Values for DialCallStatus parameter {#action_dialCallStatus} The DialCallStatus parameter of the action attribute can be one of the following values: | Value | | | -: | | | completed | The number that was dialed answered the call and was successfully connected to the caller. | | answered | When calling to a conference, the number that was dialed answered the call and was successfully connected to the caller. | | busy | SignalWire received a busy signal when connecting to the dialed number. | | no-answer | The number that was dialed did not answer the call in time. | | failed | SignalWire was unable to connect to the dialed number. This usually occurs when the dialed number does not exist. | | canceled | The call was canceled through a REST API before it was answered. |
#### Values for record parameter {#record_channels} The record attribute allows for recordings in **mono-channel** or **dual-channel**: - **mono-channel**: both legs of a call are combined into one channel in one recording file - _record-from-answer_: starts the recording when the call is answered - _record-from-ringing_: starts the recording when ringing begins - **dual-channel**: both legs of a call use separate channels in one recording file - _record-from-answer-dual_: starts the recording when the call is answered - _record-from-ringing-dual_: starts the recording when ringing begins
#### Request parameters for recordingStatusCallback {#dial_recordingStatusCallback} The recordingStatusCallback request contains the following parameters: | Parameter | | | -: | | | AccountSid string | The unique ID of the Account this call is associated with. | | CallSid string | A unique identifier for the call. Always refers to the initial caller. | | RecordingSid string | The unique identifier for the recording. | | RecordingUrl string | The URL for the audio recording. | | RecordingStatus string | The status of the recording. Possible values are: **in-progress**, **completed**, **failed**. | | RecordingDuration integer | The duration, in seconds, of the recording. | | RecordingChannels integer | The number of channels in the recording. Can be **1** or **2**. | | RecordingSource string | The type of call that initiated the recording. | | RecordingTrack string | Which audio tracks are recorded. Can be **inbound**, **outbound**, or **both**. | ## Examples ### A Simple Dial xml 123-456-7890 javascript const { RestClient } = require(@signalwire/compatibility-api); const response = new RestClient.LaML.VoiceResponse(); response.dial(123-456-7890); console.log(response.toString()); csharp using Twilio.TwiML; using System; class Example { static void Main() { var response = new VoiceResponse(); response.Dial(123-456-7890); Console.WriteLine(response.ToString());; } } python from signalwire.voice_response import VoiceResponse, Dial response = VoiceResponse() response.dial(123-456-7890) print(response) ruby require signalwire/sdk response = Signalwire::Sdk::VoiceResponse.new do |response| response.dial(123-456-7890) end puts response.to_s If the dialed number answers the call, the two parties can talk to each other until one of them hangs up the phone. ### Dial a Number from a SignalWire Client xml +18004445566 javascript const { RestClient } = require(@signalwire/compatibility-api); const response = new RestClient.LaML.VoiceResponse(); dial = response.dial({ callerId: +18007778899 }); dial.number(+18004445566); console.log(response.toString()); csharp using Twilio.TwiML; using Twilio.TwiML.Voice; using System; class Example { static void Main() { var response = new VoiceResponse(); var dial = new Dial(callerId: +18007778899); dial.Number(+18004445566); response.Append(dial); Console.WriteLine(response.ToString());; } } python from signalwire.voice_response import VoiceResponse, Dial, Number response = VoiceResponse() dial = Dial(caller_id=+18007778899) dial.number(+18004445566) response.append(dial) print(response) ruby require signalwire/sdk response = Signalwire::Sdk::VoiceResponse.new do |response| dial.number(+18004445566) end end puts response.to_s In order to dial from a SignalWire client, you need to make sure you are inputting a valid phone number. If the number in the callerID is not valid, the call will fail. ### Mono-Channel Recording xml +10123456789 javascript const { RestClient } = require(@signalwire/compatibility-api); const response = new RestClient.LaML.VoiceResponse(); dial = response.dial({ record: record-from-ringing, recordingStatusCallback: https://example.com/recording_status, }); dial.number(+10123456789); console.log(response.toString()); csharp using Twilio.TwiML; using Twilio.TwiML.Voice; using System; class Example { static void Main() { var response = new VoiceResponse(); var dial = new Dial(record: record-from-ringing, recordingStatusCallback: new Uri(https://example.com/recording_status)); dial.Number(+10123456789); response.Append(dial); Console.WriteLine(response.ToString());; } } python from signalwire.voice_response import VoiceResponse, Dial, Number response = VoiceResponse() dial = Dial(record=record-from-ringing, recording_status_callback=https://example.com/recording_status) dial.number(+10123456789) response.append(dial) print(response) ruby require signalwire/sdk response = Signalwire::Sdk::VoiceResponse.new do |response| response.dial(record: record-from-ringing, recording_status_callback: https://example.com/recording_status) do |dial| dial.number(+10123456789) end end puts response.to_s With mono-channel recording, each participant in the call will be recorded on the same channel. The recording will then be stored in a single recording file. Since we have set record to **record-from-ringing**, the recording will begin when the phone starts to ring. ### Dual-Channel Recording for a Conference Call xml teamcall javascript const { RestClient } = require(@signalwire/compatibility-api); const response = new RestClient.LaML.VoiceResponse(); dial = response.dial({ record: record-from-ringing-dual, recordingStatusCallback: https://example.com/recording_status, }); dial.conference(teamcall); console.log(response.toString()); csharp using Twilio.TwiML; using Twilio.TwiML.Voice; using System; class Example { static void Main() { var response = new VoiceResponse(); var dial = new Dial(record: record-from-ringing-dual, recordingStatusCallback: new Uri(https://example.com/recording_status)); dial.Conference(teamcall); response.Append(dial); Console.WriteLine(response.ToString());; } } python from signalwire.voice_response import VoiceResponse, Dial, Conference response = VoiceResponse() dial = Dial(record=record-from-ringing-dual, recording_status_callback=https://example.com/recording_status) dial.conference(teamcall) response.append(dial) print(response) ruby require signalwire/sdk response = Signalwire::Sdk::VoiceResponse.new do |response| response.dial(record: record-from-ringing-dual, recording_status_callback: https://example.com/recording_status) do |dial| dial.conference(teamcall) end end puts response.to_s This example connects the caller to the conference call, **teamcall**. With dual-channel recording, each participant in the call will be recorded in a separate channel. The recording will then be stored in a single recording file. Since we have set record to **record-from-ringing-dual**, the recording will begin when the phone starts to ring.