GitHubContribute in GitHub: Edit online

copyright: years: 2019, 2023 lastupdated: "2023-01-06"


Making outbound calls by using REST API

Outbound calls can be made via a REST API to Session Initiation Protocol (i.e., sip or tel) URIs. This feature could be used for robo-calling or for a testing bot that could drive various dialogs. Users of the REST API can monitor the call to completion.

Outbound dialing is supported in Version 1.0.2 and later.

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.

Table 1. Expected fields
Field Name Description
to A SIP/Tel URI to be called.
from Optional. A calling party SIP/Tel URI.
context Optional. A name/value pair of state variables to be forwarded to Watson Assistant when a call starts.
tenantConfig* Optional. See the description in Table 2.
route Optional. A comma-separated list of SIP Route headers to be added to an outbound call.
statusWebhook Optional. A webhook to be used for asynchronous HTTP callbacks. Voice Gateway will use a webhook for sending notifications about the life cycle of the call.
statusWebhookUsername Optional. A username to be used for authentication when sending notifications to a webhook. Version 1.0.2 and later.
statusWebhookPassword Optional. A password to be used for authentication when sending notifications to a webhook. Version 1.0.2 and later.
Table 2. tenantConfig settings
Field Name Description
config Configuration settings to be used for the call. See Advanced JSON configuration properties for the format and configuration settings names.
updateMethod Optional. Valid values are merge and replace; the default is merge. Indicates whether to merge the settings with the existing configuration settings for that tenant or overwrite them. Only the settings specified in the config field will be merged with the existing settings. If a certain setting or object isn't specified, Voice Gateway will use the settings configured for that tenant.

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.

Table 3. Response fields
Field Name Description
vgwSessionID The unique identifier of the newly created session.
failureReason Optional. A failure reason in case an error occurred when trying to start a call.
Table 4. HTTP Status codes
HTTP Status Code Response Model
200 vgwSessionID
400 failureReason (string)
403 failureReason (string)
404 failureReason (string)

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.

Table 5. Expected fields
Name Description
vgwSessionID The unique identifier of the newly created session.
callState Call state.
failureReason Optional. A failure reason if an error occurred.
Table 6. Call state
State Description
started An INVITE request was sent to the destination.
ringing A 180 response was received.
active The call is successfully connected.
transferred The call was transferred.
failed A failure occurred.
ended The call was disconnected.

Reporting interface

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