Authentication template with Copy Code button

In this case, you create an authentication template with a Copy Code button:

Uses the fixed text <VERIFICATION_CODE> is your verification code. by setting language to en_US. See also Supported Languages for all codes.
Adds security disclaimer to the end of the text.
Contains expiration warning in the footer.

Code sample

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "otp_copy_code",
  "language": "en_US",
  "category": "AUTHENTICATION",
  "messageSendTtlSeconds": 600,
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 5
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "COPY_CODE",
          "text": "Copy Code"
        }
      ]
    }
  ]
}'

Response body sample

Returns the actual template body text and buttons. Automatically approved the template (status is APPROVED).

{
  "wabaId": "{{WABA-ID}}",
  "name": "otp_copy_code",
  "language": "en_US",
  "category": "AUTHENTICATION",
  "messageSendTtlSeconds": 600,
  "status": "APPROVED",
  "components": [
    {
      "type": "BODY",
      "text": "*{{1}}* is your verification code. For your security, do not share this code.",
      "add_security_recommendation": true,
      "example": {
        "body_text": [
          [
            "123456"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "This code expires in 5 minutes.",
      "code_expiration_minutes": 5
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "URL",
          "otp_type": "COPY_CODE",
          "text": "Copy Code",
          "url": "https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code=otp{{1}}",
          "example": [
            "https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code=otp123456"
          ]
        }
      ]
    }
  ]
}

Note

Authentication templates with OTP buttons consist of:
- Fixed preset text: <VERIFICATION_CODE> is your verification code.
- An optional security disclaimer: For your security, do not share this code.
- An optional expiration warning: This code expires in<NUM_MINUTES> minutes.
- Either a copy code button, a one-tap autofill button, or no button at all if using zero-tap.
Copy Code text is optional. If omitted, the text will default to a pre-set value localized to the template's language. For example, Copy Code for English (US).
URLs, media, and emojis are not supported. Because authentication templates with OTP buttons only consist of preset text and buttons, their risk of being paused is significantly minimized.
If we are unable to deliver a message for an amount of time that exceeds its time-to-live, we will stop retrying and drop the message. By default, messages that use an authentication template have a default TTL of 10 minutes, and messages that use a utility or marketing template have a default TTL of 30 days.
Set its value between 30 and 900 seconds (i.e., 30 seconds to 15 minutes) for authentication templates, or 30 and 43200 seconds (i.e., 30 seconds to 12 hours) for utility templates, or 43200 and 2592000 seconds (i.e., 12 hours to 30 days) for marketing templates. Alternatively, you can set this value to -1, which will set a custom TTL of 30 days for either type of template.
See also sending an authentication template message.

Authentication template with One-Tap button

In this case, you create an authentication template with a One-tap button:

Uses the fixed text <VERIFICATION_CODE> is your verification code. by setting language to en_US.
Adds security disclaimer to the end of the text.
Contains expiration warning in the footer.
Contains Copy code button text and One-tap button text.
Specifies your Android app's package name and signature hash.

Code sample

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "otp_one_tap",
  "language": "en_US",
  "category": "AUTHENTICATION",
  "messageSendTtlSeconds": 600,
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 5
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "ONE_TAP",
          "text": "Copy Code",
          "autofill_text": "Autofill",
          "supported_apps": [
            {
              "package_name": "com.example.myapplication",
              "signature_hash": "K8aFAINcGX7"
            }
          ]
        }
      ]
    }
  ]
}'

Response body sample

Returns the actual template body text and buttons. Automatically approved the template (status is APPROVED).

