Triggers & Flows

Express your conversational UX using flows written in BFML

Triggers

Triggers are used to start a bot flow based on some external event. A flow file typically consists of two main sections: the first containing all the triggers associated with the flow, and the second the flow steps. Below is an example of a triggers section:

triggers:
  - keyword: order_return
    action:
      jump: start
      data:
        order_id: o-4
  - regex: order.*debug
    action:
      jump: order_debug

From this snippet you can see that the triggers section can contain multiple triggers, and all triggers get evaluated every time a new event occurs. So when the user types the text order debug in their chat client, a Meya integration will create a new meya.text.event.say event. Once the event is created all the triggers will be evaluated at the same time, and the one with the best match will fire - in this case it will be the regex trigger.

The Meya SDK provides many different types of triggers that can be used to start flows. The most common triggers are:

  • NLU triggers: These use NLU providers such as Dialogflow, Wit.ai or Luis to match intents based off the user's text input. NLU triggers are very useful for resolving intent from complex sentences.
  • keyword trigger: This is the one of the simplest text triggers in the Meya SDK, and it simply does a string comparison on the user's text. This trigger is mostly used by bot developers for debugging purposes.
  • regex trigger: This allows you to use a regular expression to match more complex text input.
  • catchall trigger: This trigger will match when no other triggers could be matched successfully. This is useful to capture any user input that the bot could not understand.
  • Dynamic triggers: These are special triggers that get created by ask and button components. You would generally not need to define these explicitly with BFML, but it's useful to understand how they work.
  • Custom triggers: The Meya SDK allows you to build your own custom triggers using Python code. This is very useful if you have some advanced matching logic that the built-in triggers don't support.

Flows

Flows are made up of steps, or in other words, a series of components that are executed in order. Below is an example of a flow section:

steps:
  - (start)
  - type: component.order.get
    order_id: (@ flow.order_id )
  - thread_set: order
  - type: component.product.get
    product_id: (@ thread.order.product_ids[0] )
  - thread_set: product
  - ask_form: Why would you like to return this item?
    label: Please specify reason
    composer:
      visibility: hide
  - flow_set: reason
 
  - (order_debug)
  - say: >
      Thanks. Before we can approve your return, I need to bring a human to help.
      One moment, while I get someone...
  - flow: flow.escalate.ticket
    data:
      subject: '♻️ Return: Order #(@ thread.order.id ) - (@ thread.product.name )'
      comment: |
        order #: (@ thread.order.id )
        status: (@ thread.order.status )
        product: (@ thread.product.name )
        price: (@ "${:,.0f}".format(thread.product.price) )
        reason: (@ flow.reason )

From this snippet you can see that each step defines a specific action that the bot performs. In Meya we typically refer to these steps/actions as components. Each component takes in a number of configuration properties for example: label, composer, order_id etc. The app runtime will then evaluate these properties and then execute the component's associated Python code that contains all the execution logic.

The Meya SDK provides many different types of components that can be used to enable the bot to perform complex tasks. The most common components used are:

  • say component: This component simply creates a new meya.text.event.say event that contains some text that gets sent to the user from the bot.
  • ask component: This component will create a meya.text.event.say event and create a dynamic trigger that will wait for text input from the user. Once the user replied with some text input the dynamic trigger will match and the bot can then use this text input to continue processing the flow.
  • if component: This component allows the bot to evaluate a boolean expression defined using Jinja2 syntax and then branch to another flow or step in the same flow.
  • jump component: This component allows the bot to jump to a specific label in a flow.
  • label component: This is a special component that defines a labeled step with in the flow. You can then use jump components or actions to jump to specific steps with in a flow. Using a combination of if, jump and label components, you can program the bot to perform complex branching and even loops.
  • user_set: This component allows the bot to save data into the user data scope that the bot can then retrieve again in other flow steps.
  • thread_set: This component allows the bot to save data into the thread data scope.
  • flow_set: This component allows the bot to save data into the flow data scope.
  • Custom components: The Meya SDK allows you to build your own custom components using Python code. This is very useful if you would like the bot to perform some specific action that's not supported in the many built-in components. A very common use case for a custom component is to retrieve specific data from 3rd party APIs.

Complete Flow Example

Putting it all together a complete flow would look as follows:

triggers:
  - keyword: order_return
    action:
      jump: start
      data:
        order_id: o-4
  - regex: order.*debug
    action:
      jump: order_debug

steps:
  - (start)
  - type: component.order.get
    order_id: (@ flow.order_id )
  - thread_set: order
  - type: component.product.get
    product_id: (@ thread.order.product_ids[0] )
  - thread_set: product
  - ask_form: Why would you like to return this item?
    label: Please specify reason
    composer:
      visibility: hide
  - flow_set: reason
 
  - (order_debug)
  - say: >
      Thanks. Before we can approve your return, I need to bring a human to help.
      One moment, while I get someone...
  - flow: flow.escalate.ticket
    data:
      subject: '♻️ Return: Order #(@ thread.order.id ) - (@ thread.product.name )'
      comment: |
        order #: (@ thread.order.id )
        status: (@ thread.order.status )
        product: (@ thread.product.name )
        price: (@ "${:,.0f}".format(thread.product.price) )
        reason: (@ flow.reason )

Implementing Flows

This quickest, and simplest way to implement or change a flow file is to use the Meya Console. The Meya Console provides a simple flow text editor as well as a more advanced visual flow editor. It is often useful to switch between text and visual flow editing modes when building out new flows, where most bot developers prefer to use the text editor because it's often quicker to make large changes, but they will also use the visual flow editor to help visualize the flow branching.

25822582

An example of editing a flow in the Meya Console text editor.

The visual flow editor also helps non-technical users to visualize the flow logic and to make simple flow changes without having to understand BFML syntax.

25842584

An example of the same flow in the Meya Console visual flow editor.

Using a Python IDE and Meya CLI

The Meya Console is convenient to make quick flow changes, however, most developers prefer to use a fully featured Python IDE to develop an advanced bot. Using a Python IDE is particularly useful when implementing custom elements in Python e.g. custom components, triggers or integrations. Meya provides all the required Python source code for the Meya SDK that enables a bot developer to easily implement custom elements with full Python code completion.

27702770

An example of editing the same flow file in the PyCharm IDE.

When developing a Meya bot using a Python IDE, you will also need to setup the Meya CLI to be able to push code changes to your app running on the Meya platform.

You are free to use in Python IDE or local editor of your choice, however, we strongly recommend using either PyCharm or Visual Studio Code as both these IDEs have excellent Python support.