Configure campaigns for Listrak SMS

Listrak SMS is an automation platform for audience activation through mobile messaging campaigns and personalized SMS marketing.

Caution

Audience members sent to Listrak SMS from Amperity are automatically subscribed to a list and can receive SMS messages as the default behavior in Listrak SMS. Audience members who did not already exist in Listrak SMS are created and subscribed by default.

To avoid sending unsubscribed customers, apply filters to remove any customers who have unsubscribed from receiving SMS messages before sending audiences to Listrak SMS using campaigns, journeys, or orchestrations.

Amperity updates the contact attributes of SMS audiences in Listrak, including phone (required), email, first name, last name, birthdate, and postal code. Additional attributes may be sent when a matching custom segmentation field exists in Listrak SMS.

Talk with your Amperity representative about the Listrak SMS connector before configuring it in your tenant.

Use the Listrak SMS REST API to manage SMS profiles in Listrak SMS.

1. Amperity uses the Start a Contact Update Import endpoint to update an audience member’s information by {phoneNumber}.

2. Amperity uses the Unsubscribe Contact endpoint to unsubscribe audience members from an SMS list.

3. Amperity processes each addition individually. For each audience member with additions, Amperity uses the Get Contact endpoint to find out if the audience member already exists in the Listrak SMS list.

4. Amperity uses the Subscribe Contact endpoint to subscribe each contact to the SMS list. This action only subscribes contacts that already exist on the sender code.

5. Amperity uses the Create Contact endpoint to create and subscribe a new audience member for {phoneNumber} values that do not exist on the sender code.

How this destination works

Listrak SMS is a subscription-based model and this connector manages the membership of an SMS list. Full audiences must be sent each time.

Amperity manages the membership of the SMS list by sending an audience to Listrak SMS, and then updating the SMS list to match the set of audience profiles sent by Amperity.

Profile attributes for existing members of the SMS list are updated. Audience members who are not in the SMS list are added and are automatically subscribed to the SMS list.

Caution

Audiences are built from a query or segment in Amperity, and then sent to Listrak SMS will refresh the membership of an SMS list to match the membership of the audience sent from Amperity.

If more than one audience is sent to the same SMS list, then the membership of the SMS list will match the membership of the most recently sent audience.

Use a single query or segment in Amperity to manage a single SMS list in Listrak SMS. Use a single activation workflow–a single campaign or a single orchestration–for each SMS list in Listrak SMS.

Ensure the audience built by the query or segment matches the intended use case for the SMS list in Listrak SMS.

Important

To avoid sending SMS messages to people who did not consent to receiving them, ensure only consented phone numbers are included in the data provided to Amperity, or maintain consent status as a separate attribute.

For example, bring Listrak subscriber status to Amperity as a data source, and then use that data source with the SMS Opt Status table to help ensure customers are filterable by subscriber status in queries and segments.

SMS opt-in requirements are different from email opt-in requirements and require separate consent tracking.

Amperity uses specific endpoints in the Listrak SMS REST API to manage SMS profiles in Listrak SMS.

