💬 פרק 1

מה מקבלים, חיבור וואטסאפ לסוכני AI

היכולת לחבר סוכן בינה מלאכותית לחשבון וואטסאפ פעיל משנה מן היסוד את הדרך שבה מנהלים תקשורת, מסמכים והודעות. במקום להעתיק ידנית טקסטים בין חלונות, סוכן ה-AI מסוגל לסקור שיחות, לאתר בקשות דחופות, לקרוא מסמכים שנשלחו בצ'אט, לנסח טיוטות תגובה מותאמות ולתזמן הודעות עתידיות.

רוצים לחבר את הוואטסאפ ל-AI בלי להסתבך בהתקנות?

ב-NeoTech Vision פיתחנו את Connecta, מערכת WhatsApp MCP מוכנה, המתארחת בשרת המאובטח שלנו. במקום להקים ולתחזק שרת בעצמכם, נרשמים, מחברים את הוואטסאפ בסריקת QR ומגדירים את החיבור לכלי AI תומך, כמו Claude או ChatGPT.

אפשר לסכם שיחות, למצוא מידע ולנסח תשובות, עם אישור שלכם לפני כל שליחה.

להיכרות עם Connecta ולפתיחת חשבון:

מעדיפים להתקין בעצמכם על המחשב או השרת שלכם? המשיכו למסלולי ההקמה במדריך.

הארכיטקטורה מבוססת על חיבור מאובטח ומקומי. על גבי המחשב או השרת רץ מנוע קוד פתוח בשם GOWA, המקיים תקשורת מול פרוטוקול WhatsApp Web בדיוק כמו דפדפן רגיל. לצדו פועל שרת MCP (פרוטוקול Model Context Protocol), החושף את יכולות הוואטסאפ ככלים מובנים עבור סביבות פיתוח וסוכנים כגון קלוד קוד (Claude Code), קלוד דסקטופ, קרסור (Cursor) או גרוק CLI.

כל התהליך בנוי על עקרון ברור: אישור אנושי לפני כל שליחה. הסוכן קורא, מנתח ומציע, אך אינו שולח הודעה לאף נמען ללא הצגת הטקסט והאישור המפורש שלכם.

flowchart LR
    A["טלפון נייד (WhatsApp)"] <-->|"סריקת QR חד-פעמית"| B["מנוע GOWA (קונטיינר מקומי)"]
    B <-->|"REST API מקומי (127.0.0.1)"| C["שרת MCP (FastMCP Python)"]
    C <-->|"פרוטוקול MCP"| D["סוכן AI (Claude Code / Cursor / Grok)"]
    D -->|"טיוטה לאישור"| E["משתמש מאשר"]
    E -->|"אישור שליחה"| D

#שני מסלולי הקמה במדריך

המדריך מציג שני אפיקים לביצוע החיבור, בהתאם לרמת השליטה הנדרשת:

1. מסלול ההודעה האחת המלאה (מומלץ): פרומפט מקיף אחד שמוזן לקלוד קוד. הסוכן מזהה את סביבת מערכת ההפעלה, מתקין את מנוע GOWA בתוך קונטיינר Docker מבודד, מנחה אתכם לסרוק ברקוד, בונה שרת FastMCP מלא ב-Python עם עשרות כלים מותאמים אישית (קריאה, שליחה, תזמון מותאם, טיפול במדיה וניהול קבוצות), ומחבר את כל הכלים לסביבות המקומיות והמרוחקות.
2. המסלול המודולרי: התקנה של מנוע GOWA בלבד ואימות החיבור. החל מגרסה v9, שרת ה-MCP ושרת ה-REST מאוחדים תחת הפקודה ./whatsapp rest. נקודת הקצה זמינה בתעבורת streamable HTTP בנתיב /mcp. ברירת המחדל היא http://localhost:3000/mcp. כשמוגדר APP_BASE_PATH, הנתיב הוא <base-path>/mcp. אין תהליך נפרד ואין תת-פקודה mcp. מכבים את נקודת הקצה עם MCP_ENABLED=false או --mcp-enabled=false (ברירת המחדל: מופעל). הסוכן מתחבר ישירות, ובוחר פעולה מתוך שבעה כלים מאוחדים באמצעות type או action.

#מה זה מנוע GOWA

