Message template parameters - - Alibaba Cloud Documentation Center

This topic describes the parameters required for calling the SendChatappMessage API to send messages.

WhatsApp-related parameters

The following sections describe the Content field for different MessageType values when ChannelType is whatsapp and Type is message.

Location

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

Contacts

Note

The Contacts parameter must be passed as an array.

Parameter	Required	Description
addresses	No	Address information of the contact. A complete contact address object contains the following fields: street (string): Optional. Street number and name. city (string): Optional. City name. state (string): Optional. State abbreviation. zip (string): Optional. ZIP code. country (string): Optional. Country/region name. country_code (string): Optional. Two-letter country/region code. type (string): Optional. Enumerated values: HOME, WORK.
birthday	No	Birthday of the contact, in YYYY-MM-DD format.
emails	No	Email addresses of the contact. A complete contact email object contains the following fields: email (string): Optional. Email address. type (string): Optional. Enumerated values: HOME, WORK.
name	Yes	Name of the contact. A complete contact name object contains the following fields: formatted_name (string): Required. Usually the full name. first_name (string): Optional. First name. last_name (string): Optional. Last name. middle_name (string): Optional. Middle name. suffix (string): Optional. Name suffix. prefix (string): Optional. Name prefix. Note The formatted_name parameter must include at least one optional parameter.
org	No	Organization information of the contact. A complete contact organization object contains the following fields: company (string): Optional. Company name of the contact. department (string): Optional. Department name of the contact. title (string): Optional. Job title of the contact.
phones	No	Phone number of the contact. A complete contact phone number object contains the following fields: phone (string): Optional. Automatically populated with the value of wa_id as a formatted phone number. type (string): Optional. Enumerated values: CELL, MAIN, IPHONE, HOME, WORK. wa_id (string): Optional. WhatsApp ID.
urls	No	Personal homepage of the contact. A complete URL object contains the following fields: url (string): Optional. URL. type (string): Optional. Enumerated values: HOME, WORK.

Media

Parameter	Required	Description
link	Yes	The protocol and URL of the media to be sent. Only HTTP or HTTPS URLs are supported. This parameter is not used when MessageType is set to text. This parameter is required when MessageType is set to audio, document, image, or video and you are not using a link.
caption	No	Describes the specified document, image, or video media. Not used with audio media. Maximum length: 1024 characters.
filename	No	Describes the filename for a specific document. Used only with document media. Note The extension of the filename will indicate the document's format in WhatsApp.

Text

Parameter

Required

Description

text

Yes

The text content of the message, which can include formatted URLs.

previewUrl

Preview URL. String type. Default value: false. Valid values:

true: Preview is enabled.
false: Preview is disabled.

Interactive

Parameter	Required	Description
type	Yes	The type of interactive message you want to send. Valid values: list: For list messages. button: For reply buttons. product: For single product messages. product_list: For multi-product messages. catalog_message: For catalog messages. cta_url: For messages with a Call-to-Action (CTA) URL button. flow: For WhatsApp flow messages. address_message: For address messages. location_request_message: For location request messages.
header	-	The header content displayed at the top of the message. The header cannot be set if type is product. Note Required when type is product_list; optional for other types. The header object contains the following fields: document (object): Required when MessageType is document. Pass the media object for the document. image (object): Required when MessageType is image. Pass the media object for the image. video (object): Required when MessageType is video. Pass the media object for the video. text (string): Required when MessageType is text. The header text supports emojis but not markdown. Maximum length of 60 characters. type (string): Required. The type supports the following values: text: For list messages, reply buttons, and multiple product messages. video: For reply buttons. image: For reply buttons. document: For reply buttons.
body	-	An object with the message body. Note Optional when type is product; required for other types. The body object contains the following field: text (string), which is required if you want to display it. The message body supports emojis and markdown. Maximum length of 1024 characters.
footer	No	An object for the message footer. The footer object contains the following field: text (string), which is required if you want to display it. The footer content supports emojis and markdown. Maximum length of 60 characters.
action	Yes	An action object containing the action you want the user to perform after reading the message.

Interactive > Action

Message type	Parameter		Description
List message	button		The button content, which is required when the type parameter is set to list. Button content cannot be an empty string and must be unique within the message. It supports emojis but not markdown. Maximum length of 20 characters.
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 option for reply button messages is reply. title: The button title. Cannot be an empty string and must be unique within the message. Supports emojis but not markdown. Maximum length of 20 characters. ID: A unique identifier for the button. This ID is returned in the webhook when the user clicks the button. Maximum length of 256 characters. 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. A unique identifier for the Facebook catalog linked to your WhatsApp Business Account. This ID can be retrieved from Commerce Manager.
	product_retailer_id		This parameter is required when the type parameter is set to product or product_list. A unique identifier for the product in the catalog. Maximum length of 100 characters for single or multi-product messages.
Message with a CTA button	name		String. Required. Set name to cta_url.
	parameters		Object.
		display_text	String. Required. The button text.
		url	String. Required. The URL to load in the device's default web browser when the user taps the button.
WhatsApp flow message	name		String. Required. Set the parameter to flow.
	parameters		Object.
		mode	String. Required. The current state of the flow. Valid values: draft and published. Default value: published.
		flow_message_version	String. Required. Set the parameter to 3.
		flow_token	String. Required. A token generated by the business to be used as an identifier.
		flow_id	String. Required. The unique ID of the flow, provided by WhatsApp.
		flow_cta	String. Required. The text on the CTA button, for example, "Sign Up". Maximum length: 20 characters (no emojis).
		flow_action	String. Optional. Valid values: navigate and data_exchange. Note Use navigate to pre-define the first screen as part of the message. For advanced use cases where the first screen is provided by an endpoint, use data_exchange. Default value: navigate.
		flow_action_payload	String. Optional. Required only when flow_action is navigate. This object can contain the following parameters: screen: String. Required. The ID of the first screen of the flow. data: Object. Optional. Input data for the first screen of the flow. If provided, it must be a non-empty object.
