Using the REST API to control SMS sessions

Operations that you can perform

With the REST API, you can perform the following operations.

• Manage sessions

  • Create session: Creates an SMS session between the specified user and tenant phone numbers.
  • Delete session: Ends and removes an existing SMS session.

• Test configurations

  • Test the SMS provider configuration: Sends an SMS message that says "Test Connection message from SMS Gateway". If the message can be sent, the test is successful.
  • Test the Watson Assistant service configuration: Sends the request to the configured Watson Assistant workspace. If a non-null response is received, the test is successful.

  Remember: To get a response, your dialog must include a node with the conversation_start condition and a node with a default response. You can test with the sample conversation or create your own dialog.

  • Test the XSLD caching server configuration: Sends the request to the configured XSLD catalog endpoints. The request creates an entry with a test value in the XSLD data grid, fetches the value, and deletes the entry. If all of these actions are completed, the test is successful.

• Integrate SMS Gateway during voice calls During a conversation with a caller, IBM® Voice Gateway might need to interact with the caller via SMS messages. The following operations support Integrating SMS Gateway with Voice Gateway

  • Create the SMS pipe: Creates an SMS pipe session between Voice Gateway and SMS Gateway, the SMS Pipe, and creates an encrypted SMS Pipe ID that contains the user phone number and tenant phone number. This enables SMS messaging between a voice agent and the caller through SMS Gateway.
  • Send an SMS message using the SMS Pipe ID: After the SMS pipe session between Voice Gateway and SMS Gateway is created, Voice Gateway uses this operation to send SMS messages to a caller.
  • Send an SMS message without the SMS Pipe ID: This operation sends only the outbound SMS message to the caller. The user provides the tenant phone number, the user phone number, and the message.
  • Delete the SMS Pipe: Ends and removes the SMS pipe session created by Voice Gateway.

If any of the operations are not successful, check the SMS Gateway logs for information about what went wrong.

Testing an operation

1. Under the Data type column, click the example to prepopulate the Value field.
2. Modify the JSON data in the Value field, such as by entering the user and tenant phone number. Important: The tenant phone number must exactly the tenant phone number that is specified in the SMS Gateway configuration.
3. Click Try it out! to perform the operation.
4. If prompted, enter the user name and password. you're prompted to authenticate only if you enabled authentication for the REST API.

After you try the operation, the interface displays the following information:

• The cURL command that was used to perform the operation
• The URL of the request
• The response information from SMS Gateway

Command examples

The following sample curl commands demonstrate various operations that you can perform with the REST API. When you run the sample commands, be sure to replace the smsUserPhoneNumber and smsTenantPhoneNumber values with your own values.

Important: The tenant phone number must exactly match the tenant phone number that is specified in the SMS Gateway configuration. The user phone number must be specified in a matching format as required by your SMS provider. For example, Twilio phone numbers require a plus sign (+), but RestcommONE phone numbers must be specified without a plus sign (+).

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsUserPhoneNumber": "+18765554321", \
   "smsTenantPhoneNumber": "+12345556789", \
   "smsUserData": { "data": "Data"}, \
   "smsSessionTimeoutCount": 600 \
}' 'http://host:9080/sms.gateway/session'

curl -X DELETE --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsUserPhoneNumber": "+18765554321", \
   "smsTenantPhoneNumber": "+12345556789" \
}' 'http://host:9080/sms.gateway/session'

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsTenantPhoneNumber": "+18765554321", \
   "smsUserPhoneNumber": "+12345556789" \
 }' 'http://host:9080/sms.gateway/testConfig/SMSProvider'

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsTenantPhoneNumber": "+18765554321", \
   "smsUserPhoneNumber": "+12345556789", \
   "smsUserData": { "data": "Data" }, \
   "smsSessionTimeoutCount": 600 \
}' 'http://host:9080/sms.gateway/testConfig/WCS'

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsTenantPhoneNumber": "+18765554321" \
}' 'http://host:9080/sms.gateway/testConfig/XS'

Integrating SMS Gateway support for Voice Gateway command examples

The following sample curl commands demonstrate the commands that SMS Gateway uses to support customers sending and receiving SMS messages to Voice Gateway during a call. When you run the sample commands, replace the smsUserPhoneNumber and smsTenantPhoneNumber values with your own values. For the sample commands to work successfully, you must also configure the host and port in your SMS Gateway server URL to send requests. Your SMS Gateway server URL can be either http:// or https://, depending on when the secure port is configured, but must always include the /sms.gateway/smsPipe.

You can find descriptions of the request and response variables on the REST API Swagger UI. See Accessing the REST API Swagger user interface.

Important: The tenant phone number must exactly match the tenant phone number that is specified in the SMS Gateway configuration. The user phone number must be specified in a matching format as required by your SMS provider. For example, Twilio phone numbers require a plus sign (+), but RestcommONE phone numbers must be specified without a plus sign (+).

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsUserPhoneNumber": "+18765554321", \
   "smsTenantPhoneNumber": "+12345556789", \
   "smsResponseURL": "https://vgwServer:port/smsRecv", \
   "smsToken": "tokenID",\
   "smsMediaURL": [ "https://media.com/media/l4JyRqcDU93S334KQ/first.gif", \
        "https://media.com/media/l4JyRqcDU93S334KQ/second.gif" ], \
   "smsMessage": "Hello this is a chat message sent from Voice Gateway.",\
   "smsOpaqueData": { "data": "Data"} ,\
   "smsPipeTimeoutCount": 1200 \
}' 'http://host:port/sms.gateway/smsPipe'

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsMessage": "Hello this is a chat message sent from Voice Gateway.",\
   "smsMediaURL": [ "https://media.com/media/l4JyRqcDU93S334KQ/first.gif", \
           "https://media.com/media/l4JyRqcDU93S334KQ/second.gif" ], \
   "smsOpaqueData": { "data": "Data"}
 }' 'http://host:port/sms.gateway/smsPipe/pipeID/KzE1MTAzMzAyNTgyOisxOTE5Njk5MjYwzJjZmNhZC1lMzc/sms'

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsUserPhoneNumber": "+18765554321", \
   "smsTenantPhoneNumber": "+12345556789", \
   "smsMessage": "Hello this is a chat session starting from Voice Gateway."\
   "smsMediaURL": [ "https://media.com/media/l4JyRqcDU93S334KQ/first.gif", \
           "https://media.com/media/l4JyRqcDU93S334KQ/second.gif" ]
 }' 'http://host:port/sms.gateway/smsPipe/sms'

curl -X DELETE --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{}' 'http://host:port/sms.gateway/smsPipe/pipeID/KzE1MTAzMzAyNTgyOisxOTE5Njk5MjYwzJjZmNhZC1lMzc'

{:codeblock}