Dial

Create a new call by dialing out to a telephone number, a registered sip user, a sip uri, or a Microsoft Teams user.

Overview

The dial verb creates a new call by dialing out to a telephone number, a registered SIP user, a SIP URI, or a Microsoft Teams user.

Example

{
  "verb": "dial",
  "actionHook": "/outdial",
  "callerId": "[phone]",
  "answerOnBridge": true,
  "dtmfCapture": ["*2", "*3"],
  "dtmfHook": {
    "url": "/dtmf",
    "method": "GET"
  },
  "amd": {
    "actionHook": "/answeringMachineDetection",
    "disconnectOnAMD": true
  },
  "target": [
    {
      "type": "phone",
      "number": "[phone]",
      "trunk": "Twilio"
    },
    {
      "type": "sip",
      "sipUri": "sip:[e-mail]",
      "auth": {
        "username": "foo",
        "password": "bar"
      },
      "proxy": "sip:192.0.0.1:5060"
    },
    {
      "type": "user",
      "name": "[e-mail]"
    }
  ]
}

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”) 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).

Endpoint types you can dial:

• Telephone number — sent out through your configured Carrier
• WebRTC or SIP client — registered directly with your subdomain
• SIP endpoint — identified by a SIP URI (and optionally authentication)
• Microsoft Teams user

Parameters

Parameter	Type	Required	Description
target	array	Yes	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.
actionHook	string	No	Webhook to invoke when the call ends. The webhook will include properties describing the outcome of the call attempt.
amd	object	No	Enable answering machine detection. See answering machine detection for details.
anchorMedia	boolean	No	If true, Graine will not release the media from feature server for the bridged call. Default: false.
answerOnBridge	boolean	No	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: false.
boostAudioSignal	string | number	No	A string or integer value indicating the number of decibels to boost or reduce the strength of the outgoing audio signal (e.g. “-6 dB”). Applies to the main track only, not to any dub tracks.
callerId	string	No	The inbound caller’s phone number, displayed to the number that was dialed. Must be a valid E.164 number. Defaults to caller ID on inbound call.
confirmHook	string	No	Webhook for an application to run on the callee’s end after the dialed number answers but before the call is connected. Allows call screening (e.g. “Press 1 to decline”). You can specify the ‘url’ property on the nested target object for destination-specific behavior.
dialMusic	string	No	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.
dtmfCapture	array	No	Array of strings representing DTMF sequences which, when detected, will trigger a mid-call notification via the configured dtmfHook.
dtmfHook	string	No	Webhook to call when a dtmfCapture entry is matched. Notification only — no response expected; use REST updateCall API for actions.
dub	object	No	A nested dub verb to add additional audio tracks into the outbound call.
exitMediaPath	boolean	No	If true, Graine will attempt to re-invite itself completely out of the media path for the call. Defaults: false. See exitMediaPath below.
forwardPAI	boolean	No	Controls if the P-Asserted-Identity and Privacy headers from the inbound call are forwarded to the outbound leg. Defaults: true.
headers	object	No	Object containing arbitrary SIP headers to apply to the outbound call attempt(s).
listen	object	No	A nested listen action to stream call audio to a remote server over a websocket.
referHook	string	No	Webhook to invoke when an incoming SIP REFER is received on a dialed call. Return HTTP 200 with no body to accept; Graine sends 202 Accepted. See sip-blind-transfer example for details.
timeLimit	number	No	Max length of call in seconds.
timeout	number	No	Ring no answer timeout, in seconds. Defaults: 60.
transcribe	object	No	A nested transcribe action to transcribe the call.

Target types

phone

Sends the call to a telephone number using one of your provisioned Carriers.

option	description	required
type	must be “phone”	yes
confirmHook	Webhook on callee’s end after answer, before connect. Overrides parent dial confirmHook.	no
number	Telephone number in E.164 format	yes
trunk	Name of a Carrier created in the Graine portal or API. If not provided, Graine selects a configured Carrier with an outbound trunk.	no

sip

Sends the call to a SIP URI. Use the auth property if the SIP trunk requires username/password.

option	description	required
type	must be “sip”	yes
confirmHook	Webhook on callee’s end after answer, before connect. Overrides parent dial confirmHook.	no
sipUri	SIP URI to send call to	yes
auth	Authentication credentials	no
auth.username	SIP username	no
auth.password	SIP password	no
proxy	SIP Proxy for the outgoing INVITE (e.g. sip:192.168.0.1:5060)	no

user

Sends the call to a registered WebRTC or SIP user.

option	description	required
type	must be “user”	yes
confirmHook	Webhook on callee’s end after answer, before connect. Overrides parent dial confirmHook.	no
name	Registered SIP user including domain (e.g. “[e-mail]”)	yes

teams

If Microsoft Teams integration is configured, you can dial out to Teams users.

option	description	required
type	must be “teams”	yes
tenant	Microsoft Teams customer tenant domain. Defaults to the tenant of the calling party.	no
number	Phone number mapped to the Teams user by the Microsoft Teams administrator	yes
voicemail	If true, dial directly into user’s voicemail to leave a message	no

The confirmHook on a target is a web callback invoked when the outdial is answered. It should return an application to run on the outbound call before bridging. If the application completes with the outbound call still connected, the two calls will be bridged.

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

actionHook properties

The actionHook invoked when the dial command ends will include:

Property	Description
dial_call_sid	Unique call_sid for the child call
dial_call_status	Final status: ‘completed’, ‘failed’, ‘busy’, ‘no-answer’, or ‘queued’
dial_sip_status	SIP status of the final response to the INVITE

amd.hook properties

When amd is included, this webhook is invoked when Graine has determined the type of called party (human or machine) or detected a tone or beep.

Property	Description
event	One of ‘amd’, ‘beep’, or ‘silence’
amd_type	’human’ or ‘machine’ (only when event = ‘amd’)

exitMediaPath

The exitMediaPath option supports use cases where the media path must not touch Graine—for example PCI-compliant credit card collection where the conversation must not be recorded or stored by Graine. Using dial with exitMediaPath: true ensures media does not flow through Graine.

For more on controlling the media path during a call, see Managing media path during call.

proxy

If you set a proxy value on the target, Graine will use it as the SIP Proxy for the outgoing INVITE (e.g. sip:192.168.0.1:5060).