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:

example-messaging-otp.webp

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.

example-template-body.png

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.

example-template-quickreply.png

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.

example-template-calltoaction.png

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.

example-messaging-text.png

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:

example-messaging-image.png

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.

example-messaging-video.png

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.

example-messaging-audio.png

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.

example-messaging-document.png

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.

example-messaging-sticker.png

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.

example-messaging-contacts.png

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.

example-messaging-location.png

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.

example-messaing-reaction.png
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.

example-messaging-interactivelist.png

The recipient can select an item from the list by clicking the button:
example-messaging-interactivelist-select.png

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.

example-messaging-interactivebutton.png
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:

example-messaging-product.png

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:

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>"
            }
          ]
        }
      ]
    }
  }
}'