A Listrak SMS destination works like this:

	START WORKFLOW After the workflow starts, Amperity: Gets the value for the {senderCodeId} from Amperity configuration. This destination stores this value in the Sender Code ID field. Amperity replaces the “{senderCodeId}” value in the path to Listrak SMS API endpoints with this value. Gets the value for the {phoneListID} from Amperity configuration. The destination stores this value in the SMS List ID field. Amperity replaces the “{phoneListID}” value in the path to Listrak SMS API endpoints with this value. Amperity builds the audience list for the query or segment. Amperity validates the audience list. Amperity normalizes phone numbers for each audience member. SMS audience members are referred to as “contacts” in Listrak documentation.
	UPDATE ATTRIBUTES FOR {phoneNumber} IN {phoneListId} All members of an audience in Listrak must have a phone number. In addition to phone numbers, you may send email addresses, first and last names, birthdates, and postal codes. Custom attributes may also be defined. When attributes for existing audience members change, Amperity will update the profile to match the updated attributes. For example, a custom attribute for “Most recent purchase” has an existing value of “Socktown 5-pack ankle” and Amperity updates the attribute to “Socktown 5-pack mid-calf”. Amperity uses the Start a Contact Update Import endpoint to update an audience member’s information by {phoneNumber}. All system fields (phone, email, first_name, last_name, birthdate, and postal_code) and custom fields are updated for all customers. Amperity does not change an audience member’s opt status.
	UNSUBSCRIBE {phoneNumber} FROM {phoneListId} Audience members that exist in the SMS list in Listrak, but are not in the current audience for this workflow, are unsubscribed from the SMS list. Amperity uses the Unsubscribe Contact endpoint to unsubscribe audience members from an SMS list. Important Only audience members that exist in a matching {senderCodeId} and {phoneListID} are unsubscribed. Amperity does nothing when an audience member does not exist in the matching {senderCodeId} and {phoneListID} even when that audience member is in the current audience.
	Amperity processes each addition individually. For each audience member with additions, Amperity uses the Get Contact endpoint to find out if the audience member already exists in the Listrak SMS list. Amperity takes one of two possible actions: Subscribes the existing audience member to the SMS list. Adds the audience member to the sender code and subscribes them to the list.
	SUBSCRIBE EXISTING {phoneNumber} TO {phoneListId} Audience members that exist in the sender code in Listrak are subscribed to the SMS list. Amperity uses the Subscribe Contact endpoint to subscribe each contact to the SMS list. This action only subscribes contacts that already exist on the sender code. Important Amperity uses the Create Contact endpoint to create and subscribe the audience member when they do not already exist on the sender code.
	CREATE AND SUBSCRIBE {phoneNumber} TO {phoneListId} Audience members that do not exist in the SMS list in Listrak, but do exist in the current audience being sent to Listrak SMS are automatically subscribed to the SMS list. Amperity uses the Create Contact endpoint to create and subscribe a new audience member for {phoneNumber} values that do not exist on the sender code. All audience members added to an SMS list using this endpoint are automatically subscribed to the SMS list when the phone number does not already exist on the sender code. Important Use the SMS_Opt_Status table in Amperity to filter query results and audience segments to include only customers who consent to receiving SMS messaging. Consider using double opt-in messaging for campaigns sent from Listrak. Double opt-in uses two messages: the first message asks for consent, the second message confirms receipt of consent.
	END WORKFLOW The workflow ends when all attributes are updated for existing audience members, certain existing audience members are unsubscribed from SMS lists, or certain new audience members are subscribed to SMS lists.

Get details

