Bot Triggers & Actions

When creating a new flow, you can select various triggers (listed below). When you're editing a flow, click the 'Edit' button to select a new trigger.

New Message (trigger)

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 (overhear).

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?)

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 message type is also given as an output, so you can use filters to exclude certain messages too.
Shortcut Button - choose whether to display a button along with the bot's welcome text. 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.

You'll have these outputs available to filter on or to feed into actions as outputs:

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
Message
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 set against this response path.

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).

Catch-all (trigger)

This triggers when the bot is first installed by a user (or when they reinstall it), or whenever the user types anything that isn't recognised. It has the same set of outputs as the New Message trigger.

When a catch-all is triggered because someone first installed your bot, the message will contain either 'start' (Web Messenger or Facebook Messenger) or '/start' (Telegram). Note that not all platforms support Catch-all being run when the bot is first installed. For example, Twilio SMS.

By default, if Catch-all triggers are found, they will run instead of the welcome message. You can change this in your bot's settings (so the welcome message is also shown).

New File (trigger)

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.

The extra outputs for New File are File Type and File URL. File type can be one of 'image', 'video', 'audio', 'location' or 'other'. It's not currently possible to send 'location' via the web messenger.

The file URL is the location of the file given to us by the platform. This is not always suitable for sharing publicly so be careful that it doesn't contain any credentials. If you want to share it publicly it's usually best to place the file somewhere else before sharing it.

For locations, the File Type will be a link to a Google Map for the location, and you'll find an extra Metadata data type output containing the location:

{
  "long": "53.7969493",
  "lat": "-2.3344111"
}

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

New Command (trigger)

The New Command trigger lets you run flows using an exact-match keyword, such as "/help", and can also extract additional information from a command message as a "command argument" Please see this article for more information on implementing commands using the New Command trigger: https://support.flowxo.com/article/261-working-with-commands

Send a Message (action)

This action simply sends a message back to a user/channel. It takes only a few inputs:

Response Path - this tells Flow XO where to route the message (it's normally the response path output from the trigger).
Message - you can choose to 'add a variation' to create several versions of the message. One of the variations will be chosen at random, making the conversation feel more natural if it's a message that's sent often to the user.
Shortcuts - add shortcuts to prompt the user for their next action. These are displayed as buttons in most platforms. When the user clicks a shortcut button, the word/phrase is triggered, just as if they'd typed it in. This is what shortcuts look like in Messenger:

Most platforms support simple markdown such as *emphasis* and `code`, but your messages should generally be simple text. You can of course include links, and most platforms will make them clickable. Some platforms will 'unfurl links' and display a snippet or preview inline if the website is recognised.

Ask a Question (action)

This action allows you to easily and intelligently collect input from the user.Read our separate help doc for Ask a Question for full details about how to use this action.

Send an Image/Card/Videos (actions)

Take a look at our guide to Images, Cards and Videos to learn how to send images and rich content summaries through your flows.

Make a Custom Request (action)

Use this action to make custom requests directly to each of the platforms we support. See our separate help doc for Make a Custom Request.

Let us know how we can improve Flow XO on our feedback site.