מנוע GOWA (ראשי תיבות של go-whatsapp-web-multidevice) הוא פרויקט קוד פתוח הכתוב בשפת Go. בתיעוד הרשמי הכותרת היא Go WhatsApp, והפרויקט מוצג כבנוי לשימוש יעיל בזיכרון. המנוע מתחבר לפרוטוקול התקשורת הרב-מכשירי (Multi-Device) של וואטסאפ ופועל כמכשיר מקושר עצמאי. החל מגרסה v8, המנוע מאפשר לחבר ולנהל מספר חשבונות וואטסאפ במקביל על גבי אותו מופע שרת יחיד.

הפרויקט מזמין תמיכה דרך GitHub Sponsors. גם דיווח שגיאות שאפשר לשחזר, שיפור תיעוד והפצה של GOWA מסייעים לתחזוקה.

התיעוד המפורט נמצא ב-gowa-docs ועוקב אחרי main הממוזג, כולל שינויים שאחרי v9.7.0. בבינארי או בתג קונטיינר נעול בודקים את הערות השחרור ואת GET /app/info.

./whatsapp --help מציג את כל דגלי שורת הפקודה. ב-Windows: .\whatsapp.exe --help. ./whatsapp version מדפיס רק את מספר הגרסה. בתיעוד הרשמי הדוגמה היא 9.6.0.

בנייה ממקור דורשת Go 1.26.0 ומעלה. עיבוד מדיה דורש FFmpeg. חבילת webp מספקת את cwebp (מקודד), dwebp (מפענח) ו-webpmux (מחלץ פריימים). webpmux עם dwebp משמשים למדבקות WebP מונפשות. הפלטפורמות בתיעוד: Linux (x86_64, ARM64), macOS (Intel ו-Apple Silicon) ו-Windows (x86_64, מומלץ WSL). בתיעוד יש גם בנייה מוצלבת ל-Raspberry Pi או למכשיר ARM אחר בלי שרשרת כלי C: תג הבנייה purego בוחר מימוש SQLite ב-Go טהור. היעדים שם הם ARMv6 (Raspberry Pi Zero / 1) ו-ARMv7 32-bit (Raspberry Pi 2 / 3 / 4).

Docker חוסך התקנה של Go, FFmpeg ו-libwebp ישירות על המארח. בלי Docker, התלויות לפי התיעוד:

• ב-macOS: brew install ffmpeg webp, ואחר כך export CGO_CFLAGS_ALLOW="-Xpreprocessor".
• ב-Linux: sudo apt update, ואחר כך sudo apt install ffmpeg webp.
• ב-Windows, כש-WSL מומלץ: מתקינים את FFmpeg. מתקינים את libwebp, מחלצים אותו ומוסיפים את תיקיית bin ל-PATH. התיעוד מפנה גם אל התקנת WSL.

אם ב-macOS מופיעה השגיאה invalid flag in pkg-config --cflags: -Xpreprocessor, מריצים export CGO_CFLAGS_ALLOW="-Xpreprocessor".

הורדה מוכנה, עם תמיכה ב-ARM, ב-AMD64 וב-MCP: עמוד השחרורים, Docker Hub בתמונה aldinokemal2104/go-whatsapp-web-multidevice, ו-GitHub Container Registry בתמונה ghcr.io/aldinokemal/go-whatsapp-web-multidevice.

טעינת ההגדרות מתחילה מדגלי שורת הפקודה, ואחר כך חלים רוב משתני הסביבה. ערך סביבה שכבר מוגדר יכול לדרוס את הדגל התואם. קובץ .env ממלא רק משתנים שעדיין לא הוגדרו בסביבת התהליך.

דגלים מפורשים מנצחים בהגדרות MCP OAuth, ב---allow-unauthenticated, ב---trusted-origins, ב---chatwoot-webhook-allow-unsigned וב---webhook-all-device-receipts. מגדירים כל אפשרות במקום אחד. לדוגמה, WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true דורס --webhook-insecure-skip-verify=false.

כדי להגדיר משתני סביבה מתוך קובץ:

1. העתיקו את קובץ הדוגמה מתוך שורש המאגר: cp src/.env.example src/.env.
2. עדכנו את הערכים בקובץ src/.env לפי הצורך.
3. לחלופין, הגדירו את אותם המשתנים ישירות בסביבת הריצה של התהליך.

המנוע מספק:

