OutDial

The OutDial command is used to call a phone number.

PerCL commands are always executed in the context of a specific call leg. When OutDial is successful, an entirely new execution context is created in the form of the child call leg that has been created. Handling the Call that initiated the OutDial (the parent call) and the Call that was created via OutDial (the child call) can be done independently. To enable this, the OutDial command provides two callback URLs — one for the parent call leg and one for the child leg. The Webhooks sent to both URLs contain data that shows the relationship between the two Calls.

The parent call and child call can be connected to each other using a Conference, or the two Calls can move on independently of each other. The logical separation between creating a Call and determining what to do with the created Call (as well as the Call that created it) enables you to design flexible solutions to accomplish your goals.

The OutDial command is non-blocking — that is, it returns immediately. Meanwhile, FreeClimb starts the OutDial. It is possible for the client application to do other things, such as put the Call on hold, or to go ahead and make other out dials. This makes things such as call blast very easy to implement. OutDial is a terminal command: control of the call is picked back up on the outdialed actionUrl callback. Control for the new call leg will be picked up on the callConnectUrl callback.

🚧

International calling is disabled by default

Nesting Rules

No actions can be nested within OutDial, and OutDial cannot be nested in any other actions.

Example

[
  {
    "OutDial": {
      "destination": "+18475722071",
      "callingNumber": "+17113334444",
      "timeout": 30,
      "callConnectUrl": "http://www.example.com/OutDialEstablished",
      "actionUrl": "http://www.example.com/OutDialSpawned"
    }
  }
]

Notes

Connecting the Call to another Call or to a Conference with many participants is done using the AddToConference PerCL command.


Command Attributes

The OutDial command supports the following attributes that modify its behavior:

Attribute

Description

actionUrl

URL to which FreeClimb sends an HTTP POST request.

callConnectUrl

URL to which FreeClimb makes an HTTP POST request informing the result of the OutDial.

callingNumber

The caller ID to show to the called party when FreeClimb calls.

destination

E.164 representation of the phone number to call.

ifMachine

Specifies how FreeClimb should handle this OutDial if an answering or fax machine answers the Call.

ifMachineUrl

When the ifMachine flag is set to redirect, this attribute specifies a URL to which FreeClimb makes a POST request when an answering machine or a fax machine is detected.

sendDigits

DTMF tones to play to the outdialed Call.

statusCallbackUrl

When the outdialed Call leg terminates, FreeClimb sends a callStatus Webhook to the statusCallbackUrl.

timeout

Maximum time in seconds the OutDial command waits for the called party to answer the Call.

privacyMode

Indicates if the request contains sensitive information which should be hidden.


actionUrl

Required

Type: absolute URL
Default: null

URL to which FreeClimb sends an HTTP POST request (an outDialStart Webhook) immediately when the OutDial command executes. PerCL received in response to this URL is executed on the parent Call that requested the OutDial. This allows the parent Call leg to proceed without being blocked by the outdialing process.

The callId parameter in the Webhook body is for the parent Call. Note that the actual status of the child Call leg is not known until later when FreeClimb invokes the callConnectUrl.

Additional Request Parameters

Request Parameter

Description

`dialCallId`

The ID of the child Call that was generated as a result of the OutDial.


callConnectUrl

Required

Type: absolute URL
Default: null

URL to which FreeClimb makes an HTTP POST request informing the result of the OutDial. The status property of the request message specifies if the call was connected or not. Any PerCL received in response to this URL is executed on the child Call leg that was generated as a result of the OutDial.

📘

A PerCL response is expected if the outbound call is connected (status=inProgress).

Additional Request Parameters

Request Parameter

Description

`parentCallId`

The Call ID of the leg which initiated the child Call

`dialCallStatus`

The outcome of the dial attempt.
Valid values are listed below.

dialCallStatus Valid Values

Value

Description

`inProgress`

The called party answered the call.

`busy`

FreeClimb received a busy signal when trying to connect to the called party.

`noAnswer`

The called party did not pick up before the timeout period passed.

`failed`

FreeClimb was unable to route to the given phone number.
This is frequently caused by dialing a properly formatted but non-existent phone number.

`canceled`

The Call was canceled via the REST API before it was answered.


callingNumber

Required

Type: E.164 phone number (e.g. +13125551212)
Default: null

The caller ID to show to the called party when FreeClimb calls. This can be one of the following:

  • The To or From number provided in the first Webhook to your webserver.
  • Any phone number you have purchased from FreeClimb.

destination

Required

Type: E.164 phone number (e.g. +13125551212)
Default: null

E.164 representation of the phone number to call. For trial accounts, this number must be verified.


ifMachine

Optional

Type: string
Default: null

Specifies how FreeClimb should handle this OutDial if an answering machine answers the Call. Must be one of two valid values:

Value

Description

`redirect`

Invokes the ifMachineUrl for instructions.

`hangup`

Hangs up the Call. The ifMachineUrl will not be invoked.

Processing of the Call continues normally if ifMachine is empty.

Note that ifMachine detects an answering machine via the tone stream; therefore, the accuracy is less than 100 percent and may not work reliably in all countries.

Also, the callConnectUrl, almost always, is invoked before the ifMachineUrl – as such, if PerCL returned by callConnectUrl is being executed when a machine is detected, the execution is affected if this flag is set to redirect or hangup. If the value is hangup, the Call is hung up. If the value is redirect, the currently executing Call connect PerCL is aborted, and the ifMachineUrl invoked. If the outdialed Call has already been placed in a Conference, it is up to the application to decide how to treat the Call when the ifMachineUrl is invoked.


ifMachineUrl

Optional

Type: absolute URL
Default: null

When the ifMachine flag is set to redirect, this attribute specifies a URL to which FreeClimb makes a POST request when an answering machine or a fax machine is detected. This URL is required if the ifMachine flag is set to redirect. Otherwise, it must be omitted.

Note: Including ifMachineUrl when ifMachine is set to hangup results in the command being rejected.

Note: A PerCL response is expected to control the Call.

Additional Request Parameters

Request Parameter

Description

`machineType`

The type of machine detected. Valid values are answeringMachine or faxMachine.


sendDigits

Optional

Type: digits 0-9, #, or *
Default: null

DTMF tones to play to the outdialed Call. This is typically used to dial a number and then dial an extension.


statusCallbackUrl

Optional

Type: absolute URL
Default: null

When the outdialed Call leg terminates, FreeClimb sends a callStatus Webhook to the statusCallbackUrl. This is a notification only; any PerCL command returned is ignored.

Additional Request Parameters

Request Parameter

Description

`parentCallId`

ID of the call leg which initiated the OutDial.

`callDuration`

Duration in seconds of the completed Call.

`recordingUrl`

URL of the Call's recorded audio file. This URL can be used in a Play command to play the Recording, or can be used to download the Recording file. No authentication is needed when this URL is used in the Play command.

`recordingId`

Unique ID of the Recording from this Call.

`recordingDurationSec`

Duration in seconds of the Recording, rounded up to the nearest second.


timeout

Optional

Type: integer > 0
Default: 30 seconds

Maximum time in seconds the OutDial command waits for the called party to answer the Call. When a timeout occurs, FreeClimb invokes the callConnectUrl Webhook to report that the out-dialed Call has ended with a status of noAnswer.


privacyMode

Optional

Type: boolean
Default: false

Indicates if the request contains sensitive information which should be hidden. When set to true, the contents of the sendDigits attribute will be replaced with the string "xxxxx" in the logs.