Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
edit checklist
Gabriel Moraes5f612e44d166
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.### Changeddiff --git a/dashboard/src/i18n/locales/ar.json b/dashboard/src/i18n/locales/ar.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.mdindex 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.mdindex 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 numberof DB rows fetched so far, not the length of the rendered list — the thread also carries engine