• ממשק REST API מלא לשליחה וקבלה של הודעות, קבצים, אנשי קשר, מיקומים, סקרים, קישורים, עדכוני סטטוס ומדבקות, וגם העברת הודעה קיימת ב-POST /message/:message_id/forward. המפרט בקובץ docs/openapi.yaml, וכולל גם POST /send/interactive. נוסף צימוד Passkey: GET /app/passkey, POST /app/passkey/response, POST /app/passkey/confirm. ב-API יש גם POST /call/reject, ייצוא משתתפי קבוצה ל-CSV ב-GET /group/participants/export, ומידע על קבוצה מקישור ב-GET /group/info-from-link. תחת שיחה: הצמדה ב-POST /chat/:chat_jid/pin, הודעות נעלמות ב-POST /chat/:chat_jid/disappearing, ובקשת היסטוריה ישנה ב-POST /chat/:chat_jid/history. GET /app/metrics מאומת, בלי כותרת מכשיר, ומחזיר JSON (תהליך, זיכרון, דיסק, מספר מכשירים ומטא-נתוני אחסון), לא טקסט Prometheus. POST /user/presence/subscribe נרשם לעדכוני מחובר או לא מחובר של איש קשר, והם מגיעים באירוע presence. שליחת הנוכחות שלכם נשארת ב-POST /send/presence. GET /user/avatar מבחין בין 404 AVATAR_NOT_SET ל-403 AVATAR_HIDDEN. משתמשים בקוד השגיאה לפני שפוסלים תמונה שנשמרה במטמון. POST /send/interactive ניסיוני: כפתורי native-flow, בקשת מיקום וקרוסלת תמונות. השליחה מיידית בלבד ורק ב-REST, והתאימות אצל הנמען משתנה. הפירוט ב-docs/interactive-messages.md.
• ערוצי ניוזלטר: מעקב או ביטול מעקב, מטא-נתונים לפי JID או הזמנה, חיפוש במדריך, והורדת מדיה. הקריאה ב-GET /newsletter/messages, רענון מונים ב-GET /newsletter/message-updates, ומנויים מתחדשים למונים חיים ב-/newsletter/live-updates (GET, POST, DELETE). המנויים החיים נשמרים בזיכרון. אחרי הפעלה מחדש של השרת נרשמים שוב. אירועי המונים מגיעים כ-newsletter.message. נתיבים נוספים: GET /user/my/newsletters, POST /newsletter/follow, POST /newsletter/unfollow, GET /newsletter/info, GET /newsletter/directory, והורדת מדיה ב-GET /newsletter/messages/{server_id}/download.
• תזמון שליחת הודעות מובנה (Scheduled sends): אפשרות לשלוח כל הודעה במועד מאוחר יותר, באופן חד-פעמי או בחזרות יומיות, שבועיות או חודשיות. מוסיפים את השדות scheduled_at (בפורמט RFC3339) ו-timezone (בפורמט IANA) לבקשת השליחה. השדות recurrence, weekdays, day_of_month, end_at ו-occurrence_limit שולטים בהגדרות החזרה. תזמונים שורדים הפעלה מחדש של השרת וממתינים למכשיר אם הוא במצב לא מקוון. ניתן לצפות ברשימת התזמונים, לקבל תזמון בודד, להשהות, לחדש או לבטל אותם בנתיב /send/schedules. מופע שנכשל מנוסה שוב תחת אותו מזהה הודעה של וואטסאפ, כך ששליחה שאישור שלה אבד אינה יוצאת מחדש תחת זהות חדשה. גם ניסיון חוזר של סקר משתמש בסוד שנשמר. מופע בפרוטוקול החדש שנקטע בהפעלה מחדש ממשיך באותו אופן. ניסיונות במנגנון הישן עם תוצאה לא ידועה מדולגים או מסומנים ככישלון. אין בזה הבטחה למסירה של פעם אחת בדיוק.
• שרת MCP מובנה באותו תהליך של ./whatsapp rest, בנתיב /mcp, עם תמיכה אפשרית באימות OAuth 2.1. כש-OAuth פעיל, /mcp מקבל אסימון Bearer או את פרטי ה-Basic Auth. אימות ה-OAuth אינו חל על נתיבי ה-REST או על ממשק המשתמש. לקוח, פרוקסי הפוך, תת-נתיב ומודל האבטחה מתועדים ב-docs/mcp-oauth.md.
• שבעה כלי MCP מאוחדים. הסוכן בוחר התנהגות לפי type או action, במקום כלי נפרד לכל פעולה:

whatsapp_send מקבל גם את scheduled_at, timezone, recurrence, weekdays, day_of_month, end_at ו-occurrence_limit כדי לתזמן במקום לשלוח מיד. את התוצאה מנהלים עם whatsapp_schedule.

בפריסה מרובת מכשירים, כותרת X-Device-Id על חיבור לקוח ה-MCP בוחרת את המכשיר לכל קריאות הכלים באותו חיבור. בלי הכותרת נבחר מכשיר ברירת המחדל, כמו ב-REST. קריאה בודדת יכולה לעקוף זאת עם ארגומנט device_id.

