Document toolboxDocument toolbox

Marketing SMS Playbook - Refactor

Owned by Lindsey Huber
Last updated: Aug 26, 2022 by Francisco Reyes (Deactivated)
11 min read

Twilio

Twilio is used to send text messages to your customers. You will use this to manage your company's SMS numbers.

If you are already using marketing SMS in your legacy instance of Blueshift, there is no need to do anything on the Twilio side as part of your migration to the refactored instance.

Configuring Twilio

  1. Logon to Twilio. You will come to the default dashboard page

  2. Click the ellipsis under the house icon on the left-hand side

  3. Under Super Network, go to phone numbers > manage numbers > active numbers. This will display all of the numbers your company can send SMS from. This is essentially an IP for an email.

  4. Select a number

The number of phone numbers that appear here will vary by client. Each phone number can only be assigned to one LLC. Splitting numbers across an LLC will break customer boundaries.

5. Scroll down to Messaging. Messaging automation needs to be set up in order to for SignupApp to get the information. 

Under Messaging complete the following fields: 

 

CONFIGURE WITH

Select Webhooks, TwiML Bins, Functions, Studio, or Proxy

A MESSAGE COMES IN

Select Webhook, then, copy and paste the URL below.

Please be sure to copy the entire link.

Best practice: right-click and select Copy Link Address.

https://twilio:Hs3JGbJv@twilio-route-14west-spine-webhook-publisher-prod.apps.c3.balt.ocp.14west.io/camel/ingest/twilio#ct=10000&rt=15000&rc=3&rp=5xx,ct,rt&e=ashburn,umatilla

6. Click Save

Gathering Info for SUA and Blueshift

Gather the following information from Twilio for inputs in SUA and Blueshift.

Required information for SUA to talk to Twilio:

Phone Number

  1. Click the ellipsis under the house icon on the left hand side.

  2. Under Super Network, go to phone number > manage numbers > active numbers.

  3. Make note of the phone number that will be used.

Account SID

Located on the main dashboard page in Twilio

Auth Token

Located on the main dashboard page in Twilio

Required information to set up Blueshift adaptors:

Phone Number

  1. Click to ellipsis under house icon on left hand side.

  2. Under Super Network, go to phone numbers > manage numbers > active numbers.

  3. Make note of the phone number that will be used.

API Key SID

Located under settings in Twilio

API Secret

This pops up when you create an API key. You will need to copy it save it then or else it will be lost.

Account SID

Located on the main dashboard page in Twilio

Auth Token

Located on the main dashboard page in Twilio

Blacklisting and Validation

You will need to coordinate the following with Twilio. 

Blacklisting

You will need to coordinate with our Twilio rep, Dominique Kaittinat <dkiattinat@twilio.com> on the handling of your own opt-in/opt-outs.

This needs to be setup correctly/requested appropriately on the application. "Correctly" in this instance means the blacklisting feature is NOT being utilized. SUA is handling the opt-ins/outs, not Twilio. 

Validation

You will need to add free Twilio validation service to the forms for your phone numbers to ensure the customer is added to correct list. This will ensure no international customers sign up to domestic lists.

The following documentation from Twilio will help you set this up, but feel free to engage Dominique for direction first. 

SignupApp

Next, you will need to set up the Twilio information in SignupApp. SignupApp is used as the scaffolding or the structure that is going to handle the lifecycle of people that get signed up for SMS campaigns. SignupApp will also manage the opt-ins for SMS signups.

SMS Code Setup

  1. Log in to SignupApp

  2. Select SMS lists at the top of the page then click on SMS CODE SETUP.

  3. Click + sign in the lower right-hand corner of the screen to set up a new SMS code.

  4. Complete the following fields:

SMS Provider

Select Twilio

Twilio Account Token

(Called "Auth Token" in Twilio)

Varies, copy and paste from the Auth Token field in Twilio. This will be found of the main dashboard.

To copy, select Show, then select and copy the token.

Twilio SID

(Called "Account SID" in Twilio)

Varies, copy and paste from the Account SID field in Twilio. This will be found on the main dashboard.

Code Type

Select Long for full length phone numbers and Short for short codes.

SMS Code

Varies, copy and paste from the Phone number field in Twilio.

Twilio Sender ID (Optional - for SHORT or LONG code)

Only used to send outbound SMS messages, and customers cannot send an SMS in response. As a consequence, all SMS messages sent from this code and associated lists must mention the short or long code in the SMS Code box above for the customer to respond STOP to, otherwise they cannot unsubscribe, which is a legal requirement. Additionally, a customer service phone number may be added to each message to handle unsubscribes as well

