Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

edit checklist

Gabriel Moraes5f612e44d166
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 88f79273c..a116ca20c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Baileys inbound button, template quick-reply, list-row and native-flow replies arrive as `type: "text"` with a structured `button { id, text? }` on `message.received` / chat history (whatsapp-web.js still has no interactive reply fields).
- Baileys inbound business prompts that offer buttons (or list rows) also carry `buttons: [{ id, text }, …]` on `message.received`, so choices like Sim/Não are no longer flattened away into `body` only.
- `POST /api/sessions/:sessionId/messages/click-button` sends a structured button/list reply against a stored WhatsApp Business prompt on Baileys (whatsapp-web.js returns `501`).
+- The dashboard Chats thread renders inbound Baileys prompt `buttons` and taps them through `POST .../messages/click-button`; prompt choices are also kept in persisted message `metadata` so they survive reload.
### Changed
diff --git a/dashboard/src/i18n/locales/ar.json b/dashboard/src/i18n/locales/ar.json
index 1a57514e9..b126b027e 100644
--- a/dashboard/src/i18n/locales/ar.json
+++ b/dashboard/src/i18n/locales/ar.json
@@ -116,6 +116,7 @@
"groupSubtitle": "مجموعة",
"privateContactSubtitle": "جهة اتصال خاصة",
"deleteConfirm": "حذف هذه الرسالة للجميع؟",
+ "promptButtons": "خيارات الرسالة",
"messageDeleted": "🚫 تم حذف هذه الرسالة",
"messageMasked": "🔒 أخفته واتساب على الأجهزة المرتبطة — تحقق منه على هاتفك الأساسي",
"kind": {
@@ -173,6 +174,7 @@
"send": "فشل إرسال الرسالة",
"react": "فشل التفاعل مع الرسالة",
"delete": "فشل حذف الرسالة",
+ "clickButton": "فشل النقر على الزر",
"fileTooLarge": "الملف كبير جدًا (الحد الأقصى 18 ميغابايت)"
},
"loadMessagesError": "تعذّر تحميل الرسائل. تحقّق من سجلّات الخادم.",
diff --git a/dashboard/src/i18n/locales/de.json b/dashboard/src/i18n/locales/de.json
index 36a154b8d..ae2c92834 100644
--- a/dashboard/src/i18n/locales/de.json
+++ b/dashboard/src/i18n/locales/de.json
@@ -113,6 +113,7 @@
"groupSubtitle": "Gruppe",
"privateContactSubtitle": "Privater Kontakt",
"deleteConfirm": "Diese Nachricht für alle löschen?",
+ "promptButtons": "Nachrichtenoptionen",
"messageDeleted": "🚫 Diese Nachricht wurde gelöscht",
"messageMasked": "🔒 Von WhatsApp für verknüpfte Geräte ausgeblendet — prüfe dein Haupttelefon",
"kind": {
@@ -162,6 +163,7 @@
"send": "Nachricht konnte nicht gesendet werden",
"react": "Reaktion auf die Nachricht fehlgeschlagen",
"delete": "Nachricht konnte nicht gelöscht werden",
+ "clickButton": "Schaltfläche konnte nicht angeklickt werden",
"fileTooLarge": "Die Datei ist zu groß (max. 18 MB)"
},
"loadMessagesError": "Nachrichten konnten nicht geladen werden. Prüfe die Serverprotokolle.",
diff --git a/dashboard/src/i18n/locales/es.json b/dashboard/src/i18n/locales/es.json
index 2dde5473d..46621afa1 100644
--- a/dashboard/src/i18n/locales/es.json
+++ b/dashboard/src/i18n/locales/es.json
@@ -113,6 +113,7 @@
"groupSubtitle": "Grupo",
"privateContactSubtitle": "Contacto privado",
"deleteConfirm": "¿Eliminar este mensaje para todos?",
+ "promptButtons": "Opciones del mensaje",
"messageDeleted": "🚫 Este mensaje fue eliminado",
"messageMasked": "🔒 Ocultado por WhatsApp en dispositivos vinculados — revísalo en tu teléfono principal",
"kind": {
@@ -162,6 +163,7 @@
"send": "Error al enviar el mensaje",
"react": "Error al reaccionar al mensaje",
"delete": "Error al eliminar el mensaje",
+ "clickButton": "Error al pulsar el botón",
"fileTooLarge": "El archivo es demasiado grande (máx. 18 MB)"
},
"loadMessagesError": "No se pudieron cargar los mensajes. Revisa los registros del servidor.",
diff --git a/dashboard/src/i18n/locales/fr.json b/dashboard/src/i18n/locales/fr.json
index 71979b553..5307360a2 100644
--- a/dashboard/src/i18n/locales/fr.json
+++ b/dashboard/src/i18n/locales/fr.json
@@ -113,6 +113,7 @@
"groupSubtitle": "Groupe",
"privateContactSubtitle": "Contact privé",
"deleteConfirm": "Supprimer ce message pour tout le monde ?",
+ "promptButtons": "Choix du message",
"messageDeleted": "🚫 Ce message a été supprimé",
"messageMasked": "🔒 Masqué par WhatsApp sur les appareils liés — consultez votre téléphone principal",
"kind": {
@@ -162,6 +163,7 @@
"send": "Échec de l'envoi du message",
"react": "Échec de la réaction au message",
"delete": "Échec de la suppression du message",
+ "clickButton": "Échec du clic sur le bouton",
"fileTooLarge": "Le fichier est trop volumineux (max 18 Mo)"
},
"loadMessagesError": "Impossible de charger les messages. Vérifiez les journaux du serveur.",
diff --git a/dashboard/src/i18n/locales/he.json b/dashboard/src/i18n/locales/he.json
index 4a5fdae7c..88c81f887 100644
--- a/dashboard/src/i18n/locales/he.json
+++ b/dashboard/src/i18n/locales/he.json
@@ -115,6 +115,7 @@
"groupSubtitle": "קבוצה",
"privateContactSubtitle": "איש קשר פרטי",
"deleteConfirm": "למחוק הודעה זו עבור כולם?",
+ "promptButtons": "אפשרויות ההודעה",
"messageDeleted": "🚫 הודעה זו נמחקה",
"messageMasked": "🔒 הוסתר על ידי וואטסאפ במכשירים המקושרים — בדוק בטלפון הראשי שלך",
"kind": {
@@ -169,6 +170,7 @@
"send": "שליחת ההודעה נכשלה",
"react": "התגובה להודעה נכשלה",
"delete": "מחיקת ההודעה נכשלה",
+ "clickButton": "לחיצה על הכפתור נכשלה",
"fileTooLarge": "הקובץ גדול מדי (מקסימום 18 MB)"
},
"loadMessagesError": "לא ניתן לטעון את ההודעות. בדקו את יומני השרת.",
diff --git a/dashboard/src/i18n/locales/it.json b/dashboard/src/i18n/locales/it.json
index fcf56622b..7cc623c08 100644
--- a/dashboard/src/i18n/locales/it.json
+++ b/dashboard/src/i18n/locales/it.json
@@ -113,6 +113,7 @@
"groupSubtitle": "Gruppo",
"privateContactSubtitle": "Contatto privato",
"deleteConfirm": "Eliminare questo messaggio per tutti?",
+ "promptButtons": "Opzioni del messaggio",
"messageDeleted": "🚫 Questo messaggio è stato eliminato",
"messageMasked": "🔒 Nascosto da WhatsApp sui dispositivi collegati — controlla sul telefono principale",
"kind": {
@@ -162,6 +163,7 @@
"send": "Impossibile inviare il messaggio",
"react": "Impossibile reagire al messaggio",
"delete": "Impossibile eliminare il messaggio",
+ "clickButton": "Impossibile cliccare il pulsante",
"fileTooLarge": "Il file è troppo grande (max 18 MB)"
},
"loadMessagesError": "Impossibile caricare i messaggi. Controlla i log del server.",
diff --git a/dashboard/src/i18n/locales/ko.json b/dashboard/src/i18n/locales/ko.json
index 90f3d7220..c1a817714 100644
--- a/dashboard/src/i18n/locales/ko.json
+++ b/dashboard/src/i18n/locales/ko.json
@@ -113,6 +113,7 @@
"groupSubtitle": "그룹",
"privateContactSubtitle": "개인 연락처",
"deleteConfirm": "모두에게서 이 메시지를 삭제할까요?",
+ "promptButtons": "메시지 선택지",
"messageDeleted": "🚫 삭제된 메시지입니다",
"messageMasked": "🔒 연결된 기기에서는 WhatsApp이 이 메시지를 가려 표시합니다 — 기본 휴대폰을 확인하세요",
"kind": {
@@ -162,6 +163,7 @@
"send": "메시지를 보내지 못했습니다",
"react": "메시지에 반응하지 못했습니다",
"delete": "메시지를 삭제하지 못했습니다",
+ "clickButton": "버튼 클릭에 실패했습니다",
"fileTooLarge": "파일이 너무 큽니다 (최대 18 MB)"
},
"loadMessagesError": "메시지를 불러올 수 없습니다. 서버 로그를 확인하세요.",
diff --git a/dashboard/src/i18n/locales/te.json b/dashboard/src/i18n/locales/te.json
index d3130e230..b915ac8c6 100644
--- a/dashboard/src/i18n/locales/te.json
+++ b/dashboard/src/i18n/locales/te.json
@@ -113,6 +113,7 @@
"groupSubtitle": "సమూహం",
"privateContactSubtitle": "ప్రైవేట్ పరిచయం",
"deleteConfirm": "ఈ సందేశాన్ని అందరి కోసం తొలగించాలా?",
+ "promptButtons": "సందేశ ఎంపికలు",
"messageDeleted": "🚫 ఈ సందేశం తొలగించబడింది",
"messageMasked": "🔒 లింక్ చేసిన పరికరాల్లో WhatsApp దీన్ని దాచింది — మీ ప్రధాన ఫోన్‌లో చూడండి",
"kind": {
@@ -162,6 +163,7 @@
"send": "సందేశాన్ని పంపడం విఫలమైంది",
"react": "సందేశానికి ప్రతిస్పందించడం విఫలమైంది",
"delete": "సందేశాన్ని తొలగించడం విఫలమైంది",
+ "clickButton": "బటన్ క్లిక్ విఫలమైంది",
"fileTooLarge": "ఫైల్ చాలా పెద్దది (గరిష్టం 18 MB)"
},
"loadMessagesError": "సందేశాలను లోడ్ చేయడం సాధ్యం కాలేదు. సర్వర్ లాగ్‌లను తనిఖీ చేయండి.",
diff --git a/dashboard/src/i18n/locales/tr.json b/dashboard/src/i18n/locales/tr.json
index a53d3bd24..d20a38034 100644
--- a/dashboard/src/i18n/locales/tr.json
+++ b/dashboard/src/i18n/locales/tr.json
@@ -113,6 +113,7 @@
"groupSubtitle": "Grup",
"privateContactSubtitle": "Özel kişi",
"deleteConfirm": "Bu mesaj herkesten silinsin mi?",
+ "promptButtons": "Mesaj seçenekleri",
"messageDeleted": "🚫 Bu mesaj silindi",
"messageMasked": "🔒 Bağlı cihazlar için WhatsApp tarafından gizlendi — ana telefonunuzu kontrol edin",
"kind": {
@@ -162,6 +163,7 @@
"send": "Mesaj gönderilemedi",
"react": "Mesaja tepki verilemedi",
"delete": "Mesaj silinemedi",
+ "clickButton": "Düğmeye tıklanamadı",
"fileTooLarge": "Dosya çok büyük (maks 18 MB)"
},
"loadMessagesError": "Mesajlar yüklenemedi. Sunucu kayıtlarını kontrol edin.",
diff --git a/dashboard/src/i18n/locales/zh-CN.json b/dashboard/src/i18n/locales/zh-CN.json
index 4d719efb6..67ae034a2 100644
--- a/dashboard/src/i18n/locales/zh-CN.json
+++ b/dashboard/src/i18n/locales/zh-CN.json
@@ -113,6 +113,7 @@
"groupSubtitle": "群组",
"privateContactSubtitle": "私人联系人",
"deleteConfirm": "为所有人删除此消息?",
+ "promptButtons": "消息选项",
"messageDeleted": "🚫 此消息已被删除",
"messageMasked": "🔒 WhatsApp 已对关联设备隐藏此消息 — 请在主手机上查看",
"kind": {
@@ -162,6 +163,7 @@
"send": "发送消息失败",
"react": "回应消息失败",
"delete": "删除消息失败",
+ "clickButton": "点击按钮失败",
"fileTooLarge": "文件过大(最大 18 MB)"
},
"loadMessagesError": "无法加载消息。请检查服务器日志。",
diff --git a/dashboard/src/i18n/locales/zh-HK.json b/dashboard/src/i18n/locales/zh-HK.json
index 65cbca474..85faaf330 100644
--- a/dashboard/src/i18n/locales/zh-HK.json
+++ b/dashboard/src/i18n/locales/zh-HK.json
@@ -113,6 +113,7 @@
"groupSubtitle": "群組",
"privateContactSubtitle": "私人聯絡人",
"deleteConfirm": "為所有人刪除此訊息?",
+ "promptButtons": "訊息選項",
"messageDeleted": "🚫 此訊息已被刪除",
"messageMasked": "🔒 WhatsApp 已對已連結裝置隱藏此訊息 — 請在主手機上查看",
"kind": {
@@ -162,6 +163,7 @@
"send": "傳送訊息失敗",
"react": "回應訊息失敗",
"delete": "刪除訊息失敗",
+ "clickButton": "點擊按鈕失敗",
"fileTooLarge": "檔案過大(最大 18 MB)"
},
"loadMessagesError": "無法載入訊息。請檢查伺服器日誌。",
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 765b4b3fb..23f2bf829 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -1268,7 +1268,7 @@ Get persisted message history for a session from the local DB (paginated, filter
}
```
-Each `Message`: `{ id (uuid), sessionId, waMessageId (string|null), chatId, from, to, body (string|null), type, direction ('incoming'|'outgoing'), timestamp (number|null), metadata (object|null), status ('pending'|'sent'|'delivered'|'read'|'failed'), createdAt (ISO date) }`. Ordered by `createdAt` DESC, then by a dialect-dependent second key. The tiebreaker matters: `createdAt` is not unique (SQLite stores whole seconds, a PostgreSQL bulk write ties every row it inserts, and a history backfill carries WhatsApp's own second-resolution timestamp), and without a total order two pages of one walk can repeat a row and omit another. On SQLite the second key is `rowid`, the stored insertion sequence, so messages sharing a second come back in the order they arrived. PostgreSQL has no equivalent (`ctid` moves on every ack update), so it keeps `id`, a random uuid: the walk is equally correct there, but a same-second group is not in arrival order. Note that `offset` still addresses a position by count, so a list taking concurrent writes can shift under a walk: a message arriving mid-walk pushes every older row down one, and the next page re-serves a row the previous one already returned. Pass `after` instead to walk a live chat safely; it anchors on the last row you received, which an arriving message cannot move. The response is the raw service object (no envelope). Unlike the live `IncomingMessage` shape below, this persisted `Message` does **not** carry `kind` — re-derive the chat kind from `chatId` (see `ChatKind` / `chatKind()`) if needed.
+Each `Message`: `{ id (uuid), sessionId, waMessageId (string|null), chatId, from, to, body (string|null), type, direction ('incoming'|'outgoing'), timestamp (number|null), metadata (object|null), status ('pending'|'sent'|'delivered'|'read'|'failed'), createdAt (ISO date) }`. Ordered by `createdAt` DESC, then by a dialect-dependent second key. The tiebreaker matters: `createdAt` is not unique (SQLite stores whole seconds, a PostgreSQL bulk write ties every row it inserts, and a history backfill carries WhatsApp's own second-resolution timestamp), and without a total order two pages of one walk can repeat a row and omit another. On SQLite the second key is `rowid`, the stored insertion sequence, so messages sharing a second come back in the order they arrived. PostgreSQL has no equivalent (`ctid` moves on every ack update), so it keeps `id`, a random uuid: the walk is equally correct there, but a same-second group is not in arrival order. Note that `offset` still addresses a position by count, so a list taking concurrent writes can shift under a walk: a message arriving mid-walk pushes every older row down one, and the next page re-serves a row the previous one already returned. Pass `after` instead to walk a live chat safely; it anchors on the last row you received, which an arriving message cannot move. The response is the raw service object (no envelope). Unlike the live `IncomingMessage` shape below, this persisted `Message` does **not** carry `kind` — re-derive the chat kind from `chatId` (see `ChatKind` / `chatKind()`) if needed. When present, `metadata` may include `media`, `quotedMessage`, `call`, `reactions`, and — for Baileys inbound business prompts — `buttons: [{ id, text }, …]` so a client (including the dashboard Chats thread) can re-render the choices after reload and tap them via [`POST .../click-button`](#post-apisessionssessionidmessagesclick-button).
> **Inline media is carried up to a budget, then omitted.** `MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES` (8 MiB of encoded base64 by default) bounds how much inline media one response may hold across its rows. A row is not a bounded object — `limit` is clamped to `[1,100]` but each row can carry its base64 in `metadata.media.data`, so a page of media rows could otherwise reach hundreds of megabytes and fail the read outright. The budget is spent newest-first, matching the `createdAt` DESC order above, so a page that cannot carry everything keeps the most recent media. Past it a payload is replaced with `{ mimetype, filename?, omitted: true, sizeBytes }` — the same marker the engine emits for inbound media over `MEDIA_DOWNLOAD_MAX_BYTES` — and the bytes remain available from [`GET /messages/:chatId/:messageId/media`](#get-apisessionssessionidmessageschatidmessageidmedia). Two rules bound the edges: the newest payload is always inlined even when it alone exceeds the budget (otherwise a single large photo would be permanently unreadable through this route), and a budget of `0` means "never inline" and grants no such allowance. The knob is validated at boot — `8MiB` would parse to 8 bytes — and is forwarded by both compose files. The MCP `MessageList` tool shares this path and the same budget.
diff --git a/docs/17-dashboard-design.md b/docs/17-dashboard-design.md
index 406caeda6..9c8f8e439 100644
--- a/docs/17-dashboard-design.md
+++ b/docs/17-dashboard-design.md
@@ -400,8 +400,11 @@ package to pull from.
| `GithubIcon` | `components/GithubIcon.tsx` | Inline brand SVG |
Chat-specific pieces live one level down in `components/chats/`: `MessageBody` (WhatsApp text
-formatting + link detection) and `MediaLightbox` (the media viewer, built on
-`yet-another-react-lightbox`).
+formatting + link detection), `ChatThread` (bubble list, including inbound Baileys prompt buttons
+that call `POST /sessions/:id/messages/click-button`), and `MediaLightbox` (the media viewer, built
+on `yet-another-react-lightbox`). Prompt choices arrive on live `message.received` / engine history
+as top-level `buttons` and are also stored in message `metadata.buttons` so a reload can re-render
+them.
The message thread is paged. `useChatMessages` is a `useInfiniteQuery` whose cursor is the number
of DB rows fetched so far, not the length of the rendered list — the thread also carries engine