Create Outbound Calls - Cognigy Documentation

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 have configured an application and added the phone number you intend to call from to Phone Numbers. To initiate an outgoing call, use one of the following methods:

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

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, Voice Gateway invokes the specified webhook to manage the call. You authorize the request with a Bearer token. This token contains an API key value generated in the Voice Gateway Self-Service Portal.

API Base URL

The API Base URL is the endpoint used to access the Cognigy Voice Gateway API.
The table below outlines the base URLs for different environments.

Environment	API Base URL
Trial (trial.cognigy.ai)	Choose the environment you use: Trial (EU) - `https://api-vg-trial.cognigy.ai` Trial (US) - `https://api-vg-trial-us.cognigy.ai`
SaaS	Choose the environment you use: EU - `https://voicegateway-app-vg.cognigy.ai` US - `https://api-vg-us.cognigy.ai` UK - `https://api-vg-uk.cognigy.ai` AU - `https://api-vg-au.cognigy.ai` Other SaaS - use the `https://api-<company-name>-vg.cognigy.cloud` pattern where `<company-name>` is your company name. For example, if your company name is `abc123`, the URL would be: `https://api-abc123-vg.cognigy.cloud`
On-premises	Specify the API URL based on your Voice Gateway deployment configuration.
NiCE CXone Environments	Use the `cognigy-vg-api-<region>.nicecxone.com` pattern, where `<region>` matches your NiCE CXone cluster. For example, `cognigy-vg-api-na1.nicecxone.com`, `cognigy-vg-api-eu1.nicecxone.com`. For a full list of available regions, refer to NiCE CXone Shared SaaS Clusters.

Basic Configuration Request

The basic configuration provides details on initiating and managing calls, enabling the system to connect the caller and callee. It also includes call duration, handling of unanswered calls, and the attachment of 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>"
        }
}'

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

The following parameters can be provided in the request body:

Parameter	Type	Description	Required
application_sid	String	The application to invoke when the call is answered.	Yes
from	String	The user portion that identifies the caller within the domain. The user portion follows the format: `<sip:user@host>`, where `user` can be: - A username, for example, `<sip:john@host>`. - A phone number (E.164 format), for example, `<sip:+1234567890@host>`. - A unique identifier, for example, `<sip:device001@host>`.	Yes
fromHost	String	The domain of the caller, which is a part of the SIP address included in the `From` header of a SIP request. The domain follows the format: `<sip:user@host>`. For example, `<sip:user@cognigy.cloud>`, where `cognigy.cloud` is the domain where the caller’s SIP service is hosted.	No
callerName	String	A descriptive caller name that appears as the display name in a SIP request. This name is included in the `From` header, alongside the SIP address, in the following format: `From: "<callerName>" <sip:user@host>`. For example, `"John Doe" <sip:user@cognigy.cloud>`, where `"John Doe"` is the caller name and `<sip:user@cognigy.cloud>` is the SIP address.	No
to	TargetType	The destination target, either a phone number or a SIP URI.	Yes
timeout	Number	The time the system waits for an answer before considering the call unanswered. The default value is 60 seconds.	No
tag	Object	An object containing key-value pairs of metadata to be attached to this call. This metadata can be used for further call analysis, allowing you to track call details, identify patterns, and generate insightful reports.	No
headers	Object	An object containing custom SIP headers that can be applied to outbound call attempts. These headers are added alongside the system (default) headers in the SIP request. Custom SIP headers provide more control over the call setup process, including adjustments to authentication, routing, and other specific SIP parameters. For example, a custom header could be `P-Preferred-Identity: <sip:+123456@sip.cognigy.cloud>`, where the caller’s preferred identity is the specified phone number or SIP address to present during the call.	No
speech_synthesis_vendor	String	The vendor responsible for the speech synthesis service (Text-to-Speech, TTS). For example, `microsoft`.	No
speech_synthesis_voice	String	The specific voice to be used for speech synthesis. For example, `de-DE-SeraphinaMultilingualNeural`.	No
speech_synthesis_language	String	The language in which the speech should be synthesized. For example, `en-US` for American English, `es-ES` for Spanish.	No
amd	Object (AMD)	The Automatic Machine Detection (AMD) feature, which identifies whether a human or a machine answered a call.	No
notifyUrl	String/Object	An additional HTTP or WebSocket hook to receive status updates about the call, used alongside the Call Status Webhook in the application. This parameter can be configured as a simple URL (String) for the default POST request or as an object `{ "url": "", "method": "" }` to specify a different method. The choice between HTTP and WebSocket depends on your specific requirements. The most common choice is a standard HTTP hook, but a WebSocket URL can be used if desired, as it is supported for internal communication with Cognigy.AI.	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 events to Webhook. 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>"
}'

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>",
  "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 a call
Make a follow-up call

Transfer Calls

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, 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’s issue, or follow up on their satisfaction with the support received. Sequence of interactions:

A user provides information during an inbound call to the voice agent.
The voice agent triggers an outbound call to the user via a third-party service and Voice Gateway.
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.

​Create Outbound Calls via API Request

​API Base URL

​Request

​Basic Configuration Request

​Advanced Configuration Request

​Response

​Use Cases

​Transfer Calls

​Make Follow-up Calls

​More Information