Parameters of a message template - - Alibaba Cloud Documentation Center

This topic describes the parameters required for calling the SendChatappMessage operation to send Chat App messages.

Parameters

The following tables describe the parameters of Content for different values of MessageType when ChannelType is set to whatsapp and Type is set to message.

Parameters of Content when MessageType is set to location

Parameter	Required	Description
longitude	Yes	The longitude of the coordinate.
latitude	Yes	The latitude of the coordinate.
name	No	The name of the coordinate.
address	No	The address identified by the coordinate. This parameter is displayed only when the name parameter is set.

Parameters of Content when MessageType is set to contacts

Note

If MessageType is set to contacts, the values of Content are in the array format.

Parameter	Required	Description
addresses	No	The address of the contact. The complete address of the contact contains the following parameters: street (optional): the number and the name of the street. The value is a string. city (optional): the name of the city. The value is a string. state (optional): the abbreviation of the name for the borough, city, county, or state. The value is a string. zip (optional): the postal code. The value is a string. country (optional): the name of the country. The value is a string. country_code (optional): the two-letter country code. The value is a string. type (optional): the type of the address. Valid values: HOME and WORK. The value is a string.
birthday	No	The birthday of the contact. The value is in the format of YYYY-MM-DD.
emails	No	The email address of the contact. The complete email address information of the contact contains the following parameters: email (optional): the email address. The value is a string. type (optional): the type of the email address. Valid values: HOME and WORK. The value is a string.
name	Yes	The name of the contact. The complete name information of the contact contains the following parameters: formatted_name (required): Generally, the full name is used. The value is a string. first_name (optional): the first name of the contact. The value is a string. last_name (optional): the last name of the contact. The value is a string. middle_name (optional): the middle name of the contact. The value is a string. suffix (optional): the suffix of the name. The value is a string. prefix (optional): the prefix of the name. The value is a string. Note The formatted_name parameter must include at least one optional parameter.
org	No	The organization information of the contact. The complete organization information contains the following parameters: company (optional): the name of the company to which the contact belongs. The value is a string. department (optional): the name of the department to which the contact belongs. The value is a string. title (optional): the title of the contact. The value is a string.
phones	No	The phone number of the contact. The complete phone number information of the contact contains the following parameters: phone (optional): the formatted phone number. The value of phone is automatically set to the value of wa_id. type (optional): the type of the phone number. Valid values: CELL, MAIN, IPHONE, HOME, and WORK. The value is a string. wa_id (optional): the WhatsApp ID. The value is a string.
urls	No	The personal homepage of the contact. The complete URL information contains the following parameters: url (optional): the URL. The value is a string. type (optional): the type of the URL. Valid values: HOME and WORK. The value is a string.

Parameters of Content when MessageType is set to image, video, audio, document, or sticker

Parameter	Required	Description
link	Yes	The protocol and URL of the media resource to be sent. Only HTTP or HTTPS URLs are used. This parameter is not specified when MessageType is set to text. This parameter is required when MessageType is set to audio, document, image, or video, and no URL is used.
caption	No	The description of the media resource. The description can be up to 1,024 characters in length. Note This parameter is specified when MessageType is set to document, image, or video. This parameter is not specified when MessageType is set to audio.
filename	No	The name of the file. This parameter is required only when MessageType is set to document. Note The extension of the file name indicates the format of the WhatsApp document.

Parameters of Content when MessageType is set to text

Parameter

Required

Description

text

Yes

The text content of the message, which can contain a formatted URL.

previewUrl

Specifies whether to preview the URL. The value is a string. Default value: false. Valid values:

true: previews the URL.
false: does not preview the URL.

Parameters of Content when MessageType is set to interactive

