# List message

Note:
Currently, list messages are only supported by the WhatsApp channel. List messages are not natively supported on channels other than WhatsApp, and they may not be transcoded into text on other channels.

A list message is an interactive message. There are two types of list messages:

- [Choice list messages](#choice-list-message)
- [Product list messages](#product-list-message)


Choice list messages provide the recipient with a list of up to 10 choices. Pressing one of the choices causes a response to be sent back in a callback. Product list messages provide the recipient with a list of products (or a singular product) in a product catalog. Pressing one of the products allows the user to add the product to their cart.

Note:
Choice list messages and product list messages share some of the same schema structure. However, at the `items` level, you must specify either `choice` or `product`. Subsequent schema levels are specific to the type of message you specified.

## Choice list message

You can send a choice list message by making a `POST` request to the `/messages:send` Conversation API [endpoint](/docs/conversation/api-reference/conversation/messages/) with the following payloads:

```json
{
  "app_id": "{APP_ID}",
  "recipient": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "{CHANNEL}",
          "identity": "{IDENTITY}"
        }
      ]
    }
  },
  "message": {
    "list_message": {
      "title": "Choose your icecream flavor",
      "description": "The best icecream in town!",
      "sections": [
        {
          "title": "Fruit flavors",
          "items": [
            {
              "choice": {
                "title": "Strawberry",
                "postback_data": "Strawberry postback"
              }
            },
            {
              "choice": {
                "title": "Blueberry",
                "postback_data": "Blueberry postback"
              }
            }
          ]
        },
        {
          "title": "Other flavors",
          "items": [
            {
              "choice": {
                "title": "Chocolate",
                "postback_data": "Chocolate postback"
              }
            },
            {
              "choice": {
                "title": "Vanilla",
                "postback_data": "Vanilla postback"
              }
            }
          ]
        }
      ],
      "message_properties": {
        "menu": "Menu text",
        "whatsapp_header": "WhatsApp header text"
      }
    }
  }
}
```

## Product list message

You can send a product list message by making a `POST` request to the `/messages:send` Conversation API [endpoint](/docs/conversation/api-reference/conversation/messages/). However, you must have a corresponding [catalog that contains approved items](https://community.sinch.com/t5/WhatsApp/How-do-I-send-product-information-on-Sinch-s-WhatsApp-API/ta-p/9264). Then, you'll be able to use the catalog and product IDs to send list product messages. The following payload is only a structural example, and the details should not be used in an actual API call:

```json
{
  "app_id": "{APP_ID}",
  "recipient": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "{CHANNEL}",
          "identity": "{IDENTITY}"
        }
      ]
    }
  },
  "message": {
    "list_message": {
      "title": "Title for the list message with products",
      "description": "Description (or subtitle) for list message with products",
      "sections": [
        {
          "title": "Facebook product catalog item set name",
          "items": [
            {
              "product": {
                "id": "product_1_id",
                "marketplace": "FACEBOOK"
              }
            },
            {
              "product": {
                "id": "product_2_id",
                "marketplace": "FACEBOOK"
              }
            }
          ]
        }
      ],
      "message_properties": {
        "catalog_id": "id_of_catalog"
      }
    }
  }
}
```

## List message schema

A list message can take the following parameters and properties. Required parameters are marked.

```json
{
  "$ref": "#/components/schemas/ListMessageField",
  "components": {
    "schemas": {
      "MediaProperties": {
        "title": "Media Properties",
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "thumbnail_url": {
            "type": "string",
            "description": "An optional parameter. Will be used where it is natively supported."
          },
          "url": {
            "description": "Url to the media file.",
            "type": "string"
          },
          "filename_override": {
            "description": "Overrides the media file name.",
            "type": "string"
          }
        }
      },
      "ChoiceItem": {
        "type": "object",
        "title": "Choice",
        "description": "A message component for interactive messages, containing a choice.",
        "required": [
          "title"
        ],
        "properties": {
          "title": {
            "type": "string",
            "description": "Required parameter. Title for the choice item."
          },
          "description": {
            "type": "string",
            "description": "Optional parameter. The description (or subtitle) of this choice item."
          },
          "media": {
            "description": "Optional parameter. The media of this choice item.",
            "allOf": [
              {
                "$ref": "#/components/schemas/MediaProperties"
              }
            ]
          },
          "postback_data": {
            "type": "string",
            "description": "Optional parameter. Postback data that will be returned in the MO if the user selects this option."
          }
        }
      },
      "ProductItem": {
        "type": "object",
        "title": "Product",
        "description": "A message component for interactive messages, containing a product.",
        "required": [
          "id",
          "marketplace"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Required parameter. The ID for the product."
          },
          "marketplace": {
            "type": "string",
            "description": "Required parameter. The marketplace to which the product belongs.",
            "example": "FACEBOOK"
          },
          "quantity": {
            "type": "integer",
            "format": "int32",
            "description": "Output only. The quantity of the chosen product."
          },
          "item_price": {
            "type": "number",
            "format": "float",
            "description": "Output only. The price for one unit of the chosen product."
          },
          "currency": {
            "type": "string",
            "description": "Output only. The currency of the item_price."
          }
        }
      },
      "ListItem": {
        "type": "object",
        "title": "List Item",
        "description": "Item containing either choiceItem or ProductItem",
        "oneOf": [
          {
            "required": [
              "choice"
            ],
            "type": "object",
            "properties": {
              "choice": {
                "$ref": "#/components/schemas/ChoiceItem"
              }
            },
            "title": "Choice"
          },
          {
            "required": [
              "product"
            ],
            "type": "object",
            "properties": {
              "product": {
                "$ref": "#/components/schemas/ProductItem"
              }
            },
            "title": "Product"
          }
        ]
      },
      "ListSection": {
        "type": "object",
        "title": "List Section",
        "description": "Section for interactive WhatsApp messages containing ListItem",
        "required": [
          "items"
        ],
        "properties": {
          "title": {
            "description": "Optional parameter. Title for list section.",
            "type": "string"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ListItem"
            }
          }
        }
      },
      "ListMessageField": {
        "type": "object",
        "title": "List",
        "description": "A message containing a list of options to choose from. All items must be of the same type.",
        "properties": {
          "list_message": {
            "title": "List Message",
            "type": "object",
            "required": [
              "title",
              "sections"
            ],
            "properties": {
              "title": {
                "description": "A title for the message that is displayed near the products or choices.",
                "type": "string"
              },
              "description": {
                "description": "This is an optional field, containing a description for the message.",
                "type": "string"
              },
              "media": {
                "$ref": "#/components/schemas/MediaProperties"
              },
              "sections": {
                "description": "List of ListSection objects containing choices to be presented in the list message.",
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ListSection"
                }
              },
              "message_properties": {
                "description": "Additional properties for the message. Required if sending a product list message.",
                "properties": {
                  "catalog_id": {
                    "description": "Required if sending a product list message. The ID of the catalog to which the products belong.",
                    "type": "string"
                  },
                  "menu": {
                    "description": "Optional. Sets the text for the menu of a choice list message.",
                    "type": "string"
                  },
                  "whatsapp_header": {
                    "description": "Optional. Sets the text for the header of a WhatsApp choice list message. Ignored for other channels.",
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

The following sections give examples of how list messages are rendered in each channel and specific parameter support:

- [WhatsApp](#whatsapp)


## WhatsApp

WhatsApp channel natively supports list messages. Note the following limitations:

- The top-level `title` property supports a maximum of 1024 characters
- The top-level `description` property supports a maximum of 60 characters
- The `menu` property of the `message_properties` parameter supports a maximum of 20 characters
- The `whatsapp_header` property of the `message_properties` parameter supports a maximum of 60 characters and this property is only supported for choice list messages
- The `title` property of the `sections` object supports a maximum of 24 characters
- The `title` property of a `choice` object supports a maximum of 24 characters
- The `description` property of a `choice` object supports a maximum of 72 characters
- The `postback_data` property of a `choice` object supports a maximum of 200 characters


The following images give examples of the different list message functionalities:

**Choice list message**

![List Message](/assets/whatsapp_list_message.d28f459e2a74fb8834364ce17385ac1b428c27b4658eb809c7ceb9d56403c713.3a8dbadf.png)

**Choice list message details**

![List Message](/assets/whatsapp_list_message_details.a874ca7b6e2c447c58b4587dcb2cfd6190055c72377172a8de72473c018584e6.3a8dbadf.png)

**Product list message (single product)**

![Single Product Message](/assets/whatsapp_single_product_message.5ad538a6b6f6160a820d19236a15f8459a94f4284142a2c12239b07ca745feb6.3a8dbadf.png)

**Product list message details (single product)**

![Single Product Message Details](/assets/whatsapp_single_product_details.71a5f566e35befb2eeca813759b599986bfac963f9a2368e97a4c0beed9853e1.3a8dbadf.png)

**Product list message (multi-product)**

![Multi Product Message](/assets/whatsapp_multi_product_message.d813a1923c5c93d20a81cff94eb4c7b420da87b3477cbce74cbc2123177e0da1.3a8dbadf.png)

**Product list message details (multi-product)**

![Multi Product Message Details](/assets/whatsapp_multi_product_details.4195179741a8d5e7553cbf1f02a6fbc7d687a7baa16208b6e430a168943cb549.3a8dbadf.png)