Skip to main content

Create scrollable menus using the Carousel block

Overview

Carousels are easy-to-use and attractive option menus you can add to an Answer. The options present as individual cards, complete with image, description, and interaction buttons. Chatters can scroll through the cards horizontally—like a carousel! Carousels are a great way to add visual interest and a more interactive feel to your bot.

You create carousels using the Carousel block. Everything you need to set up the cards is right in the block. Just add the block to an Answer, configure the card settings, and your carousel is ready to go.

a gif of a chatter perusing a carousel food delivery menu

Configure the Carousel block

Configuring the Carousel block consists of essentially one task—setting up the individual cards. And you can create as many cards as you like for a single carousel.

There are three ways to configure the cards:

Each card has a title, a description, an image, and a maximum of two interaction buttons. The buttons can either trigger a postback action—which creates a text output that you define, and saves it to a variable—or open a link to a URI of your choosing. You can use the variable created with the postback action in another process, such as sharing the chatters selection with your sales system, or providing contextual information or experiences based on what the chatter chose from the carousel. We're always excited to see the different ways you incorporate carousels into your Answer flows.

Manual carousels

A manual carousel is one that you build directly in the block. You can use either the card configuration fields, or you can create a JSON blob to define the card setup.

Create a manual carousel using the card configuration fields

The easiest way to create a carousel is with the card configuration fields. Add a title, descriptive content, an image, and interaction buttons, and your carousel is ready to go.

The card creation fields accept either static text or variables. If you use variables, the card details can update automatically based on what those variables contain.

  1. On the Ada dashboard, go to Build > Answers. Select or create an Answer, then drag and drop the Carousel block in the Answer editor.

  2. In the Carousel block under Select Action, click the Select an action drop-down menu, then click Create manual carousel from the list. The manual carousel configuration fields appear.

  3. [Optional] Chatters engaging with your bot in an external channel see an introductory message and a button they must click to open a carousel. Use the Message Text and Button Label fields to customize text for each.

    Note

    The Message Text and Button Label fields don't apply to conversations in the native Ada Web Chat window. A carousel presented in the Ada Web Chat window opens automatically, and does not display a message or a button.

  4. Add custom text to the Message Text and Button Label fields. The message text and bu

  5. the text in this field precedes the appearance of a carousel. Use this text to briefly inform the chatter about the carousel.

    Note

    This text only appears for external channels, and not in the Ada Web Chat window.

  6. Button Label – When you present your bot in an external channel, chatter's must click a button to open the carousel. Use this field to customize the text on the button. Button text doesn't appear in the Ada Web Chat window since carousels open automatically and don't present a button.

  7. Now add the individual cards to appear in your carousel. Under Configure Cards, complete the Card 1 configuration fields. Use the following table as a guide.

    Card Title

    Add a title for the carousel card.

    Description

    Craft a brief note with the details of this selection.

    Image Link

    Insert a link to an image for this card. The ideal aspect ratio for carousel images is 1.91:1

    Alternative Text

    Add an image description for use by screen readers for the visually impaired. This is an important accessibility feature as screen readers can't "see" images.

    First/Second Button

    You can provide selection buttons for up to two options. Click the drop-down menu and select which option each button should provide:

    • Link to External URL – Sets the button to link to a URL of your choice.

      Use the fields provided to add a button title and the URL the button points to.

    • Save Selection as Variable – Sets the button to save a value to a variable.

      Use the fields provided to add a button title and the value to save as a variable. You can add text manually, or use the data from an existing variable.

      Note

      You select the variable to save to under the Select Variables section of the block.

    • No Button – Omits the button from the carousel card.

    + Add Another Card

    Click this to add a new card to your carousel.

    Capture Settings

    Use the Optional toggle to change the behavior of the Cancel Capture button.

    • OFF (default) – Clicking the Cancel Capture button cancels the Answer. The bot reverts to a ready state, ready for the chatter to ask a new question.

    • ON – The Cancel Capture button cancels the carousel, only. The bot moves forward and presents any of the Answer's remaining blocks.

  8. The next step is to set a variable for capturing the chatter's carousel selection.

    Under Select Variables, click the Select Optional Variables drop-down menu, then click Variable for 'Save Selection as Variable' value.

  9. Click the Choose a Variable drop-down menu, then choose an existing variable or create a new variable for storing the chatter's selection.

  10. Click Save.

    an image of the carousel block with the taco card completed

Use a JSON blob

Another way to create a manual carousel is with a JSON blob. Carousels created this way are completely static. You can't use variables to allow the card details to update automatically. Any changes have to be done manually in the Carousel block.

Remember to structure your JSON blob according to the carousel schema.

