Overview

This guide provides step by step instructions on how to integrate the sending of SMS from an Autopilot Journey using the Burst SMS platform.


Requirements


Burst SMS Account


If you are not yet a customer you can sign up here or contact us

  • You are required to have an API key and secret that is found in the SETTINGS section of your Burst SMS account.


Autopilot Account


More information regarding Autopilot can be found here: https://www.autopilothq.com/


Contacts that contain a mobile number


In order to send a text message your contact must have a mobile number defined in the MOBILE PHONE field of your contact.


Instructions


Create a Journey


"Journeys" are the term used in Autopilot to describe the path a contact flows through. Think of them as workflows. 


For support on creating Journeys, visit the Autopilot website

What are Journeys?



Add a Trigger


In our example we will be using a list based trigger. So when a contact enters an Autopilot list, an SMS will be sent.


To get started drag the List Trigger Shape to the Canvas



Click the trigger configuration button



We are going to choose the option to send a message when a new contact gets added to the list. 

WARNING!

If you choose ADD ALL CONTACTS ON THIS LIST this option will trigger the send SMS function as soon as the journey is made active. We always recommend testing your automations with a small list with trusted contacts beforehand to make sure that the behaviour is as expected.


Add a Webhook Action


In order to Send SMS we are going to use the Webhook Action. Drag the Webhook Action shape to the canvas next to the trigger and connect the two then click the configure button.




Configuring the Webhook Action to Send SMS



Understanding Webhooks


A webhook is essentially a website address where an application can send a notification containing information to. In our case we have created an application with an address on our servers where Autopilot can send information as soon as an action happens.


The address of the Burst SMS webhook is 

https://autopilot.transmitsms.com/sendsms


HTTP method:


As Autopilot is sending us a document, the POST method is used.


HTTP method: POST


Auth


Burst SMS uses basic auth to connect to your account. Add your API Key and Secret found on your Account Settings page.


HTTP auth user :{{API Key}}

HTTP auth password: {{API Secret}}



Webhook Configuration


In order for us to receive correct instructions regarding the message send, parameters are added to the webhook URL. This can be done directly or in the header fields that Autopilot provides on their configuration form.


The benefit of using a field is that variables can be added here. Variables cannot be used directly in the URL.


HTTP header 1 & HTTP header 2


We use these fields to supply optional configuration information to the webhook. 


The two most common are:


Sender ID


Usually a dedicated virtual mobile number (VMN) or short code found in the NUMBERS section of your account. If no value is set here, will default to the shared sender ID for the country you are sending to. Can also be an 11 character alphanumeric sender if available for destination country.

Sender ID functionality varies by country. 

Global SMS delivery list

Mobile and dedicated VMN's should be in international format. Alphanumeric senders (cannot be replied to) can have a maximum of 11 characters. No spaces.


HTTP header 1: x-sms-from:61477333222


Country Code


Formats number for international delivery. If you have contacts that need delivery to different countries, more often that not the numbers will only be stored in local format. In order for the SMS gateways to route to the correct country we need the number in international format.


In the contact record we 1st check MailingCountry field if available then lastLocation field and if still not available we use these countrycode field if defined to format your number in case it is not in international format.

2 letter ISO 3166 format country code or country name. Automatically formats numbers to international format required for reliable SMS delivery. eg. In Australia 0422222222 will become 6142222222 when set to AU or Australia. If not set to numbers must be defined in E.164 international format.


HTTP header 1: x-sms-countrycode:AU



Creating your message


Custom payload


The Custom payload field is used for your message. You can use Autopilot variables in this field.


Can be upto 612 alphanumeric characters. A single billable part is 160 characters for a single SMS or 153 characters per billable part for multi-part SMS. If the message contains Unicode UTF8 encoded characters such as Emoji’s or non latin character sets, then a single billable part is 70 characters or 67 characters for multiple billable parts.



Other available Parameters


Here is the list of other  parameters you can use to improve your SMS messaging experience. Keep in mind that parameter values such as URL’s and dates will need to be encoded. 


HTTP Header format

URL Query format

Description

x-sms_send_at

send_at

You can schedule the message to be sent in the future, ignore these parameter to send immediately

x-sms-validity

validity

Expire a message send if it is undeliverable

Specify the maximum time to attempt to deliver. In minutes, 0 (zero) or not set implies maximum validity period.  

If a message is not delivered and not failed it is given a PENDING status in the system. These messages can be requested to be expired by the carrier after a certain time. This will return a DLR with a soft-bounce value. If no value is set, messages that remain in a PENDING state will be expired by the system automatically after 72hrs.

What does a message with a pending status mean?


x-sms-replies_to_email

replies_to_email

Send Replies to this Email

Specify an email address to send responses to this message. Email will come from the email address <to-number>@transmitsms.com eg. 0456789010@transmitsms.com

NOTE: If expectation is for replies to this email to be returned to the recipient as SMS then the email address must be authorised to send messages in your account under the 'EMAIL SMS' section. Emails can also be authorised using the add-email call.

How to set up Email SMS