Parameter	Required	Description
type	Yes	The type of interactive message you want to send. Valid values: list: used for list messages. button: used for reply buttons. product: used for single-product messages. product_list: used for multi-product messages. catalog_message: used for product catalog messages. cta_url: used for messages with call to action (CTA) buttons. flow: used for WhatsApp Flows messages. address_message: used for address messages. location_request_message: used for location request messages.
header	-	The title displayed at the top of the message. This parameter is not specified when the type parameter is set to product. Note This parameter is required when the type parameter is set to product_list. It is optional when the type parameter is set to list or button. The header object contains the following parameters: document: the media object of the document, which is required when MessageType is set to document. The value is an object. image: the media object of the image, which is required when MessageType is set to image. The value is an object. video: the media object of the video, which is required when MessageType is set to video. The value is an object. text: This parameter is required when MessageType is set to text. Emojis can be used in the text in the header. The Markdown syntax is not supported. The value can be up to 60 characters in length. The value is a string. type (required): The value is a string. The following types are supported: text: used for list messages, reply buttons, and multi-product messages. video: used for reply buttons. image: used for reply buttons. document: used for reply buttons.
body	-	The object that specifies the message body. Note This parameter is optional only when the type parameter is set to product. It is required when the type parameter is set to list, button, or product_list. The body object contains the text parameter. This parameter is required when you need to display it. The value of the text parameter is a string. The value can be up to 1,024 characters in length and emojis and the Markdown syntax are supported.
footer	No	The object that specifies the message footer. The footer object contains the text parameter. This parameter is required when you need to display it. The value of the text parameter is a string. The value can be up to 60 characters in length and emojis and the Markdown syntax are supported.
action	Yes	The action object, which contains the actions you want the user to perform after they read the message.

Parameters of Action for the interactive parameter

Suitable message type	Parameter		Description
List message	button		The button content, which is required when the type parameter is set to list. The value cannot be an empty string and must be unique in a message. It can be up to 20 characters in length. Emojis are supported. The Markdown syntax is not supported.
Reply button message	buttons		The button object, which is required when the type parameter is set to button. This object can contain the following parameters: type: The only supported value is reply when the type parameter is set to button. title: the title of the button. The value cannot be an empty string and must be unique in the message. Emojis are supported. The Markdown syntax is not supported. The value can be up to 20 characters in length. ID: the unique identifier of the button. This ID is returned in the webhook after the user clicks the button. The value can be up to 256 characters in length. Note Do not use leading or trailing spaces when you set the ID. Example `{ "type":"reply", "reply":{ "id":"********231211", "title":"Click" } }`
List message or multi-product message	sections		This parameter is required when the type parameter is set to list or product_list. An array of section objects. Valid values: 1 to 10.
Single-product message or multi-product message	catalog_id		This parameter is required when the type parameter is set to product or product_list. The unique identifier of the Facebook catalog linked to your WhatsApp Business account. You can search for the ID by using Commerce Manager.
	product_retailer_id		This parameter is required when the type parameter is set to product or product_list. The unique identifier of the product in the catalog. The value can be up to 100 characters in length for single-product messages or multi-product messages.
Message with a CTA button	name		The value is a string. This parameter is required. Set name to cta_url.
	parameters		The value is an object
		display_text	The value is a string. This parameter is required. This parameter indicates the text of the button.
		url	The value is a string. This parameter is required. This parameter indicates the URL to which WhatsApp users are redirected in the default browsers of their devices after they tap the button on their devices.
WhatsApp Flows message	name		The value is a string. This parameter is required. Set the parameter to flow.
	parameters		The value is an object
		mode	The value is a string. This parameter is optional. This parameter indicates the mode of the Flow. Valid values: draft and published. Default value: published.
		flow_message_version	The value is a string. This parameter is required. Set the parameter to 3.
		flow_token	The value is a string. This parameter is required. This parameter indicates the token that is generated by the enterprise to serve as an identifier.
		flow_id	The value is a string. This parameter is required. This parameter indicates the unique identifier of the Flow provided by WhatsApp.
		flow_cta	The value is a string. This parameter is required. This parameter indicates the text on the CTA button. Example: Signup. The value can be up to 20 characters in length. The value cannot contain emojis.
		flow_action	The value is a string. This parameter is optional. Valid values: navigate and data_exchange. Note To predefine the first screen as a part of the message, set flow_action to navigate. Set flow_action to data_exchange for advanced use cases where the first screen is provided by your endpoint. Default value: navigate.
		flow_action_payload	The value is a string. This parameter is optional. This parameter is required if flow_action is set to navigate. The object can contain the following parameters: screen: The value is a string. This parameter is required. This parameter indicates the ID of the first screen for the Flow. data: The value is an object. This parameter is optional. This parameter indicates the input data for the first screen of the Flow. The value is a non-empty object. This parameter is optional.
