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": "currency",
"currency": {
"fallback_value": "$9.9",
"code": "USD",
"amount_1000": "9900"
}
},
{
"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. - 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/3gp
. Only H.264 video codec and AAC audio codec is supported. - 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, each section has at most 10 rows.
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>"
}
]
}
]
}
}
}'