Buttons and quick replies

In this guide, you’ll learn everything there is to know about buttons and quick replies, their uses, and how to use them effectively in your app.

Quick replies vs buttons

First, let’s review what buttons and quick replies are.

Quick replies make interacting with your app easier for the user by suggesting pre-written phrases the app is able to understand and that make sense in the current context. They are written from the perspective of the user.

Examples:

  • I need to reset my password
  • I haven’t received my order
  • I can’t login to my account

Buttons are UI elements. As a result, they typically contain few words (think commands, not phrases). Suggested reading: imperative mood.

Examples:

  • Create account
  • Contact support
  • Cancel order

On the Meya platform, both quick replies and buttons offer the same functionality. However, how they’re used in conversational design is where they differ. The UI is different, which informs how the user thinks, acts and interacts with the element.

Buttons are typically tied to a card or tile. Quick replies are typically in response to a question or provide out-of-band options to jump tracks in a conversation.

Here’s how buttons and quick replies appear in the Orb integration:

Button and quick reply compatibility

Buttons and quick replies are not available on all components. View the links below to learn which components support buttons and quick replies, and what button properties are compatible with other button properties.

Button and quick reply properties

Buttons and quick replies share the same set of properties. This section describes each of the properties and offers some examples of how they can be used.

URL

The url property let’s the user open a webpage in a new tab when they click the button.

The presence of the url property will cause the button’s inferred type to be url. Not all properties are compatible with the url button type. Refer to the compatibility section above for more detail.

Example

In this example, we’ll create a url button that opens the Google search page in a new tab.

  1. Create a new flow in your app’s flow folder called url_button.yaml. Copy this code into it:
triggers:
  - keyword: test

steps:
  - tiles:
      - title: A URL button
        buttons:
          - url: https://www.google.com
            text: Google
  - say: Done!

Save the file and push it to the Grid:

meya format
meya push

Open the chat simulator in your browser and test the flow with the keyword test:

📘

Since url buttons do not generate dynamic triggers, the flow continued on to the next step without waiting for the user to click the button.

Javascript

A button can execute Javascript using the javascript property. This is a very powerful feature that opens up the possibility of interacting with the webpage the app is running on.

Examples:

  • A button that updates a map on your webpage to show stores near the user.
  • A button that fills out a form on your webpage with information it already knows about the user.

🚧

The presence of the javascript property will cause the button’s inferred type to be static. Not all properties are compatible with the static button type. Refer to the compatibility section above for more detail.

Example

In this example, we’ll create a button that runs a simple Javascript function to print a message to the browser’s console.

  1. In your app’s flow folder, create a new file called js.yaml. Copy this code into the file:
triggers:
  - keyword: test

steps:
  - tiles:
      - title: A Javascript button
        buttons:
          - text: Run some Javascript
            javascript: test()
            action: next
  - say: Done!
  1. Create an Orb integration by adding a file called orb.yaml to your app’s integration folder. Copy this code into the file:
type: meya.orb.integration
  1. Save the new files and run these commands in your terminal to push your code to the Grid:
meya format
meya push
  1. In your browser, go to your app’s console, click the Integrations tab and open the Meya Orb integration. Copy the HTML snippet and paste it into a new Codepen.

  2. Add a new Javascript function to your Codepen:

function test() {
    console.log("This is a test");
}

Test the button’s Javascript by typing the word test:

You should see the phrase This is a test appear in the console.

Icon

The icon property can be used to display an icon inside the button or quick reply. Icons can be used instead of, or in addition to, text.

📘

You can use any icons found any icon found in the Light, Regular or Bold collection found in Streamline icons here. Learn more about how to add icons using this guide.

Example 1

In this example, we’ll use icons on our buttons and quick replies instead of text.

  1. In your app’s root folder, create a file called config.yaml, if it doesn’t exist already. Copy this code into the file:
icon:
  bird: streamline-regular/33-pets-animals/12-wild birds/wild-bird.svg
  cat: streamline-regular/33-pets-animals/04-cats/cat-sitting.svg
  dog: streamline-regular/33-pets-animals/03-dogs/dog.svg
  1. Create a new flow file called buttons.yaml and copy this code into it:
triggers:
  - keyword: test

steps:
  - tiles:
      - title: Buttons with icons
        buttons:
          - icon: (@ config.icon.bird )
            result: bird
          - icon: (@ config.icon.cat )
            result: cat
          - icon: (@ config.icon.dog )
            result: dog
    quick_replies:
      - icon: (@ config.icon.bird )
        result: bird
      - icon: (@ config.icon.cat )
        result: cat
      - icon: (@ config.icon.dog )
        result: dog

After saving the files, run these commands in your terminal:

meya format
meya push

Go ahead and test the new flow in the app’s chat simulator. You should see something like this:

Example 2

In this example, we’ll use icons in addition to text. Replace the code in buttons.yaml with this:

triggers:
  - keyword: test

steps:
  - buttons:
      - icon: (@ config.icon.bird )
        text: Bird
        result: bird
      - icon: (@ config.icon.cat )
        text: Cat
        result: cat
      - icon: (@ config.icon.dog )
        text: Dog
        result: dog
    quick_replies:
      - icon: (@ config.icon.bird )
        text: Bird
        result: bird
      - icon: (@ config.icon.cat )
        text: Cat
        result: cat
      - icon: (@ config.icon.dog )
        text: Dog
        result: dog

After saving the file, run these commands in your terminal:

meya format
meya push

The result:

Text

The text property lets you specify what text appears in the button or quick reply. Text is an optional property, so you can omit it if you prefer to use an icon, for example.

Example 1

In this example, we’ll create a very simple button and quick reply, both of which will have an inferred type of text.

triggers:
  - keyword: test

steps:
  - buttons:
      - text: This is a button
    quick_replies:
      - text: This is a quick reply

After saving the file, run these commands in your terminal:

meya format
meya push

The result:

📘

Since the text button type does not produce a dynamic trigger, this flow would normally continue on without waiting for a button click. In this case, though, there are no other steps in the flow, so the flow has not continued. See Dynamic triggers for more detail.

Example 2

If you want to only specify the text for the button or quick reply and do not care about the other properties, there is an even quicker way to define the element: just specify the text alone, as in this example:

triggers:
  - keyword: test

steps:
  - buttons:
      - This is another button
    quick_replies:
      - This is another quick reply

The output of this will be the same as in the previous example.

Action

The action property lets you specify an action to perform when the button or quick reply is clicked. The action itself can be any component.

🚧

The presence of the action property will cause the button’s inferred type to be action. Not all properties are compatible with the action button type. Refer to the compatibility section above for more detail.

Example 1

A common use for actions is to jump to another step in the flow when the button is clicked.

In this example, we use the flow.next component to go to the next step, which has the label good, if the user clicks the Good button. We use the flow.jump component to go to the bad label if the user clicks the Bad button.

  1. In your app’s flow folder, create a new file called action_button.yaml and copy this code into it:
triggers:
  - keyword: test

steps:
  - tiles:
      - title: How was your experience?
        buttons:
          - text: Good
            action: next
          - text: Bad
            action:
              jump: bad

  - (good)
  - say: That's great to hear!
  - end

  - (bad)
  - say: I'm sorry to hear that.

Save the new file and run these commands in your terminal to push your code to the Grid:

meya format
meya push

The result:

Example 2

This example results in the same output as the previous example, but uses the say component as the action instead of jump and next.

  1. Replace the code in action_button.yaml with this code:
triggers:
  - keyword: test

steps:
  - tiles:
      - title: How was your experience?
        buttons:
          - text: Good
            action:
              say: That's great to hear!
          - text: Bad
            action:
              say: I'm sorry to hear that.

Save the new files and run these commands in your terminal to push your code to the Grid:

meya format
meya push

Result

Most components and triggers place some output data on flow scope at flow.result. Using the result property, you can place data at flow.result when the user clicks a button or quick reply.

🚧

The presence of the result property will cause the button’s inferred type to be flow_next. Not all properties are compatible with the flow_next button type. Refer to the compatibility section above for more detail.

Example

