> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognigy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Dial
Updated in 2026.9
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.
```json expandable theme={null}
{
"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"
}
]
}
```
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](#actionhook-properties) describing the outcome of the call attempt. The default value is `dial`. | No |
| amd | object | Enables the [Answering Machine Detection](/voice-gateway/references/verbs/amd), 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](/voice-gateway/references/verbs/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](/voice-gateway/references/verbs/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](#changing-the-media-path-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](/voice-gateway/references/verbs/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](/voice-gateway/webapp/carriers) 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