1. Pendula for Enterprise
  2. Pendula user guides
  3. Engagement Hub
  4. SMS

Reference
Inbound message trigger

Angel Cheung
Angel Cheung
  • Updated

Complete overview of Flow Builder

The Inbound message trigger initiates a flow when it detects incoming messages that meet specified criteria or rules. This ensures that your automated workflows respond appropriately to each relevant customer interaction.

Understanding rules and recipes

Rules are specific conditions that a message must meet to trigger a response. These conditions can be based on the content of the message, such as keywords or phrases. Recipes are predefined sets of rules designed to match common patterns such as email addresses, phone numbers and more. They simplify the process of setting up common reply scenarios.

Merging rules and recipes within a path allows for comprehensive coverage of potential customer responses, ensuring the flow can handle the varied ways customers might respond.

For a detailed guide on each, see Rules and recipes

Usage scenario

The example below demonstrates the use of the Inbound Trigger Node within a flow that initiates an experience when a customer expresses interest in an event. By replying with ATTEND, the customer indicates their intention to attend the event, while replying with CONTACT signifies an interest to get in touch with the organisers. The Inbound Message Trigger node evaluates the different replies and appropriately routes the flow to handle each specific request.

Inbound-trigger-example.png

Configuring the trigger

Path labelling
You can define clear labels for each path. These labels appear on the canvas, providing a visual representation of message routing within your flow.

Defining trigger criteria
Determine the specific conditions—known as rules or recipes—that incoming messages must meet to initiate the flow.

Implementing OR logic within paths
Multiple rules or recipes can be set within a single path, where each is connected with "OR" logic. This means that if an incoming message matches any of the listed conditions, it will follow that path.

If a reply matches several paths, the topmost path or rule will always take precedence. If a reply matches several triggers, all matching triggers will be fired.

Prioritisation in reply matching

The Inbound Message Trigger starts a flow in response to incoming messages that meet specific criteria. When a message is received, a systematic prioritising exact keywords before considering broader rules.

1. Active Conversations
The system checks if there are any ongoing conversations with the sender. If so, it looks for a match within these conversations first, prioritising exact keywords before considering broader rules.

2. Inbound SMS Triggers
If the message does not fit into any active conversation, the system then attempts to match it with any Inbound SMS Triggers. Here, all triggers that detect the keyword are activated.

3. Match Priority
Within a node, if multiple paths or rules could match a reply, the system follows the top-down priority. The first path or first rule of a path that aligns with the incoming message takes precedence.

4. Unmatched Messages
Messages that do not correspond with any active conversations or triggers are labeled as “unmatched.” If you have an Unmatched Message Trigger flow set up, it will then handle these messages to ensure no communication is left without a response.

For a detailed explanation on setting up an unmatched message trigger, see Unmatched Message Trigger Node.

For a detailed explanation, see How reply matching works and Best practices for creating two-way conversations with reply matching.

When an inbound message comes into Pendula, both the phone number and the keywords in the message body are used to match an inbound message to a flow and continue the recipient down the correct path of their customer journey.
What happens if the message matches two or more flows?
Only the most recent flow will be matched.
What happens if it matches a recipient number, but no flows?
When Pendula receives an inbound message, first it checks if it will trigger an active flow with an inbound message node trigger. If there’s no match, then Pendula looks for any messages that might have been sent to this number; if it was expecting any keywords from this number as part of a conversation node (outbound SMS) in any active flow.
What happens if it doesn’t match either a recipient number, or a flow?
The message will be persisted into the database and Pendula will publish an UnmatchedMessageEvent to the event queue.

Mergefield explorer

Mergefields function as dynamic placeholders within a flow, automatically populated with actual data as the flow progresses. Below are key mergefields accessible in subsequent nodes following the Inbound Message Trigger

Mergefield name Description Possible outputs Definition and examples
fromNumber The number from which the message was received   "+61 400000000"
matchedIntent The intent/branch matched based on the message content   Indicates the flow's path or intent that the incoming message has triggered, based on its content (e.g., “YES”).
matchedPart The part of the message that matched the rule   Specifies the segment of the inbound message that fulfilled the criteria of a rule. This is helpful when the Contains rule is used. For example, "annie@acme.com" would be the matched part of the message "my email is mailto:annie@acme.com
matchedType Classifies the kind of rule match that prompted the flow to activate. This can be used in later nodes such as Criteria Filter. Exact Match (Trigger) An inbound message has been matched to the is exactly rule in an Inbound SMS Trigger Node.
    Rule Match (Trigger) An inbound message has been matched to a free response, a rule or recipe in a Inbound SMS Trigger Node.
messageBody The entire body of the inbound message   “Yes, thank you”.
timeStamp The time at which the message was received in Unix Epoch time in milliseconds   “1672534861000”

Opt-in and opt-out flows

  • Opt-in and opt-out trigger flows should be used as final 'catch all' flows. Triggers contain limited context, meaning if a customer decides to opt-out mid-flow, you would not be able to see which flow caused the opt-out. Instead, in your marketing flows, add opt-in and opt-out paths of your Conversation Nodes for a richer context.

For other best practices, see Best practices for creating two-way conversations with reply matching.

  • Opt outs will not affect active flows. This means if a recipient is mid-way through an active flow and triggers an opt-out flow, they won’t drop out of the active flow. They will however, be excluded from any new flows. For example, if Pendula is waiting on a reply from a particular number and that person messages 'STOP' (as an opt-out) and then messages 'CONFIRM' in response to the original offer, the flow will continue on the 'CONFIRMED' path.

    In the following example, we have two flows.

    Flow I triggers an experience when the keyword OFFER is used. The flow prompts the customer to either CONFIRM or DECLINE the offer and based on the reply, sends outbound SMS.


    opt-out-one.png


    Flow II is an opt-out flow that triggers an experience when the keyword STOP is used. The flow updates the CRM, and sends the confirmation outbound SMS to the customer. 

    opt-out-two.png

    Here is an example conversation where the person messages 'STOP' (as an opt-out) and then messages 'CONFIRM' in response to the original offer, the flow will continue on the 'CONFIRMED' path.

    opt-out-three.png