About List Structured Messages

Last updated: 2022-09-29Contributors
Edit this page

This structured message provides a list from which the customer can pick some elements. See Channel capabilities to know on which channel you can use this structured message.

Request Example

curl -X POST "https://[YOUR DOMAIN].api.digital.ringcentral.com/1.0/contents"
{
  "source_id": "<source_id>",
  "in_reply_to_id": "<in_reply_to_id>",
  "structured_content": {
    "type": "list",
    "title": "List title",
    "items": [
      {
        "title": "Option 1",
        "payload": "first_option"
      },
      {
        "title": "Option 2",
        "payload": "second_option"
      },
      {
        "title": "Option 3"
      }
    ]
  }
}

Primary Parameters

API Property Type Description
source_id String Optional. ID of the source. Most interactions are in reply to a message being sent to the agent. In these cases, the source ID is not required.
in_reply_to_id String ID of the message being replied to.
structured_content Object Payload of the structured message.
Structured Content Settings
structured_content.type String Type of the structured message. Must be "list".
structured_content.title String Title of the list structured message. Limited to 1024 characters.
structured_content.subtitle String Optional. Subtitle of the list structured message. Limited to 512 characters.
structured_content.sections Array Optional. An array of sections in which the items will be organized.
Limited to 10 elements.
If blank, every item will be part of the same section.
Section Settings
structured_content.sections.title String Optional if there's only a single section. The title of the section.
Limited to 24 characters.
structured_content.sections.identifier String Identifier of the section that will be used to organize items in the section.
Limited to 200 characters.
structured_content.items Array An array of items representing the options presented to the customer. A maximum of 10 items is supported.
Item Settings
structured_content.items.title String The title of the item. Limited to 80 characters.
structured_content.items.payload String Optional. Payload that will be returned with the structured response. Limited to 200 characters.
Automatically gets populated as a random hex if blank. Can only contain ASCII characters.
structured_content.items.subtitle String Optional. The subtitle of the item. Limited to 100 characters.
structured_content.items.section_identifier String Optional if there's no section. The identifier of the section where the item is.
If there's no section, the section_identifier field should be removed.
Each section must have at least 1 item.
Limited to 200 characters.

Example: Apple Messages for Business (List Picker)

This list picker structured content has multiple specific fields. So here’s an example payload format.

JSON Body

{
  "source_id": "<source_id>",
  "in_reply_to_id": "<in_reply_to_id>",
  "structured_content": {
    "type": "list",
    "title": "Pick some options",
    "subtitle": "We have great options",
    "attachment_id": "<attachment_id>",
    "attachment_fallback_id": "<attachment_id>",
    "sections": [
      {
        "title": "section 1",
        "multiple_selection": true,
        "identifier": "1"
      },
      {
        "title": "section 2",
        "multiple_selection": false,
        "identifier": "2"
      }
    ],
    "items": [
      {
        "section_identifier": "1",
        "title": "option 1-1",
        "attachment_id": "<id>",
        "attachment_fallback_id": "<attachment_id>",
      },
      {
        "section_identifier": "1",
        "title": "option 1-2",
        "subtitle": "subtitle"
      },
      { "section_identifier": "2",
        "title": "option 2-1",
        "payload": "payload"
      },
      { "section_identifier": "2",
        "title": "option 2-2"
      }
    ]
  }
}

Properties Unique to this Channel

Primary parameters are used by default, however, some parameters are unique or overwritten by parameters specific to this example.

API Property Type Description
Structured Content Settings
structured_content.title String Title of the list structured message.
Truncated to 512 UTF-16 code units.
structured_content.subtitle String Optional. The subtitle field.
Truncated to 512 UTF-16 code units.
structured_content.attachment_id String Optional. Existing attachment id used to decorate the structured message with an image. Supports private attachments. Upload attachments for you own custom images.
structured_content.attachment_fallback_id String Optional. Fallback in case the attachment related to the attachment_id doesn’t meet the source requirements. Must be public. Only jpg, jpeg, png formats. Maximum size of 5 MB. Upload attachments for you own custom images.
Section Settings
structured_content.sections.multiple_section Boolean Optional. Allows the section to be multi selectable. False by default.
Item Settings
structured_content.items.attachment_id String Optional. Existing attachment id used to decorate the item with an image. Supports private attachments. Upload attachments for you own custom images.
structured_content.items.attachment_fallback_id String Optional. Fallback in case the attachment related to the attachment_id doesn’t meet the source requirements. Must be public. Only jpg, jpeg, png formats. Maximum size of 5 MB. Upload attachments for you own custom images.
structured_content.items.subtitle String Optional. The subtitle of the item. Limited to 512 characters.

Example: WhatsApp (List Messages)

The following example uses WhatsApp with list messages.

JSON Body

{
  "source_id": "<source_id>",
  "in_reply_to_id": "<in_reply_to_id>",
  "structured_content": {
    "type": "list",
    "header": "Welcome to the store!",
    "title": "Hello! What do you wish?",
    "subtitle": "We're always happy to offer you the best options!",
    "button": "See options",
    "sections": [
      {
        "title": "section 1",
        "identifier": "1"
      },
      {
        "title": "section 2",
        "identifier": "2"
      }
    ],
    "items": [
      {
        "section_identifier": "1",
        "title": "Option 1",
        "payload": "first_option",
        "description": "The first option"
      },
      {
        "section_identifier": "2",
        "title": "Option 2",
        "payload": "second_option",
        "description": "The second option"
      },
      {
        "section_identifier": "2",
        "title": "Option 3",
        "payload": "third_option",
        "description": "The third option"
      }
    ]
  }
}

Properties Unique to this Channel

Primary parameters are used by default, however, some parameters are unique or overwritten by parameters specific to this example.

API Property Type Description
Structured Content Settings
structured_content.button String Optional. The button text field.
Limited to 20 characters.
Truncated to 20 UTF-16 code units.
"See options" by default.
structured_content.subtitle String Optional. The subtitle field.
Truncated to 60 UTF-16 code units.
structured_content.header String Optional. The header field.
Limited to 60 UTF-16 code units.
Section Settings
structured_content.sections.title String Optional if there's only a single section. The title of the section.
Limited to 24 characters.
Truncated to 24 UTF-16 code units.
Item Settings
structured_content.items.title String The item title field.
Truncated to 24 characters.
Truncated to 24 UTF-16 code units.
structured_content.items.subtitle String Optional. The item subtitle field.
Truncated to 72 UTF-16 code units.