Address message	name		String. Required. Set the parameter to address_message.
	parameters		Object.
		country	String. Required. Two-letter country/region code. For example: SG, IN.
		values	Array. Required. Contains the following parameters: name: User's name. phone_number: User's phone number.
		validation_errors	String. Optional. Throws an error in the address field, which will then prevent the user from submitting the address in WhatsApp.
		saved_addresses	Saved addresses associated with the user. Contains the following parameters: id: String. Required. The ID of the saved address. value: Array. Required. name: Name. Text. Supported in India and Singapore. phone_number: Phone number. Supported in India and Singapore. Must be a valid phone number. in_pin_code: PIN code. Text. Max 6 characters. For India only. sg_post_code: Postal code. Number. Max 6 characters. For Singapore only. house_number: Apartment or house number. Text. For India only. floor_number: Floor number. Text. For India only. tower_number: Tower number. Text. For India only. building_name: Building or apartment name. Text. For India only. address: Address. Text. Supported in India and Singapore. landmark_area: Landmark or area. Text. For India only. unit_number: Unit number. Text. For Singapore only. city: City. Text. Supported in India and Singapore. state: State/Province/Autonomous Region/Municipality. Text. For India only.
Location request message Note For more information about location request messages, see Location Request Messages.	name		String. Required. Set the parameter to send_location.

Interactive > Section

Parameter	Description
title	Required if the message has multiple sections. The title of the section. Maximum length of 24 characters.
rows	Required for list messages. A list of row objects. A total of 10 rows are allowed across all sections. Each row object contains the following fields: title (string): Required. Maximum length of 24 characters. ID (string): Required. Maximum length of 200 characters. description (string): Optional. Maximum length of 72 characters.
product_items	Required for multi-product messages. A list of product objects. Each section must have at least one product, with a maximum of 30 products across all sections. Each product object contains the following field: product_retailer_id, which is the unique identifier for the product in the catalog.

reaction

Parameter	Required	Description
messageId	Yes	Message ID. String type. Example: 2022129384888829****.
emoji	Yes	Emoji. String type.

typing_indicator

ContextMessageld cannot be empty.

pin (For WhatsApp group messages only)

Parameter	Required	Description
type	Yes	The action to perform (pin or unpin). Valid values: pin unpin
expirationDays	No	The pin duration in days. Required when type=pin. Valid values: 1 to 30.
messageId	Yes	The message ID.

Viber-related parameters

The following sections describe the Content field for different MessageType values when ChannelType is viber and Type is message.

When MessageType is text

Parameter	Required	Description
text	Yes	Text content.

When MessageType is image

Parameter	Required	Description
link	Yes	The URL of the image.

When MessageType is 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.

When MessageType is document

Parameter	Required	Description
link	Yes	The URL of the file.
fileName	Yes	File name. Maximum length of 25 characters.
fileType	Yes	The file type.

When MessageType is text_button

Parameter	Required	Description
text	Yes	Text content.
caption	Yes	Button text.
action	Yes	The URL that the button opens.

When MessageType is text_image_button

Parameter	Required	Description
text	Yes	Text content.
link	Yes	The URL of the image.
caption	Yes	Button text.
action	Yes	The URL that the button opens.

When MessageType is text_video

Parameter	Required	Description
text	Yes	Text content.
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 video. Unit: seconds.

When MessageType is text_video_button

Parameter	Required	Description
text	Yes	Text content.
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 video. Unit: seconds.
caption	Yes	Button text.

Important

For buttons with video, clicking the button will open the video in a browser for playback.

In addition to opening web pages, buttons can also use URL schemes to perform the following actions:

Make a phone call: viber://keypad?number=%2B
Open a new conversation: viber://chat?service=
Open the QR code scanner: viber://more/qr

Supported media types and size limits

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

Media HTTP cache

If you use a link to media assets on your own server, add the headers below in your server response to instruct WhatsApp to cache the asset for reuse in future messages. If you do not add any of the headers below, the asset will not be cached.

Cache-Control

Indicates how to handle asset caching. The following directives are supported:

max-age=n: Indicates the number of seconds (n) to cache the asset.
The cached asset is reused in subsequent messages until this time limit is exceeded. WhatsApp will request the asset again if needed.
Example: Cache-Control: max-age=604800.
no-cache: Indicates that the system can cache the asset but should update it if the Last-Modified header value differs from the previous response.
Requires the Last-Modified header to be provided.
Example: Cache-Control: no-cache.
no-store: Indicates that the asset are not cached.
Example: Cache-Control: no-store.
private: Indicates that the asset is personalized for the recipient and are not cached.

Last-Modified

Indicates the time the asset was last modified. Used in conjunction with Cache-Control: no-cache.

If the Last-Modified value is different from the previous response and the current response includes Cache-Control: no-cache, WhatsApp will update the cached asset with the one from the current response.

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

ETag

The ETag header is a unique string that identifies a specific version of an asset.

Example: ETag: "33a64df5". WhatsApp will ignore the ETag header unless the response does not include both Cache-Control and Last-Modified headers. In that case, WhatsApp will cache the asset based on its own internal logic.

Viber

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, XLTX	200 MB
Video	MP4, M4V, MOV, 3GP	200 MB
Image	JPG, JPEG, PNG, GIF, WebP	GIF: 20 MB. Other formats: up to 50 MB is recommended. Recommended resolution: 800 x 800. Recommended cover resolution: 400 x 400.