Review the following details before configuring credentials for Listrak SMS and before configuring Amperity to send phone numbers and SMS profile attributes to Listrak SMS.

	Credential settings You must configure this destination for SMS profiles: SMS client ID and client secret A client ID and secret for an SMS integration that is already set up in Listrak SMS. Tip The client ID and client secret are available from the Integrations menu in Listrak SMS. Open the Integrations menu, select Integrations Management, and then from the Integrations page choose an integration. The client ID and client secret are on the Setup tab.
	SMS lists and Listrak An active SMS list must exist in Listrak SMS before Amperity can send SMS profiles to that list. Log in to your Listrak account . Open the Contacts menu, and then choose SMS Lists. On the SMS Lists page, review the list of Active lists or click New list to add a list. The List Name in Listrak SMS is the value for the Phone list ID configuration setting in Amperity. Caution Audience members sent to Listrak SMS from Amperity are automatically subscribed to a list and can receive SMS messages as the default behavior in Listrak SMS. Audience members who did not already exist in Listrak SMS are created and subscribed by default. To avoid sending unsubscribed customers, apply filters to remove any customers who have unsubscribed from receiving SMS messages before sending audiences to Listrak SMS using campaigns, journeys, or orchestrations. Amperity updates the contact attributes of SMS audiences in Listrak, including phone (required), email, first name, last name, birthdate, and postal code. Additional attributes may be sent when a matching custom segmentation field exists in Listrak SMS. Talk with your Amperity representative about the Listrak SMS connector before configuring it in your tenant.
	Define custom SMS profile attributes Custom SMS profile attributes must be created in Listrak SMS before Amperity can send custom attributes. Up to fifty custom attributes may be defined in Listrak SMS. Important Custom attributes must be configured as custom profile fields in Listrak before Amperity can send custom attributes with Listrak SMS profiles. The attribute name in Amperity must match the profile field name in Listrak SMS. Attribute names are not case-sensitive. All custom attributes sent by Amperity must match a custom profile field that exists in Listrak SMS. Custom attributes are defined in the Listrak SMS user interface. Open the Contacts menu, and then choose Profile Fields. Click New Profile Field to add custom attributes. System fields–Birthday, Email Address, First Name, Last Name, and Postal Code–are pre-defined by Listrak SMS and cannot be modified. Phone Number is the primary identifier for each SMS profile and is required.
	Required configuration settings SMS list ID Required The SMS list ID for a list in Listrak SMS. The SMS list ID is available from the Listrak SMS user interface. Open the Contacts menu, and then choose SMS Lists. Open a list. The SMS list ID is available in the URL of the list after the equals symbol. Note Lists are available from the Contacts menu within the Listrak SMS user interface. Under SMS Contacts open the Contacts menu, and then choose SMS Lists. Listrak SMS uses a list named “Master List” by default, but allows custom lists to be created. Verify the name of the list in Listrak SMS before configuring this destination in Amperity. If you are not sure which lists should be managed by Amperity, work with your Listrak representative to determine the best approach for list management. Sender code ID Required A sender code associates your brand’s Listrak SMS account with SMS campaigns, such as broadcast, split tests, keyword, and subscription. The sender code ID is provided by Listrak SMS. Ask your Listrak SMS representative for the sender code if necessary.
	Audience configuration Use a query or a segment to build an audience to send to Listrak SMS. The phone field must be part of the audience. You may append additional profile attributes to the query or segment.

About Listrak SMS profile attributes

Listrak SMS uses phone numbers as the primary identifier for each SMS profile.

Listrak SMS has the following SMS pre-defined attributes to collect additional information about SMS profiles.

System fields

• Birthday Use for date-based segmentation.

• Email Address A contact attribute.

• First Name and Last Name Use for personalization.

• Postal Code Use for location targeting.

Use system attributes to personalize messages, such as adding a first name to an SMS message, and to filter messages to only those who match certain criteria.

Custom attributes

Enable the Include attributes that match custom profile fields field to sychronize all profile attributes in Amperity that match custom profile fields defined in Listrak SMS.

Important

Custom attributes must be configured as custom profile fields in Listrak before Amperity can send custom attributes with Listrak SMS profiles.

The attribute name in Amperity must match the profile field name in Listrak SMS. Attribute names are not case-sensitive.

All custom attributes sent by Amperity must match a custom profile field that exists in Listrak SMS.

Listrak SMS supports up to fifty custom SMS profile attributes. Use these to define additional SMS profile attributes to support your brand’s use cases.

Important

Each custom attribute must be defined in Listrak SMS before Amperity can send them with SMS profiles.

Custom attributes must be one of the following data types: Checkbox, Date, Number, or Text . Any custom attributes sent from Amperity must match one of these data types.

Configure credentials

Configure credentials for Listrak SMS before adding a destination.

An individual with access to Listrak SMS should use SnapPass to securely share “refresh token” details with the individual who configures Amperity.

To configure credentials for Listrak SMS

	From the Settings page, select the Credentials tab, and then click the Add credential button.
	In the Credentials settings dialog box, do the following: From the Plugin dropdown, select Listrak SMS. Assign the credential a name and description that ensures other users of Amperity can recognize when to use this destination.
	The settings that are available for a credential vary by credential type. For the “listrak-sms” credential type, configure settings, and then click Save. You must configure this destination for SMS profiles: SMS client ID and client secret A client ID and secret for an SMS integration that is already set up in Listrak SMS. Tip The client ID and client secret are available from the Integrations menu in Listrak SMS. Open the Integrations menu, select Integrations Management, and then from the Integrations page choose an integration. The client ID and client secret are on the Setup tab.

