Triggered Two-way messaging allows your customers to reply directly to the text messages received from your campaign. This can be useful for use cases, such as collecting NPS responses or customer feedback by SMS. Most importantly, paired with Keywords Auto Responses, such as the keyword opt-in and opt-out, they provide customers with an easy and user-friendly way to unsubscribe, subscribe or ask for HELP from all SMS communications by reply, such as “STOP”, “JOIN” or “HELP”. This is especially important for businesses based in the US that need to follow and understand [TCPA and CTIA Compliance for SMS Marketing](🔗).

# How triggered two-way messaging works

When a customer replies to an SMS message to the client's dedicated phone number, the SMS vendor will forward the mobile-originated message to Bloomreach Engagement. Bloomreach Engagement then handles the incoming SMS messages in near real-time (subject to network operators) and tracks a `campaign` event with the status `incoming_message` to the customer profile. More details on how to set up two-way messaging [here](🔗) and more details on the content of the events [below](🔗).

The campaign events containing the reply message can be used in different ways based on the use case such as:

  • Reporting of rating for the NPS Use Case

  • Triggering an automated follow-up scenario based on the reply message

    • which allows you to create the whole conversational journey

# How keyword auto-responses work

When a customer replies to an SMS message starting with one of the configured keywords, the corresponding auto-response is executed immediately. The auto-response consists of a consent action (revoke consent, grant consent, and no action) and a real-time auto-reply message. Based on the consent action type, different consent-related actions will be performed.

## Revoke Consent Action (Opt-out/Unsubscribe)

Revoke consent action will track 2 types of events to the customer profiles, which will be processed near real time (subject to network operators):

Event typeParameterNotes
consentaction=rejectDuring the Revoke Consent setup, you have to select Consent categories. One consent event for each category will be tracked.
campaignstatus=incoming_messageN/A

When the message is received by Bloomreach Engagement, the phone number is blocklisted immediately. Once a number is on a blocklist, it's not possible to send any more messages unless using `General consent` for, e.g., transactional messages or there was a `consent` with action `accept` tracked with a higher timestamp than the time of blocklisting.

Important

The system **unsubscribes all customer** profiles **with** the **matching phone** customer **attribute**.



## Grant Consent Action (Opt-in/Subscribe)

Grant consent action will track 2 types of events to the customer profile, that will be processed near real time (subject to network operators):

Event typeParameterNotes
consentacceptDuring the Grant Consent setup, you have to select Consent categories. One consent event for each category will be tracked.
campaignincoming_messageN/A

Important

The system will **track** the consent and campaign events **based on the [customer profile handling rules]\(# Customer profiles handling)**.



## No Action

No consent action will track only 1 type of event to the customer profile, which will be processed near real time (subject to network operators):

Event typeParameter
campaignincoming_message

Important

The system will **track** the campaign event **based on the [customer profile handling rules]\(# Customer profiles handling)**.



# How auto-reply works

An Auto-reply message, if provided, will be sent out after receiving a message [starting with the matching keyword]\(## A guide to keywords). The auto-reply message will be sent out **immediately** to any phone number without looking up the profile, which means that it will be sent regardless of whether it belongs to an existing customer profile or whether the customer has SMS-related consent. Sending and auto-reply will track an **SMS campaign** event to the customer based on the [customer profile handling rules]\(# Customer profiles handling). These events will also be processed near real-time (subject to network operators).

To send out the auto-reply message, Bloomreach Engagement will use the following:

  • default SMS provider to send the SMS

  • recipient field (message.from) from the incoming webhook as a sender

  • sender field (message.to) from the incoming webhook as a recipient

# Customer profiles handling

Every inbound SMS message is tracked in Engagement as a `campaign` event with the status `incoming_message`. Every consent information is tracked in Engagement as a `consent` event with action `accept` or `reject`. These events are associated with a specific customer based on the following logic:

  1. **Callback data (Client reference)** Each outbound message sent from the Engagement usually contains callback data (unique customer and campaign identifiers). This data is returned by the SMS vendor (Sinch/Infobip) as part of the inbound message. Based on this data we are able to track events to the specific customer near real-time (subject to network operators). In some specific cases, the callback data are not available, e.g.:

    • customer proactively texting without previously receiving an SMS from Engagement

    • lack of support on a particular carrier side In these cases, Engagement follows the steps below:

  2. **Latest SMS Recipient:** The system first links the inbound message to the customer who most recently received an SMS campaign.

  3. **Newest Customer by Internal ID:** If the latest SMS recipient criterion doesn't apply, the system associates the message with the newest customer based on their internal ID.

  4. **Creating Anonymous Profiles:** If no existing customer profile matches the phone customer attribute, an anonymous profile is generated. This profile is equipped with an **inbound** identifier (`e.g. inbound-abcdefgh-1234-5678-9101-abc123def456`) within the **SOFT ID** `cookie`. In cases where the cookie isn't accessible, an alternative SOFT ID is employed. The international-format phone number (beginning with "00" or "+") is also stored as the customer's `phone` attribute value.

Anonymous profile handling

Anonymous profiles are diligently managed throughout the process. Each time a `phone` customer attribute is updated in the database, the system cross-references with existing anonymous profiles. If an anonymous profile shares the same `phone` customer attribute, it is intelligently merged into the profile that's receiving the phone attribute update.

## More profiles with the same phone number

To give an example, let's have 2 customer profiles with the same phone number. If the recipient replies with “STOP”, then both customer profiles are unsubscribed because both profiles have consent rejection tracked but only one profile has an incoming message tracked as an event based on the [customer profile handling rules]\(# Customer profiles handling). In other words, you want to unsubscribe from all profiles but track messages for only one profile in order to not create duplicates.

# How to set up two-way messaging and keyword auto-responses

## Requirements

  1. Sinch/Infobip SMS integration is necessary

    • Request Sinch or Infobip integration and Two-way messaging from your CSM or technical consultant. Read more about [Sinch integration](🔗) or [Infobip integration](🔗).

    • You must also request a short or long dedicated phone number (for customers to send messages to). Customers cannot reply to alphanumeric senders.

  2. Consent categories for SMS communication are created

    • Define which consent categories are used for SMS communication. A maximum of 5 categories can be selected.

  3. Phone numbers must be in the international format (either starting with "00" or with "+").

## Configuration

  1. Enable a new account module called “SMS Two Way Messaging”. To do this, contact your CSM.

  2. Go to `Project Settings` > `Channels` > `SMS`

  3. Here, make sure that Sinch SMS or Infobip SMS is set as your default provider.

  4. Under 2-Way messaging, enable _Track incoming messages_

  5. Next, you will have to configure your Keyword auto responses including keywords, consent actions, and auto-replies. To do so, simply start typing into the relevant text field, as shown in the picture below. Especially when setting up your own keywords, it might be useful to consider our guide below.



Using consents

It is recommended to use Consents, not Legitimate interest as a consent category for SMS campaigns. When legitimate interest is used the phone number blocking works also for newly created customers: if a new customer is created with a phone number that was unsubscribed, the sending messages will be blocked until explicit consent accept is tracked.

## A guide to keywords

SMS Opt-out keywords in Bloomreach Engagement have the following traits:

  1. Case insensitive

  2. Accents and whitespaces are ignored

  3. Match only if the message starts with the keyword

  4. Max 100 opt-out keywords allowed, each keyword up to 20 characters

  5. Regex is accepted as a keyword

In the case of MMS replies the message can contain multiple message parts. All parts are checked for a keyword based on the rules above.

**Example** with opt-out keywords: "_stop_" (English) , "_arret_" (French)

  1. Messages that **WILL trigger** opt-out: "STOP", "Stop", "stop", " stop", "šťóp", "stopwatches", "Arret", "ARRET", "arret", "arrêt"

  2. Messages that **will NOT trigger** opt-out: "Please stop", "Unsubscribe me", "Garret", "barret"

## Testing out the keyword auto-responses

Now that you set up all the necessary technicalities, you are ready to start using the SMS keyword auto-responses within your campaigns. To test out if you set up keyword auto replies correctly, you can simply send some keywords e.g. STOP to your dedicated sender number. You should immediately receive the auto-reply and see the events. Go to `Data & Assets` > `Customers` where you should find that the customer has a `consent` event with `action` = `reject`, and `campaign` event with `status` = `incoming_message`, as shown below.



# Event tracking

## Inbound message tracking

Incoming SMS messages will be tracked as a `campaign` event or custom event configured in mapping.

Event propertyValueDescription
status"incoming_message"/
action_type"sms"/
timestamp (event timestamp)timestamp e.g. 2020-09-04T07:59:43.580671+00:00When the system received the message.
messagee.g. “stop”The text of the received message.
senderphone number e.g. "00421905123456"The sender's (customer's) phone number from which the message originates.
recipientphone number e.g. "00421911123435"Your dedicated sender phone number.

More technical information on inbound messages can be found within the external documentation: [Sinch SMS](🔗) or [Infobip SMS](🔗).

Incoming MMS messages will be tracked as a "campaign" event or a custom event configured in mapping.

event propertyvaluedescription
status"incoming_message"
action_type"mms"
timestamp (event timestamp)timestampWhen the system received the message.
subjecte.g. “Hello!”received message subject
messagee.g “STOP <image link>”received message constructed from the MMS message parts received, included media will be attached in the form of a URL
senderphone number e.g. "00421905123456"sender's (customer's) phone number from which the message originates

## Consent tracking

The `consent` event is tracked to all customers with a phone number matching the sender's number.

Event propertyValueDescription
timestamp (event timestamp)timestampThe time at which the SMS was received by the operator.
imported_timestamp
The time of consent is tracked.
action"reject"/
source"sms_reply"/
categoryconsent categoryThe consent category is specified in the SMS opt-out configuration.
identificationphone number e.g. "00421905123456"The sender's (customer's) phone number from which the message originates.
identification_type"phone"/
messageE.g. "stop"The text of the received message that triggered the unsubscription.

