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.

{
    "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

{
    "from": "+12090000000",
    "to": "+12090001111",
    "whatsapp_message": {
        "type": "whatsAppTemplate",
        "value": "{\"name\":\"marketing_quick_reply_button\",\"language_code\":\"en\"}"
    }
}

Value structure

{
    "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

{
    "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

{
    "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

{
    "from": "+12090000000",
    "to": "+12090001111",
    "whatsapp_message": {
        "type": "whatsAppTemplate",
        "value": "{\"name\":\"marketing_static_url_button\",\"language_code\":\"en\"}"
    }
}

Value structure

{
    "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

{
    "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

{
    "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

{
    "from": "+12090000000",
    "to": "+12090001111",
    "whatsapp_message": {
        "type": "whatsAppTemplate",
        "value": "{\"name\":\"marketing_phone_button\",\"language_code\":\"en\"}"
    }
}

Value structure

{
    "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

{
    "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

{
    "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

{
    "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

{
    "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

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.
Parameter order - For positional parameters, the order in the parameters array must exactly match the order of placeholders in the template.
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.