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": 40,
      "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:

Type: absolute URL

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

Type: absolute URL

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

dialCallStatus Valid Values

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

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.

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

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

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:

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.

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

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.

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

Type: integer > 0
Default: 40 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.

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.