דוגמה לחיבור לקוח MCP. הכותרות אופציונליות: Authorization רק כשמוגדר Basic Auth, ו-X-Device-Id רק בפריסה מרובת מכשירים.

{
  "mcpServers": {
    "whatsapp": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Basic dXNlcjpzZWNyZXQ=",
        "X-Device-Id": "628123456789"
      }
    }
  }
}

הגדרת מינימום ל-OAuth 2.1, עבור לקוח MCP מרוחק שאינו יכול לשלוח כותרת Basic Auth. ברירת המחדל כבויה:

APP_BASIC_AUTH=admin:replace-with-a-strong-password
MCP_ENABLED=true
MCP_OAUTH_ENABLED=true
MCP_OAUTH_ISSUER_URL=https://gowa.example.com

• ניהול מספר מכשירים דרך נקודות קצה ייעודיות תחת /devices. שיוך קריאת API למכשיר ספציפי נעשה באמצעות כותרת X-Device-Id או פרמטר device_id (כאשר רשום מכשיר אחד בלבד, הוא נבחר כברירת מחדל). שיוך חיבור WebSocket למכשיר מתבצע באמצעות /ws?device_id=<id>. ה-hub הנוכחי משדר אירועי לוח לכל המנויים המאומתים. הפרמטר אינו מבודד אירועים בין חשבונות. לאינטגרציה של יישום משתמשים ב-webhook נפרד לכל מכשיר.
• ממשק משתמש מקומי בדפדפן לצפייה במצב החיבור וסריקת קוד QR. החל מגרסה v9, לוח הבקרה הוא קובץ עצמאי gowa-ui.html במאגר aldinokemal/gowa-ui. השרת מוריד את המהדורה האחרונה בהפעלה, ושוב בכל APP_UI_UPDATE_INTERVAL (ברירת מחדל 3h), מוודא את חתימת ה-SHA-256, שומר במטמון תחת storages/ui/ ומגיש את הלוח בנתיב / מאחורי Basic Auth. APP_UI_ENABLED=false מחזיר באנר JSON (מצב API בלבד). APP_UI_REPO עוקב אחרי המהדורה האחרונה של המאגר, בלי נעילת גרסה. APP_UI_ASSET_SHA256 הוא הנעילה היחידה ל-build מסוים. כל מהדורה מפרסמת גם נכס .sha256. חתימת המהדורה מוכיחה שההורדה תואמת למה ש-GitHub מפרסם, לא את זהות מי שפרסם אותה. אפשר גם להפנות את APP_UI_REPO למזלג שבשליטתכם. בשרת מנותק מהרשת שמים קובץ gowa-ui.html שהורד מראש בנתיב storages/ui/index.html ומגדירים APP_UI_AUTO_UPDATE=false. אפשר גם לארח את הלוח בנפרד בכל מקום שמגיש קבצים סטטיים, ולהפנות אותו לכתובת השרת. הפרטים ב-README של gowa-ui.
• תמיכה בממשק מרוחק. CORS מתיר את הכותרות Authorization ו-X-Device-Id, כך שממשק במקור אחר, למשל gowa-ui, יכול לקרוא ל-API. GET /app/info מחזיר את גרסת היישום ואת מגבלות גודל המדיה. דפדפן אינו יכול להגדיר כותרות על WebSocket. כש-Basic Auth פעיל מעבירים /ws?device_id=<id>&authorization=<base64(user:pass)>. יש להשתמש ב-TLS, כי פרטי ההזדהות גלויים בכתובת. מקור null אינו מהימן: לוח שנפתח מכתובת file:// אינו יכול לבצע שינויים או לפתוח את /ws. מגישים אותו מ-GOWA (ברירת המחדל) או ממקור http או https שרשום ב-APP_TRUSTED_ORIGINS. תו כללי ב-CORS (*, כשהרשימה ריקה) אינו מאשר בקשות שמשנות מצב או את /ws. לוח במקור נפרד נרשם ב-APP_TRUSTED_ORIGINS או כמקור ספציפי ב-APP_CORS_ALLOWED_ORIGINS.
• תמיכה באימות Basic Auth עם אפשרות למספר משתמשים (APP_BASIC_AUTH). בחיבור שאינו loopback האימות נדרש, וכל רשומה כוללת שם משתמש וסיסמה. האזנה ל-loopback נשארת פתוחה לפיתוח מקומי. APP_ALLOW_UNAUTHENTICATED=true חושף את ה-API בלי Basic Auth גם מחוץ ל-loopback (לא מאובטח, מיועד לפרוקסי הפוך). ברירת המחדל false. אפשר גם להגביל האזנה לכתובת מקומית עם APP_HOST=127.0.0.1.
• פריסה תחת תת-נתיב עם APP_BASE_PATH או --base-path (לדוגמה /gowa). GET /health ציבורי ונרשם תמיד בשורש, גם כשמוגדר APP_BASE_PATH.
• מנגנון Webhooks להעברת אירועים בזמן אמת. WHATSAPP_WEBHOOK מקבל כתובת אחת או כמה כתובות מופרדות בפסיקים. הבקשות נחתמות ב-HMAC-SHA-256 בכותרת X-Hub-Signature-256. המפתח הישן שפורסם, secret, אינו בשימוש. אם לא הוגדר סוד, התהליך מייצר מפתח אקראי וכותב אזהרה. המפתח הזה משתנה בהפעלה מחדש, ואין להסתמך עליו אצל המקבל. ערך ריק או ערך שפורסם (secret, super-secret-key, your-private-key) מוחלף במפתח אקראי לתהליך. מפתח יציב, פעם אחת: openssl rand -hex 32, ואז --webhook-secret או WHATSAPP_WEBHOOK_SECRET. סכמות האירועים והחתימה ב-docs/webhook-payload.md.
• הגדרת Webhook עצמאי לכל מכשיר דרך ה-API באמצעות PATCH /devices/:device_id/webhook ובדיקתו דרך GET /devices/:device_id/webhook. כאשר מוגדר יעד ייעודי למכשיר, אירועי המכשיר נשלחים אליו, ובהיעדרו הם מועברים ל-Webhook הכללי (--webhook). שליחת מחרוזת ריקה ב-webhook_url מאפסת את ההגדרה. הגדרת WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true (או הדגל --webhook-device-merge-global=true) הופכת את יעד המכשיר לתוספת: הכתובות הכלליות ממשיכות לקבל את אירועי המכשיר, בחתימה של המפתח הכללי ולפי WHATSAPP_WEBHOOK_EVENTS, בעוד שלכתובת המכשיר נשארים מפתח ומסנן אירועים משלה.
• סינון אירועי Webhook באמצעות WHATSAPP_WEBHOOK_EVENTS או הדגל --webhook-events לפי רשימה מופרדת בפסיקים מתוך האירועים הזמינים: message, message.reaction, message.revoked, message.edited, message.ack, message.deleted, presence, chat_presence, group.participants, group.info, group.joined, label.edit, label.association, newsletter.joined, newsletter.left, newsletter.message, newsletter.mute, call.offer, device.logged_out, device.temporary_ban, device.reachout_timelock. presence הוא שינוי מחובר או לא מחובר אחרי הרשמה לנוכחות. group.info הוא שינוי שם הקבוצה. newsletter.message הוא עדכוני מונה חיים ממנוי פעיל ל-/newsletter/live-updates. device.logged_out כולל את סיבת הניתוק, device.temporary_ban הוא חסימה זמנית, ו-device.reachout_timelock הוא הגבלה על פתיחת שיחות חדשות. כאשר ההגדרה ריקה, מועברים כל האירועים. WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS=true (או --webhook-all-device-receipts) מעביר את כל אישורי המכשירים המקושרים. הצרכן מטפל בכפילויות ובעדכונים שלא לפי הסדר. ברירת המחדל false.
• סינון כתובות JID ב-Webhook באמצעות WHATSAPP_WEBHOOK_IGNORE_JIDS או --webhook-ignore-jids לדילוג על שיחות או שולחים מסוימים (תומך בתווים כלליים @g.us, @s.whatsapp.net, @lid ובכתובות JID מדויקות). הסינון הזה נפרד מ---webhook-events, שמסנן לפי סוג אירוע. לאינטגרציית Chatwoot יש משתנה נפרד: CHATWOOT_IGNORE_JIDS.
• אפשרות לביטול אימות תעודות TLS עבור Webhooks באמצעות WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true או --webhook-insecure-skip-verify=true. לפי התיעוד זה מיועד לסביבות פיתוח ובדיקה, או לרשת פנימית עם תעודה בחתימה עצמית. מנהרת Cloudflare אינה הופכת חיבור TLS יוצא בלי אימות לבטוח. בסביבת ייצור התיעוד מפנה לתעודת TLS תקפה, לדוגמה מ-Let's Encrypt. שגיאה אופיינית: tls: failed to verify certificate: x509: certificate signed by unknown authority.
• הגדרות נוכחות בעת חיבור דרך WHATSAPP_PRESENCE_ON_CONNECT או --presence-on-connect עם האפשרויות available (סימון החשבון כמחובר, משהה התראות בטלפון), unavailable (רישום השם מבלי לעבור למצב מחובר, שומר על התראות בטלפון, ברירת מחדל), או none (דילוג מלא על נוכחות: שם ה-push אינו נרשם, ואנשי קשר עשויים לראות - כשם). פולס נוכחות יומי מופעל כברירת מחדל באמצעות WHATSAPP_PRESENCE_PULSE_ENABLED=true או --presence-pulse-enabled=true. המרווח נשלט ב-WHATSAPP_PRESENCE_PULSE_INTERVAL או --presence-pulse-interval (ברירת מחדל 24h), ומשך השהייה במצב available לפני החזרה ל-unavailable נשלט ב-WHATSAPP_PRESENCE_PULSE_DURATION או --presence-pulse-duration (ברירת מחדל 5m).
• הורדת מדיה אוטומטית מהודעות נכנסות מופעלת כברירת מחדל (WHATSAPP_AUTO_DOWNLOAD_MEDIA=true), עם אפשרות להתעלם מהורדת מדיה של עדכוני סטטוס (status@broadcast) באמצעות WHATSAPP_IGNORE_STATUS_MEDIA=true. מיקומי האחסון ופקודות שמירה ידנית מתועדים ב-docs/media-storage.md.
• אימות חשבון מופעל כברירת מחדל (WHATSAPP_ACCOUNT_VALIDATION=true). מכבים אותו עם false או עם --account-validation=false.
• פרוקסי יוצא ל-WebSocket של וואטסאפ דרך WHATSAPP_PROXY, בפורמט SOCKS5, HTTP או HTTPS. לדוגמה: WHATSAPP_PROXY=socks5://user:pass@host:1080.
• אחסון נתוני הפעלה ומפתחות (Session Storage) על גבי מסד נתונים (DB_URI, ברירת המחדל היא file:storages/whatsapp.db). התיעוד מראה גם URI של PostgreSQL, לדוגמה postgres://user:pass@host/db. ב-URI של Postgres בלי sslmode (או PGSSLMODE) ברירת המחדל היא verify-full למארח מרוחק, ו-disable ליעדי loopback (localhost, 127.0.0.1, ::1) או ל-unix socket. sslmode=require שומר TLS בלי אימות. לאחסון סשנים ומפתחות ב-PostgreSQL מנוהל התיעוד מפנה אל docs/neon.md. אפשרות להפרדת מסד נתוני המפתחות באמצעות DB_KEYS_URI, עם אותה ברירת מחדל של sslmode. הגבלת חיבורי SQLite מקבילים לאחסון שיחות באמצעות CHAT_STORAGE_MAX_OPEN_CONNS (ברירת מחדל 5).
• אינטגרציית Chatwoot אופציונלית, כבויה כברירת מחדל (CHATWOOT_ENABLED=false). נתיבי Chatwoot נרשמים רק כשהיא מופעלת: POST /chatwoot/sync, GET /chatwoot/sync/status, GET /chatwoot/configs, GET ו-PUT ו-DELETE על /devices/:device_id/chatwoot/config, POST /chatwoot/webhook, ו-POST /chatwoot/webhook/:device_id. המדריך המלא הוא docs/chatwoot.md בתיעוד הרשמי. CHATWOOT_WEBHOOK_SECRET ריק דוחה את הקריאות. CHATWOOT_WEBHOOK_ALLOW_UNSIGNED=true (או --chatwoot-webhook-allow-unsigned) מקבל Webhook כשאין סוד. זה לא מאובטח, וברירת המחדל false. משתני CHATWOOT_* מופיעים בטבלה למטה.
• צומת קהילה ל-n8n: החבילה @aldinokemal2104/n8n-nodes-gowa. ב-n8n נכנסים ל-Settings, אחר כך Community Nodes, מזינים את שם החבילה ובוחרים Install.