{
  "wabaId": "{{WABA-ID}}",
  "name": "otp_one_tap",
  "language": "en_US",
  "category": "AUTHENTICATION",
  "messageSendTtlSeconds": 600,
  "status": "APPROVED",
  "components": [
    {
      "type": "BODY",
      "text": "*{{1}}* is your verification code. For your security, do not share this code.",
      "add_security_recommendation": true,
      "example": {
        "body_text": [
          [
            "123456"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "This code expires in 5 minutes.",
      "code_expiration_minutes": 5
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "URL",
          "otp_type": "ONE_TAP",
          "text": "Copy Code",
          "autofill_text": "Autofill",
          "supported_apps": [
            {
              "package_name": "com.example.myapplication",
              "signature_hash": "K8aFAINcGX7"
            }
          ],
          "url": "https://www.whatsapp.com/otp/code/?otp_type=ONE_TAP&cta_display_name=Autofill&package_name=com.example.myapplication&signature_hash=K8aFAINcGX7&code=otp{{1}}",
          "example": [
            "https://www.whatsapp.com/otp/code/?otp_type=ONE_TAP&cta_display_name=Autofill&package_name=com.example.myapplication&signature_hash=K8aFAINcGX7&code=otp123456"
          ]
        }
      ]
    }
  ]
}

Note

One-tap buttons are the preferred solution as they offer the best user experience. However, one-tap buttons are currently only supported on Android, and require changes to your app's code in order to perform a "handshake", and your app's signing key hash. See App Signing Key Hash and Handshake.
If we are unable to validate your handshake, the authentication template message will display a copy code button with this text instead.
Copy Code text and Autofill text are optional. If omitted, the text will default to a pre-set value localized to the template's language.
See also sending an authentication template message.

Zero-Tap Authentication template

Zero-tap authentication templates allow your users to receive one-time passwords or codes via WhatsApp without having to leave your app.

When a user in your app requests a password or code and you deliver it using a zero-tap authentication template, the WhatsApp client simply broadcasts the included password or code and your app can capture it immediately with a broadcast receiver.

From your user's perspective, they request a password or code in your app and it appears in your app automatically. If your app user happens to check the message in the WhatsApp client, they will only see a message displaying the default fixed text: <code> is your verification code.

Code sample

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "otp_zero_tap",
  "language": "en_US",
  "category": "AUTHENTICATION",
  "messageSendTtlSeconds": 600,
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 5
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "ZERO_TAP",
          "text": "Copy Code",
          "autofill_text": "Autofill",
          "supported_apps": [
            {
              "package_name": "com.example.myapplication",
              "signature_hash": "K8aFAINcGX7"
            }
          ],
          "zero_tap_terms_accepted": true
        }
      ]
    }
  ]
}'

Response body sample

Returns the actual template body text and buttons. Automatically approved the template (status is APPROVED).

{
  "wabaId": "{{WABA-ID}}",
  "name": "otp_zero_tap",
  "language": "en_US",
  "category": "AUTHENTICATION",
  "messageSendTtlSeconds": 600,
  "status": "APPROVED",
  "components": [
    {
      "type": "BODY",
      "text": "*{{1}}* is your verification code. For your security, do not share this code.",
      "add_security_recommendation": true,
      "example": {
        "body_text": [
          [
            "123456"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "This code expires in 5 minutes.",
      "code_expiration_minutes": 5
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "URL",
          "otp_type": "ZERO_TAP",
          "text": "Copy Code",
          "autofill_text": "Autofill",
          "supported_apps": [
            {
              "package_name": "com.example.myapplication",
              "signature_hash": "K8aFAINcGX7"
            }
          ],
          "zero_tap_terms_accepted": true,
          "url": "https://www.whatsapp.com/otp/code/?otp_type=ZERO_TAP&cta_display_name=Autofill&package_name=com.example.myapplication&signature_hash=K8aFAINcGX7&code=otp{{1}}",
          "example": [
            "https://www.whatsapp.com/otp/code/?otp_type=ZERO_TAP&cta_display_name=Autofill&package_name=com.example.myapplication&signature_hash=K8aFAINcGX7&code=otp123456"
          ]
        }
      ]
    }
  ]
}

Note

Zero-tap is only supported on Android. If you send a zero-tap authentication template to a WhatsApp user who is using a non-Android device, the WhatsApp client will display a copy code button instead. See App Signing Key Hash and Handshake.
Copy Code text and Autofill text are optional. If omitted, the text will default to a pre-set value localized to the template's language.
See also sending an authentication template message.

Utility template with variables in body

In this case, you create a template for order confirmation notifications:

Contains text with 3 variables in the body.
No header.
No footer.
No buttons.

Code sample

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "order_confirmation",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    {
      "type": "BODY",
      "text": "Your order {{1}} for a total of {{2}} is confirmed. The expected delivery is {{3}}.",
      "example": {
        "body_text": [
          [
            "ORDER-5555",
            "99 USD",
            "February 25, 2023"
          ]
        ]
      }
    }
  ]
}'