Reauthorize Amperity

You may need to reauthorize access to Listrak SMS. This is necessary when an authorization token has expired or when it has been removed by someone with permission to manage access within Listrak SMS. To reauthorize access to Listrak SMS, follow the steps to configure OAuth and create a new credential.

Add destination

Use a sandbox to configure a destination for Listrak SMS. Before promoting your changes, send a test audience, and then verify the results in Listrak SMS. After verifying the end-to-end workflow, push the destination from the sandbox to production.

To add a destination for Listrak SMS

	Open the Destinations page, select the New destinations button, and then select Campaign. To configure a campaign for Listrak SMS, do one of the following: Click the row in which Listrak SMS is located. Destinations list alphabetically and you can scroll up and down the list. Search for Listrak SMS. Start typing “list”. The list filters to show only matching destinations. Select “Listrak SMS”.
	Select the credential for Listrak SMS from the Credential dropdown, and then click Continue. Tip If there are any issues with destination connectivity, an error message will display in the destination setup dialog. If the destination saves successfully, the connection is ready for use.
	In the “Destination settings” dialog box, assign the destination a name and description that ensures other users of Amperity can recognize when to use this destination. Configure business user access By default a destination is available to all users who have permission to view personally identifiable information (PII). Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies. Enable the PII setting checkbox to allow limited access to PII for this destination. Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows.
	Configure the following settings, and then click “Save”. SMS list ID Required The SMS list ID for a list in Listrak SMS. The SMS list ID is available from the Listrak SMS user interface. Open the Contacts menu, and then choose SMS Lists. Open a list. The SMS list ID is available in the URL of the list after the equals symbol. Note Lists are available from the Contacts menu within the Listrak SMS user interface. Open the Contacts menu, and then choose SMS Lists. Listrak SMS uses a list named “Master List” by default, but allows custom lists to be created. Verify the name of the list in Listrak SMS before configuring this destination in Amperity. If you are not sure which lists should be managed by Amperity, work with your Listrak representative to determine the best approach for list management. Sender code ID Required A sender code associates your brand’s Listrak SMS account with SMS campaigns, such as broadcast, split tests, keyword, and subscription. The sender code ID is provided by Listrak SMS. Ask your Listrak SMS representative for the sender code if necessary. Audience primary key The primary key for the audience. Set to “phone”. Include attributes that match custom profile fields Select Include attributes that match custom profile fields to have Amperity synchronize all profile attributes in Amperity that match custom profile fields defined in Listrak SMS. Custom attributes must match the name of the custom profile field in Listrak and must be a supported Listrak data. Important Custom attributes must be configured as custom profile fields in Listrak before Amperity can send custom attributes with Listrak SMS profiles. The attribute name in Amperity must match the profile field name in Listrak SMS. Attribute names are not case-sensitive. All custom attributes sent by Amperity must match a custom profile field that exists in Listrak SMS. Campaign file settings Under Campaign settings select one of the following: Send audience list as separate files This option sends a standalone file for each treatment group sending an audience to Listrak SMS. Send audience lists as a single file This option consolidates all treatment groups into a single file before sending the audience to Listrak SMS.
	After configuring this destination users may send campaigns to Listrak SMS.
	Test the connection with Listrak SMS by using an audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by Listrak SMS. Send the test audience to Listrak SMS and verify the audience is correct in Listrak SMS. Make adjustments if necessary. Only send full audiences after validation is complete.

Customers, products, and orders

Configure Amperity to additional data sets–customers, products, orders, and order items–to Listrak SMS using SFTP.

Note

This option uses the SFTP destination that is built into Amperity and should follow the steps and requirements that are outlined in the Listrak SMS file import guide .

You can send the following sets of data to Listrak SMS.

1. Customers

2. Products

3. Orders

4. Order items

Work with your Listrak SMS representatives to determine which of these sets will be useful for your workflows within Listrak SMS, and then verify that attributes sent from Amperity are mapped correctly to the appropriate data schema within Listrak SMS.