Dial

Introduction

The dial command is utilized to start a new call by placing a call to a phone number, a registered SIP user, or a SIP URI.

You have the option to dial various types of endpoints, such as:

  • A phone number, which will utilize your designated Carrier to initiate the call attempt.

  • A registered SIP or WebRTC client directly associated with your subdomain.

  • A SIP endpoint identified by a SIP URI, along with any necessary authentication parameters.

The dial command can accept the following attributes:

Options

Option

Description

Required

actionHook

Specify a webhook that will be triggered when the call terminates,

and will Contain details outlining the result of the call attempt.

no

amd

Activate the capability to detect answering machines.

no

answerOnBridge

When set to true, the incoming call will continue to ring until

the dialed number answers, and a 200 OK message will be sent on

the incoming leg. If set to false, the incoming call will be answered

as soon as the outgoing call is initiated. This parameter defaults

to false. As soon as the outgoing call is established.

The default value is false.

no

callerId

The phone number of the incoming caller, which will be presented

to the called party. The caller ID must conform to the E.164 standard.

By default, the caller ID of the incoming call will be used.

no

confirmHook

Set up a webhook that triggers an application on the called party’s

side after they answer the phone but before the call is connected.

This feature enables the caller to provide information to the callee,

giving them the option to decline the call before answering. Please

note that if you want to execute different applications on specific

destinations, you can define the ‘url’ attribute on the nested target

object.

no

dialMusic

A URL that identifies an audio file in .wav or .mp3 format, which will

be played to the caller while the outgoing call is ringing, serving as

custom audio or ringback.

no

dtmfCapture

An array of strings that represent dtmf sequence which, when detect,

will trigger a mid-call notification to the application via the configured

dtmfHook.

no

dtmfHook

A web URL that will be invoked when a DTMF capture entry is match.

This is solely a notification and no response is required. Any desired

actions should be executed via the REST updateCall API.

no

headers

A collection of user-defined SIP headers to be added to the outbound

call attempt(s).

no

listen

A listen action that is nested, enabling audio from the call to be

transmitted over a websocket connection to a remote server.

no

referHook

If an incoming SIP REFER is received on a dialed call, a webhook can

be specified to handle the REFER. If the application chooses to

accept and process the REFER, it should return an HTTP status code

200 with no body. In this case, CPaaS will respond with a SIP 202

Accepted. If the application chooses not to accept the REFER, any

HTTP non-success status will cause CPaaS to send a SIP response to

the REFER with the same status code. It should be noted that CPaaS

will send the 202 Accepted and take no further action, so it is the

responsibility of the third-party application to initiate a new call

and bridge the other leg using the REST API.

no

target

An array of up to 10 destinations to be dialed simultaneously, with

the first person or entity to answer the call being connected to the

caller while the remaining numbers are disconnected.

yes

timeLimit

Max length of call in seconds

no

timeout

The amount of time, in seconds, that the call will continue ringing

without being answered before timing out. The default value is 60

seconds.

no

transcribe

A transcribe action nested within the call flow, which initiates the

transcription process for the call.

no

Target types

PSTN number

Option

Description

Required

type

The value for this field is required to be “phone”.

yes

confirmHook

A post-answer webhook that trigger an application to run on the callee’s

side before connecting the call. It take precedence over the confirmHook

property defined in the parent dial verb, if any.

no

number

An E.164 number refers to a standardized format for telephone numbers

that is recognized globally.

yes

trunk

If a value is provided for this attribute, it should be the name of a Carrier

that you have created in the jambonz portal or API and intend to use for

completing the call. If no value is provided, jambonz will automatically

choose one of your configured Carriers that has an outbound trunk.

no

SIP endpoint

Option

Description

Required

type

The value for this field is required to be “sip”.

yes

confirmHook

A post-answer webhook that trigger an application to run on the callee’s

side before connecting the call. It take precedence over the confirmHook

property defined in the parent dial verb, if any.

no

sipUri

This attribute specifies the SIP URI to which the call should be sent.

yes

auth

authentication credentials

no

auth.username

sip username

no

auth.password

sip password

no

By utilizing this method, it becomes feasible to transmit calls through a SIP trunk. In case the provider of the SIP trunk has implemented authentication with a username and password, you can provide the required credentials through the auth attribute.

A registered webrtc or sip user

Option

Description

Required

type

The value for this field is required to be “user”.

no

confirmHook

A post-answer webhook that trigger an application to run on the callee’s

side before connecting the call. It take precedence over the confirmHook

property defined in the parent dial verb, if any.

no

name

The target property specifies a registered SIP user, which includes the

domain, such as “epa@sip.epacific.net”.

no

Microsoft Teams user

In case the Microsoft Teams integration is set up, it’s possible to initiate outgoing calls to Teams users.

Option

Description

Required

type

The value for this field is required to be “teams”.

yes

tenant

Provide customer tenant domain name. Defaults to the Microsoft Teams tenant associated with the account of the calling party.

no

number

The phone number provided by Microsoft Teams administrator to map to the Teams user.

yes

voicemail

If true, connect to user’s voicemail so that you can leave a messages.

no

Example

{
    "verb": "dial",
    "actionHook": "/outdial",
    "callerId": "+84899199628",
    "answerOnBridge": true,
    "dtmfCapture": ["*2", "*3"],
    "dtmfHook": {
        "url": "/dtmf",
        "method": "GET"
    },
    "amd": {
        "hook": "/answeringMachineDetection",
        "disconnectOnAMD": true,
    }
    "target": [
        {
            "type": "phone",
            "number": "+84376120177",
            "trunk": "SBC"
        },
        {
            "type": "sip",
            "sipUri": "sip:[email protected]",
            "auth": {
                "username": "foo",
                "password": "bar"
        }
        },
        {
            "type": "user",
            "name": "[email protected]"
        }
    ]
}

As shown in the example above, when the dial command is executed, it initiates one or more outbound call attempts to establish a new call, which is connected to a parent call. The target property defines an array of call destinations that are simultaneously dialed.

If the target array contains multiple endpoints, all targets are dialed concurrently, also known as “simring” or “blast outdial.” The call is then connected to the first endpoint that answers the call or, if specified in the confirmHook property, the first call that successfully completes a call screening application.

Please contact us for timely support via: