Create Outbound Calls¶

Outbound calls are calls initiated by Voice Gateway to an external endpoint, such as a phone number, call center, or another system capable of handling voice communication.

Before initiating an outbound call, ensure you configure an application, and the phone number you intend to call from is added to Phone Numbers.

To initiate an outgoing call, use on of the following methods:

Transfer Node
REST API request:
- HTTP Request Node
- API Request via Postman or CLI

Create an Outbound Call via API Request¶

Send an HTTP POST request to the Voice Gateway API to generate an outbound call. When the call is answered, the specified webhook will be invoked to manage the call. Authorization is established via a Bearer token. This token is filled with an API key value generated in the Voice Gateway Self-Service Portal.

Basic Configuration Request¶

The basic configuration provides details for initiating and managing calls, enabling the system to establish a connection between the caller and the callee. It also includes call duration, handling unanswered calls, and attaching relevant metadata.

cURLJSON

curl --location --request POST 'https://<base_url>/v1/Accounts/<account_sid>/Calls' \
--header 'Authorization: Bearer <valid-api-token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "application_sid": "<application_sid>",
    "from": "<caller's phone number>",
    "to": {
        "type": "phone",
        "number": "<callee's phone number>"
        }
}'

POST /v1/Accounts/<account_sid>/Calls HTTP/1.1
Host: <base_url>
Authorization: Bearer <valid-api-token>
Content-Type: application/json

{
    "application_sid": "<application_sid>",
    "from": "<caller's phone number>",
    "to": {
        "type": "phone",
        "number": "<callee's phone number>"
    }
}

The following parameters can be provided in the request body:

Parameter	Description	Required
application_sid	The application to invoke when the call is answered.	Yes
from	The caller's phone number.	Yes
to	The callee's phone number.	Yes
timeLimit	Maximum length of call in seconds.	No
timeout	Ring `no-answer` timeout, in seconds. Default is 60 seconds.	No
tag	An object containing key-value pairs of metadata that will be attached to this call.	No

Advanced Configuration Request¶

The advanced configuration provides a range of features to enhance call handling and management. It includes notifications, interaction hooks, header manipulation and transcription capabilities.

In the example below, we enable the Answering Machine Detection feature using the amd parameter and use the actionHook parameter to send the events to the Webhook site. To limit the call duration, we set a timeout of 30 seconds using the timeout parameter. If the call is not answered within the specified time, Voice Gateway stops calling. We include tags in the tags parameter to send custom information about the user, such as a custom object, as well as headers to send custom headers.

cURLJSON

curl --location --request POST 'https: //<base_url>/v1/Accounts/<account_sid>/Calls' \
--header 'Authorization: Bearer <valid-api-token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "application_sid": "<application_sid>",
    "from": "<caller's phone number>",
    "to": {
        "type": "phone",
        "number": "<callee's phone number>"
    },
    "amd": {
        "actionHook": "https://webhook.site/<webhook-id>"
    },
    "timeout": 30000,
    "tag": {
        "env": "app",
        "internalId": "ABDC1234",
        "Customer": {
            "firstName": "Sara",
            "lastName": "Doe",
            "mobileNumber": "<callee's phone number>",
            "email": "sara.doe@cognigy.com",
            "salutation": "Ms"
        }
    },
    "headers": {
        "User-to-User": "UUID: <number>"
    }
}'

POST /v1/Accounts/<account_sid>/Calls HTTP/1.1
Host: <base_url>
Authorization: Bearer <valid-api-token>
Content-Type: application/json

{
  "application_sid": "<application_sid>",
  "from": "<caller's phone number>",
  "to": {
    "type": "phone",
    "number": "<callee's phone number>"
  },
  "amd": {
    "actionHook": "https://webhook.site/<webhook-id>"
  },
  "timeout": 30000,
  "tag": {
    "env": "app",
    "internalId": "ABDC1234",
    "Customer": {
      "firstName": "Sara",
      "lastName": "Doe",
      "mobileNumber": "<callee's phone number>",
      "email": "sara.doe@cognigy.com",
      "salutation": "Ms"
    }
  },
  "headers": {
    "User-to-User": "UUID: <number>"
  }
}

In addition to the basic configuration parameters, the following parameters can be provided in the request body:

Parameter	Description	Required
actionHook	Webhook to invoke when the call ends. The webhook includes properties describing the outcome of the call attempt.	No
amd	The activation of Answering Machine Detection.	No
confirmHook	A webhook designed for an application to execute on the callee's end after the dialed number has been answered, but before the call is connected. It allows the caller to provide information to the dialed number, giving them the opportunity to decline the call before answering.	No
dtmfCapture	An array of strings representing DTMF sequences. When detected, these sequences trigger a mid-call notification to the application via the configured dtmfHook.	No
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.	No
headers	An object containing arbitrary SIP headers to apply to the outbound call attempts.	No
listen	A nested `listen` action that streams call audio to a remote server over a WebSocket.	No
referHook	A webhook that gets triggered when an incoming SIP `REFER` is received on a dialed call. If the application accepts and processes the `REFER`, it should return an HTTP status code of `200` with no body. This will cause Voice Gateway to send a SIP `202 Accepted`. However, if the HTTP response is not successful, Voice Gateway will send a SIP response to the `REFER` with the same status code. Note that Voice Gateway sends the `202 Accepted` code without any further action. Then, it is the third-party application's responsibility to initiate a new call and establish the bridge between the two parties via REST API.	No
transcribe	A nested `transcribe` action that transcribes a call.	No

Response¶

The server responds with HTTP 201 and provides the session identifier (sid) of the outbound call session and the call identifier (callid) of the INVITE.

{
    "sid":"98e4dd21-b178-4af1-83b6-3c1582893890",
    "callid":"8d07a246-f1ac-123b-b8ac-02113b73b840"
}

Use Cases¶

Use cases for creating outbound calls may vary. As examples, consider the following use cases:

Transfer a call
Make a follow-up call

Transfer a Call¶

The voice agent orchestrates a transfer (outbound call) to the call center.

Sequence of interactions:

A user initiates an inbound call.
Voice Gateway passes the call to the voice agent.
The voice agent initiates a transfer to the call center via Voice Gateway.
The call center receives the transferred call.

To implement this use case, utilize a Transfer Node in your voice Flow.

Make a Follow-up Call¶

The voice agent triggers an outbound call to the user for follow-up purposes, for example, to provide additional troubleshooting steps, offer a resolution to the user issue, or follow up on their satisfaction with the support received.