Voice Agent with Watson provides a 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.


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


US East endpoint example. Replace {variable} with the API key value in your service credentials.

curl -u "apikey:{variable}" -X {request_method} ""

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. Check out the following table for a general description of each error type.

HTTP Status Code Response Model
200 vgwSessionID
400 Bad Request
403 Forbidden
404 Not Found


Initiating an outbound call

Initiating an outbound call using the cURL commands

POST /vgw/outboundCalls//startOutboundCall

Sends the following key-value pairs in a JSON object.

  • curl -X POST --header 'Content-Type: application/json' --header 'Accept: application json' -d '{ "from": "", "to": "tel:+1234556789", "statusWebhook": ""}' 'http://<hostname>:<port>/vgw/outboundCalls/<tenantID>/startOutboundCall'

Status Code

  • Outbound calling session created successfully.

No Sample Response

This method does not specify any sample responses.