What's a schema? In simple terms, a schema is the structure of a database. In this case, the database is the carousel.

Take a look at the examples below to understand how to structure your JSON blob, and what a completed JSON blob looks like. Or you can jump straight to the configuration steps if you already have a JSON blob ready.

JSON Structure

To define a carousel card, the JSON structure should include these objects:

  • items: [ card 1, card 2, card 3, etc. ]

  • card: { title, description, mediaurl, actions }

  • actions: [ action 1, action 2, etc. ]

  • action {text, type, payload/uri}

The following example shows how the hierarchy of these objects should look in your blob.

  • "items"

    • card (contained within square brackets [ ] )

      • "title" – The card title

      • "description" – The card description

      • "mediaurl" – The link to the card image

      • "actions" – The selection buttons on the card

        • action (contained within square brackets [ ] )

          • "text" – The button label

          • "type" – Button action type

          • "payload" – For the postback "type." The data returned by the button click

          • "uri" – For the link "type." The address the button

Note

You may have noticed how the objects card and action are not contained in quotation marks in the example above. That's because you don't include those two object names in the JSON code. You simply use square brackets [] to define where each card or action begins and ends.

Sample JSON Blob

This example is for a carousel with two cards. Test it out in your own bot! Follow the block setup instructions for a JSON blob and use this sample to see how it works.

{
  "role": "appMaker",
  "type": "carousel",
  "items":[
    {
      "title":"Tako",
      "description":"Try our spicy Tako.",
      "mediaurl":"https://carousel-builder-media.s3.ca-central-.amazonaws.com/bucketFolder/1604507015670.jpg"
      "actions":[
        {
          "text":"Order",
          "type":"postback",
          "payload":"Tako"
        },
        {
          "text":"Info",
          "type":"link",
          "uri":"https://en.wikipedia.org/wiki/Taco"
        }
      ],
    },
    {
      "title":"Burger",
      "description":"You'll love our greasy burger.",
      "actions":[
        {
          "text":"Order",
          "type":"postback",
          "payload":"HAMBURGER"
        },
        {
          "text":"Info",
          "type":"link",
          "uri":"https://en.wikipedia.org/wiki/Hamburger"
        }
      ],
    },
  ]
}

Your completed block should look similar to the following image.

An image of the carousel block with JSON blob setup

Create a manual carousel using a JSON blob

Go to Build > Answers, select or create an Answer, then drag and drop the Carousel block in the Answer editor.

  1. Under Select Action, click the Select an action drop-down menu, then click Create dynamic carousel - JSON Blob. The JSON Blob configuration options appear.

  2. Under Configuration, in the JSON Blob input field, add your JSON blob.

  3. [Optional] If your JSON blob uses postback, add a variable to save the returned data.

    Under Save Response as Variables, click the Select Optional Variables drop-down menu, then click Selection from the Carousel Button.

  4. Click the Choose a Variable drop-down menu, then choose an existing variable or create a new variable to capture the postback response.

  5. Click Save.

Dynamic carousels

A dynamic carousel is one whose cards update automatically. Where a manual carousel is a static structure with a fixed number of cards with fixed data, a dynamic carousel updates via an API each time the Carousel block triggers. When called, the API returns a JSON blob to the block from the endpoint URL you specify. This allows the carousel to change automatically based on the structure of the JSON blob at the time of the call.

Create a dynamic carousel using an endpoint URL

Use the following steps to connect the Carousel block to your endpoint. The JSON blob returned by the endpoint should be structured as described in the section titled Using a JSON blob.

  1. Under Select Action, click the Select an action drop-down menu, then click Create dynamic carousel - Endpoint URL. The Endpoint URL configuration options appear.

  2. Under Configuration, in the Carousel Endpoint URL input field, add the URL for your endpoint.

  3. [Optional] If your JSON blob has a postback action, add a variable to save the returned data.

    Under Save Response as Variables, click the Select Optional Variables drop-down menu, then click Button Value saved as.

  4. Click the Choose a Variable drop-down menu, then choose an existing variable or create a new variable to capture the postback response.

  5. Click Save.

    image of a carousel block using an endpoint u r l

User experience

Chatters who encounter the Carousel block can interact with it in the following ways:

Scrolling

  • Web browser – Click the arrows on the left and right of the carousel to scroll back and forth through the carousel.

  • Mobile – Swipe left or right on the carousel.

Selecting a card option

  • Web browser – Click one of two selection buttons at the bottom of each card.

  • Mobile – Tap a selection button.

Closing the carousel without selecting

  • Web browser – Click Never mind at the bottom of the chat window to close the carousel.

  • Mobile – Tap Never mind to close the carousel.

Have any questions? Contact your Ada team—or email us at help@ada.support.

In this section: