Dial - Cognigy Documentation

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

Dial Verb

The dial verb initiates a new call by connecting to a telephone number, a registered SIP user, or a SIP URI. In the example, the dial verb creates a new call and joins it to a parent call. The target property specifies multiple call destinations attempted simultaneously.

{
  "verb": "dial",
  "actionHook": "dial",
  "callerId": "+491173331212",
  "answerOnBridge": true,
  "dtmfCapture": ["*2", "*3"],
  "dtmfHook": {
    "url": "/dtmf",
    "method": "GET"
  },
  "amd": {
        "actionHook": "amd",
        "recognizer": {
            "vendor": "microsoft",
            "language": "en-US"
        }
    },
  "target": [
    {
      "type": "phone",
      "number": "+49XXXXXXXXXXX",
      "trunk": "Twilio"
    },
    {
      "type": "sip",
      "sipUri": "sip:49XXXXXXXXXXX@sip.myTrunk.com",
      "auth": {
        "username": "John",
        "password": "Doe"
      }
    },
    {
      "type": "user",
      "name": "jane@sip.example.com"
    }
  ]
}

Types of Endpoints

When multiple endpoints are mentioned in the target array, all the endpoints are dialed at the same time (also known as simring or blast dial). The call will be connected to the first endpoint that answers the call or completes a call screening application, as specified in the confirmHook property. There are several types of endpoints you can dial:

A telephone number, sent through your configured carrier.
A SIP endpoint, identified by a SIP URI (with optional authentication).
A registered SIP user, identified by their SIP username.
A Microsoft Teams user, identified by their phone number and tenant ID.

Configuration

The following table lists the available parameters:

Parameter	Type	Description	Required
actionHook	string / object	A webhook to receive an HTTP POST when the call ends. The webhook includes the properties describing the outcome of the call attempt. The default value is `dial`.	No
amd	object	Enables the Answering Machine Detection, which identifies if the called party is human, machine, or a tone/beep.	No
anchorMedia	boolean	If `true`, Voice Gateway will anchor the media, keeping RTP flowing through the server even when a call is bridged. The default value is `false`.	No
answerOnBridge	boolean	For an inbound call, if `true`, the call will continue ringing until the dialed number answers. Once answered, a 200 OK is sent on the inbound call. If `false`, the inbound call connects as soon as the outbound call is placed. The default value is `false`.	No
boostAudioSignal	string / number	Increases or decreases the outgoing audio signal by a specified number of decibels. For example, `-6 dB` reduces volume.	No
callerId	string	The phone number displayed to the dialed number. Must be a valid E.164 number. If not provided, the caller ID from the inbound call is used.	No
callerName	string	The caller name displayed on the outbound call.	No
confirmHook	string / object	A webhook that runs on the callee’s end after answering but before the call is connected. This allows the callee to hear information and accept or decline the call. Individual targets can override this using their own `confirmHook`.	No
dialMusic	string	The URL of a WAV or MP3 file to play to the caller as custom audio or ringback while the outbound call is ringing. The URL doesn’t need to include the file extension.	No
dtmfCapture	array	An array defining DTMF sequences that trigger mid-call notifications to the application via the configured `dtmfHook`.	No
dtmfHook	string / object	A webhook triggered when a `dtmfCapture` sequence is detected. This is a notification-only webhook.	No
dub	array	An array of nested dub verbs to add background audio tracks to the call.	No
exitMediaPath	boolean	If `true`, allows media to exit Voice Gateway when the call is bridged. The default value is `false`.	No
headers	object	An object of SIP headers to apply to the outbound call attempts.	No
listen	object	A nested listen verb that streams call audio to a remote server via WebSocket.	No
mediaPath	string	A string specifying the media path configuration. You can also change this value during an active call using the `updateCall` API.	No
onHoldHook	string / object	A webhook invoked when the call is placed on hold.	No
proxy	string	A SIP proxy address used for the outbound call.	No
referHook	string / object	A webhook invoked when a SIP `REFER` is received on a dialed call. If accepted (HTTP 200), Voice Gateway sends a SIP `202 Accepted`. Non-success responses cause the SIP response to mirror that status code.	No
tag	object	Custom data associated with this `dial` verb.	No
target	array	An array of up to 10 destinations to simultaneously dial. The endpoint that answers first is connected to the caller; all other calls are hung up.	Yes
timeLimit	number	The maximum call duration in seconds.	No
timeout	number	Ring-no-answer timeout in seconds. The default value is `60`.	No
transcribe	object	A nested transcribe verb, which causes the call to be transcribed.	No

