> This page is for version Scripted.
> For other versions, use one of these documentation indexes:
> - Generative (default): https://developers.ada.cx/generative/llms.txt
> - Scripted: https://developers.ada.cx/scripted/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.ada.cx/_mcp/server.

# Create scrollable menus using the Carousel block

## Overview\[#UUID-40407f27-8a63-09e4-a96e-4614cf578a33_id_4405605267347_id_h_01FMGKQB68FGWK8MCQVV05KTNQ]

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.

> **Note**
>
> This feature may not be included with your organization's subscription
> package. For more information, see Ada's
> [Pricing](https://www.ada.cx/pricing) page, or contact your Ada team.

![](/_fern-files/developers.ada.cx/932423235f81e5d7b51ad603199ed9fd2518935938c6364a9a7e0b8b5cd00d5f/ada.docs.buildwithfern.com/2025-05-28T19:49:52.708Z/versions/assets/image/uuid-1418d36f-6c68-baad-99ae-9f732dafa389.gif)

## Manual carousels\[#UUID-40407f27-8a63-09e4-a96e-4614cf578a33_id_4405605267347_id_h_01FPHCNVT9QN8G57CW9BJVKRNB]

A manual carousel is one that you build directly in the block. You can
use either the [card configuration fields](/scripted/docs/build-and-maintain-your-bot/work-with-blocks-and-apps/create-scrollable-menus-using-the-carousel-block#UUID-40407f27-8a63-09e4-a96e-4614cf578a33_id_4405605267347_id_h_01FPH9XDMHJGEMMMGC5N59KPPX),
or you can create a [JSON blob](/scripted/docs/build-and-maintain-your-bot/work-with-blocks-and-apps/create-scrollable-menus-using-the-carousel-block#UUID-40407f27-8a63-09e4-a96e-4614cf578a33_id_4405605267347_id_h_01FPAYBY1J218458CAAEPRM5H8)
to determine the content on each card.

### Create a manual carousel using the card configuration fields\[#UUID-40407f27-8a63-09e4-a96e-4614cf578a33_id_4405605267347_id_h_01FPH9XDMHJGEMMMGC5N59KPPX]

The easiest way to create a carousel is with the card configuration
fields. Add a title, descriptive content, an image, and up to two
buttons per card, 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. In the **Invalid Response** field, enter a prompt that chatters will
   see if they don't interact with your carousel as expected. For
   example, if you require chatters to choose a carousel card before
   continuing, and a chatter tries to type a question, this message
   appears to prompt the chatter to either choose a card or exit the
   Answer flow.

   > **Note**
   >
   > The button that appears after the carousel has the Cancel Capture
   > Answer's button label as the text. To avoid confusing chatters,
   > verify that the button text the prompt provides matches your Cancel
   > Capture Answer's button label.

4. Under **Configure Cards**, under **Card 1**, start building out your
   carousel content.

   1. In the **Card Title** field, enter a title for the carousel
      card.
   2. In the **Description** field, enter a basic description to
      appear under the card title.
   3. Beside **Image Link**, enter a link to an image, or click
      **Upload** ![](/_fern-files/_img/f9841202b2f05f473d08612dc758fa9e388f0eb0fa5e92068963a3954053479f.webp) to add an image to the card from your computer.
   The ideal aspect ratio for carousel images is 1.91:1.
   5. Beside **Alternative text**, if the image is important to
      understand the content of the card, enter the information the
      chatter would get from seeing it.
   That way, chatters who have visual impairments can have their
   screen readers read your description to them, so they can have
   an equivalent experience with your bot and not miss out on
   important information.
   7. Each card can have up to two buttons Under **First Button** and
      **Second Button**, you can either hide or configure those
      buttons.
   By default, both buttons are set to **No Button**. You can click
   that list and choose an option for that button:
   * **Link to External URL** - Add a button below the card to a
     URL of your choice.

     Add a **Button Title**, so chatters know what they're clicking
     on, and a **URL Link** for the card to go to.

   * **Save Selection as Variable** - Save the chatter's selection
     as a variable.

     Add a **Button Title** to describe the chatter's selection,
     and add a **Value to Save in Variable**.

     > **Note**
     >
     > If you select this option, you'll have to select a variable to
     > save these values in later in the process.

   * **No Button** - Don't show the button at all.

5. As required, click **Add Another Card** to continue creating cards.
   For each card, repeat step 4 to add content and clickable options to
   it.

6. Under **Capture Settings**, turn the **Optional** toggle on or off.
   This toggle determines what happens if the chatter doesn't want to
   interact with your carousel and clicks the Cancel Capture button.

   * By default, the toggle is set to **Off**. When the toggle is off,
     clicking the Cancel Capture button takes the chatter out of the
     current Answer flow and the bot prompts the chatter for a new
     question.

   * When the toggle is set to **On**, clicking the Cancel Capture
     button gets the chatter out of only the carousel. The bot then
     continues with the Answer flow, presenting any additional blocks
     in the current Answer.

7. If you set any of the buttons in your carousel to save values in a
   variable, choose the variable to save the values in.

   1. Under **Select Variables**, click the **Select Optional
      Variables** drop-down menu, then click **Variable for 'Save
      Selection as Variable' value**.
   2. Click the **Choose a Variable** drop-down menu, then choose an
      existing variable or create a new variable for storing the
      chatter's selection.

8. Click **Save**.

   ![](/_fern-files/_img/0210a68e47bd939df1d3341efd8acdc531dc590d8b9c9b0eefc03e4e04f5275c.webp)

### Create a manual carousel using a JSON blob\[#UUID-40407f27-8a63-09e4-a96e-4614cf578a33_id_4405605267347_id_h_01FPAYBY1J218458CAAEPRM5H8]

Another way to create a manual carousel is with a JSON blob. Carousels
created this way are static, but the format might make it easier for you
to perform updates if you can't create an endpoint to get it from
instead.

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. Under **Select Action**, click the **Select an action** drop-down
   menu, then click **Create dynamic carousel - JSON Blob**. The JSON
   Blob configuration options appear.

3. In the **Invalid Response** field, enter a prompt that chatters will
   see if they don't interact with your carousel as expected. For
   example, if you require chatters to choose a carousel card before
   continuing, and a chatter tries to type a question, this message
   appears to prompt the chatter to either choose a card or exit the
   Answer flow.

   > **Note**
   >
   > The button that appears after the carousel has the Cancel Capture
   > Answer's button label as the text. To avoid confusing chatters,
   > verify that the button text the prompt provides matches your Cancel
   > Capture Answer's button label.

4. Under **Configuration**, in the **JSON Blob** field, add your JSON
   blob.

   #### Understand how to format your JSON blob

   When creating a carousel using a JSON blob, you have to follow a
   specific structure for your data. The easiest way to create a JSON
   carousel is to copy a template and add in the information you want
   to see in your carousel.

   > **Tip**
   >
   > JSON can be tricky. If you have two items on the same level (e.g.,
   > two cards), you have to separate them with commas, but you can't
   > have a comma after the last item. To make sure that your JSON is
   > valid and free of these small errors, use a text editor or tool like
   > [JSON Lint](https://jsonlint.com/) to validate your code.

   For each card, here are the keys you have to fill out values for,
   all nested inside the `items` array:

   * `"title"` - The title of the card.

   * `"description"` - Additional text to appear in the card.

   * `"mediaurl"` - A URL for the image file to appear in the card.

   * `"actions"` - An array that contains the buttons that should go
     below the card. There are two possible formats for the buttons,
     depending on what you want them to do:

     * Link buttons

       * `"text"` - The text you want to appear in the button.

       * `"type"` - Enter `"link"` as the type so your bot recognizes
         that the button should go to an external URL.

       * `"uri"` - The address you want the button to go to.

     * Buttons that save values as variables

       * `"text"` - The text you want to appear in the button.

       * `"type"` - Enter `"postback"` as the type so your bot
         recognizes that it should expect a value to save into your
         variable.

       * `"payload"` - The value you want to save into your variable.

   This example is for a carousel with two cards. Test it out in your
   own bot! You can also use it as a starting point to start putting
   together your JSON blob.

   ```json
   { 
       "role": "appMaker",
       "type": "carousel",
       "items":[
           {
               "title":"Romantic Getaway",
               "description":"Couples massage at Ada Spa and reservations at Lovelace",
               "mediaurl":"https://static.ada.support/images/f952b9d6-35d3-4b6d-b193-2e3c2e9ce951.png",
               "actions":[
                   {
                       "text":"More details",
                       "type":"link",
                       "uri":"https://info.ada.cx/hotel"
                   },
                   {
                       "text":"Book a romantic getaway",
                       "type":"postback",
                       "payload":"romantic getaway"
                   }
               ]
           },
           {
               "title":"Capturing Memories",
               "description":"1 hour photo session - families, couples, friends",
               "mediaurl":"https://static.ada.support/images/283d7220-e481-4677-8ee0-44ecfb58fa4e.png",
               "actions":[
                   {
                       "text":"More details",
                       "type":"link",
                       "uri":"https://info.ada.cx/hotel"
                   },
                   {
                       "text":"Book a photo session",
                       "type":"postback", "payload":"photo session"
                   }
               ]
           }
       ]
   }
   ```

5. Under **Capture Settings**, turn the **Optional** toggle on or off.
   This toggle determines what happens if the chatter doesn't want to
   interact with your carousel and clicks the Cancel Capture button.

   * By default, the toggle is set to **Off**. When the toggle is off,
     clicking the Cancel Capture button takes the chatter out of the
     current Answer flow and the bot prompts the chatter for a new
     question.

   * When the toggle is set to **On**, clicking the Cancel Capture
     button gets the chatter out of only the carousel. The bot then
     continues with the Answer flow, presenting any additional blocks
     in the current Answer.

6. If you set any of the buttons in your carousel to save values in a
   variable, choose the variable to save the values in.

   1. Under **Save Response as Variables**, click the **Select
      Optional Variables** drop-down menu, then click **Selection from
      the Carousel Button**.
   2. Click the **Choose a Variable** drop-down menu, then choose an
      existing variable or create a new variable to capture the
      postback response.

7. Click **Save**.

   ![](/_fern-files/_img/037ec3fb8dce87c618ad6c924f61ad567eadd473dfd2f4999cb079c7cf3d22cd.webp)

## Dynamic carousels\[#UUID-40407f27-8a63-09e4-a96e-4614cf578a33_id_4405605267347_id_h_01FMGKYE7C1GHTSHKHFQHPXT37]

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\[#UUID-40407f27-8a63-09e4-a96e-4614cf578a33_id_4405605267347_id_h_01FPAX1PQ9D5W8JGA7A69SWKE3]

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 [Understand how to format your JSON blob](/scripted/docs/build-and-maintain-your-bot/work-with-blocks-and-apps/create-scrollable-menus-using-the-carousel-block#UUID-40407f27-8a63-09e4-a96e-4614cf578a33_sidebar-idm4535969840982433733882355798_body)
section of this topic.

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. Under **Select Action**, click the **Select an action** drop-down
   menu, then click **Create dynamic carousel - Endpoint URL**. The
   Endpoint URL configuration options appear.

3. In the **Invalid Response** field, enter a prompt that chatters will
   see if they don't interact with your carousel as expected. For
   example, if you require chatters to choose a carousel card before
   continuing, and a chatter tries to type a question, this message
   appears to prompt the chatter to either choose a card or exit the
   Answer flow.

   > **Note**
   >
   > The button that appears after the carousel has the Cancel Capture
   > Answer's button label as the text. To avoid confusing chatters,
   > verify that the button text the prompt provides matches your Cancel
   > Capture Answer's button label.

4. Under **Configuration**, in the **Carousel Endpoint URL** field, add
   the URL for your endpoint.

5. Under **Capture Settings**, turn the **Optional** toggle on or off.
   This toggle determines what happens if the chatter doesn't want to
   interact with your carousel and clicks the Cancel Capture button.

   * By default, the toggle is set to **Off**. When the toggle is off,
     clicking the Cancel Capture button takes the chatter out of the
     current Answer flow and the bot prompts the chatter for a new
     question.

   * When the toggle is set to **On**, clicking the Cancel Capture
     button gets the chatter out of only the carousel. The bot then
     continues with the Answer flow, presenting any additional blocks
     in the current Answer.

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

   1. Under **Save Response as Variables**, click the **Select
      Optional Variables** drop-down menu, then click **Button Value
      saved as**.
   2. Click the **Choose a Variable** drop-down menu, then choose an
      existing variable or create a new variable to capture the
      postback response.

7. Click **Save**.

   ![](/_fern-files/_img/a108b6b8d2ca7dc0b79683264aeca2feb4b01bcf744b705e9e16a325709645e6.webp)

---

Have any questions? Contact your Ada team, or email us at [](<mailto:help@ada.support%20%E2%80%9CHelp Docs inquiry%E2%80%9D>).