In this example, we store a different value to flow.result depending on what button is clicked.

  1. In your app’s flow folder, create a new file called result_button.yaml and copy this code into it:
triggers:
  - keyword: test

steps:
  - tiles:
      - title: What is your favourite animal?
        buttons:
          - text: Dog
            result: dog
          - text: Cat
            result: cat
          - text: Bird
            result: bird
  - say: The result is (@ flow.result )

Save the new files and run these commands in your terminal to push your code to the Grid:

meya format
meya push

The result:

Data

The data property allows you to save data to the flow scope when the button or quick reply is clicked.

🚧

The presence of the data property will cause the button’s inferred type to be flow_next. Not all properties are compatible with the flow_next button type. Refer to the compatibility section above for more detail.

Example

  1. In your app’s flow folder, create a new file called data_button.yaml and copy this code into it:
triggers:
  - keyword: test

steps:
  - tiles:
      - title: Saving data with buttons.
        buttons:
          - text: This is a button
            data:
              count: 1
              foo: bar
              my_list:
                - a
                - b
                - c
  - say: (@ flow.count | string )
  - say: (@ flow.foo )
  - say: (@ flow.my_list | string )
  1. Save the file and push the code to the Grid using these commands in your terminal:
meya format
meya push

Trigger the flow in the chat simulator. After clicking the button, you should see this output:

Context

The context property is a dictionary of information that is added to the entry. This means you can search your app logs for data stored in the context dictionary.

This information is also sent to the frontend chat integration, meaning you could use it to pass additional data and have the frontend react to it in some manner.

Example

  1. Create a new flow called context_button.yaml and copy this code into it:
triggers:
  - keyword: test

steps:
  - tiles:
      - title: Button that uses context.
        buttons:
          - text: This is a button
            context:
              count: 1
              foo: bar
              my_list:
                - a
                - b
                - c
  - say: Done!

Save the file and push it to the Grid using these commands in your terminal:

meya format
meya push
  1. Run the flow in the chat simulator, then head to the Logs page. Enter this query into the search bar:
buttons.0.context.foo:bar

You should see an entry appear, and if you examine the data, you’ll see it is a meya.button.event.ask entry generated by our button click, and that it contains our context dictionary.

Magic

A magic button is one that is not displayed to the user. Instead of being clicked on, they are triggered when the user clicks a magic link.

One example of how this could be used is to verify a user’s email address. The bot can create a magic button and a magic link for the button, then email the magic link to the user. When the magic link is clicked, the button is triggered and causes the bot to take an action.

If a button or quick reply does not set the text, icon, or url properties, it is considered magic by default. You can also explicitly set the magic property to true.

Button ID

Button IDs allow the Meya platform to know which button the user clicked. When the user clicks a button, the button’s ID is passed back to the app and any additional functionality associated with that button, such as storing data or running another component, will be performed.

📘

Despite the name, quick replies can also have button IDs.

🚧

The presence of the button_id property will cause the button’s inferred type to be static. Not all properties are compatible with the static button type. Refer to the compatibility section above for more detail.

Button IDs can be auto-generated or explicitly defined. Both types are described below.

Auto-generated button IDs

Buttons with a type of static, action, flow_next, or component_next will have a button ID automatically generated by the Meya platform. From the compatibility section above, you can see this means that specifying a button’s action, result, data, or javascript properties will result in a button ID being created.

Static button IDs

You can also explicitly define a button ID for a button or quick reply. This causes the button’s inferred type to be static.

Static button IDs can be used with button triggers to create buttons that launch specific flows, or with magic links.

Example

Let’s create a button that launches a flow using the button_id trigger.

  1. In your app’s flow folder, create a new file called buttons.yaml. Copy this code into the file:
triggers:
  - keyword: test

steps:
  - tiles:
      - title: Button with button ID.
        buttons:
          - text: This is a button
            button_id: my_button
  1. Create a second flow called button_id.yaml and copy this code into it:
triggers:
  - button_id: my_button

steps:
  - say: Triggered by my_button

Save both files and push your code to the Grid by running these commands in your terminal:

meya format
meya push

In your app’s chat simulator, trigger the first flow and click the button. The button_id flow should be triggered: