Two-way messaging and Keywords Auto Responses

This feature is currently in BETA version.

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/MMS. Most importantly, paired with Keywords Auto Responses, they provide customers with an easy and user-friendly way to unsubscribe, subscribe or ask for HELP from all SMS/MMS communications by an SMS/MMS reply, such as “STOP”, “JOIN” or “HELP”. This is especially important for businesses based in the US that need to comply with US regulations in regard to subscription.

How two-way messaging works

When a customer replies to an SMS/MMS message to the client's dedicated phone number, the integrated SMS/MMS provider will forward the mobile-originated message to Exponea. Exponea then handles the incoming SMS or MMS messages on an hourly basis and tracks a campaign event with the status incoming_message to the customer profile matching the phone number. 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 NPS use case or triggering an automated follow-up scenario based on the reply message.

How keyword auto responses work

Exponea handles incomingSMS/MMS messages and when a customer replies to an SMS/MMS message containing 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.

Action for Revoke Consent

When the message is received by Exponea, the phone number is blacklisted immediately. Once a number is on a blacklist it's not possible to send any more messages unless using General consent for e.g transactional messages, there was a consent accept tracked with a higher timestamp that the time of blacklisting.

Revoke consent action will track 2 types of events to the customer profiles, that will be processed on an hourly basis:

Event type

To what profile?

consent reject

Consent is tracked to all customer profiles with the matching phone number attribute. A maximum of 10 customers with the same phone number will be unsubscribed if there are more customer profiles matching the same phone number.

campaign incoming message

Incoming message is tracked only to one of the customer profiles with the matching phone attribute, whoever had received the last SMS/MMS (in case of duplicates).

When setting up the keywords for Revoke consent, do not forget to select Consent categories. If you select two categories, one consent reject event for each category will be tracked.

Action for Grant Consent

Grant consent action will track 2 types of events to the customer profile, that will be processed on an hourly basis:

Event type

To what profile?

consent accept

Consent is tracked only to one of the customer profiles with the matching phone attribute, whoever had received the last SMS/MMS (in case of duplicates). In case no existing profile is found a new profile can be created if the “Map new subscribers ID” is set.

campaign incoming message

Incoming message is tracked only to one of the customer profiles with the matching phone attribute, whoever had received the last SMS/MMS (in case of duplicates).

When setting up the keywords for Grant Consent, select the consent categories to be granted. If you select two categories, one consent accept event for each category will be tracked. Here, you can also set the Map new subscribers ID field. In case no existing customer profile with a matching phone attribute is found, a new profile will be created using the new mapped subscribers' ID. The Phone number in the international format with double zeroes, e.g. "00421905123456" will be used as the mapped ID and phone attribute value. If not configured, new subscribers will not be created and only known phone numbers will be subscribed.

No Action consent

No action consent action will track 1 type of event to the customer profile, that will be processed on an hourly basis:

Event type

To what profile?

campaign incoming message

Incoming message is tracked only to one of the customer profiles with the matching phone attribute, whoever had received the last SMS/MMS(in case of duplicates).

How auto-reply works

Auto-reply message if provided, will be sent out immediately after receiving a message containing the matching keyword. The auto-reply message will be sent out to any phone number without looking up the profile. In other words, it will be sent out regardless of whether it belongs to an existing customer profile or whether the customer has SMS/MMS-related consent. This process will track a campaign SMS/MMS event to one of the customers matching phone attributes, whoever has the last SMS/MMS sent. These events are also tracked on an hourly basis.

To send out the auto-reply message, Exponea 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

More profiles with the same phone number

To give an example, let's have 2 customer profiles with the same phone number (duplicates). Both profiles are used in a SMS campaign, so the recipient will receive 2 SMS messages. 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. In other words, you want to unsubscribe all profiles but track messages for only one profile in order to not create duplicates.

📘

TIP

Other than opt-outs and opt-ins, a practical way of using two-way messaging is also for, e.g. collecting NPS responses or customer feedback by SMS.

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

Requirements

  1. Sinch SMS/MMS integration is necessary
    1.1. Request Sinch integration and Two-way messaging from your CSM or technical consultant. Read more about Sinch integration.
    1.2. 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 category/ies for SMS/MMS communication is/are created
    2.1. Define which consent categories are used for SMS/MMS communication. A maximum of 5 categories can be selected.

  3. Phone numbers must be in the international format with double zeroes, e.g. "00421905123456"

Configuration

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

  2. Go to Project Settings > Channels > SMS

  3. Here, make sure that Sinch 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 Exponea 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 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/MMS keyword auto responses within your campaigns. To test out if you set up keyword auto replies correctly, you can simply send some keyword e.g STOP to your dedicated sender number. You should immediately receive the auto-reply, but need to wait up to an hour to see the events. Wait 1-2 hours and in Data & Assets > Customers you should find that the customer has a consent event action = reject, and campaign 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 property

Value

Description

status

"incoming_message"

/

action_type

"sms"

/

timestamp
(event timestamp)

timestamp e.g. 2020-09-04T07:59:43.580671+00:00

When the system received the message.

message

e.g. “stop”

The text of the received message.

sender

phone number e.g. "00421905123456"

The sender's (customer's) phone number from which the message originates.

recipient

phone number e.g. "00421911123435"

Your dedicated sender phone number.

More technical information on inbound messages can be found within the external Sinch documentation: Sinch SMS / Inbounds Endpoint.

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

event property

value

description

status

"incoming_message"

action_type

"mms"

timestamp
(event timestamp)

timestamp

When the system received the message.

subject

e.g. “Hello!”

received message subject

message

e.g
“STOP

received message constructed from the MMS message parts received, included media will be attached in form of a URL

sender

phone number e.g. "00421905123456"

sender's (customer's) phone number from which message originates

Consent tracking

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

Event property

Value

Description

timestamp
(event timestamp)

timestamp

The time at which the SMS was received by the operator.

imported_timestamp

The time of consent tracked.

action

"reject"

/

source

"sms_reply"

/

category

consent category

The consent category specified in the SMS opt-out configuration.

identification

phone number e.g. "00421905123456"

The sender's (customer's) phone number from which the message originates.

identification_type

"phone"

/

message

E.g. "stop"

The text of the received message that triggered the unsubscription.

Send SMS tracking

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

Event property

Value

Description

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 property

Value

Description

status

"enqueued"/ "enqueue_failed"

/

action_type

"sms"

/

campaign_name

“Auto-reply keywords”

Static system generated value

action_name

e.g “Opt-out keywords”

Name of the keyword response configuration.

sender

phone number e.g. "00421905123456"

sender's (customer's) phone number from which message originates

recipient

phone number e.g. "00421911123435"

dedicated sender phone number, requires setup on service provider side (Sinch)

sent_timestamp

timestamp

timestamp of when the message was sent

message

“You have unsubscribed from SMS…”

Text of the auto-reply message

number_of_message_parts

E.g. 1

Number of message parts sent. One message part is 160 characters.

More technical information on inbound messages can be found on external Sinch documentation: Sinch SMS / Inbounds Endpoint.

Updated 6 days ago

Two-way messaging and Keywords Auto Responses


This feature is currently in BETA version.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.


We rely on cookies

to optimize our communication and to enhance your customer experience. By clicking on the Accept and Close button, you agree to the collection of cookies. You can also adjust your preferences by clicking on Manage Preferences. For more information please see our Privacy policy.

Manage cookies
Accept & close

Cookies preferences

Accept & close
Back