Dial

{
  "verb": "dial",
  "actionHook": "/outdial",
  "callerId": "+815099990004",
  "answerOnBridge": true,
  "srtpEncryption": "sdes",
  "dtmfCapture": ["*2", "*3"],
  "dtmfHook": {
    "url": "/dtmf",
    "method": "GET"
  },
  "amd": {
    "actionHook": "/answeringMachineDetection",
    "disconnectOnAMD": true,
  },
  "target": [
    {
      "type": "phone",
      "number": "+815099990005",
      "trunk": "MyCarrier"
    },
    {
      "type": "sip",
      "sipUri": "sip:815099990001@sip.carrier.example.net",
      "auth": {
        "username": "foo",
        "password": "bar"
      },
      "proxy" : "sip:192.0.0.1:5060"
    },
    {
      "type": "user",
      "name": "hanako@sip.example.com"
    }
  ]
}

As the example above illustrates, when you execute the dial command you are making one or more outbound call attempts in an effort to create one new call, which is bridged to a parent call. The target property specifies an array of call destinations that will be attempted simultaneously.

If multiple endpoints are specified in the target array, all targets are outdialed at the same time (e.g., "simring", or "blast outdial" as some folks call it) and the call will be connected to the first endpoint that answers the call (or, optionally, the first call that completes a call screening application as specified in the confirmHook property).

There are several types of endpoints that you can dial:

• a telephone phone number -- this call attempt will be sent out through your configured Carrier,
• a webrtc or sip client that has registered directly with your subdomain,
• a sip endpoint, identified by a sip uri (and possibly authentication parameters), or
• Microsoft Teams user

Parameters

array of up to 10 destinations to simultaneously dial.
The first person (or entity) to answer the call will be connected to the caller, and the rest of the called numbers will be hung up.

webhook to invoke when the call ends. The webhook will include properties describing the outcome of the call attempt.

enable answering machine detection; see the amd properties of the dial Function for details.

if true, Wipple CPaaS will not release the media from media server for the bridged call.
Default: false.

If set to true, the inbound call will ring until the number that was dialed answers the call, and at that point a 200 OK will be sent on the inbound leg.
If false, the inbound call will be answered immediately as the outbound call is placed.
Defaults to false.

A string or integer value indicating the number of decibels to boost or reduce the strength of the outgoing audio signal to the caller/called party, e.g. "-6 dB". Note this applies to the main track only, not to any dub tracks.

The inbound caller's phone number, which is displayed to the number that was dialed.
The caller ID must be a valid E.164 number.
Defaults to caller ID on inbound call.

Codec names, in preference order, to offer on the outbound INVITE, e.g. ["G722", "PCMU"]. Names are case-insensitive.
When omitted, Wipple CPaaS offers its default codecs with the inbound leg's codec placed first, so that both legs of the bridged call use the same codec and media can be released from the media server.
If any name is not supported by the media server, the whole list is ignored, an error is logged, an alert is written to the account, and default codec negotiation is used.

webhook for an application to run on the callee's end after the dialed number answers but before the call is connected.
This allows the caller to provide information to the dialed number, giving them the opportunity to decline the call before they answer.
Note that if you want to run different applications on specific destinations, you can specify the 'url' property on the nested target object.

url that specifies a .wav or .mp3 audio file of custom audio or ringback to play to the caller while the outbound call is ringing.

an array of strings that represent DTMF sequences which, when detected, will trigger a mid-call notification to the application via the configured dtmfHook.

a webhook to call when a dtmfCapture entry is matched.
This is a notification only -- no response is expected, and any desired actions must be carried out via the REST updateCall API.

a nested dub Function to add additional audio tracks into the outbound call.

if true, Wipple CPaaS will attempt to re-invite itself completely out of the media path for the call; see below for details.
Defaults to false.

Controls if the P-Asserted-Identity & Privacy headers from the inbound call are forward to the outbound leg. Defaults to true.

an object containing arbitrary SIP headers to apply to the outbound call attempt(s).

