# Extended API schema - WhatsApp template Learn the `value` field's structure when type is set to `whatsAppTemplate` in the Zoom Contact Center's **Send a Message** API. The `value` field is a JSON string that contains the template name, language code, and optional components for dynamic content. ## Base structure The `value` field is a JSON string with this base structure. ```json { "name": "template_name", "language_code": "en" } ``` | Field | Type | Required | Description | | --------------- | ------ | -------- | ----------------------------------------------------------------------------------------- | | `name` | String | Yes | The name of the WhatsApp template as registered in your WhatsApp Business account. | | `language_code` | String | Yes | The language code for the whatsApp template, like "en", "es", or "zh_CN". | | `components` | Array | No | An array of component objects for dynamic content like headers, body parameters, buttons. | ## Component types Components provide dynamic content to template placeholders. There are three main component types. - **Header** - Replaces header placeholders in the template - **Body** - Replaces body placeholders in the template - **Button** - Provides button parameters like URL and coupon code ## Quick reply custom button For templates with quick reply buttons that don't require dynamic parameters, you only need to use the base structure. ### Example ```json { "from": "+12090000000", "to": "+12090001111", "whatsapp_message": { "type": "whatsAppTemplate", "value": "{\"name\":\"marketing_quick_reply_button\",\"language_code\":\"en\"}" } } ``` ### Value structure ```json { "name": "marketing_quick_reply_button", "language_code": "en" } ``` **Note:** Quick reply buttons don't require components, as they are static in the template. ## Copy offer code button For templates with copy code buttons, include a button component with `sub_type: "copy_code"` and coupon code parameters. ### Example ```json { "from": "+12090000000", "to": "+12090001111", "whatsapp_message": { "type": "whatsAppTemplate", "value": "{\"name\":\"marketing_copy_button\",\"language_code\":\"en\",\"components\":[{\"type\":\"button\",\"sub_type\":\"copy_code\",\"parameters\":[{\"type\":\"coupon_code\",\"coupon_code\":\"1234\"}],\"index\":0}]}" } } ``` ### Value structure ```json { "name": "marketing_copy_button", "language_code": "en", "components": [ { "type": "button", "sub_type": "copy_code", "parameters": [ { "type": "coupon_code", "coupon_code": "1234" } ], "index": 0 } ] } ``` ### Button component fields | Field | Type | Required | Description | | ------------ | ------- | -------- | -------------------------------------------------------------------------- | | `type` | String | Yes | Must be `button`. | | `sub_type` | String | Yes | Must be `copy_code` for copy code buttons. | | `parameters` | Array | Yes | Array containing one parameter object with the coupon code. | | `index` | Integer | Yes | The zero-based index of the button in the template, like `0`, `1`, or `2`. | ### Coupon code parameter | Field | Type | Required | Description | | ------------- | ------ | -------- | -------------------------------------- | | `type` | String | Yes | Must be `coupon_code`. | | `coupon_code` | String | Yes | The coupon code value to be displayed. | ## Visit website static URL button For templates with static URL buttons where the URL is defined in the template itself, no components are needed. ### Example ```json { "from": "+12090000000", "to": "+12090001111", "whatsapp_message": { "type": "whatsAppTemplate", "value": "{\"name\":\"marketing_static_url_button\",\"language_code\":\"en\"}" } } ``` ### Value structure ```json { "name": "marketing_static_url_button", "language_code": "en" } ``` **Note** Static URL buttons have the URL hardcoded in the template, so no dynamic components are required. ## Visit website dynamic URL button For templates with dynamic URL buttons, include a button component with `sub_type: "url"` and URL text parameters. ### Example ```json { "from": "+12090000000", "to": "+12090001111", "whatsapp_message": { "type": "whatsAppTemplate", "value": "{\"name\":\"marketing_dynamic_url_button\",\"language_code\":\"en\",\"components\":[{\"type\":\"button\",\"sub_type\":\"url\",\"parameters\":[{\"type\":\"text\",\"text\":\"index/admin#/admin-studios\"}],\"index\":0}]}" } } ``` ### Value structure ```json { "name": "marketing_dynamic_url_button", "language_code": "en", "components": [ { "type": "button", "sub_type": "url", "parameters": [ { "type": "text", "text": "index/admin#/admin-studios" } ], "index": 0 } ] } ``` ### Button component fields | Field | Type | Required | Description | | ------------ | ------- | -------- | -------------------------------------------------------------------------- | | `type` | String | Yes | Must be `button`. | | `sub_type` | String | Yes | Must be `url` for URL buttons. | | `parameters` | Array | Yes | Array containing one parameter object with the URL text. | | `index` | Integer | Yes | The zero-based index of the button in the template, like `0`, `1`, or `2`. | ### URL text parameter | Field | Type | Required | Description | | ------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `type` | String | Yes | Must be `text`. | | `text` | String | Yes | The dynamic parameter value that replaces the URL placeholder in the template. The template itself defines the base URL structure, and this `text` value fills in the variable part. | ## Call phone number button For templates with phone number buttons, only the base structure is needed - similar to quick reply buttons. ### Example ```json { "from": "+12090000000", "to": "+12090001111", "whatsapp_message": { "type": "whatsAppTemplate", "value": "{\"name\":\"marketing_phone_button\",\"language_code\":\"en\"}" } } ``` ### Value structure ```json { "name": "marketing_phone_button", "language_code": "en" } ``` **Note** Phone number buttons typically have the phone number defined in the template itself, so no dynamic components are required. ## Named parameters For templates that use named parameters, include header and body components with parameters that specify `parameter_name`. ### Example ```json { "from": "+12090000000", "to": "+12090001111", "whatsapp_message": { "type": "whatsAppTemplate", "value": "{\"name\":\"marketing_named_parameter_text_header\",\"language_code\":\"en\",\"components\":[{\"type\":\"header\",\"parameters\":[{\"type\":\"text\",\"parameter_name\":\"system\",\"text\":\"contact center\"}]},{\"type\":\"body\",\"parameters\":[{\"type\":\"text\",\"parameter_name\":\"consumer\",\"text\":\"dear consumer\"},{\"type\":\"text\",\"parameter_name\":\"agent\",\"text\":\"ZCC Agent\"},{\"type\":\"text\",\"parameter_name\":\"bot\",\"text\":\"ZVA bot\"}]}]}" } } ``` ### Value structure ```json { "name": "marketing_named_parameter_text_header", "language_code": "en", "components": [ { "type": "header", "parameters": [ { "type": "text", "parameter_name": "system", "text": "contact center" } ] }, { "type": "body", "parameters": [ { "type": "text", "parameter_name": "consumer", "text": "dear consumer" }, { "type": "text", "parameter_name": "agent", "text": "ZCC Agent" }, { "type": "text", "parameter_name": "bot", "text": "ZVA bot" } ] } ] } ``` ### Header and body component fields | Field | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------------------ | | `type` | String | Yes | Must be header or body. | | `parameters` | Array | Yes | Array of parameter objects for the named placeholders. | ### Named text parameter | Field | Type | Required | Description | | ---------------- | ------ | -------- | --------------------------------------------------------------------------------------------- | | `type` | String | Yes | Must be `text`. | | `parameter_name` | String | Yes | The name of the parameter placeholder in the template, like `system`, `consumer`, or `agent`. | | `text` | String | Yes | The text value to replace the named placeholder. | **Note** When using named parameters, the `parameter_name` must match the placeholder name defined in your WhatsApp template. ## Positional parameters For templates that use positional parameters which are replaced in order, include header or body components with parameters that don't specify `parameter_name`. ### Example ```json { "from": "+12090000000", "to": "+12090001111", "whatsapp_message": { "type": "whatsAppTemplate", "value": "{\"name\":\"custom_utility_dynamic\",\"language_code\":\"en\",\"components\":[{\"type\":\"header\",\"parameters\":[{\"type\":\"text\",\"text\":\"Dear Customer\"}]},{\"type\":\"body\",\"parameters\":[{\"type\":\"text\",\"text\":\"Transfer to Agent\"},{\"type\":\"text\",\"text\":\"Yes\"},{\"type\":\"text\",\"text\":\"No\"}]}]}" } } ``` ### Value structure ```json { "name": "custom_utility_dynamic", "language_code": "en", "components": [ { "type": "header", "parameters": [ { "type": "text", "text": "Dear Customer" } ] }, { "type": "body", "parameters": [ { "type": "text", "text": "Transfer to Agent" }, { "type": "text", "text": "Yes" }, { "type": "text", "text": "No" } ] } ] } ``` ### Header and body component fields | Field | Type | Required | Description | | ------------ | ------ | -------- | ----------------------------------------------------------- | | `type` | String | Yes | Must be `header` or `body`. | | `parameters` | Array | Yes | Array of parameter objects for the positional placeholders. | ### Positional text parameter | Field | Type | Required | Description | | ------ | ------ | -------- | --------------------------------------------------------------------------------------------------------- | | `type` | String | Yes | Must be `text`. | | `text` | String | Yes | The text value to replace the placeholder. Parameters are replaced in the order they appear in the array. | **Note** When using positional parameters, the order of parameters in the array must match the order of placeholders in the template. The first parameter replaces first placeholder, the second parameter replaces second placeholder, and so on. ## Important notes 1. **JSON string encoding** - The `value` field must be a JSON string, not a JSON object. When constructing the request, ensure that the JSON is properly escaped. 1. **Parameter order** - For positional parameters, the order in the `parameters` array must exactly match the order of placeholders in the template. 1. **Supported button types** - Currently, WhatsApp templates only support the button types listed in this document. Other button types, like Flow buttons, are not supported at this time.