Triggers

Conversational workflows in Flow XO are implemented by Flows, which are sequences of actions (behaviors) kicked off by triggers:

What your bot can do is defined by its actions, which you can read about here. Why your flows run at all are the result of triggers. Flow XO provides a wide variety of triggers. The most commonly used of these are message-based triggers that are activated when Flow XO receives a message from the chat platforms you have connected to via bots.

There are other types of triggers as well, however, that can come in handy in a variety of scenarios, particularly as you begin to integrate your chatbot more deeply into your existing technology systems and business processes.

There are three main categories of triggers:

Messaging Triggers - these are fired based of messages received from a platform like Facebook Messenger or Telegram.
Broadcast Triggers - these are just like integration triggers, but instead of triggering a single flow, they trigger a 'broadcast' which will run your flow for every selected member of your audience.
Special Purpose Triggers - these are provided by Flow XO for specialized tasks.
Integration Triggers - these are fired by external integrations, such as HTTP webhooks or e-mail

Messaging Triggers

Messaging Triggers are fired in response to messages sent by users of a messaging platform (such as Facebook or Telegram). There are three different messaging triggers.

New Message

The New Message trigger is how you'll start your flows most of the time. It allows you to react to messages either directed at the bot (direct messages or direct mentions), messages where the bot is mentioned (mentions) or any other message in a channel that the bot is participating in (overhear).

You have these options when setting up the trigger:

Bots - select whether all bots or just specific bots will listen for this trigger.
Words or Phrases - choose the words or phrases that should trigger this flow. You don't need to include the bot's @handle here. You can learn more about how we match words and phrases. You can group your words or phrases, see Word or Phrase Grouping below.
Message Types - select the types of messages to respond to.

The supported message types are:
- Direct Message (what time is it?)
- Direct Mention (@timebot what time is it?)
- Mention (What time is it @timebot @john?)
- Overhear (Does anyone know the time?)
Shortcut Button - choose whether to display a button along with the bot's welcome text for this flow. The first word or phrase will be used as the button's text. Note that there are varying character limits on each platform, and if buttons can't be used for all options, fallback text will be used instead.
Additional Welcome Text - any text provided here will be appended to the bot's main welcome text. It's intended to give additional explanation to the user, if needed. Keep this relatively short, maybe 2 lines of text at most.

Word or Phrase Grouping

Sometimes you might want to categorise words/phrases into groups so that you can handle different types of messages in the same flow.

For example, look at some of the words/phrases that our Small Talk Template handles:

hello [greeting]
hi [greeting]
hey [greeting]
bye [farewell]
exit [farewell]

So you can see that 'hello', 'hi' or 'hey' are grouped as 'greeting' and 'bye' and 'exit' are grouped into 'farewell'. You can group any word or phrase simply by adding a group name in square brackets after the word/phrase.

The group is included as an output on the trigger. You can then use the output as you wish, but it's common to then filter actions based on it. So you might have one message that is sent for 'greeting' and another message that is used for 'farewell' (this is exactly what we do in the Small Talk Template).

Your user's first interaction with your bot

The first time a user interacts with your bot, a special 'start' message is sent to Flow XO for Facebook Messenger, Telegram and the Web Messenger.

Facebook Messenger: start is sent when the user taps or clicks 'Get Started' on your page
Telegram: /start is sent when the user taps or clicks 'start bot' or 'restart bot' in Telegram
Web: start is sent when the user opens the chat window for the first time, or clicks 'reset' on the chat widget
SMS: There is no start message for Twilio SMS
Slack: There is no start message for Slack

You can take advantage of this fact in your trigger filters (or anywhere else in your flow) to respond differently to users who are interacting with your bot for the first time. A common usage of this start message is to define a flow with a New Message trigger that matches either 'start' or '/start' and welcomes first-time users to the bot.

After the initial 'start' message, the only messages Flow XO will receive are ones directly sent by your end-users in their chat windows. When testing, it is often convenient to reset the conversation in your messenger and simulate first-time use of your chatbot.

At any time, however, if you want to see how your bot will respond to a first time user, in the test console (or any of the platform Messenger applications) you can simply type 'start' (or '/start') and the result will be the same as if you were interacting with your bot for the first time.

Catch-All

The Catch-All trigger is very simple, and true to its name. It will fire when any message is sent to the bot that is not handled by a more specific trigger. If the message passes any filters you defined on the catch-all, the trigger will fire.

New File

This is triggered every time a file is sent directly to the bot or every time a file is uploaded to any channel that the bot has been invited to (depending on the setting you choose for Message Type).

It has a similar set of outputs to New Message, including Message Type and Message, as on some platforms it's possible to send a message containing both text and a file. The message won't always be present on this trigger.

In addition to the standard outputs defined below, New File will include two additionalThe extra outputs for New File are

File Type - can be one of 'image', 'video', 'audio', 'location' or 'other'. It's not currently possible to send 'location' via the web messenger.
File URL - the URL of the sent file.

If more than one file is sent, the trigger will fire separately for each file.

Intent Detection (NLP) Triggers

Two of our integrations ( Dialogflow and Wit.ai) offer a specialized type of trigger, called an Intent Detection Trigger. These triggers behave very similarly to messaging triggers - they are activated by messages sent by users on a messaging platform, they offer the same trigger outputs - but the real work is delegated to a third party service (Dialogflow or Wit.ai).

These triggers add a few specialized outputs to the standard messaging trigger outputs that are useful when using a Natural Language Processing service:

Intent - the name of the detected intent, such as 'support' or 'order_pizza'
Is Conversation Complete - whether or not the NLP service thinks the intent is ready for fulfillment. For Dialogflow, if you are using slot filling, Is Conversation Complete won't be true until all required variables are provided.
Parameters - any detected parameters
Fulfillment Text (Dialogflow only) - The message the NLP service was configured to send for this intent.

Message Trigger Outputs

Like actions, messaging triggers have outputs that can be used in filters, as inputs to other fields later in the flow, as well as variables that can be inserted into messages or buttons.

For more information on outputs, please see this article: https://support.flowxo.com/article/143-data-outputs

You'll have these outputs available to filter on or to feed into actions. Note that if you put a filter on the trigger itself, and an incoming messages does not pass the filter, the trigger will not fire and you will not be charged an interaction. Only unfiltered triggers are counted as an interaction.

Response Path - used to route a reply message or question.
Bot ID - the ID of the bot.
Bot Connection ID - the ID of the connection to the messaging platform.
Bot Name - the name you gave the bot in Flow XO, e.g. Time Bot.
Bot Platform - the messaging platform, e.g. slack or telegram.
User ID - the ID of the user who sent the message.
User Name - the user's full 'real' name.
User First Name - the user's first name (either supplied by the messaging platform or derived from the full name if not).
User Last Name - the user's last name (either supplied by the messaging platform or derived from the full name if not).
User Handle - the user's handle or username on the platform that the message came from.
Channel ID - the ID of the user/channel/room where the message is sent.
Date & Time Received
User First Active - the first time a user interacted with your bot.
User Last Active - the most recent time a user interacted with your bot. This will always be right now for message triggers, because by definition, you just received a message.
Message - the actual text of the message that caused this trigger to fire
Message Type - the type of message. Either direct_message, direct_mention, mention or overhear.
Group - see Word or Phrase Grouping below.
Metadata - any extra data that is available from the platform where the message came in from (will be different for each platform).
Attributes - any attributes previously stored for the current user.

Broadcast Triggers

Sometimes you will want to start a flow with all, or some segment, of your entire audience. The mechanism Flow XO provides for this is called a Broadcast, and a Broadcast is any flow that starts with one of the special Broadcast Triggers.

You can read about each of the broadcast triggers, and sending broadcasts in general, here: https://support.flowxo.com/article/160-broadcast

Broadcast Triggers provide a similar, but not identical, set of outputs. Here are the outputs associated with broadcasts:

Response Path - used to route a reply message or question.
Bot ID - the ID of the bot.
Bot Connection ID - the ID of the connection to the messaging platform.
Bot Name - the name you gave the bot in Flow XO, e.g. Time Bot.
Bot Platform - the messaging platform, e.g. slack or telegram.
User ID - the ID of the user who sent the message.
User Name - the user's full 'real' name.
User First Name - the user's first name (either supplied by the messaging platform or derived from the full name if not).
User Last Name - the user's last name (either supplied by the messaging platform or derived from the full name if not).
User Handle - the user's handle or username on the platform that the message came from.
Channel ID - the ID of the user/channel/room where the message is sent.
User First Active - the first time a user interacted with your bot.
User Last Active - the most recent time a user interacted with your bot. This will always be right now for message triggers, because by definition, you just received a message.
Metadata - any extra data that is available from the platform where the message came in from (will be different for each platform).
Attributes - any attributes previously stored for the current user.

Special Purpose Triggers

Flow XO provides a few special triggers to facilitate certain types of interactions.

Attribute Updated

This is a trigger that will start a flow every time a known attribute is first set or its value changes.

A separate interaction is triggered for every ruser/attribute combination that is updated. You'll get these outputs:

Response Path
Attribute
Old Value
New Value
Created At - the date & time (ISO 8601 format) that the attribute was first set.
Updated At - the date & time that the attribute was last updated. This will be set to '0000-00-00 00:00:00' for a newly set attribute.

You can read more about using attributes in Flow XO here: https://support.flowxo.com/article/141-attributes

Receive a Webhook

Receive a Webhook is one of the more powerful non-messaging triggers. It allows you to trigger a flow from any other system that send an HTTP request, and effectively allows you to create your own APIs for your bots. You can read about using Webhook triggers here: https://support.flowxo.com/article/22-webhooks

Warning: There are TWO 'Receive a Webhook' triggers in the main trigger menu - a regular Webhook trigger and a Broadcast Webhook Trigger. Make absolutely sure you are using the correct one - if you use a Broadcast trigger instead of a regular Webhook trigger accidentally, you will cause a flow to be triggered for every single user, which will unnecessarily use up your interactions.

Live Chat Ended

Live Chat Ended allows you to run a flow when a human agent session with a user has been completed. A common use for this trigger is to request feedback on the interaction, and/or present the bots main menu again. You can read more about using live chat, including the Live Chat Ended trigger, here: https://support.flowxo.com/article/174-live-chat

Receive a Payment

Receive a Payment is used to continue a conversation with a user once they have been asked for, and completed, a payment. You can read more about handling payments, including the Receive a Payment trigger, here: https://support.flowxo.com/article/173-payments

New Trigger

The "New Trigger" trigger allows you to specify a flow that should only be triggered from another flow. This trigger works in conjunction with the Trigger a Flow action, and both the action and the trigger should be configured with the same Keyword or Phrase. This trigger is frequently used for managing flow control.
For a complete walkthrough, please see this article.

Integration Triggers

Many of our third party integrations provide triggers that are available for starting flows when some event happens within your account. For example there is a trigger that will fire when a new row is added to a Google Sheet, or when a new contact is added to one of the several CRM's we have integrations with. You can explore our list of integrations here: https://support.flowxo.com/category/3-integrations