Basic Default Messaging Keywords:

These messages will be sent as replies when the corresponding keyword is sent to the phone number.

These default messages can by overridden, but all verbiage (including default messages) must be approved by legal before go-live.

 

Save

A message will be sent instructing the customer to contact customer service.

 

Help

This message provides the customer with instructions on unsubscribing when they request help.

 

Info

This message will be sent to the customer when they request more info. They will be sent a link to the terms and conditions.

 

Unsubscribe

Confirmation customer will receive when successfully unsubscribed.

 

Fallback

"Fallback" is used as a catchall and will be sent when SignupApp doesn't understand the request.

The Twilio credentials can be found by navigating to the SMS Setup Codes section and under the SMS code actions you will see a button called “Show Twilio Credentials.”

SMS List Keywords

To navigate to this section go to SMS lists > SMS list keywords

In this section you will find the default keywords and the reply messages they are associated with. In addition to these you can create custom keywords that will allow you to send a custom reply.

To do this click on the orange plus button located in the lower right hand side of the page. Here is an example:

If a customer texts OFFER to the short code then they will receive the reply message that is set.

SMS List Members

To navigate to this section go to SMS lists > SMS list members

In this section you can see the customer that are subscribed, unsubscribed, and those that are pending a welcome text

To the far right of a record there is a button that allows you to unsubscribe the customer from the SMS list

Creating a Free SMS List

  1. Navigate to SMS LISTS.

  2. Click + sign in the lower right-hand corner of the screen to set up a new Free SMS List.

  3. Complete the following fields:

List Code

Enter a list code for identification purposes. Customers will be required to include this list code in their text responses. The SMS codes (phone numbers) are most likely going to be used for multiple list. This will identify which list the customer is contacting us about. (Opt in, unsubscribes, etc)

This is a free form field.

List Description

Enter a description of the list here.

List Channel

This will default to SMS.

List Type

The list type of Free should be selected.

SMS Code

Select the phone number (SMS code) set up previously.

Item Number

Enter the free list that this phone number will be supporting. This field is required for profile validation and is helpful when creating segments in Blueshift.

If the item number is not added or is added incorrectly, it could be added to the wrong customer number and email pair.

Default Messages

These messages are specific to the individual list (rather than the phone number which might have multiple lists attached) and will be sent when a reply from the customer is required and/or when a reply from the customer is received.

Update all of the placeholders within the default messages. All messages must include the list code.

These default messages can be overridden, but all verbiage (including default messages) must be approved by legal before go-live.

Opt In

Customers will be required to confirm or opt in to their subscription. They will be reqired to reply with "COMFIRM" followed by the list code.

(Example: COMFIRM XYZSMS)

There is no time limit to opt in, but failure to do so or failure to do so correctly will prevent the signup process from completing.

If a customer attempts to signup again in the interim, the original signup and opt in will be replaced by the new one. If they have already opted in to the original signup, nothing will happen with the new signup.

Customers will not exist in Blueshift until they opt in.

Unsubscribe

Comfirmation customer will receive when successfully unsubscribed.

Welcome

Welcome message sent to a customer when they submit a signup. This message include various instructions including confirming a signup/opting in.

Instructions to unsubscribe, get info, and get help are also included.

If a customer is requesting to unsubscribe and replies STOP without a list following, they customer will be unsubscribed from all lists attached to that phone number instead this specific list.

Info

This message will be sent to the customer when they request more info. They will be sent a link to the terms and conditions.

Help

This message will be sent to the customer when they request help. The message includes information on how to unsubscribe, as well as customer service contact info.

Rest Calls

You will need to set up rest calls in SignupApp in order for your website to be able to talk to SignupApp. These rest calls will check to see if a user is already on an SMS list. Follow the instructions below to complete this setup.

 

1. Log into SignupApp

2. To locate the user token, navigate to the USERS tab

3. Locate yourself

4. Click on the Update User icon

5. Click on the Token tab

6. Click Reveal Token

7. Select and copy the token

13. Below is the information needed to make the rest calls.

Authentication Value

header x-auth-token:{signupApp user token}

Rest call to check to see if a users is already on an SMS list

 

https://signupapp2.com/signupapp/v1/lists/members?listCode={:listCode}&phoneNumber={:phoneNumber}

Rest call to subscribe a user to free SMS

