Transactional SMS messages provide an additional channel to send subscribed customer updates about their orders and shipments. This guide covers how to configure messages to use the Transactional REST API Integration to send messages. If you are a ShopifyPlus customer who is interested in using Journey Hub to send SMS and Email transactional updates, click here.
You can configure many types of transactional messages, including:
Order Confirmation | Shipping Confirmation | Shipping Updates |
Delivery Confirmation | Payment Due | Membership Renewal |
Buy Online Pick-up In-Store Order Confirmation | Order Out for Delivery | Loyalty Membership Points Earned |
How does Listrak's transactional SMS messaging work?
There are four major components that need to be set up before you can send a transactional SMS message using Listrak's API. A fifth optional setting can be configured to allow contacts to opt in to transactional messages.
📷 Click Image to Enlarge
SMS Sender Code: The first step is to provision a sender code for your transactional program. You'll work with Listrak's SMS team to provision a sender code. A sender code can be provisioned for transactional only (recommended) or for both transactional and other messages.
SMS List: Once your sender code is provisioned, a list must be created in order for contacts to be added to when subscribing. Contacts must specifically opt in receive SMS notifications about their order. A contact who is not subscribed to your SMS list is not eligible to receive an SMS message associated with the list.
Message Shells: A transactional message shell allows you to specify the analytics of your message. It also creates the API IDs that will be needed to send a specific message.
SMS REST API Integration: The REST API Integration allows you to send information to Listrak to populate the message shells and specify a contact's phone number and message-specific information, such as order number.
Optional Subscription Points: A subscription point is one of the ways contacts can be added to your SMS list. The second way is to subscribe contacts via an API call. For subscription points, you can use these subscription points to add contacts when they fill out a form on your website opting in to transactional messages, for example at checkout.
Once these components are configured, you can begin sending messages. You will use the IDs created for the message steps to send data through Listrak's API integrations. Contacts who are subscribed to the list on your sender code will be eligible to receive messages.
Set Up Process
This guide reviews the set up and send process for your transactional messages. Your sender code must be provisioned to complete the following steps.
Once a message has been sent you can also view the reporting.
Transactional List Set Up
The first step in being able to set up a transactional message is to set up a list.
⚠️ If you are working with the Listrak Implementation team, they will complete this setup.
Navigate to Contacts > SMS Contacts SMS Lists.
Select the sender code provisioned for your transactional messages from the sender code drop-down.
Click Create New List in the top right corner.
Give your list a name.
Select Transactional from the list type.
⚠️ If your sender code is provisioned for more than one type of message, consult the SMS team for more information on setup.
Set up your Opt-In and Existing Subscriber messages.
💡 Learn more about the important compliance information to include in your messages.
Click Save List.
Create a Transactional SMS Message Shell
The next step is to create the shell of your transactional message. This shell will be filled with the specific information provided in the REST API call.
💡 Repeat this setup process for each of the different types of messages you will be sending.
In the SMS channel, select your transactional sender code.
On the home dashboard, click New Campaign.
Select the Transactional message type.
Enter a message name. This will typically be the type of message being sent.
Select your previously created transactional list from the list drop-down.
Set your Campaign Type to Transactional.
Fill in your Listrak and Google Analytics, if desired.
Click Commit.
On the main Transactional message screen, copy the List and Message IDs to use when sending messages.
Your messages are now ready to begin sending when the appropriate information is received by Listrak in your REST API call.
SMS API Integration Set Up
The next step is to set up and verify your Transactional SMS API Integration. The verification needs to be complete before sending messages. If you have already set up your integration and verified your API you can now send a message.
💡 The SMS REST API utilizes Bearer tokens to authenticate your requests.
If you have not created a SMS REST API Integration, follow the steps below:
Access the Integration Dashboard by navigating to Integrations > Integration Management.
Click New Integration.
Select the SMS API card > click Integrate.
Open the SetUp tab at the top.
Enter an Integration Name.
Now, you can configure the IP address(es) that are permitted to access the integration. You may also disable the whitelist, if desired.
To configure a whitelist:
Select on the following options - Single IP Address, Wildcard Match, or IP Address Range.
Add IP Address(es)
Disable the IP Address(es) that have been whitelisted.
Check the box to disable any previously whitelisted IP addresses
When clicking save you will be required to confirm that you want to disable whitelisting.
This will NOT delete the IP addresses listed. You can re-enable at any time by unchecking the box.
Click Save to complete the setup.
Copy your Client ID and Secret for use in authenticating your API.
SMS API Authentication
After your integration has been set up, you're ready to authenticate your REST API Integration. The instructions below use Postman, but you can authenticate in languages such as PHP or JAVA.
In Postman, paste the following value in the Request URL box: https://auth.listrak.com/OAuth2/Token
Select the POST type.
Save the authentication request.
In the popup that appears:
Give the request a name.
Select an existing collection, or create new.
Click save to confirm your settings.
In the body section of the request:
Select the x-www-form-urlencoded type.
In the key specifications enter the following:
Key 1: grant_type
Value 1: client_credentials
Key 2: client_id
Value 2: Unique client ID copied during the integration
Key 3: client_secret
Value 3: Unique client secret copied during the integration
Save your integration.
Use the Send function to generate your bearer access token.
In the authorization tab, select the bearer access type.
Paste the bearer access token into the field.
Once you are authenticated you can begin sending messages to contacts who are on your transactional SMS list. Read more below to learn the two ways contacts can be added to your list.
Adding Contacts to Your Transactional List
Before you can send a message about a customer's transaction, they need to be opted-in to your transactional list. This opt-in can be accomplished via one of two ways 1) use Listrak's SMS API to add a contact or 2) use Listrak's subscription points to subscribe a contact when they fill out a form on your website.
API Method
The SMS API allows you to use the API to subscribe contacts or create new contacts so that they are eligible to receive messages. The call you make may depend on if a contact is already known to your program.
You can make a CreateContact call to add a contact to your sender code and subscribe a contact to your transactional list if they are a new new contact.
You can make a SubscribeContact call to subscribe the contact to your transactional list. This is used if contact is already known on the sender code, but not subscribe to the transactional list.
💡 You can also make a GetContact call prior to a Create call to determine if a contact is already on your transactional SMS list.
A few notes about API calls:
The double-opt in message configured for the transactional list will be sent to contacts who are not already subscribed to the list.
When making the call, a country code is necessary and the phone number should be 11 characters long. E.g. 1-123-456-7890
Subscription Point Method
The subscription point method allows you to integrate JavaScript subscription code on your forms, such as checkout, and have a contact opt in to transactional updates.
💡 Contacts can opt in to multiple subscriptions (e.g. subscribe to the master marketing list and transactional list) when filling out the same form.
⚠️ Don't forget to include compliance language for any programs a contact is opting into when filling out the form.
To use the subscription point method, follow this guide to create a list subscription campaign on your transactional sender code.
In the list subscription campaign, confirm the contact has opted in for status updates about their order.
ProgramName: Thanks for signing up! You will receive updates about your order. Msg freq varies. HELP 4help STOP 2quit. Msg&data rates may apply.
Send Messages
Once your API Integration is complete, you are able to start sending messages to those who you have subscribed to the list using one of the two methods mentioned above. When sending messages you can specify the content based on the order or shipping information available in your ecommerce system. When Listrak receives the message into the API service it will then be processed by Listrak's SMS system and sent to the subscriber.
⚠️ Be sure that your checkout forms follow the SMS Compliance Guidelines for Transactional Messages.
Open https://api.listrak.com/sms in a tab.
Select TransactionalMessage in the left sidebar.
Then select, Send Transactional Message.
In the right pane, click POST and copy the relative Send Transactional Messages URL that appears.
Navigate to Postman.
Paste the relative URL in the address bar.
Copy the address from step 1
Paste this address in front of the relative URL
Select the POST type
Replace the specific IDs for your sender code and message into the placeholders of the URL.
For sendercodeID, if you are unsure of the ID please contact [email protected].
For phoneListId, paste the ID provided when you created the message in the previous section.
For transactionalMessageId, paste the ID of the message you created in the previous section.
Add the request sample to your call
Navigate back to Listrak's API documentation.
Copy the request sample in the format of your choice
In Postman, select the body section
Select the raw radio button and the format that matches the request sample
Paste the request sample into the body section
Fill out the required information, such as content and phone number.
Content should be kept under the 160 character limit for a single SMS message, if possible.
Don't forget to include a link so that Listrak can attribute revenue to the message.
Links will automatically be shortened to 22 characters when sending your message.
Click Send to send the specified content to the phone number identified.
Refer to the results code in the API documentation to learn more about if your SMS message was received.
Appendix: Transactional SMS Compliance
Below you will find examples of suggested compliance language for your messages. You may need additional compliance information depending on your business industry. Please consult with your Account Manager or SMS Implementation team for more information when integrating your transactional messages. It is also strongly recommended to confirm this opt-in language with your internal legal team before implementation.
Opt-in and Existing Subscriber Messages
When setting up your list, you must create a Opt-in Confirmation and Existing Subscriber message.
If a contact is not currently subscribed, they will receive the Opt-in Confirmation.
Program Name: You're all signed up to receive alerts about your order! More soon. Msg freq varies. Text HELP 4 help, STOP 2 opt out. Msg&data rates may apply.
If a contact is currently subscribed to the transactional list, they will receive the Existing Subscriber Message.
💡 This message is only triggered by Listrak's JavaScript, such as the checkout form, and will not fire if using the Subscribe Contact API call.
Program Name: Good news - you're already subscribed to receive alerts about your orders! More to come soon
Website Forms
Contacts must specifically opt-in to your transactional sender code and consent to receive messages about their order or transactional programs. A customer can opt-in to these messages when placing their order.
⚠️ The checkbox for an opt-in cannot be pre-checked.
⚠️ You must provide a link to your terms and conditions for your SMS program.
📌Strategy tip: Typically, brands choose to only have one type of SMS program opt in at checkout however can have opt ins for multiple programs (each with their own checkbox) in a single form.
☐ Yes, I would like to receive text updates about my order from [INSERT BRAND NAME].*
*By checking the box above, I agree to receive order text msgs to the mobile number provided from [INSERT BRAND NAME] on [INSERT SENDER CODE #]. Reply with birthday MM/DD/YYYY to verify legal age of [INSERT 18+ or 21+] in order to receive texts. Msg frequency will vary. Consent is not a condition of purchase. Msg & data rates may apply. Reply HELP for help and STOP to cancel. See Terms and Conditions & Privacy Policy.