[!IMPORTANT] מנוע GOWA אינו שירות ענן חיצוני ואינו WhatsApp Business API הרשמי של מטא. הוא מתנהג בדיוק כמו חיבור של WhatsApp Web בדפדפן נוסף, תחת רשימת "מכשירים מקושרים" בהגדרות הטלפון שלכם. לפי התיעוד הרשמי, הפרויקט אינו רשמי ואינו מסונף לוואטסאפ. לאינטגרציה נתמכת בסביבת ייצור, התיעוד מפנה אל WhatsApp Business Platform.

[!WARNING] מלכודות ושינויי גרסה קריטיים ב-GOWA:

1. החל מגרסה v6, הפעלת שרת ה-REST מחייבת לציין את תת-הפקודה rest, למשל ./whatsapp rest במקום ./whatsapp. באותה גרסה מצב MCP היה תת-פקודה נפרדת, ./whatsapp mcp.
2. החל מגרסה v7, קובצי ההרצה הבינאריים נבנים באמצעות GoReleaser וזמינים להורדה ישירות מעמוד השחרורים הרשמי.
3. החל מגרסה v8, בכל מופע המנהל יותר ממכשיר אחד, חובה להוסיף את הכותרת X-Device-Id או את הפרמטר device_id לקריאות ה-API כדי לשייך אותן לחשבון המתאים. כל מטעני ה-Webhook כוללים שדה עליון בשם device_id המזהה את המכשיר שקיבל את האירוע. דוגמה מהתיעוד:

