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 South:
https://sms-south.voiceagent.cloud.ibm.com - US East:
https://sms-east.voiceagent.cloud.ibm.com - Frankfurt:
https://sms-fra04.voiceagent.cloud.ibm.comorhttps://sms-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://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.
The phone number of the user to send messages to. This number must be specified in a matching format as needed by your SMS provider.
The phone number of the voice agent that the user is contacting. Provide the value in the format needed by your SMS provider, matching the format of the number specified in the voice agent configuration.
(Optional) Any data in JSON format to be passed to the service orchestration engine or conversation service. This data is not sent as an SMS message.
smsUserData
(Optional) An amount of time in seconds that defines how long the session lasts. If not specified, the default value of 3600s is used.
curl -u 'apikey:YOUR_API_KEY' -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ "smsUserPhoneNumber": "NUMBER_TO_SEND_TO", "smsTenantPhoneNumber": "YOUR_TENANT_NUMBER", "smsUserData": { "data": "Data"}, "smsSessionTimeoutCount": 600 }' 'https://sms-south.voiceagent.cloud.ibm.com/sms.gateway/session'
Request
Sends the following key-value pairs in a JSON object.
The phone number of the user to send messages to. This number must be specified in a matching format as needed by your SMS provider.
The phone number of the voice agent that the user is contacting. Provide the value in the format needed by your SMS provider, matching the format of the number specified in the voice agent configuration.
curl -u 'apikey:YOUR_API_KEY' -X DELETE --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ "smsUserPhoneNumber": "NUMBER_TO_SEND_TO", "smsTenantPhoneNumber": "YOUR_TENANT_NUMBER" }' 'https://sms-south.voiceagent.cloud.ibm.com/sms.gateway/session'
Response
The message response
The SMS session ID
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.
{ "msg": "message response", "smsSessionID": "1bxxfxxx-956e-4exx-8c7e-666fc6xxxaac" }