The examples below apply to both the Send a WhatsApp message directly API and the Enqueue a WhatsApp message API.
Authentication template message with one-time password buttons
Authentication templates with one-time password buttons will be available starting May 1, 2023. Starting May 29, 2023, all newly created authentication templates must include a one-time password button.
This functionality will not be available to businesses based in India until later this year.
In this case, you send an authentication template message with a one-time password button:
- Contains a one-time password or verification code to be delivered to the customer.
- Contains a Copy code button or a One-tap button depending on the template you choose.
Note:
- For more examples about creating authentication templates, see Authentication template with Copy Code button, and Authentication template with One Tap button.
Code sample:
curl 'https://api.ycloud.com/v2/whatsapp/messages' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR-API-KEY' \
-d '{
"from": "BUSINESS-PHONE-NUMBER",
"to": "CUSTOMER-PHONE-NUMBER",
"type": "template",
"template": {
"name": "otp_one_tap",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "797011"
}
]
},
{
"type": "button",
"sub_type": "url",
"index": "0",
"parameters": [
{
"type": "text",
"text": "797011"
}
]
}
]
}
}'
Template message with variables
In this case, you send a template
message:
- Contains text with 3 variables in the body.
Note:
- Starting with template messages is an easy way to initiate a conversation. Once the customer replies to the business's template message, the business can begin sending any type of message to the customer.
- Make sure that the corresponding template has been approved.
- Set the right
type
for messages you send. In this case,type
is set totemplate
, and thecomponents
andparameters
of the messaging request must match the template.
Code sample:
curl --location --request POST 'https://api.ycloud.com/v2/whatsapp/messages' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"from": "BUSINESS-PHONE-NUMBER",
"to": "CUSTOMER-PHONE-NUMBER",
"type": "template",
"template": {
"name": "order_confirmation",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Lucy"
},
{
"type": "text",
"text": "$9.9"
},
{
"type": "text",
"text": "February 25"
}
]
}
]
}
}'
Template message with image and Quick Reply buttons
In this case, you send a template
message:
- Contains an image in the header.
- Contains text with 1 variable in the body.
- Contains text in the footer.
- Contains 2 Quick Reply buttons. The maximum number of Quick Reply buttons is 3.
Note:
caption
parameter (Used to describe the specifiedimage
,video
, ordocument
media.) is unsupported intemplate
orinteractive
messages.- For more information about header media limitations, see Supported Media Types.
Code sample:
curl --location --request POST 'https://api.ycloud.com/v2/whatsapp/messages' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"from": "BUSINESS-PHONE-NUMBER",
"to": "CUSTOMER-PHONE-NUMBER",
"type": "template",
"template": {
"name": "marketing_friday",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "image",
"image": {
"link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/sample/tmp/sample.jpg"
}
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Lucy"
}
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": 0,
"parameters": [
{
"type": "payload",
"payload": "more_about_marketing_friday"
}
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": 1,
"parameters": [
{
"type": "payload",
"payload": "unsubscribe_marketing_notifications"
}
]
}
]
}
}'
Template message with video and Call To Action buttons
In this case, you send a template
message:
- 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 1URL
button. TheURL
button can have at most 1 variable at the end of the URL.
Note:
caption
parameter (Used to describe the specifiedimage
,video
, ordocument
media.) is unsupported intemplate
orinteractive
messages.
Code sample:
curl --location --request POST 'https://api.ycloud.com/v2/whatsapp/messages' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"from": "BUSINESS-PHONE-NUMBER",
"to": "CUSTOMER-PHONE-NUMBER",
"type": "template",
"template": {
"name": "marketing_friday_more",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "video",
"video": {
"link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/sample/tmp/sample.mp4"
}
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "The Friday"
}
]
},
{
"type": "button",
"sub_type": "url",
"index": 0,
"parameters": [
{
"type": "text",
"text": "qptHJVK2EjU"
}
]
}
]
}
}'
Text message with mention
In this case, you send a text message:
- Contains only plain text.
- Contains a URL, and includes a preview box in text messages by setting
preview_url
totrue
. - Specifies a message (
context.message_id
) you reply to.
Note:
- You can only send template messages before the customer replies to your message.
- Use
context.message_id
to specify a message you reply to. Please be aware that it’s the original message ID on WhatsApp’s platform, starting withwamid.
, not the message ID on YCloud. The propertywamid
can be found in both YCloud’swhatsappMessage
object (when the status changes tosent
) andwhatsappInboundMessage
object. This feature also applies to other types of messages, excepttemplate
andsticker
messages.
Code sample:
curl --location --request POST 'https://api.ycloud.com/v2/whatsapp/messages' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"from": "BUSINESS-PHONE-NUMBER",
"to": "CUSTOMER-PHONE-NUMBER",
"type": "text",
"text": {
"body": "*Learn* how to format your messages: https://faq.whatsapp.com/539178204879377",
"preview_url": true
},
"context": {
"message_id": "wamid.BgNODYxN..."
}
}'
Image message
In this case, you send an image message:
- Contains an image URL.
- Contains a caption to describe the image.
Note:
- Supported image types:
image/jpeg
,image/png
. Images must be 8-bit, RGB or RGBA. - An embedded color profile is required. See also How to Embed the Profile, Embed a color profile in Adobe Photoshop.
- Image size limit: 5MB.
- See also Supported Media Types.
Code sample:
curl --location --request POST 'https://api.ycloud.com/v2/whatsapp/messages' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"from": "BUSINESS-PHONE-NUMBER",
"to": "CUSTOMER-PHONE-NUMBER",
"type": "image",
"image": {
"link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/sample/tmp/sample.jpg",
"caption": "Describes the specified media."
}
}'
Video message
In this case, you send a video message:
- Contains a video URL.
- Contains a caption to describe the video.
Note:
- Supported video types:
video/mp4
,video/3gpp
.- Only H.264 video codec and AAC audio codec is supported.
- We support videos with a single audio stream or no audio stream.
- The MP4 file format is derived from the ISO base media file format, which is directly derived from the QuickTime file format developed by Apple. But QuickTime video files are not supported, even if you renamed the file extension from
.mov
to.mp4
.
- Video size limit: 16MB.
- See also Supported Media Types.
Code sample:
curl --location --request POST 'https://api.ycloud.com/v2/whatsapp/messages' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"from": "BUSINESS-PHONE-NUMBER",
"to": "CUSTOMER-PHONE-NUMBER",
"type": "video",
"video": {
"link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/sample/tmp/sample.mp4",
"caption": "Describes the specified media."
}
}'
Audio message
In this case, you send an audio message:
- Contains an audio URL.
Note:
- Supported audio types:
audio/aac
,audio/mp4
,audio/mpeg
,audio/amr
,audio/ogg
(only opus codecs, baseaudio/ogg
is not supported). - Audio size limit: 16MB.
- See also Supported Media Types.
caption
can be used forimage
,video
, anddocument
media messages, but is not supported for audio messages.
Code sample:
curl --location --request POST 'https://api.ycloud.com/v2/whatsapp/messages' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"from": "BUSINESS-PHONE-NUMBER",
"to": "CUSTOMER-PHONE-NUMBER",
"type": "audio",
"audio": {
"link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/sample/tmp/sample.mp3"
}
}'
Document message
In this case, you send a document message:
- Contains a document URL.
- Contains a caption to describe the document.
- Specifies the document filename.
Note:
- Supported document types:
text/plain
,application/pdf
,application/vnd.ms-powerpoint
,application/msword
,application/vnd.ms-excel
,application/vnd.openxmlformats-officedocument.wordprocessingml.document
,application/vnd.openxmlformats-officedocument.presentationml.presentation
,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
. - Document size limit: 100MB.
- See also Supported Media Types.
filename
is only supported for document messages, not supported for any other media messages.
Code sample:
curl --location --request POST 'https://api.ycloud.com/v2/whatsapp/messages' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"from": "BUSINESS-PHONE-NUMBER",
"to": "CUSTOMER-PHONE-NUMBER",
"type": "document",
"document": {
"link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/sample/tmp/sample.pdf",
"caption": "Describes the specified media.",
"filename": "Sample.pdf"
}
}'
Sticker message
In this case, you send a sticker message:
- Contains a sticker URL.
Note:
- Supported sticker types:
image/webp
. Expected dimension: 512x512. - Sticker size limit: 100KB for statics stickers, and 500KB for animated stickers.
- See also Supported Media Types.
Code sample:
curl --location --request POST 'https://api.ycloud.com/v2/whatsapp/messages' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"from": "BUSINESS-PHONE-NUMBER",
"to": "CUSTOMER-PHONE-NUMBER",
"type": "sticker",
"sticker": {
"link": "https://whatsticker.online/stickers_asset/ws-pack-196906m7W4ngr/c8e072f92595.webp"
}
}'
Contacts message
In this case, you send a contacts message:
- Contains 1 contact with addresses, birthday, emails, name, phones, etc.
Note:
contacts[].name.formatted_name
is required.
Code sample:
curl --location --request POST 'https://api.ycloud.com/v2/whatsapp/messages' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"from": "BUSINESS-PHONE-NUMBER",
"to": "CUSTOMER-PHONE-NUMBER",
"type": "contacts",
"contacts": [
{
"addresses": [
{
"street": "<ADDRESS_STREET>",
"city": "<ADDRESS_CITY>",
"state": "<ADDRESS_STATE>",
"zip": "<ADDRESS_ZIP>",
"country": "<ADDRESS_COUNTRY>",
"country_code": "<ADDRESS_COUNTRY_CODE>",
"type": "HOME"
}
],
"birthday": "2001-01-01",
"emails": [
{
"email": "[email protected]",
"type": "WORK"
}
],
"name": {
"formatted_name": "<CONTACT_FORMATTED_NAME>",
"first_name": "<CONTACT_FIRST_NAME>",
"last_name": "<CONTACT_LAST_NAME>",
"middle_name": "<CONTACT_MIDDLE_NAME>",
"suffix": "<CONTACT_SUFFIX>",
"prefix": "<CONTACT_PREFIX>"
},
"org": {
"company": "<CONTACT_ORG_COMPANY>",
"department": "<CONTACT_ORG_DEPARTMENT>",
"title": "<CONTACT_ORG_TITLE>"
},
"phones": [
{
"phone": "+447901614024",
"wa_id": "447901614024",
"type": "WORK"
}
],
"urls": [
{
"url": "<CONTACT_URL>",
"type": "WORK"
}
]
}
]
}'
Location message
In this case, you send a location message:
- Contains latitude and longitude of the place.
- Contains name and address of the place.
Note:
latitude
andlongitude
are required.
Code sample:
curl --location --request POST 'https://api.ycloud.com/v2/whatsapp/messages' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"from": "BUSINESS-PHONE-NUMBER",
"to": "CUSTOMER-PHONE-NUMBER",
"type": "location",
"location": {
"latitude": 1.40435,
"longitude": 103.79304,
"name": "Singapore Zoo",
"address": "80 Mandai Lake Road Singapore 72"
}
}'
Reaction message
In this case, you send an emoji reaction message:
- Contains the ID of the mentioned message.
- Contains an emoji.
Note:
- The
message_id
is the original message ID on WhatsApp's platform, starting with thewamid.
prefix. - Set
emoji
to""
if you want to remove the emoji.
Gives a thumbs up to a message previously sent or received.
Code sample:
curl --location --request POST 'https://api.ycloud.com/v2/whatsapp/messages' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"from": "BUSINESS-PHONE-NUMBER",
"to": "CUSTOMER-PHONE-NUMBER",
"type": "reaction",
"reaction": {
"message_id": "wamid.BgNODYxN...",
"emoji": "👍"
}
}'
Interactive List message
In this case, you send an interactive list message:
- Contains header text, body text, and footer text.
- Sets the
interactive.type
tolist
, and contains a button with 2 sections, and each section has 2 rows.
Note:
- For interactive
list
messages, you need to set a button and set 1 to 10 sections. You can have a total of 10 rows across your sections.
The recipient can select an item from the list by clicking the button:
Code sample:
curl --location --request POST 'https://api.ycloud.com/v2/whatsapp/messages' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"from": "BUSINESS-PHONE-NUMBER",
"to": "CUSTOMER-PHONE-NUMBER",
"type": "interactive",
"interactive": {
"type": "list",
"header": {
"type": "text",
"text": "<HEADER_TEXT>"
},
"body": {
"text": "<BODY_TEXT>"
},
"footer": {
"text": "<FOOTER_TEXT>"
},
"action": {
"button": "<BUTTON_TEXT>",
"sections": [
{
"title": "<LIST_SECTION_1_TITLE>",
"rows": [
{
"id": "<LIST_SECTION_1_ROW_1_ID>",
"title": "<SECTION_1_ROW_1_TITLE>",
"description": "<SECTION_1_ROW_1_DESC>"
},
{
"id": "<LIST_SECTION_1_ROW_2_ID>",
"title": "<SECTION_1_ROW_2_TITLE>",
"description": "<SECTION_1_ROW_2_DESC>"
}
]
},
{
"title": "<LIST_SECTION_2_TITLE>",
"rows": [
{
"id": "<LIST_SECTION_2_ROW_1_ID>",
"title": "<SECTION_2_ROW_1_TITLE>",
"description": "<SECTION_2_ROW_1_DESC>"
},
{
"id": "<LIST_SECTION_2_ROW_2_ID>",
"title": "<SECTION_2_ROW_2_TITLE>",
"description": "<SECTION_2_ROW_2_DESC>"
}
]
}
]
}
}
}'
Interactive Button message
In this case, you send an interactive button message:
- Contains body text.
- Sets the
interactive.type
tobutton
, and contains 2 quick reply buttons.
Note:
- For interactive
buttons
messages, you need to set at most 3 quick reply buttons.
The recipient can click any of the buttons to reply to you a message.
Code sample:
curl --location --request POST 'https://api.ycloud.com/v2/whatsapp/messages' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"from": "BUSINESS-PHONE-NUMBER",
"to": "CUSTOMER-PHONE-NUMBER",
"type": "interactive",
"interactive": {
"type": "button",
"body": {
"text": "<BUTTON_TEXT>"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "<UNIQUE_BUTTON_ID_1>",
"title": "<BUTTON_TITLE_1>"
}
},
{
"type": "reply",
"reply": {
"id": "<UNIQUE_BUTTON_ID_2>",
"title": "<BUTTON_TITLE_2>"
}
}
]
}
}
}'
Interactive Single-Product message
In this case, you send an interactive product message:
- Contains body text and footer text.
- Sets the
interactive.type
toproduct
, and contains an action with product info.
Note:
- To get product and catalog ID, go to Meta Commerce Manager.
- See also Share Products With Customers.
Code sample:
curl --location --request POST 'https://api.ycloud.com/v2/whatsapp/messages' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"from": "BUSINESS-PHONE-NUMBER",
"to": "CUSTOMER-PHONE-NUMBER",
"type": "interactive",
"interactive": {
"type": "product",
"body": {
"text": "<OPTIONAL_BODY_TEXT>"
},
"footer": {
"text": "<OPTIONAL_FOOTER_TEXT>"
},
"action": {
"catalog_id": "367025965434465",
"product_retailer_id": "<ID_TEST_ITEM_1>"
}
}
}'
Interactive Multi-Product message
In this case, you send an interactive product list message:
- Contains body text and footer text.
- Sets the
interactive.type
toproduct_list
, and contains multi products.
Note:
- To get product and catalog ID, go to Meta Commerce Manager.
- See also Share Products With Customers.
Code sample:
curl --location --request POST 'https://api.ycloud.com/v2/whatsapp/messages' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"from": "BUSINESS-PHONE-NUMBER",
"to": "CUSTOMER-PHONE-NUMBER",
"type": "interactive",
"interactive": {
"type": "product_list",
"header": {
"type": "text",
"text": "<YOUR_TEXT_HEADER_CONTENT>"
},
"body": {
"text": "<YOUR_TEXT_BODY_CONTENT>"
},
"footer": {
"text": "<YOUR_TEXT_FOOTER_CONTENT>"
},
"action": {
"catalog_id": "146265584024623",
"sections": [
{
"title": "<SECTION1_TITLE>",
"product_items": [
{
"product_retailer_id": "<YOUR_PRODUCT1_SKU_IN_CATALOG>"
},
{
"product_retailer_id": "<YOUR_SECOND_PRODUCT1_SKU_IN_CATALOG>"
}
]
},
{
"title": "<SECTION2_TITLE>",
"product_items": [
{
"product_retailer_id": "<YOUR_PRODUCT2_SKU_IN_CATALOG>"
},
{
"product_retailer_id": "<YOUR_SECOND_PRODUCT2_SKU_IN_CATALOG>"
}
]
}
]
}
}
}'