Introduction

Voice Agent with Watson provides a REST API that you can use in your contact center applications so that agents can manage SMS sessions between a customer and the SMS agent. You can incorporate the REST API in the applications by using its cURL commands. Voice Agent with Watson supports SMS session management endpoints. These endpoints are protected with IAM authentication by using the service credentials that are found under your Voice Agent with Watson instance. To manage service credentials, you must have 'Writer' access(service scoped privilege) or above in the resource group your instance is contained in.

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://sms-south.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 East: https://sms-east.voiceagent.cloud.ibm.com
  • US South: https://sms-south.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://sms-east.voiceagent.cloud.ibm.com"

Your service instance might not use this URL

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 Error Code Description Recovery
200 Success The request was successful.
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
401 Unauthorized You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
403 Forbidden The supplied authentication is not authorized to access the specified voice agent.
404 Not Found The requested resource could not be found.
408 Request Timeout The connection to the server timed out. Wait a few minutes, then try again.
409 Conflict The entity is already in the requested state.
500 Internal Server Error Voice Agent with Watson is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

Methods

Create a session

Creates an SMS session between the specified user and voice agent phone number.

PUT /sms.gateway/session
Request

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

Example:
Response

Status Code

  • SMS session created successfully.

  • SMS session creation failed. Incorrect input.

  • SMS session creation failed. Phone number not registered.

Example responses

Delete a session

Ends and removes an existing SMS session.

DELETE /sms.gateway/session
Request

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

Example:
Response

Status Code

  • SMS session deleted successfully.

  • SMS session deletion failed. Incorrect input.

  • SMS session deletion failed. Phone number not registered.

  • SMS session does not exist for the specified user and phone number.

Example responses