העתק

{
  "event": "message",
  "device_id": "[email protected]",
  "payload": { ... }
}

4. החל מגרסה v9, שרת ה-MCP ושרת ה-REST מאוחדים תחת הפקודה rest. השרת פועל בנתיב /mcp, ותת-הפקודה הישנה mcp בוטלה לחלוטין. מעבר: ./whatsapp mcp מוחלף ב-./whatsapp rest, וכתובת ישנה http://localhost:8080/sse מוחלפת ב-http://localhost:3000/mcp.
5. החל מגרסה v9, ממשק המשתמש אינו כלול עוד במאגר הראשי אלא מנוהל כקובץ עצמאי gowa-ui.html במאגר aldinokemal/gowa-ui. בלי נעילת APP_UI_ASSET_SHA256 השרת עוקב אחרי המהדורה האחרונה.
6. יש להימנע משימוש באחסון מפתחות בזיכרון בלבד בסביבת עבודה קבועה, משום שאתחול השרת עלול לגרום לאובדן נתוני החיבור (Session) של וואטסאפ.
7. ב-WebSocket עם Basic Auth, פרטי authorization נמצאים בשאילתת הכתובת. בלי TLS הם חשופים. device_id בשאילתה אינו מבודד אירועי לוח בין חשבונות.
8. בטבלת כלי ה-MCP בתיעוד הרשמי מופיעים שבעה כלים, כולל whatsapp_newsletter. בסעיף המעבר ממצב MCP נפרד כתוב שהמעבר הוא מארבעים כלים גרעיניים אל חמישה כלים מאוחדים. זה לפי התיעוד הרשמי נכון ל-2026-11-02.
9. GET /user/my/groups מחזיר לכל היותר 500 קבוצות, בגלל מגבלה של פרוטוקול וואטסאפ. את המגבלה אוכפים שרתי וואטסאפ, לא ה-API הזה. התיעוד מפנה לקובץ group.go במאגר whatsmeow.
10. סוד ה-Webhook: בלי מפתח קבוע המקבל רואה חתימה שמשתנה בכל הפעלה מחדש. יוצרים מפתח עם openssl rand -hex 32.
11. Basic Auth נדרש כשההאזנה אינה על loopback. APP_ALLOW_UNAUTHENTICATED=true פותח את ה-API בלי אימות.
12. משתנה סביבה שמוגדר דורס בדרך כלל דגל תואם. הדגל המפורש מנצח רק בהגדרות MCP OAuth, ב---allow-unauthenticated, ב---trusted-origins, ב---chatwoot-webhook-allow-unsigned וב---webhook-all-device-receipts.
13. מנוי /newsletter/live-updates נשמר בזיכרון. אחרי הפעלה מחדש נרשמים מחדש.
14. תזמון חוזר תחת אותו מזהה הודעה. אין הבטחה למסירה של פעם אחת בדיוק.
15. URI של Postgres מרוחק בלי sslmode עובר ל-verify-full.