Note

A template consists of HEADER, BODY, FOOTER, and BUTTONS components. The BODY component is required, while the others are optional.
The template variables are placeholders (numbers wrapped with curly braces) used to send messages, such as {{1}}. You can replace these placeholders with actual values when you send messages. For an example of how to use variables when sending template messages, see also WhatsApp Messaging Examples.
Variable parameters must be sequential in each template component. For example, it’s invalid that {{1}}, {{2}}, {{4}}, {{5}} are defined but {{3}} does not exist.
If we are unable to deliver a message for an amount of time that exceeds its time-to-live, we will stop retrying and drop the message. By default, messages that use an authentication template have a default TTL of 10 minutes, and messages that use a utility or marketing template have a default TTL of 30 days.
Set its value between 30 and 900 seconds (i.e., 30 seconds to 15 minutes) for authentication templates, or 30 and 43200 seconds (i.e., 30 seconds to 12 hours) for utility templates, or 43200 and 2592000 seconds (i.e., 12 hours to 30 days) for marketing templates. Alternatively, you can set this value to -1, which will set a custom TTL of 30 days for either type of template.
See also Common Rejection Reasons.
See also sending a template message with variables.

Marketing template with image and Quick Reply buttons

In this case, you create a template for a specific campaign:

Contains an image in the header.
Contains text with 1 variable in the body.
Contains text in the footer.
Contains 2 Quick Reply buttons.

Code sample

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "marketing_friday",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": {
        "header_url": [
          "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Hi {{1}}, The Black Friday is coming!",
      "example": {
        "body_text": [
          [
            "Joe"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "FOOTER-TEXT"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Learn more"
        },
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe"
        }
      ]
    }
  ]
}'

Note

The HEADER component format can be one of TEXT, IMAGE, VIDEO, or DOCUMENT. For TEXT, you need to provide a sample text in example.header_text. For the other media formats, that is IMAGE, VIDEO, or DOCUMENT, you need to provide a sample URL in example.header_url.
The FOOTER component can only be text, and variables are not supported.
For image media in the header, the example.header_url of the messaging request must end with one of .jpg, .jpeg, or .png. Image size limit is 5MB.
For video media in the header, the example.header_url of the request payload must end with .mp4. Video size limit is 16MB.
For document media in the header, the example.header_url of the request payload must end with .pdf. Document size limit is 100MB.
Buttons are optional interactive components that perform specific actions when tapped. Templates can have a mixture of up to 10 button components in total, although there are limits to individual buttons of the same type as well as combination limits.
Quick reply buttons are custom text-only buttons that immediately message you with the specified text string when tapped by the app user. Templates are limited to 10 quick reply buttons. If using quick reply buttons with other buttons, buttons must be organized into two groups: quick reply buttons and non-quick reply buttons. If grouped incorrectly, the API will return an error indicating an invalid combination.

Examples of valid groupings:
- Quick Reply, Quick Reply
- Quick Reply, Quick Reply, URL, Phone
- URL, Phone, Quick Reply, Quick Reply
Examples of invalid groupings:
- Quick Reply, URL, Quick Reply
- URL, Quick Reply, URL
If a template has more than three buttons, two buttons will appear in the delivered message and the remaining buttons will be replaced with a See all options button. Tapping the See all options button reveals the remaining buttons.
See also sending a template message with image and quick reply buttons.

Marketing template with video and Call To Action buttons

In this case, you create a template for a specific campaign:

Contains a video in the header.
Contains text with 1 variable in the body.
Contains text in the footer.
Contains 2 Call To Action buttons: 1 PHONE_NUMBER button, and 1 URL button. The URL button can have at most 1 variable at the end of the URL.

Code sample

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "marketing_friday_more",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "VIDEO",
      "example": {
        "header_url": [
          "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.mp4"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Click the URL bellow to see more about {{1}} campaign.",
      "example": {
        "body_text": [
          [
            "The Friday"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "FOOTER-TEXT"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "URL",
          "text": "Visit website",
          "url": "https://www.youtube.com/watch?v={{1}}",
          "example": [
            "https://www.youtube.com/watch?v=zvI4cVGWJhM"
          ]
        },
        {
          "type": "PHONE_NUMBER",
          "text": "Call us",
          "phone_number": "+447901614024"
        }
      ]
    }
  ]
}'

Note

Phone number buttons call the specified business phone number when tapped by the app user. Templates are limited to one phone number button.
URL buttons load the specified URL in the device's default web browser when tapped by the app user. Templates are limited to two URL buttons.
When you set a dynamicURL button, which contains a variable at the end of the URL, you should provide a full URL in example other than a sample value for the variable.
See also sending a template message with video and call to action buttons.

Coupon template

Coupon code templates are marketing templates that display a single copy code button. When tapped, the code is copied to the customer's clipboard.

In this case, you create a coupon code template for a specific campaign:

Contains text with 2 variables in the body.
Contains a copy code button to allow the customer to copy the coupon code.

Code sample

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "marketing_coupon",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "BODY",
      "text": "🎉Hi {{1}}, Welcome to our shop!\n🥰I'\''ve been waiting for so long. \n\nThis is your coupon code:\n*{{2}}*\n\nNote that this coupon will expire after 24 hours. \nPlease copy the code via the copy button below. ↓",
      "example": {
        "body_text": [
          [
            "Mike",
            "12312393"
          ]
        ]
      }
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "COPY_CODE",
          "example": [
            "12312393"
          ]
        }
      ]
    }
  ]
}'

Note

Copy code buttons copy a text string (defined when the template is sent in a template message) to the device's clipboard when tapped by the app user. Templates are limited to one copy code button.
Button text is a pre-set value and cannot be customized.
See also sending a coupon template message.

Location template

You can add a location header in templates categorized as UTILITY or MARKETING. Location headers appear as generic maps at the top of the template and are useful for order tracking, delivery updates, ride hailing pickup/dropoff, locating physical stores, etc.

Code sample

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "location_header",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    {
      "type": "HEADER",
      "format": "LOCATION"
    },
    {
      "type": "BODY",
      "text": "Click and see our location"
    }
  ]
}'

Note

Provider the longitude and latitude of location when sending this template. See also location template message.

Limited-Time Offer template

In this case, you create a limited-time offer (LTO) template for a specific campaign:

Contains an image in the header.
Displays expiration dates and running countdown timers for the offer code.
Contains text with 2 variables in the body.
Contains 2 buttons: 1 COPY_CODE button, and 1 URL button.

Code sample

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "limited_time_offer_caribbean_pkg_2023",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": {
        "header_url": [
          "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
        ]
      }
    },
    {
      "type": "LIMITED_TIME_OFFER",
      "limited_time_offer": {
        "text": "Expiring offer!",
        "has_expiration": true
      }
    },
    {
      "type": "BODY",
      "text": "Good news, {{1}}! Use code {{2}} to get 25% off all Caribbean Destination packages!",
      "example": {
        "body_text": [
          [
            "Pablo",
            "CARIBE25"
          ]
        ]
      }
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "COPY_CODE",
          "example": [
            "CARIBE25"
          ]
        },
        {
          "type": "URL",
          "text": "Book now!",
          "url": "https://awesomedestinations.com/offers?code={{1}}",
          "example": [
            "https://awesomedestinations.com/offers?ref=n3mtql"
          ]
        }
      ]
    }
  ]
}'

Note

