English

# Flex Message elements

A Flex Message consists of three nested data structures: a container, blocks (header, hero, body, footer), and components. This page explains elements constituting a Flex Message through an example.

Structure of a Flex Message

# Container

A container is the top-level structure of a Flex Message. Here are the types of containers available:

Type Description
Bubble A container that displays a single message bubble.
Carousel A container that displays multiple message bubbles arranged side by side.

# Bubble

A bubble is a container that contains one message bubble.

Bubble example

For more information about the JSON schema, see Bubble in the API reference.

A carousel is a container that contains multiple bubble elements. The bubbles in the carousel can be browsed by scrolling horizontally.

Carousel example

The Flex Message above can be created by the JSON data below.

{
  "type": "carousel",
  "contents": [
    {
      "type": "bubble",
      "body": {
        "type": "box",
        "layout": "horizontal",
        "contents": [
          {
            "type": "text",
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
            "wrap": true
          }
        ]
      },
      "footer": {
        "type": "box",
        "layout": "horizontal",
        "contents": [
          {
            "type": "button",
            "style": "primary",
            "action": {
              "type": "uri",
              "label": "Go",
              "uri": "https://example.com"
            }
          }
        ]
      }
    },
    {
      "type": "bubble",
      "body": {
        "type": "box",
        "layout": "horizontal",
        "contents": [
          {
            "type": "text",
            "text": "Hello, World!",
            "wrap": true
          }
        ]
      },
      "footer": {
        "type": "box",
        "layout": "horizontal",
        "contents": [
          {
            "type": "button",
            "style": "primary",
            "action": {
              "type": "uri",
              "label": "Go",
              "uri": "https://example.com"
            }
          }
        ]
      }
    }
  ]
}

For more information about the JSON schema, see Carousel in the API reference.

# Block

Blocks make up a bubble. Here are the types of blocks available.

Type Description
Header Block that displays the message subject or header.
Hero Block that displays main image content.
Body Block that displays main message content.
Footer Block that displays buttons and supplementary information.

The order of display from top to bottom is: header, hero, body, footer. Each type of block can be specified only once in a bubble (or omitted).

Block style example

The Flex Message above can be created by the JSON data below.

{
  "type": "bubble",
  "styles": {
    "header": {
      "backgroundColor": "#ffaaaa"
    },
    "body": {
      "backgroundColor": "#aaffaa"
    },
    "footer": {
      "backgroundColor": "#aaaaff"
    }
  },
  "header": {
    "type": "box",
    "layout": "vertical",
    "contents": [
      {
        "type": "text",
        "text": "header"
      }
    ]
  },
  "hero": {
    "type": "image",
    "url": "https://example.com/flex/images/image.jpg",
    "size": "full",
    "aspectRatio": "2:1"
  },
  "body": {
    "type": "box",
    "layout": "vertical",
    "contents": [
      {
        "type": "text",
        "text": "body"
      }
    ]
  },
  "footer": {
    "type": "box",
    "layout": "vertical",
    "contents": [
      {
        "type": "text",
        "text": "footer"
      }
    ]
  }
}

For more information about the JSON schema, see header property, hero property, body property, and footer property in Bubble in the Messaging API reference.

# Component

Components are elements that make up a block. Here are the types of components available:

Type Description
Box This component defines the layout of the other components.
Button Component that renders a button. When the user taps a button, a specified action is performed.
Image Component that renders an image.
Video Component that renders a video.
Icon Component that renders an icon.
Text This component renders a text string in a single row. You can specify font color, size, and weight.
Span This component renders multiple text strings with different designs in one row. You can specify font color, size, weight, and decoration.
Separator Component that renders a separating line.
Filler (deprecated) Component that adds empty space.

# Box

This component is used to define the layout of the message.

It can include other components (such as boxes, buttons, or images). The components (child elements) included in the box are laid out according to the properties of the box and the properties of the child elements. For more information about the layout, see Flex Message layout.

For more information about the JSON schema, see Box in the API reference.

# Button

This component renders a button.

When the user taps a button, an action is performed. For more information about available actions, see Actions.