## Send SMS tracking

A new `status` is tracked when attempting to send an SMS to a phone number that has been blocklisted, but the unsubscription is still being transformed into consent events. There is a delay between the immediate phone number blocklist and consent events being generated to a customer profile. If an SMS campaign runs during this small time window, this special event is tracked.

Event propertyValueDescription
status"enqueue_failed"/
message"Phone number is blacklisted by an opt-out keyword."/

## Auto-reply SMS sent tracking

SMS auto-reply action tracks `campaign` event or custom event configured in mapping.

Event propertyValueDescription
status"enqueued"/ "enqueue_failed"/
action_type"sms"/
campaign_name“Auto-reply keywords”Static system-generated value
action_namee.g. “Opt-out keywords”Name of the keyword response configuration.
senderphone number e.g. "00421905123456"sender's (customer's) phone number from which the message originates
recipientphone number e.g. "00421911123435"dedicated sender phone number requires setup on the service provider side (Sinch/Infobip)
sent_timestamptimestamptimestamp of when the message was sent
message“You have unsubscribed from SMS…”Text of the auto-reply message
number_of_message_partse.g. 1Number of message parts sent. One message part is 160 characters.

More technical information on inbound messages can be found within the external documentation: [Sinch SMS](🔗) or [Infobip SMS](🔗).

# Limitations

  • You must have a dedicated phone number (short or long number) that is used for accepting incoming messages. Customers cannot reply to alphanumeric senders (e.g. "Kiwi.com").

  • Customer phone attributes must be in string international format (either starting with "00" or with "+").

  • Revoke consent keyword unsubscribes only already existing customers, not customers who are created after the opt-out message is processed (in other words: unsubscribe only present customers, not future ones). It's recommended to use consent, not Legitimate interest as a consent category for SMS campaigns. When a legitimate interest is used the phone number blocking works also for newly created customers: if a new customer is created with a phone number that was unsubscribed, the sending messages will be blocked until an explicit consent acceptance is tracked.

  • Incoming messages are handled based on the [customer profile handling rules]\(# Customer profiles handling).

  • Keywords revoke/grant consent categories selected in the auto-response project settings, not the consent category that was used to send the SMS campaign (SMS action node in scenarios).

  • Blocklisting phone numbers by revoking the consent keyword overrides all consent categories and legitimate interests. While phone numbers are blocklisted, SMS can be sent only under General consent.

  • If SMS campaign events are disabled, we do not track incoming messages as events.

  • Limits:

    • max 20 distinct keywords auto-response configurations

    • max 100 distinct keywords per configuration, each keyword up to 20 characters

    • max 5 consent categories can be selected

    • max 10 customers are unsubscribed if there are more customer profiles matching the same phone number