Making outbound calls by using REST API

Configuring outbound dialing

To configure outbound calling for single tenant environments, refer to the Outbound calls environment variables.

To configure outbound calling for multi-tenant environments, refer to Configuring a multi-tenant deployment for outbound dialing and the Multi-tenant deployment settings.

Initiating an outbound call via a REST API

To make a new outbound call, make an HTTP POST request to the following URL:

https://<hostname>:<port>/vgw/outboundCalls/<tenantID>/startOutboundCall

Provide data in JSON format.

The API returns the ID of the newly created outbound call, or an error message if an error occurred when trying to start the call.

Note: HTTP Basic authentication is used to authorize a REST request.

Initiating an outbound call using the cURL commands

You can perform REST API operations by using the cURL command. Use the following request format:

curl -X <HTTP request> --header 'Content-Type: application/json' --header 'Accept: application/json' -d <JSON data>

You can also specify the following options. For details about each option, see documentation for cURL.

-k: Bypass SSL/TLS encryption for an unsecured connection
-u: <user name>:<password>: Send the user name and password (if you enabled authentication for the REST API)

Initiate an outbound call using the cURL command:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application json' \
-d '( \
     "from": "sip:alice@example.com", \
     "to": "tel:+1234556789", \
     "statusWebhook": "http:www.example.com"\
)' 'http://<hostname>:<port>/vgw/outboundCalls/<tenantID>/startOutboundCall'

Configuring a single tenant deployment for outbound dialing

To configure outbound calling for single tenant environments, refer to the Single tenant deployment environment variables

Configuring a multi-tenant deployment for outbound dialing

To enable outbound calling, include a section like the following example in the tenant configuration. For more information on these properties, see Multi-tenant deployment settings.

{
  ...
  "enableOutboundCalls": true,
  "outboundCalls": {
    "statusWebhook": "<URL for asynchronous notifications>",
    "statusWebhookUsername": "<username to authenticate when sending asynchronous notifications>",
    "statusWebhookPassword": "<password to authenticate when sending asynchronous notifications>",
    "tenantURI": "<tenant SIP / Tel URI>",
    "connectTimeout": 3,
    "readTimeout": 5,
    "maxRetryNo": 2
  },
  "restAPI": {
    "username": "<username>",
    "password": "<password>"
  }
}

Conversation turns

When a REST API call is activated for outbound calls, Voice Gateway initiates a turn to the Conversation service. A vgwIsOutboundCall state variable is set to Yes to specify that it's an outbound call. Once the Conversation service and Media relay are initialized successfully, Voice Gateway issues an INVITE request with an offer to the specified destination.

When a call is successfully established, Voice Gateway starts speech recognition and activates the response timer. A new turn is initiated to the Conversation service when either the response timer expires or an input is detected from the user.

Asynchronous notifications

If a webhook URL was provided, Voice Gateway will send asynchronous notifications about the call state. A notification is sent in JSON format.

Reporting interface

For outbound calls, CDR reports will contain an outboundCall field set to true.