> ## Documentation Index
> Fetch the complete documentation index at: https://developer.chatsyncs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Send Interactive Buttons
> Send a WhatsApp session message with up to 3 reply buttons via the ChatSyncs API, optionally with an image/video/document header. Use when a developer asks how to send tappable reply buttons, or why a media+buttons request failed.
Sends a session message with up to 3 tappable **reply buttons**, optionally with an image,
video, or document attached as the header.
Like [Send Text Message](/developer-api/whatsapp/send-text-message), this is a **session
message** — only deliverable within the 24-hour window after the recipient last messaged you.
## Limits
* **1 to 3 buttons**, sent as a JSON array. Each is either a string or `{"id":"buy_now","title":"Buy Now"}`; the `id`
comes back when the contact taps it.
* Each **title** is at most **20 characters** (`Button title may not be greater than 20 characters.`).
* A media header can be an **image, video or document** — never audio. `button_header_text` is ignored when media is
attached.
```bash theme={null}
curl -X POST 'https://platform.chatsyncs.com/api/v1/whatsapp/send/interactive-buttons' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID' \
-d 'phone_number=PHONE-NUMBER' \
-d 'message=Would you like to continue?' \
-d 'buttons=[{"id":"buy_now","title":"Buy Now"},{"id":"details","title":"View Details"}]'
```
The response includes the `wa_message_id`, like the other send endpoints.
## OpenAPI
````yaml POST /whatsapp/send/interactive-buttons
openapi: 3.1.0
info:
title: ChatSyncs Developer API
version: 1.0.0
description: >-
REST API for sending WhatsApp messages and managing subscribers through
ChatSyncs.
**Authentication.** Send your key as the `apiToken` parameter, or as
`Authorization: Bearer ` — both work on every endpoint **except Custom
Fields List**, which only accepts the `apiToken` parameter (a Bearer header
alone is answered with *The api token field is required.*). A wrong key
returns HTTP 401 `{"status":"0","message":"Unauthenticated."}`; no key at
all redirects to the login page.
**Methods.** Every endpoint accepts both GET and POST with the same
parameters, except Upload Media, which is POST-only. Use POST for anything
that changes data.
**Errors.** Failures usually come back as HTTP 200 with `"status":"0"` and
the reason in `message`, so always check `status`. `status` is the string
`"1"` or `"0"` on most endpoints and a boolean on a few.
**Lists.** Endpoints that return rows put them in `message` as a list; there
is no `data` field (Custom Fields List is the exception and uses `data`).
servers:
- url: https://platform.chatsyncs.com/api/v1
security: []
paths:
/whatsapp/send/interactive-buttons:
post:
tags:
- WhatsApp API
summary: Send Interactive Buttons
description: >-
Between 1 and 3 buttons; each title is at most 20 characters. A media
header can be an image, video or document, never audio.
operationId: sendInteractiveButtons
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
apiToken:
type: string
description: >-
Your ChatSyncs API key (not a WhatsApp/Meta access token).
[Where to find
it](/developer-api/finding-ids#api-token-apitoken).
example: API-KEY
phone_number_id:
type: string
description: >-
The WhatsApp account's phone number ID. [Where to find
it](/developer-api/finding-ids#phone-number-id-phone_number_id).
example: PHONE-NUMBER-ID
phone_number:
type: string
description: >-
The subscriber's phone number, with country code, digits
only.
example: PHONE-NUMBER
message:
type: string
description: The message body shown above the buttons.
example: Choose an option
buttons:
type: string
description: >-
JSON array of 1 to 3 reply buttons. Each item is a string or
an object with `id` and `title` (max 20 characters).
example: >-
[{"id":"buy_now","title":"Buy
Now"},{"id":"details","title":"View Details"}]
button_header_text:
type: string
description: >-
Optional text header. Ignored if a media header is sent
instead.
example: Limited Time Offer
button_footer_text:
type: string
description: Optional footer text shown below the buttons.
example: Powered by ChatSyncs
media_url:
type: string
description: >-
Public HTTPS URL of an image, video, or document to use as
the header. Use either media_url or media_id, not both.
example: https://example.com/image.jpg
media_id:
type: string
description: >-
A WhatsApp media ID from [Upload
Media](/developer-api/whatsapp/upload-media). Requires
media_type when used.
example: '1739230482390482'
media_type:
type: string
description: >-
One of image, video, document. Required when using media_id,
or when media_url has no file extension. Audio is not
supported.
example: image
media_name:
type: string
description: Filename to display — only used when media_type is document.
example: brochure.pdf
required:
- apiToken
- phone_number_id
- phone_number
- message
- buttons
responses:
'200':
description: >-
Standard ChatSyncs response. `status` is `"1"` on success and `"0"`
on failure.
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: '`"1"` = success, `"0"` = failure.'
message:
type: string
description: Human-readable result message.
examples:
success:
summary: Success
value:
status: '1'
wa_message_id: >-
wamid.HBgNODgwMTcyMzMwOTAwMxUCABEYEjlGQkY3MEFEMEVGODhCNDkxNQA=
message: Message sent successfully.
error:
summary: A required field is missing
value:
status: '0'
message: phone_number_id is required.
noButtons:
summary: buttons is required (JSON array of 1-3 reply buttons)
value:
status: '0'
message: buttons is required (JSON array of 1-3 reply buttons).
tooMany:
summary: You can send between 1 and 3 reply buttons
value:
status: '0'
message: You can send between 1 and 3 reply buttons.
titleTooLong:
summary: Button title may not be greater than 20 characters
value:
status: '0'
message: Button title may not be greater than 20 characters.
audioHeader:
summary: >-
Audio media is not supported as a header for interactive
buttons
value:
status: '0'
message: >-
Audio media is not supported as a header for interactive
buttons. Use image, video, or document.
notJson:
summary: buttons must be a valid JSON array
value:
status: '0'
message: buttons must be a valid JSON array.
outsideWindow:
summary: Outside the 24-hour window
value:
status: '0'
message: >-
Sending message outside 24 hour window is not allowed. You
can only send template message to this user.
'401':
description: >-
`apiToken` is wrong. (With no token at all the API redirects to the
login page with HTTP 302 instead of returning JSON.)
content:
application/json:
schema:
type: object
properties:
status:
type: string
message:
type: string
examples:
unauthenticated:
summary: Wrong apiToken
value:
status: '0'
message: Unauthenticated.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.