Build Media and Interactive Messages in Chatbot

About Media Messages

Media messages can be used to send media items to create rich conversations with your WhatsApp users. Various media types, including images, video, audio, and documents, are supported.

About Interactive Messages

Interactive Messages can be used in A2P WhatsApp flows to make it easier for end users to interact with businesses compared with plain text messages.

📘

Notes:

• Two or more Interactive messages can be combined in the same flow.
• Interactive messages can be combined together in the same flow.
• You cannot select more than one option at the same time from a list or button message, but you can go back and re-open a previous message.
• List or reply button messages cannot be used as notifications. Currently, they can only be sent within 24 hours of the last message sent by the user. If you try to send a message outside the 24-hour window or without a previous MO message, you get an error message.

The following are the four types of interactive messages supported:

• Reply Messages: A message with up to three quick reply buttons. This type of message gives you a faster way to select from a menu when interacting with your business. Reply buttons have the same user experience as interactive templates with buttons.
• List Messages: A message with a menu of up to 10 options. This type of message provides an easier and more consistent way for users to make choices when interacting with your business.
• Single Product Messages: A message containing a single product item from a business’ inventory.
• Multi Product Messages: A message containing a selection of up to 30 items from a business’ inventory.
• Catalogue: A message that allows you to showcase your product catalogue entirely within WhatsApp. Application on the end-user device. The catalogue message type can be sent only using business numbers that are associated with version v2 of Kaleyra platform WhatsApp API.
• Flow: A message that allows you to build structured interactions. It can be used to generate leads, recommend products, get new sales leads, or anything else where structured communication is more natural or comfortable for your customers. The flow message type can be sent only using business numbers that are associated with version v2 of Kaleyra platform WhatsApp API.
• Carousel: A message that allows you to send a single text message accompanied by a set of up to 10 media cards in a horizontally scrollable view. The carousel message type can be sent only using business numbers that are associated with version v2 of Kaleyra platform WhatsApp API.

Media and Interactive Messages JSON Specification

This section outlines the JSON required to use media and interactive messages with the Kaleyra.io chatbot product. These types of messages can be configured as responses to an Intent, follow-up question, or as Welcome, Fallback, or Goodbye messages. You can choose which sections to use to create a media or an interactive message.

📘

Note:

All the guidance text (in italics) plus spaces, tabs, and line breaks/carriage returns need to be removed before using the JSON to send an API Request.

interactive:{

Type – It can be one of the following types: media, reply (quick reply buttons), list, singleproduct, multiproduct, catalog_message, flow.

"type":"media",
"type":"reply", 
"type":"list",
"type":"singleproduct",
"type":"multiproduct",

Header - Mandatory for multi-product messages, optional for reply, list messages, flow and catalogue, and not supported for media or single-product messages. It can be any one of the following types: text, image, video, or document.

Text headers are specified as follows for list messages and flow:

"header":{"type":"text","text":"This is the header text"},

Text headers are specified as follows for the reply and multi-product messages:

"header_type":"text",  
"header_value":"This is the header text",

All other header types are only supported for reply messages.

Optional caption for image, video, and document header types.

"header_type":"image",  
"header_value":"<URL>",  
"caption":"Image Caption",

"header_type":"video",  
"header_value":"<URL>",  
"caption":"Video Caption",

"header_type":"document",  
"header_value":"<URL>",  
"caption":"Document Caption",

Main body text (not supported for media messages, optional for single product messages, otherwise mandatory).

"body":"This is the body text",

Optional footer (not supported for media messages).

"footer":"This is the footer text",

Media URL (only for media messages).
Optional caption (not displayed for some media types).

"media_url":"<URL>",  
"caption":"Media Caption",

Action (not supported for media messages and flow, mandatory for all other types, format dependent on type).

Reply messages – quick reply buttons (up to three)
Button titles have a maximum length of 20 characters.

{ 
   "action":{ 
      "buttons":[ 
         { 
            "type":"reply", 
            "reply":{ 
               "id":"1", 
               "title":"First Button Title" 
            } 
         }, 
         { 
            "type":"reply", 
            "reply":{ 
               "id":"2", 
               "title":"Second Button Title" 
            } 
         }, 
         { 
            "type":"reply", 
            "reply":{ 
               "id":"3", 
               "title":"Third Button Title" 
            } 
         } 
      ] 
   } 
}

Catalogue

"action": {"name": "catalog_message","parameters": {"thumbnail_product_retailer_id": "<Product-retailer-id>"}} 

For more information on thumbnail_product_retailer_id, see Send a Multi-Product Message Template.

Flow action (supported only for Flows)

"flow_action": "navigate","flow_action_payload": {"screen": "QUESTION_ONE","data": {"product_name": "name","product_description": "description","product_price": 100}

List messages - Can have 1 to 10 sections
Sections – section title (24 characters maximum, mandatory if more than 1 section), must have at least 1 row per section, the limit of 10 rows across all sections.
Each item (row) has an id (must be unique), a title, and an optional description (included below for section 1 but not section 2).

Section in Text format is for 2nd section – can be removed if only 1 section is required, should be repeated for 3rd and subsequent sections

"action":{
	"button":"Text for list button",
	"sections":[
		{
		"title":"Section 1 title",
		"rows":[
			{"id":"1","title":"First Button Title","description":"Description for 1st button"},
			{"id":"2","title":"Second Button Title","description":"Description for 2nd button"},
			{"id":"3","title":"Third Button Title","description":"Description for 3rd button"}
		]},
	
	]
}

	{
		"title":"Section 2 title",
		"rows":[
			{"id":"4","title":"S2 First Button Title"},
			{"id":"5","title":"S2 Second Button Title"},
			{"id":"6","title":"S2 Third Button Title"}
		]}

Single product messages:

Need to specify the catalogue and the product id.

"action":{
	"catalog_id":"<catalog_id>",
	"product_retailer_id":"<product_retailer_id>"
}

For more information on product_retailer_id, see Send a Multi-Product Message Template.

Multi-product messages:

When creating a multi-product message, you need to specify the catalogue and provide the product IDs. Each message can contain between 1 to 10 sections.

Sections:

• If there is more than one section, a section title (maximum 24 characters) is mandatory.
• Each section must include at least one product.
• The total number of products across all sections cannot exceed 30.

Text Format for Sections:

• The second section should be in text format.
• If there is only one section, the text format requirement can be ignored.
• For the third and subsequent sections, the text format should be repeated.

"action":{
	"catalog_id":"<catalog_id>",
	"sections":[
		{
		"title":"Section 1 Title",
		"product_items":[
			{"product_retailer_id":"<product_retailer_id_1>"},
			{"product_retailer_id":"<product_retailer_id_2>"},
			{"product_retailer_id":"<product_retailer_id_3>"}
		]},
			]
}

{
		"title":"Section 2 title",
		"product_items":[
			{"product_retailer_id":"<product_retailer_id_4>"},
			{"product_retailer_id":"<product_retailer_id_5>"},
			{"product_retailer_id":"<product_retailer_id_6>"}
		]}