Blocks

Prev Next

Blocks are the components you will use to create the UI layout in surfaces. Within some of these blocks, you can add block elements and objects. The available blocks are:

  • section

  • divider

  • image

  • actions

  • context

  • input

  • preview

We will now look at the JSON payload and more details to define each of these blocks in your apps.

section

A section is used to display text and can contain additional block elements.

Supported surfaces: Messages, contextual bars, modals

Field

Type

Required?

Description

blockId

String

No

A unique identifier for the block.

type

String

Yes

The type of the block, in this case, the value is section.

text

Object{}

No

An array of text elements that should contain the following:

  • type: The type in which you want to enter the text. It can either be plain_text or mrkdown.

  • text: The text that you want to enter.

  • emoji: A boolean that indicates whether the text should display emojis or not. This field is optional.

fields

Array[{}]

No

An array of text elements that should contain the following:

  • type: The type in which you want to enter the text. It can either be plain_text or mrkdown.

  • text: The text that you want to enter.

accessory

Object{}

No

A section can contain the following block elements:

  • button

  • image

  • datepicker

  • overflow

  • static_select

Example of a section block

The following section block example contains a text object

{
  type: 'section',
  blockId: 'section_1',
  text: {
      type: 'plain_text',
      text: 'lorem ipsum 🚀',
      emoji: true,
    },
  fields: [{
      type: 'plain_text',
      text: 'field section'
    },
    {
      type: 'plain_text',
      text: 'field section'
    }
  ],
 accessory: { /* define any of the block elements in this object */ }
}

The UI looks something like this:

With the fields array:

divider

A divider is a horizontal line used to visually separate different pieces of content.

Supported surfaces: Messages, contextual bars, modals

Field

Type

Required?

Description

blockId

String

No

A unique identifier for the block.

type

String

Yes

The type of the block, in this case, the value is divider.

Example of a divider block

The following example shows the divider block:

{
  type: 'divider',
  blockId: 'divider_1',
}

On a message surface, the divider looks like this:

image

Add images to make your app more appealing.

Supported surfaces: Messages, contextual bars, modals

Field

Type

Required?

Description

blockId

String

No

A unique identifier for the block.

type

String

Yes

The type of the block, in this case, the value is image.

imageUrl

String

Yes

The URL of the image.

altText

String

Yes

A text describing the image being displayed.

title

Object{}

No

The text is displayed as the image's title. The object should contain the following fields:

  • type: The type in which you want to enter the text. It can either be plain_text or mrkdown.

  • text: The text that you want to enter.

  • emoji: A boolean that indicates whether the text should display emojis or not. This field is optional.

Example of an image block

The following example shows an image block with a title and alternate text.

{
  type: 'image',
  blockId: 'image_1',
  imageUrl: 'https://picsum.photos/200/300',
  altText: 'An image',
  title: {
      type: 'plain_text',
      text: 'lorem ipsum 🚀',
      emoji: true,
    }
}

actions

An actions block contains interactive elements and can be used to provide options.

Supported surfaces: Messages, contextual bars, modals

Field

Type

Required?

Description

blockId

String

No

A unique identifier for the block.

type

String

Yes

The type of the block, in this case, the value is actions.

elements

Array[{}]

Yes

A list of interactive block elements. The available options are:

  • button

  • checkbox

  • datepicker

  • linear_scale

  • overflow

  • radio_button

  • static_select

  • timepicker

Example of an actions block

The following example shows an actions block containing a static_select block element.

{
  type: 'actions',
  blockId: 'actions_1',
  elements: [
      {
           type: 'static_select',
           appId: appId,
           blockId: 'static_select_action_block',
           actionId: 'static_select_action_1',
           placeholder: {
                type: 'plain_text',
                text: 'Select an option'
      },
           options: [
      {
               value: 'option_1',
               text: {
               type: 'plain_text',
               text: 'This is your first option'
      }},
      {
           value: 'option_2',
           text: {
                type: 'plain_text',
                text: 'This is your second option'
       }}
  ]}
]
}

context

You can use the context block to provide quick information or notifications to your users.

Supported surfaces: Messages, contextual bars, modals

Field

Type

Required?

Description

blockId

String

No

A unique identifier for the block.

type

String

Yes

The type of the block, in this case, the value is context.

elements

Array[{}]

Yes

A list of block elements. Allowed elements are plain text object and image element.

Example of a context block

The following example shows a context block with text and image elements.

{
  type: 'context',
  blockId: 'context_1',
  elements: [
      {
            type: 'plain_text',
            text: 'This is a context block'
      },
      {
            type: 'image',
            imageUrl: 'https://img.freepik.com/free-vector/rocket-background-flat-style_23-2147904992.jpg?size=338&ext=jpg&ga=GA1.1.2008272138.1726444800&semt=ais_hybrid',
            altText: 'An icon of a rocket'
       }]
}

input

Similar to the actions block, an input block can contain elements to provide options and get information from users.

Supported surfaces: Messages, contextual bars, modals

Field

Type

Required?

Description

blockId

String

No

A unique identifier for the block.

type

String

Yes

The type of the block, in this case, input.

element

Object{}