#מה הסוכן מסוגל לעשות לאחר החיבור

במסלול ההקמה המלא, הסוכן מקבל גישה לקטלוג כלים רחב:

• קריאה ומודיעין: שליפת רשימת שיחות אחרונות, קריאת הודעות בהקשר מלא, חיפוש טקסט חופשי בהיסטוריה, איתור שיחות שלא נענו, וסריקת קבוצות.
• שליחה ומולטימדיה: שליחת הודעות טקסט, תמונות, מסמכי PDF ו-Word, קטעי אודיו, סרטוני וידאו, מדבקות סטטיות ומונפשות (בפורמט WebP בגודל מדויק של 512x512, עד 500 KB ובמשך של עד 10 שניות), אנשי קשר, סקרים ופרסום עדכוני סטטוס. המנוע ממיר תמונות ל-WebP מתוך JPG, JPEG, PNG, WebP ו-GIF, משנה גודל אוטומטית ל-512x512 ושומר שקיפות ב-PNG. מדבקת WebP מונפשת שאינה עומדת בדרישות יש לשנות לפני ההעלאה. התיעוד מציין כלי כגון ezgif.com. המנוע כולל דחיסה של תמונות וסרטוני וידאו לפני שליחה. ב-MCP המובנה נוספות גם שליחת מיקום, קישור והעברה, דרך whatsapp_send.
• תיוג והפצה בקבוצות: תיוג משתמשים לפי מספר טלפון בטקסט ההודעה או בכיתוב של תמונה, וידאו או קובץ, וכן תיוג נסתר של חברי הקבוצה ללא הצגת המספרים בטקסט באמצעות שדה mentions או שימוש במילת המפתח @everyone לתיוג אוטומטי של כל המשתתפים. דוגמה מהתיעוד: Hello @628974812XXXX, @628974812XXXX.
• תזמון ואוטומציה: תזמון שליחת הודעות ישירות במנוע דרך scheduled_at ו-timezone (כולל חזרות יומיות, שבועיות או חודשיות, השהיה, חידוש וביטול ב-/send/schedules), או ניהול תזמונים מקומי במסד נתונים SQLite בשרת הפייתון במסלול המלא. מופע שנכשל במנוע חוזר תחת אותו מזהה הודעה, בלי הבטחה למסירה של פעם אחת בדיוק.
• ניהול וסדר: סימון הודעות כנקראו, סימון הודעות שמע והודעות קוליות ככאלו שהושמעו, הוספת תגובות רגש (Reactions), הצמדת שיחות, דחייה אוטומטית של שיחות קוליות וניהול הרשאות קבוצה. ב-MCP המובנה נוספות גם עריכה, ביטול, מחיקה, סימון בכוכב והסרת כוכב, והורדת מדיה, דרך whatsapp_message.
• ערוצי ניוזלטר ב-MCP המובנה: whatsapp_newsletter למעקב, למידע, למדריך, להודעות, לעדכון מונים ולמנוי חי. המנוי החי בזיכרון, ונרשמים אליו מחדש אחרי הפעלה מחדש של השרת.
• הודעות אינטראקטיביות ב-REST: POST /send/interactive ניסיוני, מיידי בלבד, ואינו כלי MCP. התאימות אצל הנמען משתנה.
• עיבוד מסמכים ומדיה: תמלול הודעות קוליות וקריאת תוכן מתוך קבצים מצורפים.

