When building chatbot experiences you will frequently want to provide your users with a structured way to navigate the various capabilities your bot offers. Sometimes, for full conversational applications, this may involve a multi-level menu system with layers of categories and actions, or it might consist simply of a few simple actions. Either way, the easiest way to add this kind of navigation using Flow XO is our Menu feature.

Once a menu has been designed, it can be sent to your users from any flow, and automatically includes convenient navigational features like 'Back' and 'Home' buttons to help your users move easily through your app to get to the functionality they need. Menus run without requiring any specific workflow to be running, and can be configured to trigger an appropriate workflow when the user presses a menu action. Menus an submenus can be nested as deeply as you need to organize the user interface of your bot.

Basic Concepts

In Flow XO, menus are composed of two main elements: Submenus and Actions. When selected, Submenus display an additional list of actions, submenus, or a mix of the two, while Actions will trigger flows. When an action triggers a flow, the flow will receive information about the action in its metadata. This allows you to have several actions trigger a single flow that behaves differently based on which action was pressed. For example, if you were building an online store, you may have a menu for each category, and an action for each product. Every product action could trigger the same "purchase" flow which can check its metadata to know which product to present to the user.

Fundamentally, menus provide a clean, easy way to separate your chatbots navigation from your workflow logic, which should result in simpler, and therefore faster and more reliable workflows because each flow you design can be very simply targeted to a single type of user interaction while the menu handles the messy part of letting your users navigate between the various areas of functionality within your application.

Getting Started

Getting started with Menus is easy. Simply navigate to the "Menus" area on Flow XO's main navigation bar.

1. Create a new Menu

You can now give your menu a name, a description, and specify the message that should get sent along with the menu buttons when the user is viewing the top level of the menu.

Label - the Label field determines how a menu or action will be displayed on a menu button. For the top level menu, the label is just a name you can use to identify the menu, since the top level menu is not shown on a button.

Description - this is an internal description of your menu/submenu or action.

Message Template
The Message Template can also insert certain variables into your message, from either the user or the users attributes. To display variables enclose the variable name with {{ and }}, similar to how variables are inserted into flow actions. For instance to insert a variable to display the user attribute "LastPurchase" you would include {{attributes.LastPurchase}} in the Message Template field. Please see here for available variables.

External ID - This is an advanced field. You can put anything you want in this field, and access it later when a menu action triggers a flow. You can use this to associate actions with specific entities in your database, like a product ID, or for anything else.

Enabled - as the name suggests, you can toggle a menu, sub-menu or action on and off. You can use this to prepare menus and sub-menus in advance without showing them to users until you are ready to go live with the new functionality.

Once you click "Save" you will be taken to the Menu Editor for your new menu:

Here you have a blank menu, and you'll need to add some menu items. If you need to change any of the basic data about your menu such as the Message Template or Label, you can click the 'Edit' button next to your Menu title:

2. Add Menu Items

Once you have created your menu, you'll need to add some menu items. You can add two types of menu items, Submenus and Actions.

Submenus are like categories or pages of your menu, and hold more menu items. When a user clicks on a Submenu, they get taken to a new "page" of your menu, with the option to navigate back to the previous page, or to the home page (which is your top level menu).
Actions will trigger the flows that make your app actually do something useful.

Let's add an action first. Some of your menus may have only actions, and no submenus at all, but every menu should have actions that allow the user to do something useful.

Click "Add Action" in the menu editor.

Action Settings

Let's take a look at each configuration options.

