dial@v2

Connect the current caller to another party. Replaces dial@v1 (cli becomes callerId, ring becomes an audioFile).


Version	`dial@v2`
Runs in	`inbound-call` and your own branches · `api-initiated` and `inbound-sms`

Parameters

Name	Type	Required	Default	Description
`callerId`	`"clone"` or `"restricted"` or phone number (E.164)		`"clone"`	`clone`: Use the caller ID of the current call; `restricted`: Hide the caller ID (CLIR); phone number (E.164): An approved caller ID (or a phone number) of your account accepts `${{ }}`
`parallel`	boolean		`false`	Dial all destinations in parallel (fork dialing). First target to answer wins, the other ones are canceled. accepts `${{ }}`
`answerOnBranch`	branch name			If defined, the outbound call is not bridged upon answer; the callee will receive its actions from this branch while the caller hears a ringtone. Useful for whisper messages. The Leg B branch must call bridge@v3 to bridge the legs. accepts `${{ }}`
`targets`	array of object	yes		1..5 items · accepts `${{ }}`
`targets[].number`	phone number (E.164) or SIP URI	yes		accepts `${{ }}`
`targets[].timeout`	integer	yes	`60`	5..120 · accepts `${{ }}`
`ring`	object			Audio file played in a loop to the caller while the targets ring, instead of the ringing tone
`ring.audioFile`	object	yes		An audio file of your library, by its SID (REST API v2 identifier). audio file of your library: `sid`

Every parameter that accepts ${{ }} can be computed from an expression.

How it works

Same as dial@v1 with two changes:

cli is now callerId: clone (default), restricted (hidden caller ID, CLIR), or a phone number in E.164 format (caller ID rules apply when the call is placed)
ring is an audio file of your library: ring: { audioFile: { sid } }

From an api-initiated or inbound-sms branch, answerOnBranch is required and ring is not available.

Examples

Short example

- action: dial@v2
  params:
    targets:
      - number: '+33199004242'
        timeout: 30
  result: $dial

Full example with defaults

- action: dial@v2
  params:
    callerId: clone # clone | restricted | '+33199000000'
    parallel: false
    ring: # audio file played in a loop while the targets ring, instead of the ringing tone
      audioFile:
        sid: 'fdsanjkf'
    targets:
      - number: '+33199004242'
        timeout: 30
    answerOnBranch: outboundCall # the branch must call bridge@v3 when ready
  result: $dial

Using the result

- if: "!$dial?.ok"
  action: play@v3
  params:
    tts:
      text: Sorry, I couldn't connect you to the other party.

Result

Set result: $myVariable to keep it. Result of dial@v1 and dial@v2

Field	Type	Description
`ok`	boolean	`true` when the callee answered and was bridged with the caller (`status: bridged`)
`status`	`bridged`, `answered`, `dialing`, `noanswer`, `busy`, `failed`, `error_dial_on_leg_b`, `error_no_targets`	Outcome of the call. `rejected:<reason>` when the platform refused to place the call (for example `rejected:prefix-blacklisted`)
`callid`	integer or null	Call ID of the outbound leg (leg B), `null` when no call was placed
`cdr`	object or null	CDR of the outbound leg, same format as `call.cdr` (it depends on `compat.version`). `null` when no call was placed, or when the CDR was not ready within 4 seconds
`hangup`	`caller`, `callee`, `null`	`caller` when the caller hung up first, `callee` when the outbound leg ended first (answered or not). `null` when no call was placed

{
  "ok": true,
  "status": "bridged",
  "callid": 1234567890,
  "cdr": null,
  "hangup": "callee"
}

Older versions

Older versions keep working in existing scenarios. Use the version above in new scenarios.

dial@v1: Connect the current caller to another party