Target Types

PSTN Number

Parameter	Type	Description	Required
type	string	Select a `phone` type.	Yes
number	string	A telephone number in E.164 format.	Yes
confirmHook	string / object	A webhook that triggers an application on the callee’s end after the dialed number answers but before the call is connected. This action will override any `confirmHook` property set on the parent `dial`.	No
from	object	An object specifying the `user` and `host` for the From header.	No
headers	object	An object containing SIP headers to include in the INVITE request.	No
overrideTo	string	A string to override the To header in the SIP INVITE.	No
proxy	string	A SIP proxy address to use for this target.	No
trunk	string	If provided, this should be the name of a carrier that you created in the Voice Gateway Self-Service portal, which you want to use to complete this call. If not provided, Voice Gateway will select one of your configured carriers that has an outbound SIP trunk.	No

SIP Endpoint

Parameter	Type	Description	Required
type	string	Select a `sip` type.	Yes
sipUri	string	SIP URI to send the call to.	Yes
auth	object	Authentication credentials.	No
auth.username	string	SIP username.	Yes (if auth is provided)
auth.password	string	SIP password.	Yes (if auth is provided)
confirmHook	string / object	A webhook that triggers an application on the callee’s end after the dialed number answers but before the call is connected. This action will override any `confirmHook` property set on the parent `dial`.	No
from	object	An object specifying the `user` and `host` for the `From` header.	No
headers	object	An object containing SIP headers to include in the `INVITE` request.	No
overrideTo	string	A string to override the To header in the SIP INVITE.	No
proxy	string	A SIP proxy address to use for this target.	No

If the SIP Carrier provider requires username/password authentication, specify the credentials in the auth parameter.

User Endpoint

Parameter	Type	Description	Required
type	string	Select a `user` type.	Yes
name	string	The registered SIP user name.	Yes
confirmHook	string / object	A webhook that triggers an application on the callee’s end after the dialed number answers but before the call is connected.	No
from	object	An object specifying the `user` and `host` for the From header.	No
headers	object	An object containing SIP headers to include in the INVITE request.	No
overrideTo	string	A string to override the To header in the SIP INVITE.	No
proxy	string	A SIP proxy address to use for this target.	No
vmail	boolean	If `true`, the call will be sent to the voicemail of the user.	No

Microsoft Teams Endpoint

Parameter	Type	Description	Required
type	string	Select a `teams` type.	Yes
number	string	The Teams user’s phone number.	Yes
tenant	string	The Microsoft Teams tenant ID.	Yes
confirmHook	string / object	A webhook that triggers an application on the callee’s end after the dialed number answers but before the call is connected.	No
from	object	An object specifying the `user` and `host` for the From header.	No
headers	object	An object containing SIP headers to include in the INVITE request.	No
overrideTo	string	A string to override the To header in the SIP INVITE.	No
proxy	string	A SIP proxy address to use for this target.	No
vmail	boolean	If `true`, the call will be sent to the voicemail of the user.	No

ActionHook Properties

After the dial verb ends, the actionHook will be triggered and it will contain the following properties:

Property Name	Type	Description
dial_call_sid	string	The unique `call_sid` identifier for the child call.
dial_status	string	The final status of the call attempt, one of `completed`, `failed`, `busy`, `no-answer`, or `queued`.
dial_sip_status	number	The SIP status of the final response to the `INVITE` that was sent.

AMD Hook Properties

The webhook triggers when the amd parameter is used and Voice Gateway identifies the called party as either human or machine, or detects a tone or beep.

Property Name	Type	Description
event	string	Indicates one of the following events: `amd`, `beep`, or `silence`.
amd_type	string	Specifies either `human` or `machine`. This property is provided only when the event is `amd`.

More Information

Last modified on June 10, 2026