Address message Note This feature is only available for enterprises and their customers in Singapore and India. For more information about address messages, see the Address Messages section of the Sending Free-Form Messages topic.	name		The value is a string. This parameter is required. Set the parameter to address_message.
	parameters		The value is an object
		country	The value is a string. This parameter is required. This parameter indicates the country or region code. Example: SG and IN.
		values	The value is an array of objects. This parameter is required. The following parameters are included: name: the name of the user. phone_number: the phone number of the user.
		validation_errors	The value is a string. This parameter is optional. You can throw errors in the address fields and WhatsApp will prevent the user from submitting the address until the issues are resolved.
		saved_addresses	The saved addresses associated with the user. The following parameters are included: id: the ID of the saved address. The value is a string. This parameter is required. value: an array of objects. This parameter is required. name: the name of the user. The value is text. This parameter is available for customers in India and Singapore. phone_number: the valid phone number. This parameter is available for customers in India and Singapore. in_pin_code: the personal identification number (PIN) code. The value is text. The PIN code can be up to 6 characters in length and is available for customers only in India. sg_post_code: the post code. The value is a digit number and can be up to 6 characters in length. This parameter is available for customers only in Singapore. house_number: the house number. The value is text. This parameter is available for customers only in India. floor_number: the floor number. The value is text. This parameter is available for customers only in India. tower_number: the tower number. The value is text. This parameter is available for customers only in India. building_name: the building or apartment name. The value is text. This parameter is available for customers only in India. address: the address. The value is text. This parameter is available for customers in India and Singapore. landmark_area: the landmark or area. The value is text. This parameter is available for customers only in India. unit_number: the unit number. The value is text. This parameter is available for customers only in Singapore. city: the city. The value is text. This parameter is available for customers in India and Singapore. state: the state, province, autonomous region, or municipality. The value is text. This parameter is available for customers only in India.
Location request message Note For more information about location request messages, see Location Request Messages.	name		The value is a string. This parameter is required. Set the parameter to send_location.

Parameters of Section for the interactive parameter

Parameter	Description
title	The title of the section. This parameter is required when the message has multiple sections. The value can be up to 24 characters in length.
rows	This parameter is required for list messages. The value contains a list of row objects. All sections have up to 10 rows. Each row object contains the following parameters: title (required): The value is a string. The value can be up to 24 characters in length. ID (required): The value is a string. The value can be up to 200 characters in length. description (optional): The value is a string. The value can be up to 72 characters in length.
product_items	This parameter is required for multi-product messages. The value contains a list of product objects. Each section has at least one product and all sections have up to 30 products. Each product object contains the product_retailer_id parameter. This parameter specifies the unique identifier of the product in the catalog, which is required for multi-product messages.

Parameters when MessageType is set to reaction

Parameter	Required	Description
messageId	Yes	The message ID. The value is a string. Example: 2022129384888829****.
emoji	Yes	The emoji. The value is a string.

The following tables describe the parameters of Content for different values of MessageType when ChannelType is set to viber and Type is set to message.

Parameters of Content when MessageType is set to text

Parameter	Required	Description
text	Yes	The text.

Parameters of Content when MessageType is set to image

Parameter	Required	Description
link	Yes	The URL of the image.

Parameters of Content when MessageType is set to video

Parameter	Required	Description
link	Yes	The URL of the video.
thumbnail	Yes	The URL of the thumbnail.
fileSize	Yes	The size of the file. Unit: MB.
duration	Yes	The duration of the file. Unit: seconds.

Parameters of Content when MessageType is set to document

Parameter	Required	Description
link	Yes	The URL of the file.
fileName	Yes	The name of the file. The name can be up to 25 characters in length.
fileType	Yes	The file type.

Parameters of Content when MessageType is set to text_button

