Twilio Webhook Integration

This is a guide on integrating Twilio SMS messaging as a webhook into the Talon.One system. This guide will use the Twilio SMS messaging request to determine the inputs for the Talon.One webhook such that these steps can be adapted for other applications.

#Twilio Account

There are a few things from your Twilio account that are necessary for this guide. Your Twilio account should have:

  • an Account SID

  • Authorization Token

  • a Twilio phone number (this will be the sent from number)

  • add a recipient phone number and verify on Twilio (this is only necessary for testing)

Note: phone numbers are in the form +1 222-345-6789 starting with the country code followed by the number.

The Twilio documentation provides this API request to send an SMS. This will tell us what information is needed to add a Twilio webhook to Talon.One. https://www.twilio.com/docs/api/rest/sending-messages

curl -X POST 'https://api.twilio.com/2010-04-01/Accounts/account_SID/Messages.json' \
--data-urlencode 'To=recipient#'  \
--data-urlencode 'From=twilio#'  \
--data-urlencode 'Body=Message Text'  \
-u account_SID:auth_token

Run this curl in your terminal to test that you have Twilio set up correctly. If it successfully executes then you can continue with this integration. If an error occurs, find the Twilio documentation to fix the error.

#Creating a Twilio Webhook in Talon.One

This section will explain what should be added into the Webhook fields and give hints on how to determine this for other APIs. First navigate to the Webhook page under Developer Tools in your Talon.One account. You should go to Create Webhooks and enter a title for your new Webhook.

Next, you should add parameters which will be webhook inputs in the rule builder. In this integration, parameters are the "To" phone number, the "From" phone number, and the message "Body"; all three are a string type. For the Request details, this will be a POST request and the URL is https://api.twilio.com/2010-04-01/Accounts/account_SID/Messages.json with your Account SID. You can see this in the first line of the request to the Twilio API above.

The next part has a couple steps. You want to add an HTTP authentication header, but first you need to encode your Twilio Authorization Token. Run this command in your terminal:

echo api:auth_token | base64

This will return a base64 encoding which you can enter as a Header like this:

Authorization: Basic encoded_auth_token

You need to add another header which will be Content-Type: application/x-www-form-urlencoded; you can see this in the lines for the parameters in the Twilio curl starting with --data-urlencode. The last thing to add to this webhook is the payload. A payload always consists of the input parameters that the request contains. The payload for this webhook will look like this:

{
    "To": "${$To}",
    "From": "${$From}",
    "Body": "${$Body}"
}

Be sure that the box Display in Rule Builder is ticked before saving your webhook.

#Create a Rule and Test

Now that the Twilio Webhook is created, you want to test it is working correctly. You can navigate to the Application and Campaign where you'd like to test, maybe create a new one to be safe. You should go to the Rule Builder and click create rules.

For a simple test, you can set the condition to Customer Account Registration and the effect to the Twilio webhook with the necessary information for To, From, and Body. You can title this rule and save it.

Next you should navigate to the Developer section to the API Tester. You only need to choose the application where the rule is located and the path /v1/customer_profiles. You can copy the command and execute it in your terminal. This request will return some information but to check if the message was sent successfully you should navigate to the Webhook logs page. You should see the log listed. If it was successful, the response code will be 201 and you will have received a SMS. If it failed, you can check the response on the log for the error.