Only templates categorized as MARKETING are supported.
Footer components are not supported.
Users who view a limited-time offer template message using that WhatsApp web app or desktop app will not see the offer, but will instead see a message indicating that they have received a message but that it's not supported in the client they are using.
See also sending a limited-time offer template message.

Carousel template

In this case, you create a carousel template for a specific campaign:

Contains text with 2 variables in the body.
Contains 2 carousel cards in a horizontally scrollable view.

Code sample

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "summer_carousel_promo_2023",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "BODY",
      "text": "Summer is here, and we have the freshest produce around! Use code {{1}} to get {{2}} off your next order.",
      "example": {
        "body_text": [
          [
            "15OFF",
            "15%"
          ]
        ]
      }
    },
    {
      "type": "CAROUSEL",
      "cards": [
        {
          "components": [
            {
              "type": "HEADER",
              "format": "IMAGE",
              "example": {
                "header_url": [
                  "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
                ]
              }
            },
            {
              "type": "BODY",
              "text": "Rare lemons for unique cocktails. Use code {{1}} to get {{2}} off all produce.",
              "example": {
                "body_text": [
                  [
                    "15OFF",
                    "15%"
                  ]
                ]
              }
            },
            {
              "type": "BUTTONS",
              "buttons": [
                {
                  "type": "QUICK_REPLY",
                  "text": "Send more like this"
                },
                {
                  "type": "URL",
                  "text": "Buy now",
                  "url": "https://www.luckyshrub.com/shop?promo={{1}}",
                  "example": [
                    "https://www.luckyshrub.com/shop?promo=summer_lemons_2023"
                  ]
                }
              ]
            }
          ]
        },
        {
          "components": [
            {
              "type": "HEADER",
              "format": "IMAGE",
              "example": {
                "header_url": [
                  "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
                ]
              }
            },
            {
              "type": "BODY",
              "text": "Exotic fruit for unique cocktails! Use code {{1}} to get {{2}} off all exotic produce.",
              "example": {
                "body_text": [
                  [
                    "20OFFEXOTIC",
                    "20%"
                  ]
                ]
              }
            },
            {
              "type": "BUTTONS",
              "buttons": [
                {
                  "type": "QUICK_REPLY",
                  "text": "Send more like this"
                },
                {
                  "type": "URL",
                  "text": "Buy now",
                  "url": "https://www.luckyshrub.com/shop?promo={{1}}",
                  "example": [
                    "https://www.luckyshrub.com/shop?promo=exotic_produce_2023"
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}'

Note

A message bubble is required. Message bubbles are text-only and support variables. There is no maximum character limit on variables, but it counts against the message bubble limit of 1024 characters.
Card body text supports variables. Maximum 160 characters.
Carousel templates support up to 10 carousel cards. Cards must have a media header (image or video), body text, and at least one button. Supports 2 buttons. Buttons can be the same or a mix of quick reply buttons, phone number buttons, or URL buttons.
The media header format and buttons must be the same across all cards that make up a carousel template.
Media assets will be cropped to a wide ratio based on the customer's device.
See also sending a carousel template message.

Catalog template

Catalog templates are marketing templates that allow you to showcase your product catalog entirely within WhatsApp. Catalog templates display a product thumbnail header image of your choice and custom body text, along with a fixed text header and fixed text sub-header.

When a customer taps the View catalog button in a catalog template message, your product catalog appears within WhatsApp.

Code sample

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "intro_catalog_offer",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "BODY",
      "text": "Now shop for your favourite products right here on WhatsApp! Get Rs {{1}} off on all orders above {{2}}Rs! Valid for your first {{3}} orders placed on WhatsApp!",
      "example": {
        "body_text": [
          [
            "100",
            "400",
            "3"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Best grocery deals on WhatsApp!"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "CATALOG",
          "text": "View catalog"
        }
      ]
    }
  ]
}'

Note

You must have inventory uploaded to Meta in an ecommerce catalog connected to your WhatsApp Business Account.
Enable the shopping cart and the product catalog on a per-business phone number basis. By default, the shopping cart is enabled and the storefront icon is hidden for all business phone numbers associated with a WhatsApp Business Account. Use the Update commerce settings endpoint to enable or disable these features.
Text for CATALOG buttons cannot be modified and must always be View catalog.
See also sending a catalog template message.

Multi-Product Message template

MPM templates can be used to open marketing conversations. They allow you to showcase up to 30 products from your ecommerce catalog, organized in up to 10 sections, in a single message.

Customers can browse products and sections within the message, view details for each product, add and remove products from their cart, and submit their cart to place an order. Orders are then sent to you via a webhook.

Code sample

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "abandoned_cart",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Forget something, {{1}}?",
      "example": {
        "header_text": [
          "Pablo"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Looks like you left these items in your cart, still interested? Use code {{1}} to get 10% off!",
      "example": {
        "body_text": [
          [
            "10OFF"
          ]
        ]
      }
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "MPM",
          "text": "View items"
        }
      ]
    }
  ]
}'

Note

You must have inventory uploaded to Meta in an ecommerce catalog connected to your WhatsApp Business Account.
Enable the shopping cart and the product catalog on a per-business phone number basis. By default, the shopping cart is enabled and the storefront icon is hidden for all business phone numbers associated with a WhatsApp Business Account. Use the Update commerce settings endpoint to enable or disable these features.
The components value must be an array of objects that describe each component that makes up the template. MPM templates must have the following components:
- a single header component
- a single body component
- a single footer component (optional)
- a single MPM button component
Text for MPM buttons cannot be modified and must always be View items.
See also sending an MPM template message.

Flow template

WhatsApp Flows is a way to build structured interactions for business messaging. With Flows, businesses can define, configure, and customize messages with rich interactions that give customers more structure in the way they communicate.

You can use Flows to generate leads, recommend products, get new sales leads, or anything else where structured communication is more natural or comfortable for your customers.

Code sample

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "example_template_name",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "BODY",
      "text": "This is a flows as template demo"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "FLOW",
          "text": "Open flow!",
          "flow_id": "{{FLOW-ID}}",
          "navigate_screen": "{{SCREEN-ID}}",
          "flow_action": "navigate"
        }
      ]
    }
  ]
}'