[post]https://signupapp2.com/signupapp/v1/lists/members {   "phoneNumber": "491719392833", --required 14 numaric must have country code appended   "listCode": "PPC", --required   "firstName": "fname", --limit 50 char   "lastName": "lname", --limit 50 char   "emailAddress": "email", --limit 255 char   "sourceUrl": "http://someplace", -- whatever you want   "listMemberIp": "123.123.123.123", --char 20   "consentText": "legal stuff" -- whatever you want } 

Signup Errors

When an error occurs during sign-up, you will need to know why the opt-in failed. These error statuses will appear on the dashboard in Twilio and will define why the customer didn’t make it on the list.

https://www.twilio.com/docs/sms/api/message-resource#delivery-related-errors

Signup Logic

To avoid a customer signing up to a new SMS list with a different phone number but the same email address, the logic was written such that it only checks the phone number against currently subscribed SMS list members with the same email address.

Meaning, if a customer is subscribed to an SMS list with email1@domain.com and phone number 123-456-7890 and tries to signup for another SMS list with the same email address (email1@domain.com) and new phone number 098-765-4321, they would not be able to signup since there is already an email to phone number relationship that exists in SUA2.

Blueshift

Next, you will need to set up the content, campaigns, and connection to Twilio in Blueshift. Blueshift is used to create SMS content and target subscribers. The content will then be sent from Blueshift and out through Twilio.

Creatives

SMS creatives aren't much different than Email creatives in Blueshift. Follow the instructions below to create an SMS creative.

  1. Navigate to Creatives.

  2. Select SMS.

  3. To create a new SMS creative, click +TEMPLATE in the upper right corner of the screen.

  4. Enter a name for your creative and click OK.

  5. Enter any tag folder/tags you wish to use.

  6. Click Content.

  7. Add your content on the left side of the screen.

  8. A preview of your content will appear on the right side of the screen. By default, you will be previewing the content as a customer named Jane Doe. You can search for and select a different customer if you choose to do so.

  9. Click Save.

10. Click Test Send.

11. Send a test text by entering the phone number you want receive the test and click Send.

Events/Transactions

When a customer subscribes/unsubscribes to a marketing SMS list, the marketing_sms_subscribe/unsubscribe event is added to their profile. This event triggers an update to the lists transaction, sets the sms_active to either true or false and adds the sms_list_code attribute (this is the SMS list code that’s being used in SUA2).

Additionally, the phone number attribute at the user level is updated with the phone number that was present in the marketing_sms_subscribe event.

Segments

  1. Navigate to segments.

  2. Click +SEGMENT.

  3. Under the “What type of segment do you want to create?” section select Basic or Advanced Segment

  4. Under the “What do you want to segment on?“ section select the Transactions radio button and then lists from the drop down menu

  5. Enter a name for the segment.

  6. Click + to add a condition.

  7. Make the following selections:

Transaction is:

lists

With the following attributes:

list_code | is equal to | [enter the list name from SUA here]

AND

sms_active | is equal to | True

SMS Campaigns

SMS campaigns are the basically same as email campaigns with one main difference: Instead of selecting email, you will select SMS.

  1. Navigate to Campaigns.

  2. Click +CAMPAIGN in the upper right corner of the screen.

  3. Select One Time Send.

  4. Enter a name for the campaign and click OK.

  5. Start setting up the campaign as you usually would. Add tag folder/tags, select the start date and time, and select the segment.

  6. Click Save

  7. Click Add your first trigger and select SMS.

  8. From there select the template you would like to use.

  9. Select the Twilio adapter. Choices will be limited to SMS adapters only.

10. Click Create Trigger

11. Click Launch

Omni-Channel Campaigns

Omni-Channel campaigns allow you to send messages to customers using different communication channels such as Email, SMS and Push. Here we are focusing on Email and SMS.

  1. Navigate to Campaigns.

  2. Click +CAMPAIGN in the upper right corner of the screen.

  3. Select Segment Triggered

  4. Enter in the name of the campaign and click OK.

  5. Start setting up the campaign as you usually would. Add tag folder/tags, select the start date and time

  6. Click Save

  7. At the Journey Start select a lists transactional segment. (This should be a segment that does not already contain the sms_active criteria)

  8. Click Add you first trigger and select Email

  9. From there select the template you would like to use along with the appropriate adapter

  10. Then click the + button on either the left or right of the email trigger

11. Select SMS

12. From there add a filter on the SMS trigger that uses the sms_active attribute and set that equal to true (see screenshot)

13. Click Save

14. Select the SMS Template for the SMS Trigger

15. Select the Twilio adapter. Choices will be limited to SMS adapters only.

16. Click Create Trigger

17. Click Launch

com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'html-macro' is unknown.