Yes

A list of interactive block elements. The available options are:

  • checkbox

  • datepicker

  • linear_scale

  • plain_text_input

  • radio_button

  • static_select

  • timepicker

label

Object{}

Yes

The label for the block. The object should contain the following fields:

  • type: The type in which you want to enter the text. It can either be plain_text or mrkdown.

  • text: The text that you want to enter.

Example of an input block

The following example shows an input block with the plain_text_input element:

{
     type: 'input',
     label: {
               type: 'plain_text',
               text: 'Plain text input'
      },
     element: {
             type: 'plain_text_input',
             appId: appId,
             actionId: 'plain_text_input_action_1',
             blockId: 'plain_text_input_block_1',
             placeholder: {
             type: 'plain_text',
             text: 'Enter the text input here'
       },
}},

preview

Previews can be used to share notices or a block of information with users.

Supported surfaces: Messages, contextual bars, modals

Field

Type

Required?

Description

blockId

String

No

A unique identifier for the block.

type

String

Yes

The type of the block, in this case, the value is preview

description

Array[{}]

Yes

The preview description object should contain the following fields:

  • type: The type in which you want to enter the text. It can either be plain_text or mrkdown.

  • text: The text that you want to enter.

title

Array[{}]

Yes

The preview title object should contain the following fields:

  • type: The type in which you want to enter the text. It can either be plain_text or mrkdown.

  • text: The text that you want to enter.

Example of a preview block

The following example shows a preview block:

{
  type: 'preview',
  description: [
      {
           type: 'plain_text',
           text: 'Description of preview'
       }],
  title: [
  {
    type: 'plain_text',
    text: 'Title of preview'
   }
]}

callout

A callout block can be used to bring attention to specific information.

Supported surfaces: Contextual bars, modals

Field

Type

Required?

Description

appId, blockId

String

No

See Parameter details.

type

String

Yes

The type of the block, in this case, the value is callout

text

Object{}

Yes

The text object should contain the following fields:

  • type: The type in which you want to enter the text. It can either be plain_text or mrkdown.

  • text: The text that you want to enter.

title

Object{}

No

The callout title object should contain the following fields:

  • type: The type in which you want to enter the text. It can either be plain_text or mrkdown.

  • text: The text that you want to enter.

variant

String

No

The callout style that will be displayed. The options are:

  • info

  • warning

  • success

  • danger

Example of a callout block

The following example shows the callout types in a contextual bar:

{
        type: 'callout',
        text: {
          type: 'plain_text',
          text: 'Text of callout'
        },
        title: {
          type: 'plain_text',
          text: 'Title of callout'
        },
        variant: 'info'
      },
      {
        type: 'callout',
        text: {
          type: 'plain_text',
          text: 'Text of callout'
        },
        title: {
          type: 'plain_text',
          text: 'Title of callout'
        },
        variant: 'danger'
      },
      {
        type: 'callout',
        text: {
          type: 'plain_text',
          text: 'Text of callout'
        },
        title: {
          type: 'plain_text',
          text: 'Title of callout'
        },
        variant: 'success'
      },
      {
        type: 'callout',
        text: {
          type: 'plain_text',
          text: 'Text of callout'
        },
        title: {
          type: 'plain_text',
          text: 'Title of callout'
        },
        variant: 'warning'
}

tab navigation

Supported surfaces: Contextual bars

Field

Type

Required?

Description

actionId, appId, blockId

String

Yes

See Parameter details.

type

String

Yes

The type of the block, in this case, the value is tab_navigation

title

Object{}

Yes

The tab title object should contain the following fields:

  • type: The type in which you want to enter the text. It can either be plain_text or mrkdown.

  • text: The text that you want to enter.

Example of a tab_navigation block

The following example shows two tabs:

{
        type: 'tab_navigation',
        tabs: [
          {
            type: 'tab',
            appId: appId,
            blockId: 'tab_block_1',
            actionId: 'tab_action_1',
            title: {
              type: 'plain_text',
              text: 'Tab Title'
            },
          },
          {
            type: 'tab',
            appId: appId,
            blockId: 'tab_block_2',
            actionId: 'tab_action_2',
            title: {
              type: 'plain_text',
              text: 'Tab Title'
            },
          }
        ]
}

conditional block

A conditional block is used to specify where the blocks can be rendered. It works with the Livechat client and in the Rocket.Chat client.

Supported surfaces: Messages, contextual bars, modals

Field

Type

Required?

Description

appId, blockId

String

No

See Parameter details.

type

String

Yes

The type of the block, in this case, the value is conditional

render

Array[{}]

Yes

This array contains the blocks that will be displayed. The options are:

  • actions

  • callout

  • context

  • divider

  • image

  • input

  • preview

  • section

  • tab_navigation

when

Array[]

No

Determine where the blocks will be displayed. The options are livechat and rocket.chat.

Example of a conditional block

The following example shows the block in a message surface:

{
        type: 'conditional',
        render: [
          {
            type: 'section',
            text: {
              type: 'plain_text',
              text: 'Conditional block'
            }
          }
        ],
      when: {
              engine: ['rocket.chat', 'livechat']
    }
}