WhatsApp Messaging Examples

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 to template, and the components and parameters 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 specified image, video, or document media.) is unsupported in template or interactive 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 1 URL button. The URL button can have at most 1 variable at the end of the URL.

Note:

caption parameter (Used to describe the specified image, video, or document media.) is unsupported in template or interactive 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 to true.
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 with wamid., not the message ID on YCloud. The property wamid can be found in both YCloud’s whatsappMessage object (when the status changes to sent) and whatsappInboundMessage object. This feature also applies to other types of messages, except template and sticker 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, base audio/ogg is not supported).
Audio size limit: 16MB.
See also Supported Media Types.
caption can be used for image, video, and document 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 and longitude 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 the wamid. 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 to list, 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 to button, 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 to product, 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 to product_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>"
            }
          ]
        }
      ]
    }
  }
}'