Skip to main content
POST
/
api
/
message
/
button
/
:instance
Send Buttons
curl --request POST \
  --url https://api.example.com/api/message/button/:instance \
  --header 'Content-Type: <content-type>' \
  --header 'token: <token>' \
  --data '
{
  "number": "<string>",
  "contentText": "<string>",
  "buttons": [
    {}
  ],
  "headerText": "<string>",
  "footerText": "<string>",
  "mediaUrl": "<string>",
  "mediaType": "<string>",
  "delay": 123,
  "replyTo": "<string>",
  "replyPrivate": true,
  "source": "<string>"
}
'
Auth: TokenAccount or TokenInstance • Rate-limit: Global (100/min) • Idempotent: no

​
Description

Sends a message with up to 3 interactive buttons (WhatsApp limit). Buttons accept four types: REPLY (default, returns the ID when clicked), URL (opens a link), CALL (dials a number) and COPY (copies a code). The header can be text (headerText) or media (mediaUrl + mediaType). If mediaUrl is sent, mediaType is required and must be uppercase: IMAGE, VIDEO or DOCUMENT. When media is present, headerText is ignored (the media replaces the title).

​
Examples

​
3 REPLY buttons

The REPLY button is used to reply to a specific message inside the conversation: when the customer taps, WhatsApp sends a reply quoting the original message with the text of the button (displayText), that is what appears in the chat. In the webhook/websocket, what reaches your application is the id of the clicked button, allowing you to identify the option without depending on the displayed text.
When REPLY is mixed with other types (URL, CALL, COPY) in the same message, the REPLY button does not appear in WhatsApp Web/Desktop, it is only visible on the smartphone app. The ideal is to use only REPLY buttons or only combinations of URL/CALL/COPY, without mixing.
Classic case of a quick menu. Each button returns its id in the webhook when clicked. 
curl -X POST "https://ryzeapi.cloud/api/message/button/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":      "5511999999999",
    "headerText":  "RyzeAPI Support",
    "contentText": "How can we help you today?",
    "footerText":  "Available 24/7",
    "buttons": [
      { "id": "menu_sales",   "displayText": "Talk to sales",    "type": "REPLY" },
      { "id": "menu_support", "displayText": "Technical support", "type": "REPLY" },
      { "id": "menu_billing", "displayText": "Billing",          "type": "REPLY" }
    ]
  }'

​
With image header

When mediaUrl is present, mediaType is required and must be uppercase (IMAGE, VIDEO, DOCUMENT). headerText is ignored in this case. 
curl -X POST "https://ryzeapi.cloud/api/message/button/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":      "5511999999999",
    "contentText": "Flash sale: 30% OFF on annual subscriptions.",
    "footerText":  "Valid until 11:59pm today",
    "mediaUrl":    "https://example.com/img/promo.jpg",
    "mediaType":   "IMAGE",
    "buttons": [
      { "id": "promo_subscribe", "displayText": "Subscribe now", "type": "REPLY" },
      { "id": "promo_details",   "displayText": "See details",   "type": "REPLY" }
    ]
  }'

​
Mix of URL + CALL + COPY

Combines three different button types in a single message. The id carries distinct semantic values per type. 
curl -X POST "https://ryzeapi.cloud/api/message/button/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":      "5511999999999",
    "headerText":  "Order #12345 confirmed",
    "contentText": "Choose how you want to proceed:",
    "footerText":  "Coupon valid for 24h",
    "buttons": [
      { "id": "https://store.example.com/order/12345", "displayText": "Track order",   "type": "URL"  },
      { "id": "+551130000000",                          "displayText": "Talk to support", "type": "CALL" },
      { "id": "RYZE10",                                 "displayText": "Copy coupon",   "type": "COPY" }
    ]
  }'

​
Success response

