Skip to main content
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 one of the following methods:

​
Create Outbound Calls 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.

​
Request

​
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.
  • cURL
  • JSON
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>",
    "callerName": "<display name>",
    "to": {
            "type": "phone",
            "number": "<callee's phone number>",
            "trunk": "<carrier name>"
        }
}'

​
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. Via timeout, we define a maximum ringing time. If the call is not answered within this time, Voice Gateway stops calling (see the NO_ANSWER event). We include tags in the tag parameter to send custom information about the user, such as a custom object, as well as headers to send custom headers.
  • cURL
  • JSON
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>",
    "fromHost": "cognigy.cloud",
    "callerName": "Vacation Agent",
    "to": {
        "type": "phone",
        "number": "<callee's phone number>",
        "trunk": "<carrier name>"
    },
    "amd": {
        "actionHook": "https://webhook.site/<webhook-id>"
    },
    "timeout": 20,
    "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>"
    },
    "notifyUrl": "https://webhook.site/<webhook-id>"
}'

​
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 Calls

The voice agent orchestrates a transfer (outbound call) to the call center. Sequence of interactions:
  1. A user initiates an inbound call.
  2. Voice Gateway passes the call to the voice agent.
  3. The voice agent initiates a transfer to the call center via Voice Gateway.
  4. The call center receives the transferred call.
To implement this use case, use a Transfer Node in your voice Flow.

​
Make Follow-up Calls

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. Sequence of interactions:
  1. A user provides information during an inbound call to the voice agent.
  2. The voice agent triggers an outbound call to the user via a third-party service and Voice Gateway.
  3. The user receives the outbound call initiated by the voice agent.
To implement this use case, use an HTTP Request Node in your voice Flow, or create an API Request via Postman or CLI.

​
More Information