Introduction
Voice Agent with Watson provides Outbound calls that 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.
Authentication
IBM Cloud uses token-based Identity and Access Management (IAM) authentication.
With Voice Agent with Watson, you authenticate to the API by using IAM API key. The username should be "apikey" and use the API key value in your service credentials as the password.
IAM authentication. Replace {variable} with the API key value in your service credentials.
curl -u "apikey:{variable}" -X {request_method} "url"
Service endpoint
The service endpoint is based on the location of the service instance. For example, when Voice Agent with Watson is hosted in Dallas, the base URL is https://gateway.voiceagent.cloud.ibm.com.
To find out which URL to use, view the Getting Started page in Voice Agent Dashboard by clicking the service instance in the Resource list.
Use that URL in your requests to Voice Agent with Watson.
Service endpoints by location:
- US South:
https://gateway.voiceagent.cloud.ibm.com - US East:
https://gateway-wdc.voiceagent.cloud.ibm.com - Frankfurt:
https://gateway-fra04.voiceagent.cloud.ibm.comorhttps://gateway-fra05.voiceagent.cloud.ibm.com
US East endpoint example. Replace {variable} with the API key value in your service credentials.
curl -u "apikey:{variable}" -X {request_method} "https://gateway-wdc.voiceagent.cloud.ibm.com"
Your service instance might not use this URL
Methods
Initiating an outbound call
Initiating an outbound call using the cURL commands
POST /vgw/outboundCalls//startOutboundCall
Request
Sends the following key-value pairs in a JSON object.
A SIP/Tel URI to be called.
Optional. A calling party SIP/Tel URI.
Optional. A name/value pair of state variables to be forwarded to Watson Assistant when a call starts.
Optional. A comma-separated list of SIP Route headers to be added to an outbound call.
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.
Optional
Optional. Configuration settings to be used for the call.
Optional. Properties for the outboundCalls. See properties.
config
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.
tenantConfig
Optional. A username to be used for authentication when sending notifications to a webhook. Version 1.0.2 and later.
Optional. A username to be used for authentication when sending notifications to a webhook. Version 1.0.2 and later.
curl -u 'apikey:YOUR_API_KEY' -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ "from": "sip:+YOUR_TENANT_NUMBER@YOUR_DOMAIN.pstn.twilio.com", "to": "sip:+NUMBER_TO_CALL@YOUR_DOMAIN.pstn.twilio.com", "statusWebhook": "http:www.example.com"}' 'https://gateway.voiceagent.cloud.ibm.com:443/vgw/outboundCalls/"YOUR_TENANT_NUMBER"/startOutboundCall'