Parameter	Required	Description
text	Yes	The text.
caption	Yes	The text of the button.
action	Yes	The URL linked to the button.

Parameters of Content when MessageType is set to text_image_button

Parameter	Required	Description
text	Yes	The text.
link	Yes	The URL of the image.
caption	Yes	The text of the button.
action	Yes	The URL linked to the button.

Parameters of Content when MessageType is set to text_video

Parameter	Required	Description
text	Yes	The text.
link	Yes	The URL of the video.
thumbnail	Yes	The URL of the thumbnail.
fileSize	Yes	The size of the file. Unit: MB.
duration	Yes	The length of the video. Unit: seconds.

Parameters of Content when MessageType is set to text_video_button

Parameter	Required	Description
text	Yes	The text.
link	Yes	The URL of the video.
thumbnail	Yes	The URL of the thumbnail.
fileSize	Yes	The size of the file. Unit: MB.
duration	Yes	The length of the video. Unit: seconds.
caption	Yes	The text of the button.

Important

After you tap a button with a video URL link, you are redirected to a browser to play the video.

In addition to opening web pages, buttons can be used to perform the following operations by using URL schemes:

Make a phone call: viber://keypad?number=%2B<number>
Open a new session: viber://chat?service=<sender_ID>
Start QR code scanning: viber://more/qr

Supported media types and size limits

Supported types and size limits

Media	Supported type	Size limit
Audio	ACC, MP4, MPEG, and AMR	16 MB
Document	TXT, PDF, PPT, DOC, XLS, DOCX, PPTX, and XLSX	100 MB
Image	JPEG and PNG	5 MB
Video	MP4 and 3GP Note Only H.264 video codecs and AAC audio codecs are supported. Videos with a single audio stream or no audio stream are supported.	16 MB
Sticker	WebP	Static sticker: 100 KB Dynamic sticker: 500 KB

Media HTTP cache

If you use the media resource link on your server, you need to add the following headers to your server response. In this way, WhatsApp will cache the resource and reuse the resource in messages. If you do not add the following headers, the resource will not be cached.

Cache-Control

The Cache-Control header specifies how a resource is cached. The Cache-Control header supports the following directives:

max-age=n: specifies how many seconds (n) it takes to cache the resource.
The cached resource is also used in other messages until the time is exceeded. After the time is exceeded, WhatsApp might send another request to obtain the resource based on the business requirements.
Example: Cache-Control: max-age=604800.
no-cache: specifies that the resource can be cached. However, the resource needs to be updated if the value of the Last-Modified header is different from that in the last response.
In this case, the Last-Modified header is required.
Example: Cache-Control: no-cache.
no-store: specifies that the resource should not be cached.
Example: Cache-Control: no-store.
private: specifies that the resource is personalized for the receiver and should not be cached.

Last-Modified

Last-Modified indicates the time when the resource was last modified. Last-Modified needs to coexist with Cache-Control: no-cache.

If the return value of Last-Modified is different from that in the last response and Cache-Control: no-cache is included in this response, WhatsApp updates the version of the cached resource to the version in this response.

Example: Date: Tue, 22 Feb 2022 22:22:22 GMT.

ETag

The ETag header is the unique string that identifies a specific version of the resource.

Example: ETag: "33a64df5". WhatsApp ignores the ETag header if both the Cache-Control and Last-Modified headers are included in the response. In this case, WhatsApp caches the resource based on its internal logic.

Viber

This type of template applies to business messages.

Media	Supported type	Size limit
Text	UTF-8	1,000 characters, including spaces and special characters
Document	DOC, DOCX, RTF, DOT, DOTX, ODT, ODF, FODT, TXT, INFO, PDF, XPS, PDAX, EPS, XLS, XLSX, ODS, FODS, CSV, XLSM, and XLTX	200 MB
Video	MP4, M4V, MOV, and 3GP	200 MB
Image	JPG, JPEG, PNG, GIF, and WebP	GIF: 20 MB. The recommended size for images of other types is less than 50 MB. Recommended resolution for the image: 800 × 800. Recommended resolution for the cover: 400 × 400.