#למי הפתרון מתאים

• אנשי מקצוע ומפתחים העובדים עם מחשב לאורך היום ומעוניינים לרכז את הטיפול בהודעות מתוך סביבת העבודה.
• משתמשים שכבר נעזרים בסוכני פקודה דוגמת Claude Code או עורכי קוד כמו Cursor.
• ארגונים וצוותים המעוניינים לחבר מספר ייעודי, או לנהל מספר חשבונות במקביל באותו שרת, עבור תהליכי עבודה ואוטומציה פנימיים.

המערכת אינה מיועדת להפצת הודעות ספאם או דיוור המוני, פעולות אשר מנוגדות לתנאי השימוש של וואטסאפ ועלולות להוביל לחסימת המספר.

#תחנת העצירה הקריטית: סריקת הברקוד

גם כאשר מריצים את פקודת ההתקנה המלאה בהודעה אחת, תהליך ההקמה מחייב עצירה יזומה אחת: שלב סריקת קוד ה-QR מהטלפון הנייד.

הסוכן אינו יכול לנחש או לעקוף את מנגנון ההצפנה והאימות של וואטסאפ. לכן, הפרומפטים במדריך זה מתוכננים להקים את מנוע ה-Docker, להציג את כתובת הדפדפן ופרטי הגישה, לעצור ולהמתין לאישורכם שהמכשיר חובר בהצלחה. רק לאחר מכן ממשיך הסוכן בהקמת שרת ה-MCP ובחיבור הכלים.

בפרק הבא נסקור את דרישות הקדם שיש להכין על המחשב לפני העתקת ההודעה הראשונה.