Allowing a third-party to trigger the bot

As part of an EngageOne Deliver integration, you can configure a bot that is triggered by an SMS text sent from a third-party to initiate a conversation with someone. For example, a dental practice sends SMS texts to remind clients of upcoming appointments, giving the option to change their appointment. The practice will send a message using this API and it would start a conversation with the intended SMS number, using a specific bot interaction. The interaction is configured to run when it receives the word init.

This REST call requires authentication using basic authorization. You must pass the authorization header using the Base64‑ encoded string user:password. For example if you set the user to demo and the password to test then the encoded “Authorization” header setting would be: Authorization = Basic ZGVtbzp0ZXN0

You create this by encoding the string user:password in Base64. This is the user and password you set in the integration configuration User and Password fields. You can use any encoding tool, including an online tool (for example search for base64 encode).

You need to use this endpoint in the SMS REST URL field:

{converseServer}/api/v1/pbSms/init/{tenantID}/{botID}

where:

  • {converseServer} is the environment to which the bot is deployed
  • {tenantID} is the EngageOne Converse tenant ID
  • {botID} is the bot ID as shown on the Details page of the Configuration

The body of the REST call will need the following fields:

{ 
   "to": "6034400000", 
   "from": "Converse", 
   "text": "Testing the init"
} 

When you call this API, the bot will have access to the information sent using the following variables:

  • {sms.message} the message sent by EngageOne Deliver. For example to send this message to the user, enter {sms.message} in the Send to user field.
  • {sms.to} the phone number of the recipient.
  • {sms.from} the data in the "from" field of the text (or a cellphone number depending on how you configure the bot).
  • {sms.timestamp} the date and time the message was sent by EngageOne Deliver.
Important: In the bot, make sure that there is one interaction where the When we receive field is set to init or that there is an intention configured to understand the word init.

Example REST call:

POST: 
https://designer.converse.pitneybowes.com/api/v1/pbSms/init/demo/9e78403f-b7c7-43cd-942f-ef849dcf4b7b 
Headers: 
Content-Type = application/json 
Authorization = Basic ZGVtbzp0ZXN0 
Body: 
{ 
 "to": "6034400000", 
 "from": "Converse", 
 "text": "Testing the init" 
} 
Response: 
{"status":"received"}