The content returns the contentText you sent, and messageType is fixed at buttons. The button definitions themselves do not come back in the response, store the messageId to correlate the clicks that arrive via webhook.
200 OK
{
  "success": true,
  "message": "Buttons message sent successfully",
  "status":  "sent",
  "data": {
    "messageId":   "3EB08FCF27E532F1F5F5",
    "direction":   "sent",
    "messageType": "buttons",
    "content":     "How can we help you today?",
    "source":      "api",
    "timestamp":   "2026-04-30T14:30:00Z",
    "chat": {
      "jid":     "5511999999999@s.whatsapp.net",
      "isGroup": false
    },
    "sender": {
      "jid":      "5511777777777@s.whatsapp.net",
      "instance": "minha-instancia"
    }
  }
}
When the user taps a REPLY button, the response arrives as a text message containing the id of the clicked button, capture that via webhook to chain the flow.

​
Path parameters

​
instance
string
required
Instance name (e.g., $Instance_Name).

​
Headers

​
token
string
required
TokenAccount or TokenInstance.
​
Content-Type
string
required
application/json

​
Request body

​
number
string
required
Destination: phone (5511999999999) or JID (@s.whatsapp.net, @lid, @g.us, @newsletter).
​
contentText
string
required
Main body text of the message (between header and buttons).
​
buttons
ButtonOption[]
required
List of buttons. Minimum 1, maximum 3 (WhatsApp limit). Each button has:
  • id (string, required), semantics vary by type: REPLY returns this ID; URL opens this URL; CALL dials this number; COPY copies this code.
  • displayText (string, required), text visible on the button.
  • type (string), REPLY (default), URL, CALL or COPY. Any other value returns 400 Button N: Type must be one of: REPLY, URL, CALL, COPY.
​
headerText
string
Title displayed at the top of the message. Ignored if mediaUrl is provided (the media replaces the header).
​
footerText
string
Optional text displayed below the buttons.
​
mediaUrl
string
URL of a media file (image, video or document) to use as the header. When sent, mediaType becomes required.
​
mediaType
string
Type of the media in mediaUrl. Required if mediaUrl is present. Accepts only IMAGE, VIDEO or DOCUMENT (uppercase). Any other value returns 400 MediaType must be one of: IMAGE, VIDEO, DOCUMENT.
​
delay
int
default:"0"
Time in seconds to wait before sending. During the interval, the server sends the “typing…” indicator and fires “paused” before the actual send.
​
replyTo
string
ID of the message to be quoted (reply). The original message must belong to the same instance and have been saved in the database.
​
replyPrivate
boolean
default:"false"
When true and replyTo points to a message originating from a group, the message is redirected to the original author’s private chat (keeping the quote).
​
source
string
default:"api"
Origin identifier for traceability (e.g., crm, bot-suporte, n8n). Saved on the message record and propagated to webhooks.

​
Notes

  • delay is in seconds (not milliseconds).
  • WhatsApp accepts up to 3 buttons per message. Four or more return 400 Maximum of 3 buttons allowed.
  • If mediaUrl is sent, headerText is silently ignored.
  • mediaType is normalized to uppercase internally, always send IMAGE, VIDEO or DOCUMENT.
  • For URL buttons, make sure the link starts with https:// to avoid being blocked by the client.
  • For CALL buttons, use the international format (+5511...).
  • Older devices may fall back to text and display the buttons as a regular message.

​
Errors

HTTPInternal statusMessage
400,Instance name is required
400,Invalid request body: <detail>
400,Number is required
400,ContentText is required
400,At least one button is required
400,Maximum of 3 buttons allowed
400,MediaType is required when MediaURL is provided
400,MediaType must be one of: IMAGE, VIDEO, DOCUMENT
400,Button N: ID is required
400,Button N: DisplayText is required
400,Button N: Type must be one of: REPLY, URL, CALL, COPY
400invalid_numberInvalid phone number format: <detail>
400invalid_request(reason for the invalid request detected by the service)
404,Instance not found
500send_failedFailed to send buttons message: <reason>
503disconnectedInstance is not connected to WhatsApp
Error envelope: 
{
  "success": false,
  "error": { "message": "Maximum of 3 buttons allowed" }
}