a nested listen action, which will cause audio from the call to be streamed to a remote server over a websocket connection.

webhook to invoke when an incoming SIP REFER is received on a dialed call.
If the application wishes to accept and process the REFER, the webhook application should return an HTTP status code 200 with no body, and Wipple CPaaS will send a SIP 202 Accepted.
Otherwise, any HTTP non-success status will cause Wipple CPaaS to send a SIP response to the REFER with the same status code.

Note that Wipple CPaaS will send the 202 Accepted and do nothing further. It is the responsibility of the third-party application to outdial a new call and bridge the other leg, presumably by using the REST API.

Request encrypted media (SRTP) on an outbound call to a sip target.
Allowed values: sdes, dtls.

• sdes — negotiate SRTP keys via SDES crypto attributes in the SDP offer (the RTP/SAVP profile with an a=crypto line); this is what SIP endpoints such as LiveKit expect.
• dtls — negotiate SRTP keys via DTLS-SRTP.
  Pair it with a sips: / transport=tls sipUri so that both the signaling (TLS) and the media (SRTP) are encrypted; the sips: scheme controls TLS on signaling, while srtpEncryption controls encryption of the media.
  When omitted, media is sent unencrypted (RTP/AVP). Applies to sip targets only.

max length of call in seconds.

ring no answer timeout, in seconds.
Defaults to 60.

a nested transcribe action, which will cause the call to be transcribed.

target types

phone

Sends the call to a telephone number using one of your provisioned Carriers. The following properties are available:

sip

Sends the call to a sip uri. If the sip trunking provider enforces username/password authentication, supply the credentials in the auth property. The following properties are available:

user

Sends the call to a registered webrtc or sip user. The following properties are available:

teams

If Microsoft Teams integration has been configured, you can dial out to Teams users. The following properties are available:

The confirmHook property that can be optionally specified as part of the target types is a web callback that will be invoked when the outdial call is answered. That callback should return an application that will run on the outbound call before bridging it to the inbound call. If the application completes with the outbound call still in a stable/connected state, then the two calls will be bridged together.

Note

The confirmHook allows you to easily implement call screening applications (e.g. "You have a call from so-and-so. Press 1 to decline").

actionHook properties

The actionHook that is invoked when the dial command ends will include the following properties:

amd.hook properties

This webhook that is invoked when amd property is included and Wipple CPaaS has either determined the type of called party (human or machine) or has detected a tone or beep.

exitMediaPath

The purpose of the exitMediaPath is to support use cases where it is important that the media path not touch the Wipple CPaaS system at all. The common use case is the need to transfer a call to a human agent or credit card system where the caller will be giving their credit card details over the phone. In order to have a PCI-Compliant transaction it is necessary that this conversation not be able to be recorded, stored, or in any way reach the Wipple CPaaS system. Performing the dial Function using the exitMediaPath property ensures this happens.

proxy

If you set a proxy value on the target then Wipple CPaaS will use this as a SIP Proxy for the outgoing INVITE, for example sip:192.168.0.1:5060

srtpEncryption

By default Wipple CPaaS sends media to a dialed sip target as unencrypted RTP. Set srtpEncryption to sdes to request encrypted media (SRTP) on the outbound leg — Wipple CPaaS will offer the RTP/SAVP profile with an a=crypto SDES key in the SDP.

This is independent of signaling encryption: the sips: scheme (or ;transport=tls) on the sipUri is what makes the SIP signaling go over TLS, while srtpEncryption is what encrypts the media. To secure both — as required by endpoints such as LiveKit — use a sips: uri together with srtpEncryption:

{
  "verb": "dial",
  "answerOnBridge": true,
  "srtpEncryption": "sdes",
  "target": [
    {
      "type": "sip",
      "sipUri": "sips:1234567890@your-project.sip.livekit.cloud:5061;transport=tls"
    }
  ]
}

Note

srtpEncryption applies to sip uri targets only. It has no effect on phone, user, or teams targets (for a Carrier, configure SRTP on the Carrier's SIP gateway instead).