1. Menu Item Type - because you chose 'Add Action' to get to this screen, this has defaulted to Action. If you change your mind, and you want to create a Submenu, instead you can change this field to switch the type to Submenu.
2. Label - what text should appear on the button label that is presented to the user to run this action? (NOTE: if you want to use emojis here, please use the emoji keyboard shortcut for your operating system.
3. Description - this is just an internal description of the action, which you can use to document your menu items.
4. External ID - this field can be filled in with whatever you like. You will have access to the External ID in the triggered flow, so you can use it to identify the specific action that was taken. It is commonly used for tying an action back to a specific identifier in an external system, such as a product ID.
5. Action - What should happen when the action is executed? Currently, there are two options:
Flow - trigger a flow directly, either by choosing the flow from a list or specifying a trigger phrase. This is the most convenient way to trigger flows from your actions, but has the limitation that you can only trigger a single flow and must specify the flow (or keyphrase) inside the action definition.
Event - trigger any flows with a 'Menu Action' trigger. When you are creating a blank flow, you will have the option to choose a 'Menu Action' trigger. From there, you can choose which menu action should trigger that flow, OR you can have a flow that responds to EVERY menu action. This is an advanced usage of menu actions, but is very flexible when you need it.

When the action is 'Flow', you will see these additional configuration options:

6. Trigger type - here you can choose to select the exact flow you want to trigger from a picklist, OR you can dynamically trigger a flow using a keyphrase. For details about how dynamic triggering works, see our article on triggering flows.
7a. Flow - When the trigger type is Direct, you will choose the specific flow you want to trigger.
7b. Keyword or Phrase - When the trigger type is Dynamic, you will enter the trigger keyword or phrase that should match a New Message trigger or a New Trigger trigger on an existing flow.

When the action is "Event", there are no additional options to select. When the action is selected by your user, Flow XO will search your flows for any flows with a matching Menu Action trigger

Create a Flow with a Menu Action Trigger

When using the "Event" action type, you will need to have one or more flows with a Menu Action trigger type. To do this, create a new flow and choose "Blank Flow" as the template. Then choose "Menu Action" as the trigger:

You can then decide which Menu and optional Menu Action should trigger this flow:

Note: The "Action" configuration of the Menu Action trigger is optional. If left blank, the flow will trigger for EVERY menu action selected for the desired menu. This can be useful if you have one master flow that will handle actions based on their external ID.

When the 'Menu Action' trigger is fired, the following properties will be passed to the flow as data that you can use in your flows:

Menu Item ID and Short ID: these are internal identifiers you won't usually need to use.
External ID: This is the external ID you specified when you created the action. This can be helpful if you have a single flow that will respond to many actions and you need to differentiate between them.
Label: This is the label on the action that was clicked. This can be helpful if you want to reply to the user with a human-friendly version of the action.

These values are also available when triggering an action directly, rather than using the Menu Action event. However, they will appear in the metadata rather than as top level data points:

NOTE FOR TELEGRAM USERS:
In Telegram, we are using 'Edit Message' to update the buttons in a single message every time a menu page changes. When an action is fired, we will send the metadata from that message to your flow, so that you can get the Telegram "message id" of the menu. You can use that if you want to further edit the menu message or remove it entirely if you want the menu to disappear once an action has been selected:

3. Create Submenus

In addition to actions, menus can contains submenus up to 10 layers deep. This is helpful when you have multiple levels of options. For example, if you were creating a management application for your sales team, your top level menu might have categories like "Orders", "Customers", and "Expenses". Under "Expenses", for example, might be "Fuel", "Schmoozing", and "Meals". To create a sub menu, click the 'Submenu' button on the menu editor:

You will then be taken to the Menu creation page, which looks just like the main menu creation page:

Once you fill out the options and click 'Save', you will be returned to the menu editor, where you can see your new submenu:

A submenu isn't very useful without it's own set of menu items. To add menu items to a submenu, you can click on the action menu for the submenu and choose 'Add Action' or 'Add Submenu':

Keep adding actions and submenus until you get your menu the way you like it. Once your done, your menu should look something like this:

4. Sending your Menu to your users

The easiest way to show your menu to your users is by making it the "Main Menu" for one of your bots. Simply pick your new menu from the dropdown list in the bot configuration of any of your bots, and your menu will be shown upon first connection and for unhandled message to your users.

Alternatively, you can send a menu to your users as part of a flow.

To display your menu for your users, you'll need to use a Send Menu action inside a flow. If you always want to send your menu to your users every time a new user connects to your bot, or any time your bot receives a message it doesn't understand, you should use a Catch-All trigger:

The 'Send Menu' action only has one configuration option, and that is the menu that you want to send. Choose your menu and save the task. Your app is now ready to send your users your menu whenever they first connect.

If you want to send your users your menu later, say, after they complete a workflow, you can use as many Send Menu tasks as you like in your flows to display your menu as the last step in your flows.

And that's all you need to get started. Next we'll briefly cover how to manage your menus in the menu editor.

Using the Menu Editor

To edit your menu settings like the label or message template, click the edit icon next to the menu name
You can toggle your menu on or off
Review your message template
On the far left of each menu item is a 'drag handle' - a small set of dots. You can use this to grab a menu item and re-order it, or move it around to a different Submenu.
Click the vertical "ellipsis" to activate the context menu for each menu item. See below for the different options.
Clicking on the label of a menu item is a shortcut to the edit page for that menu item.
Add new Submenus or Actions to the top level of your menu. To add sub-items under a submenu you will use the action menu for each menu item, as shown below.

Managing submenus and actions

The available options for a submenu are as follows:

Edit - go to the edit page for your submenu to change the label or message template
View Submenu - this focuses the editor on JUST the submenu. If you have a very big menu, this can be useful to reduce visual clutter and let you work on a submenu at a time.
Add Action - add a action to your submenu
Add Submenu - add another layer of submenu to your submenu
Delete - delete this submenu

The options available for actions are:

1. Edit - edit your action

2. Delete - delete your action

Linked Menus

If you have a set of menu options that you want to display to the user from multiple places, instead of re-creating the same menu options over and over you can use a "Linked Menu". Just define your sub-menu once, and link it from wherever you need.

Summary

Using menus in Flow XO is a powerful way to organize the structure of your bots in one single, easy to edit, easy to understand location. You can create one menu or one hundred, so you can easily create a menu for different areas of your bot, or for different bots. As always, if you have any questions or feedback, please reach out to support@flowxo.com. Happy flowing!

Menu