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

  • Link Button

  • OTP Button (Copy Button)

  • Call Button

Logo๐ŸŽฎ 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:",
          "title": ""
        }
      },
      "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:",
          "title": ""
        }
      },
      "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 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:",
          "title": "",
          "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"
}

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.

PreviousSend post to WhatsApp ChannelNextSend Emoji

Last updated

Was this helpful?