Note

To use WhatsApp Flows, you will need to verify your business, complete the display name review process and maintain a high message quality.
You will need a Flow ID to create the template. To create a new WhatsApp Flow using flows builder interface, refer to this video.
To send a Flow template message, see Flow template message.

Order Details template

Order details message template is one of the interactive message template that extends the call-to-action button to support sending order details as template and provides richer experience compare to the standard message templates.

Order details template is categorized as UTILITY template and apart from name and language of choice, it has general template components such as HEADER, BODY, FOOTER and a fixed BUTTON with ORDER_DETAILS type and Review and Pay text.

Code sample

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "order_details_example",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Header text"
    },
    {
      "type": "BODY",
      "text": "Template Body text"
    },
    {
      "type": "FOOTER",
      "text": "Footer text"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "ORDER_DETAILS",
          "text": "Review and Pay"
        }
      ]
    }
  ]
}'

Note

Must contain one button where type is ORDER_DETAILS and text is Review and Pay.
See also sending an Order Details template message.

Order Status template

Order status template is one of the interactive message templates that extends the call-to-action button to support updating order status through a template. It allows the businesses to update the order status outside of the customer session window in use cases such as charging the card for past order and updating about a shipment on order placed in the past.

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "order_status_example",
  "language": "en_US",
  "category": "UTILITY",
  "subCategory": "ORDER_STATUS",
  "components": [
    {
      "type": "BODY",
      "text": "Template Body text"
    },
    {
      "type": "FOOTER",
      "text": "Footer text"
    }
  ]
}'

Note

Must set category to UTILITY, and subCategory to ORDER_STATUS.
See also sending an Order Status template message.

Voice Call template

Supports a new button type VOICE_CALL which will trigger a WhatsApp call, when clicked by a WhatsApp consumer. In general, this button can be used anywhere the existing phone number button is possible.

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "voice_call_example",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    {
      "type": "BODY",
      "text": "You can call us on WhatsApp now for faster service!"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "VOICE_CALL",
          "text": "Call Now"
        },
        {
          "type": "URL",
          "text": "Contact Support",
          "url": "https://www.luckyshrub.com/support"
        }
      ]
    }
  ]
}'

Note

Once you create a template with WhatsApp voice call button, you can use the existing API with no changes because the voice_call button is not configurable at send-message time.
See also sending an Interactive Voice Call message

Checkout Button template

Checkout button templates are marketing templates that can showcase one or more products along with corresponding checkout buttons that WhatsApp users can use to make purchases without leaving the WhatsApp client. Checkout button templates can show a single product image or video header, along with message body text, message footer, a single checkout button, and up to 9 quick-reply buttons.

WhatsApp users who tap the button will see details of the order:

Users can proceed by selecting shipping information provided by you (if you know their information and supplied it in the send message payload)...

or can add their own shipping information:

Code sample

This example request creates a checkout button template with a single image message header, message body text that uses two variables, a footer, a single checkout button, and a quick-reply button.

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "item_back_in_stock_v1",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "header",
      "format": "image",
      "example": {
        "header_url": [
          "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
        ]
      }
    },
    {
      "type": "body",
      "text": "Hi {{1}}! The {{2}} is back in stock! Order now before it\'s gone!",
      "example": {
        "body_text": [
          [
            "Pablo",
            "Blue Elf Aloe"
          ]
        ]
      }
    },
    {
      "type": "footer",
      "text": "Tap \'Stop\' below to stop back-in-stock reminders."
    },
    {
      "type": "buttons",
      "buttons": [
        {
          "type": "order_details",
          "text": "Buy now"
        },
        {
          "type": "quick_reply",
          "text": "Stop"
        }
      ]
    }
  ]
}'

Calling permission request template

If you want to place a call to a WhatsApp user, your business must receive user permission first. When a WhatsApp user grants call permissions, they can be either temporary or permanent.

Business does not have control over this permission as it is only granted by the user and can only be revoked by the user, at any time. Permanent permission data will be stored until it is revoked.

You can obtain calling permission from a WhatsApp user in any of the following ways:

Send a call permission request to the user — Send a free-form or templated message requesting calling permission from the user. User has the option to choose between temporary or permanent.
Callback permission is provided by the WhatsApp user —The WhatsApp user automatically provides temporary call permissions by placing a call to the business. The callback setting must be enabled on the business phone number.
WhatsApp user provides call permission via Business Profile — The WhatsApp user provides call permissions to the business through their business profile.

Code sample

The following is an example of creating an calling permisson request template type

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "calling_permisson_request_example",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
   {
      "type": "HEADER",
      "text": "Support of Order No: {{1}}",
      "example": {
        "body_text": [
          [
            "ON-12345"
          ]
        ]
      }
    },    
    {
      "type": "BODY",
      "text": "We would like to call you to help support your query on Order No: {{1}} for the item {{2}}.",
      "example": {
        "body_text": [
          [
            "ON-12345",
            "Avocados"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Talk to you soon!"
    },
    {
      "type": "call_permission_request"
    }
  ]
}'

Android Deep link template

You can map an Android deep link to a marketing template URL button that, when tapped, loads a particular location or content within your app.

Code sample

The following is an example of creating a deep link template.

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "calling_permisson_request_example",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "BODY",
      "text": "hello"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "url",
          "text": "View Deals",
          "url": "https://www.luckyshrub.com/deals/summer/",
          "app_deep_link": {
            "meta_app_id": 2892949377516980,
            "android_deep_link": "luckyshrub://deals/summer/",
            "android_fallback_playstore_url": "https://www.luckyshrub.com/deals/summer/"
          }
        }
      ]
    }
  ]
}'

Marketing template with gif

In this case, you create a template for a specific campaign:

Contains a gif in the header.

Code sample

The following is an example of creating a gif template.

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "marketing_friday_more",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "GIF",
      "example": {
        "header_url": [
          "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.mp4"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "hello"
    }
  ]
}'