Send message with Buttons

The method is designed to send a message with buttons to a private or group chat

Button message functionality is currently provided on an 'as-is' basis due to its inherent instability and dependency on Meta's updates. Please be aware that with each new WhatsApp update, the behavior of button messages may change.

For more details, visit the Button Status topic.

Peculiarities when working with buttons:

• the button name can have no more than 25 characters;

• there can be no more than 3 buttons of this type;

• the button can be pressed only 1 time.

• for current nuances of button display, see the article Current status of Buttons on WhatsApp

You can send a message with the button to either private chat or group chat. The buttons, e.g. YES / NO, can be selected by the user and used as a response to the sent message.

Types of buttons

There are four types of buttons on WhatsApp:

• Simple text button (Quick-reply)

• List of options

• Url Link Button

• OTP Button (Copy Button)

• Call Button

🎮 Send interactive messageWhapi Cloud - Whatsapp API for developers

Endpoint for sending messages with different buttons

Sending requires a request to be made to:

POST https://gate.whapi.cloud/messages/interactive

---

Message with auto-reply buttons

Example of a message with quick reply buttons.

curl --request POST \
     --url https://gate.whapi.cloud/messages/interactive \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {Your_Token}' \
     --header 'content-type: application/json' \
     --data '
{
  "header": {
    "text": "Header with text"
  },
  "body": {
    "text": "Body message"
  },
  "footer": {
    "text": "Footer message"
  },
  "action": {
    "buttons": [
      {
        "type": "quick_reply",
        "title": "Button1",
        "id": "randomId1"
      },
      {
        "type": "quick_reply",
        "title": "Button2",
        "id": "randomId2"
      }
    ]
  },
  "type": "button",
  "to": "61371989950"
}
'

When the recipient clicks on a button, it automatically sends a reply to your message containing the button’s text. If you've set up a webhook for the channel, you'll receive a callback with both the button ID and the text.

{
  "messages": [
    {
      "id": "g0jEG0ZsSobn4yNGGU3TAg-gDYOS60TLw",
      "from_me": false,
      "type": "reply",
      "chat_id": "[email protected]",
      "timestamp": 1726126124,
      "source": "mobile",
      "chat_name": "Jonathan Customer",
      "reply": {
        "type": "buttons_reply",
        "buttons_reply": {
          "id": "ButtonsV3:randomId1",
          "title": "Button1"
        }
      },
      "context": {
        "quoted_id": "yqKj.Z7XWg0g1lA-wD8Sij1GoQ",
        "quoted_author": "919984351847",
        "quoted_content": {
          "header": "Header with text",
          "body": "Body message",
          "footer": "Footer message",
          "buttons": [
            {
              "type": "quick_reply",
              "text": "Button1",
              "id": "ButtonsV3:randomId1"
            },
            {
              "type": "quick_reply",
              "text": "Button2",
              "id": "ButtonsV3:randomId2"
            }
          ]
        },
        "quoted_type": "hsm"
      },
      "from": "61371989950",
      "from_name": "Jonathan"
    }
  ],
  "event": {
    "type": "messages",
    "event": "post"
  },
  "channel_id": "MANTIS-PF238"
}

Note that the callback may be slightly different if the customer clicked the button in Web WhatsApp:

{
  "messages": [
    {
      "id": "g0jEG0ZsSobn4yNGGU3TAg-gDYOS60TLw",
      "from_me": false,
      "type": "reply",
      "chat_id": "[email protected]",
      "timestamp": 1726126124,
      "source": "mobile",
      "chat_name": "Jonathan Customer",
      "reply": {
        "type": "buttons_reply",
        "buttons_reply": {
          "id": "ButtonsV3:randomId2",
          "title": "Button2"
        }
      },
      "context": {
        "quoted_id": "yqKj.Z7XWg0g1lA-wD8Sij1GoQ",
        "quoted_author": "919984351847",
        "quoted_content": {
          "body": "Body message"
        },
        "quoted_type": "text"
      },
      "from": "61371989950",
      "from_name": "Jonathan"
    }
  ],
  "event": {
    "type": "messages",
    "event": "post"
  },
  "channel_id": "MANTIS-PF238"
}

Message with Call button and url Link button

Example of a message with callback buttons and a link to a third-party site

curl --request POST \
     --url https://gate.whapi.cloud/messages/interactive \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {Your_Token}' \
     --header 'content-type: application/json' \
     --data '
{
  "header": {
    "text": "Header with text"
  },
  "body": {
    "text": "Body message"
  },
  "footer": {
    "text": "Footer message"
  },
  "action": {
    "buttons": [
      {
        "type": "call",
        "title": "Call us",
        "id": "randomId1",
        "phone_number": "61371989950"
      },
      {
        "type": "url",
        "title": "Look at the website",
        "id": "randomId2",
        "url": "https://whapi.cloud"
      }
    ]
  },
  "type": "button",
  "to": "61371989950"
}
'

Unfortunately, WhatsApp does not track the event of clicking these buttons. Therefore, it is not possible to get a webhook for pressing these buttons.

---

Message with copy button (OTP code)

Example of a message with a button to copy hidden text

You can pass any text to the snippet that will be copied after the button is clicked.

curl --request POST \
     --url https://gate.whapi.cloud/messages/interactive \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {Your_Token}' \
     --header 'content-type: application/json' \
     --data '
{
  "header": {
    "text": "Header with text"
  },
  "body": {
    "text": "Body message"
  },
  "footer": {
    "text": "Footer message"
  },
  "action": {
    "buttons": [
      {
        "type": "copy",
        "title": "Copy OTP",
        "id": "randomId1",
        "copy_code": "65545"
      }
    ]
  },
  "type": "button",
  "to": "61371989950"
}
'

Unfortunately, WhatsApp does not track the event of clicking these buttons. Therefore, it is not possible to get a webhook for pressing these buttons.

---

Message with list of options

Example of a message with a button with a list of options

The list of options will expand if the user clicks on it.

curl --request POST \
     --url https://gate.whapi.cloud/messages/interactive \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {Your_Token}' \
     --header 'content-type: application/json' \
     --data '
{
  "header": {
    "text": "Header with text"
  },
  "body": {
    "text": "Body message"
  },
  "footer": {
    "text": "Footer message"
  },
"action": {
    "list": {
      "sections": [
        {
          "title": "What's your favorite hamburger?",
          "rows": [
            {
              "title": "Hamburger without cheese",
              "id": "r1",
              "description": "A burger without cheese or sauce is often referred to as a \"plain\" burger."
            },
            {
              "id": "r2",
              "title": "Cheeseburger",
              "description": "A cheeseburger is a hamburger with a slice of melted cheese on top of the meat patty"
            }
          ]
        }
      ],
      "label": "Pick a hamburger!"
    }
  },
  "type": "list",
  "to": "61371989950"
}
'

When the recipient clicks on a button, it automatically sends a reply to your message containing the button’s text. If you've set up a webhook for the channel, you'll receive a callback with both the button ID and the text.

{
  "messages": [
    {
      "id": "A5y7S8JfMsgaYiXZC6Royw-gMoOS60TLw",
      "from_me": false,
      "type": "reply",
      "chat_id": "[email protected]",
      "timestamp": 1726127469,
      "source": "mobile",
      "chat_name": "Jonathan Customer",
      "reply": {
        "type": "list_reply",
        "list_reply": {
          "id": "ListV3:r1",
          "title": "Hamburger without cheese",
          "description": "A burger without cheese or sauce is often referred to as a \"plain\" burger."
        }
      },
      "context": {
        "quoted_id": "yqL1GxfdT7pX48I-wEASij1GoQ",
        "quoted_author": "919984351847",
        "quoted_content": {
          "title": "Header with text",
          "description": "Body message",
          "label": "Pick a hamburger!",
          "footer": "Footer message",
          "sections": [
            {
              "title": "What's your favorite hamburger?",
              "rows": [
                {
                  "id": "ListV3:r1",
                  "title": "Hamburger without cheese",
                  "description": "A burger without cheese or sauce is often referred to as a \"plain\" burger."
                },
                {
                  "id": "ListV3:r2",
                  "title": "Cheeseburger",
                  "description": "A cheeseburger is a hamburger with a slice of melted cheese on top of the meat patty"
                }
              ]
            }
          ]
        },
        "quoted_type": "list"
      },
      "from": "61371989950",
      "from_name": "Jonathan"
    }
  ],
  "event": {
    "type": "messages",
    "event": "post"
  },
  "channel_id": "MANTIS-PF238"
}

---

Send buttons with images

When using this endpoint, you can also send images containing interactive action buttons. The labels on these buttons, such as “YES” or “NO,” are selected by the user and serve as direct responses to the message transmitted using the buttons.

Sending requires a request to be made to:

POST https://gate.whapi.cloud/messages/interactive

The image can be transferred either via a direct link, Base64, or Media ID.

Send a message with buttons and an image

curl --request POST \
     --url https://gate.whapi.cloud/messages/interactive \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {Your_Token}' \
     --header 'content-type: application/json' \
     --data '
{
  "body": {
    "text": "Hello. Take your pick!"
  },
  "footer": {
    "text": "After all, this is just an example"
  },
  "action": {
    "buttons": [
      {
        "type": "quick_reply",
        "title": "Point 1",
        "id": "p1"
      },
      {
        "type": "quick_reply",
        "title": "Point 2",
        "id": "p2"
      },
      {
        "type": "quick_reply",
        "title": "Point 3",
        "id": "p3"
      }
    ]
  },
  "type": "button",
  "to": "61371989950",
  "media": "https://fileinfo.com/img/ss/xl/jpg_44-2.jpg"
}
'

---

Send Buttons with Video

This method allows you to send videos with action buttons. You can place up to three buttons with different content in a message, and whatever the user selects will be used as a response to the message sent along with the buttons.

Sending requires a request to be made to:

POST https://gate.whapi.cloud/messages/interactive

The video can be transferred either via a direct link, Base64, or Media ID.

Send a message with buttons and video

curl --request POST \
     --url https://gate.whapi.cloud/messages/interactive \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {Your_Token}' \
     --header 'content-type: application/json' \
     --data '
{
  "body": {
    "text": "Hello. Take your pick!"
  },
  "footer": {
    "text": "After all, this is just an example"
  },
  "action": {
    "buttons": [
      {
        "type": "quick_reply",
        "title": "Point 1",
        "id": "p1"
      },
      {
        "type": "quick_reply",
        "title": "Point 2",
        "id": "p2"
      },
      {
        "type": "quick_reply",
        "title": "Point 3",
        "id": "p3"
      }
    ]
  },
  "type": "button",
  "to": "61371989950",
  "media": "https://download.samplelib.com/mp4/sample-5s.mp4",
  "no_encode": true
}
'

---

Send Carousel

WhatsApp Carousel Messages

A carousel in WhatsApp is an interactive message format. It allows sending up to 10 cards in a single message — each containing an image or video, text, and interactive buttons. Using action buttons, you can redirect to links, make calls, and also provide standard responses.

Displaying the carousel in Web WhatsApp

This format is ideal for showcasing products, services, or catalogs, enabling recipients to swipe through multiple cards within one message. It provides a clear and engaging way to organize and present visual content or offer users interactive choices.

Displaying the carousel in the WhatsApp app on phone

This endpoint is responsible for sending messages with carousel:

POST https://gate.whapi.cloud/messages/carousel

Example of request payload:

{
  "body": {
    "text": "Hey, we're having a big sale today, be sure to check it out! 👇"
  },
  "to": "61371989950",
  "cards": [
    {
      "media": {
        "media": "https://as1.ftcdn.net/v2/jpg/16/63/78/04/1000_F_1663780499_vMDTzHPYceR3VReJGYm1mYiiwLdHTrfP.jpg"
      },
      "text": "Just click on the button to visit our catalog",
      "id": "Card-ID1",
      "buttons": [
        {
          "type": "url",
          "title": "Website link",
          "id": "Button-ID1",
          "url": "https://yourdomain.com/"
        }
      ]
    },
    {
      "media": {
        "media": "https://t3.ftcdn.net/jpg/15/92/71/94/240_F_1592719402_Fxu8hyWHmVUzIkSOQstoZnEhQSXsqR7S.jpg"
      },
      "text": "This product has already won over many people! It truly has no equal. Do you know why? No? Then click on the button below and our bot will tell you everything! 💥",
      "id": "Card-ID2",
      "buttons": [
        {
          "type": "quick_reply",
          "title": "Button text 2",
          "id": "Button-ID2"
        }
      ]
    },
    {
      "media": {
        "media": "https://t3.ftcdn.net/jpg/15/80/60/18/240_F_1580601875_0a4XG63mcTPUaGKaopR7bdLz3kkBrxU5.jpg"
      },
      "text": "Card text 3",
      "id": "Card-ID3",
      "buttons": [
        {
          "type": "quick_reply",
          "title": "Button text 3",
          "id": "Button-ID3"
        }
      ]
    }
  ]
}

🖼️ Send carousel messageWhapi Cloud - Whatsapp API for developers

---

We continue to explore WhatsApp's capabilities and add to our methods for automation. In the upcoming updates we will have the ability to send messages with picture/media and buttons.

If you have any questions, our team is always available to help you.