There are three styles for the button and you can change the color of the button with any of the styles.

Button example

The Flex Message above can be created by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "vertical",
    "spacing": "md",
    "contents": [
      {
        "type": "button",
        "style": "primary",
        "action": {
          "type": "uri",
          "label": "Primary style button",
          "uri": "https://example.com"
        }
      },
      {
        "type": "button",
        "style": "secondary",
        "action": {
          "type": "uri",
          "label": "Secondary style button",
          "uri": "https://example.com"
        }
      },
      {
        "type": "button",
        "style": "link",
        "action": {
          "type": "uri",
          "label": "Link style button",
          "uri": "https://example.com"
        }
      }
    ]
  }
}

For more information about the JSON schema, see Button in the API reference.

# Image

This component renders an image.

Image example

The Flex Message above can be created by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "horizontal",
    "contents": [
      {
        "type": "image",
        "url": "https://example.com/flex/images/image.jpg",
        "size": "md"
      }
    ]
  }
}

For more information about the JSON schema, see Image in the API reference.

# Video

This component renders a video.

Video example

The Flex Message above can be created by the JSON data below.

{
  "type": "bubble",
  "size": "mega",
  "hero": {
    "type": "video",
    "url": "https://example.com/video.mp4",
    "previewUrl": "https://example.com/video_preview.jpg",
    "altContent": {
      "type": "image",
      "size": "full",
      "aspectRatio": "20:13",
      "aspectMode": "cover",
      "url": "https://example.com/image.jpg"
    },
    "aspectRatio": "20:13"
  }
}

For more information about videos, see Creating a Flex Message including a video and Video in the Messaging API reference.

# Icon

This component renders an icon for decorating the adjacent text.

This component can be used only in a baseline box.

Icon example

The Flex Message above can be created by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "vertical",
    "contents": [
      {
        "type": "box",
        "layout": "baseline",
        "contents": [
          {
            "type": "icon",
            "url": "https://example.com/flex/images/icon.png",
            "size": "md"
          },
          {
            "type": "text",
            "text": "The quick brown fox jumps over the lazy dog",
            "size": "md"
          }
        ]
      },
      {
        "type": "box",
        "layout": "baseline",
        "contents": [
          {
            "type": "icon",
            "url": "https://example.com/flex/images/icon.png",
            "size": "lg"
          },
          {
            "type": "text",
            "text": "The quick brown fox jumps over the lazy dog",
            "size": "lg"
          }
        ]
      },
      {
        "type": "box",
        "layout": "baseline",
        "contents": [
          {
            "type": "icon",
            "url": "https://example.com/flex/images/icon.png",
            "size": "xl"
          },
          {
            "type": "text",
            "text": "The quick brown fox jumps over the lazy dog",
            "size": "xl"
          }
        ]
      },
      {
        "type": "box",
        "layout": "baseline",
        "contents": [
          {
            "type": "icon",
            "url": "https://example.com/flex/images/icon.png",
            "size": "xxl"
          },
          {
            "type": "text",
            "text": "The quick brown fox jumps over the lazy dog",
            "size": "xxl"
          }
        ]
      },
      {
        "type": "box",
        "layout": "baseline",
        "contents": [
          {
            "type": "icon",
            "url": "https://example.com/flex/images/icon.png",
            "size": "3xl"
          },
          {
            "type": "text",
            "text": "The quick brown fox jumps over the lazy dog",
            "size": "3xl"
          }
        ]
      }
    ]
  }
}

For more information about the JSON schema, see Icon in the API reference.

# Text

This component renders a text string in one row. You can specify font color, size, and weight.

Text example

The Flex Message above can be created by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "vertical",
    "contents": [
      {
        "type": "text",
        "text": "Closing the distance",
        "size": "md",
        "align": "center",
        "color": "#ff0000"
      },
      {
        "type": "text",
        "text": "Closing the distance",
        "size": "lg",
        "align": "center",
        "color": "#00ff00"
      },
      {
        "type": "text",
        "text": "Closing the distance",
        "size": "xl",
        "align": "center",
        "weight": "bold",
        "color": "#0000ff"
      }
    ]
  }
}

