Messaging Endpoints
Send text, templates, reply buttons and files, upload media, read a conversation, and check delivery status — with parameters and examples.
All messaging endpoints need apiToken and, except where noted, phone_number_id (your sending number) and phone_number (the customer, digits only with country code).
The 24-hour rule. Text, buttons and files are only delivered if the customer messaged you in the last 24 hours. Outside that window, send an approved template. See WhatsApp pricing.
Send a text message#
POST /whatsapp/send
| Parameter | Required | Description |
|---|---|---|
phone_number_id |
Yes | Your sending number's ID |
phone_number |
Yes | Customer's number, e.g. 919876543210 |
message |
Yes | Text, up to 4,096 characters (URL-encode it for GET) |
curl -X POST 'https://app.wably.in/api/v1/whatsapp/send' \
-d 'apiToken=YOUR_API_KEY' -d 'phone_number_id=PHONE_NUMBER_ID' \
-d 'phone_number=919876543210' -d 'message=Your order is ready for pickup 🛍️'
Success returns wa_message_id — keep it to check delivery.
Send a template#
POST /whatsapp/send/template
| Parameter | Required | Description |
|---|---|---|
phone_number_id |
Yes | Your sending number's ID |
template_id |
Yes | The short Wably template ID (not Meta's long ID) |
phone_number |
Yes | Customer's number |
templateVariable-{name}-{position} |
When the template has variables | One field per variable, e.g. templateVariable-order_id-2 for {{2}} |
template_quick_reply_button_values |
No | JSON array of postback IDs, one per quick-reply button, e.g. ["YES_START"] |
curl -X POST 'https://app.wably.in/api/v1/whatsapp/send/template' \
-d 'apiToken=YOUR_API_KEY' -d 'phone_number_id=PHONE_NUMBER_ID' \
-d 'template_id=48' -d 'phone_number=919876543210' \
-d 'templateVariable-order_id-2=ORD-1042'
Good to know:
- The customer's first name fills automatically — don't send it.
- A variable with no value is delivered as -, so send every variable the template needs.
- Values must be one line, without tabs, up to 1,024 characters.
- A URL button variable is numbered after the body variables (four body variables → the button is -5). Its value is added to the end of the link, so no spaces.
- Carousel templates, templates with an unattached media header, and templates with unmapped variables can't be sent this way — map variables first in Message Templates → Variables.
Send reply buttons#
POST /whatsapp/send/interactive-buttons
| Parameter | Required | Description |
|---|---|---|
phone_number_id, phone_number |
Yes | — |
message |
Yes | Text above the buttons |
buttons |
Yes | JSON array of 1–3 buttons: ["Yes","No"] or [{"id":"yes","title":"Yes"}]. The id comes back in webhooks when tapped |
button_header_text |
No | Text header (ignored with a media header) |
button_footer_text |
No | Footer text |
media_url / media_id |
No | Image, video or document header |
media_type |
With media_id |
image, video or document |
Send a file#
POST /whatsapp/send/file
| Parameter | Required | Description |
|---|---|---|
phone_number_id, phone_number |
Yes | — |
media_url |
If no media_id |
Public HTTPS link — WhatsApp downloads from it |
media_id |
If no media_url |
From Upload Media |
media_type |
Sometimes | image, video, audio or document — required with media_id, or when the URL has no file extension |
media_name |
For documents | File name the customer sees |
media_caption_text |
No | Caption (not for audio) |
Upload media#
POST /whatsapp/upload/media — multipart/form-data, POST only.
| Parameter | Required | Description |
|---|---|---|
phone_number_id |
Yes | — |
media_file |
Yes | The file (image, video, audio or document) |
Returns a media_id you can reuse for many recipients without uploading again.
curl -X POST 'https://app.wably.in/api/v1/whatsapp/upload/media' \
-F 'apiToken=YOUR_API_KEY' -F 'phone_number_id=PHONE_NUMBER_ID' \
-F 'media_file=@menu.pdf'
Get a conversation#
POST /whatsapp/get/conversation
| Parameter | Required | Description |
|---|---|---|
phone_number_id, phone_number |
Yes | — |
limit |
Yes | Messages to return, up to 50 |
offset |
No | Page number, default 1 |
Delivery status#
POST /whatsapp/get/message-status
| Parameter | Required | Description |
|---|---|---|
wa_message_id |
Yes | The ID returned when you sent the message |
Returns whether the message was sent, delivered, read or failed.
Postback list#
POST /whatsapp/get/post-back-list — phone_number_id required. Lists the button postback IDs on your number, for use with template quick-reply buttons.