# Wrapping text

By default, text overflowing beyond the width of the text is replaced by an ellipsis.

Example without text wrapping

The Flex Message above can be created by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "horizontal",
    "contents": [
      {
        "type": "text",
        "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
      }
    ]
  }
}

You can wrap long text around a line by setting the wrap property to true. Also, you can use a new line character (\n) to begin on a new line.

Example with text wrapping

Note

How \n is rendered at the end of a text may depend on the device environment.

The Flex Message above can be created by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "horizontal",
    "contents": [
      {
        "type": "text",
        "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod\n tempor incididunt ut labore et dolore magna aliqua.",
        "wrap": true
      }
    ]
  }
}
# Increase the line spacing in a text

You can increase the line spacing in the text by specifying the lineSpacing property for a wrapping text.

Example of increasing the line spacing in a text

The Flex Message above can be created by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "horizontal",
    "contents": [
      {
        "type": "text",
        "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod\n tempor incididunt ut labore et dolore magna aliqua.",
        "wrap": true,
        "lineSpacing": "20px"
      }
    ]
  }
}
The lineSpacing property doesn't apply to the top of the start line and the bottom of the last line

The lineSpacing property applies only to the line spacing in a text. Therefore, it doesn't apply to the top of the start line and the bottom of the last line.

For more information about texts, see Text in the Messaging API reference.

# Span

This component renders multiple text strings with different designs in one row. You can specify font color, size, weight, and decoration. Span is set to contents property in Text.

Span examples

The Flex Message above can be created by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "horizontal",
    "contents": [
      {
        "type": "text",
        "text": "hello, world",
        "contents": [
          {
            "type": "span",
            "text": "Hello, world!",
            "decoration": "line-through"
          },
          {
            "type": "span",
            "text": "\nClosing",
            "color": "#ff0000",
            "size": "sm",
            "weight": "bold",
            "decoration": "none"
          },
          {
            "type": "span",
            "text": " "
          },
          {
            "type": "span",
            "text": "the",
            "size": "lg",
            "color": "#00ff00",
            "decoration": "underline",
            "weight": "bold"
          },
          {
            "type": "span",
            "text": " "
          },
          {
            "type": "span",
            "text": "distance",
            "color": "#0000ff",
            "weight": "bold",
            "size": "xxl"
          }
        ],
        "wrap": true,
        "align": "center"
      }
    ]
  }
}

For more information about the JSON schema, see Span in the API reference.

# Separator

This component renders a separating line within a box. A vertical line will be drawn if included in a horizontal box and a horizontal line will be drawn if included in a vertical box.

Separator example

The Flex Message above can be created by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "vertical",
    "spacing": "md",
    "contents": [
      {
        "type": "box",
        "layout": "horizontal",
        "spacing": "md",
        "contents": [
          {
            "type": "text",
            "text": "orange"
          },
          {
            "type": "separator"
          },
          {
            "type": "text",
            "text": "apple"
          }
        ]
      },
      {
        "type": "separator"
      },
      {
        "type": "box",
        "layout": "horizontal",
        "spacing": "md",
        "contents": [
          {
            "type": "text",
            "text": "grape"
          },
          {
            "type": "separator"
          },
          {
            "type": "text",
            "text": "lemon"
          }
        ]
      }
    ]
  }
}

For more information about the separator, see Separator in the API reference.

# Filler

Filler components deprecated

Use the properties of each component instead of the filler components to adjust its size and position. For more information, see Component placement.

This component is used to create a space. You can put a space between, before, or after components by inserting a filler anywhere within a box.

The example below uses a filler to create a space between the images.

Filler example

The Flex Message above can be created by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "horizontal",
    "contents": [
      {
        "type": "image",
        "url": "https://example.com/flex/images/image.jpg"
      },
      {
        "type": "filler"
      },
      {
        "type": "image",
        "url": "https://example.com/flex/images/image.jpg"
      }
    ]
  }
}

For more information about the filler, see Filler in the API reference.