🏗️ פרק 4

ההודעה האחת, הקמת מערכת מלאה

זהו המסלול המומלץ והשלם ביותר. הודעה אחת מקיפה ומדויקת אשר מוזנת לסוכן ה-AI (בקלוד קוד, בלשונית Code של Claude Desktop או ב-Cursor Agent). הסוכן מבצע את כל הבדיקות הטכניות, מרים את מנוע ה-GOWA המקומי, מנחה אתכם לסרוק את הברקוד, בונה שרת FastMCP מלא בפייתון המכיל עשרות כלים מתקדמים, ומחבר את הכלים ישירות לסביבת העבודה שלכם.

לפי התיעוד הרשמי, החל מגרסה v9 של GOWA פקודת ההרצה היא rest בלבד, והיא מגישה הן את ממשק ה-REST והן את שרת ה-MCP המובנה בנתיב /mcp תחת אותו תהליך. שרת ה-MCP המובנה מאחד את הפעולות לשבעה כלים ראשיים (whatsapp_send, whatsapp_schedule, whatsapp_message, whatsapp_chat, whatsapp_group, whatsapp_app, whatsapp_newsletter). ההודעה מתוכננת כך שהסוכן מכבה את מנוע ה-MCP המובנה באמצעות MCP_ENABLED=false, ובונה במקומו שרת FastMCP מקיף ועשיר עם כלים ייעודיים לחיפוש, קריאה, תזמון, מדיה וניהול קבוצות. כמו כן, החל מגרסה v8 קיימת תמיכה מלאה בריבוי מכשירים תחת /devices, וכאשר מחובר מכשיר יחיד הוא משמש אוטומטית כברירת מחדל.

ברירת המחדל הרשמית מפעילה דופק נוכחות יומי: WHATSAPP_PRESENCE_PULSE_ENABLED=true, במרווח 24h, והחשבון נשאר available למשך 5m לפני חזרה ל-unavailable. בפרומפט שלהלן הדופק כבוי, כדי שהחשבון לא יסומן כמחובר מדי יום.

לפי התיעוד הרשמי נכון ל-2026-11-02, הפרויקט אינו רשמי ואינו קשור לוואטסאפ. כשנדרשת אינטגרציה נתמכת לפרודקשן, התיעוד מפנה אל WhatsApp Business Platform.

[!IMPORTANT] אין צורך לערוך את תוכן ההודעה. העתיקו את כל הטקסט מתוך הבלוק שלהלן, הדביקו אותו בחלון השיחה של קלוד קוד ולחצו Enter.

#מהלך ההתקנה האוטומטי

1. שלב 0: אימות סביבה: בדיקת גרסאות docker, docker compose, python3 וזמינות פורטים (3100 עבור GOWA, 3300 עבור שרת ה-MCP).
2. שלב 1: הרמת מנוע GOWA: יצירת קובץ docker-compose.yml, הגדרת סיסמת Basic Auth חזקה, מיפוי אחסון קבוע עבור storages/ ו-statics/, הפעלת הקונטיינר והצגת כתובת הדפדפן.
3. שלב 2: עצירה לסריקת QR: הסוכן עוצר את פעולתו וממתין שתסרקו את קוד ה-QR באפליקציית וואטסאפ בטלפון.
4. שלב 3: הקמת שרת FastMCP: בניית סביבת פייתון וירטואלית, הטמעת קטלוג הכלים המלא, חיבור מסד נתונים מקומי (SQLite) להודעות מתוזמנות ואוטומציות, ויצירת קובץ הנחיות CLAUDE.md.
5. שלב 4: רישום כלים מקומי: חיבור שרת ה-MCP לקלוד קוד, קלוד דסקטופ, קרסור וסביבות נוספות על גבי המחשב.
6. שלב 5: קונקטורים לענן (אופציונלי): הגדרת מנהרת Cloudflare מאובטחת עבור claude.ai או ChatGPT במידה ונדרשת גישה מחוץ למסוף המקומי.
7. שלב 6: אימות וסיכום: בדיקת זמינות הכלים ללא ביצוע שליחה בפועל.

#הגדרות סביבה ומלכודות נפוצות

#כלי ה-MCP המובנה

הכלים המובנים נגישים רק כש-MCP_ENABLED דולק. הסוכן בוחר פעולה דרך type או action:

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

• איבוד חיבור וקבצים באיתחול: לפי התיעוד הרשמי, חובה למפות את הנתיבים storages/ ו-statics/ אל אחסון קבוע במחשב המארח (כגון ./data:/app/storages ו-./statics:/app/statics). ב-storages/ נשמרים מסד הנתונים, מפתחות ההצפנה ומטמון הממשק, וב-statics/ נשמרים קבצי המדיה. שמירה בזיכרון בלבד תגרום לאובדן הסשן והמדיה בכל איתחול ותחייב סריקת QR מחדש. תמונת Docker כוללת את עיבוד המדיה, כך שאין צורך להתקין על המארח את Go, FFmpeg ו-libwebp. בבנייה מקוד המקור התיעוד דורש Go 1.26.0 או חדש יותר, וגם FFmpeg ו-libwebp. מיקומי אחסון המדיה ופקודות הניקוי הידניות מתוארים במסמך אחסון המדיה של הפרויקט.

• סדר הגדרות ומסד נתונים: לפי התיעוד הרשמי, ההגדרות מתחילות מדגלים, ואחר כך רוב משתני הסביבה חלים. ערך סביבה שמוגדר יכול לדרוס את הדגל התואם. קובץ .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. כדאי להגדיר כל אפשרות במקום אחד. ב-URI של PostgreSQL בלי sslmode (או PGSSLMODE) ברירת המחדל היא verify-full למארח מרוחק, ו-disable ליעדי loopback (localhost, 127.0.0.1, ::1) או לשקעי unix. sslmode=require שומר TLS בלי אימות. אותו כלל חל על DB_KEYS_URI. סשן ומפתחות יכולים להישמר ב-PostgreSQL מנוהל לפי מדריך Neon שבתיעוד. הפרומפט ממשיך לשמור קבצי SQLite דרך DB_URI בתוך storages/.

• הורדת ממשק הניהול ברשתות סגורות: החל מגרסה v9 לוח הבקרה מופרד, בקובץ יחיד gowa-ui.html מתוך המאגר aldinokemal/gowa-ui. השרת מוריד את ה-release האחרון בעלייה ובכל APP_UI_UPDATE_INTERVAL (ברירת מחדל 3h), בודק גיבוב SHA-256, שומר במטמון תחת storages/ui/ ומגיש בנתיב / מאחורי Basic Auth. הגיבוב מוכיח שההורדה תואמת למה ש-GitHub מפרסם, לא מי פרסם אותה. נעילת build מסוים נעשית עם APP_UI_ASSET_SHA256 (לכל release יש נכס .sha256), או בהפניית APP_UI_REPO ל-fork שבשליטתכם. בסביבה מנותקת רשת שומרים את הקובץ מראש בנתיב storages/ui/index.html ומגדירים APP_UI_AUTO_UPDATE=false. אפשר גם לארח את gowa-ui.html כאתר סטטי נפרד ולהפנות אותו לכתובת השרת, לפי ה-README של gowa-ui.

• תמיכה בריבוי מכשירים: החל מגרסה v8 קיימת תמיכה בחיבור מספר חשבונות תחת /devices. קריאות תלויות מכשיר דורשות כותרת X-Device-Id או פרמטר device_id. אם מחובר מכשיר יחיד, המערכת משתמשת בו כברירת מחדל. בחיבור MCP, כותרת X-Device-Id בוחרת את המכשיר לכל הקריאות באותו חיבור, וארגומנט device_id דורס אותה בקריאה בודדת. WebSocket מתוחם ב-/ws?device_id=<id>. הפרמטר מפעיל את תווכת המכשיר, אבל רכזת ה-WebSocket הנוכחית משדרת אירועי לוח בקרה לכל המנויים המאומתים, והפרמטר לא מבודד אירועים בין חשבונות. לאינטגרציה משתמשים ב-webhook לפי מכשיר. כש-Basic Auth פעיל, הדפדפן מעביר authorization=<base64(user:pass)> באותה כתובת, לכן משתמשים ב-TLS: האישור גלוי ב-URL. CORS מתיר את הכותרות Authorization ו-X-Device-Id. GET /app/info מחזיר את גרסת השרת ואת מגבלות גודל המדיה. בכל payload של webhook יש שדה עליון device_id שמזהה איזה מכשיר קיבל את האירוע.

• איחוד פקודת ההרצה ו-MCP בגרסה v9: פקודת ההרצה היא rest בלבד, והיא מגישה את ממשק ה-REST ואת שרת ה-MCP המובנה. הנתיב המלא הוא http://<host>:<port><base-path>/mcp (ברירת מחדל http://localhost:3000/mcp), בתעבורת streamable HTTP. כיבוי: MCP_ENABLED=false או --mcp-enabled=false. במעבר ממצב MCP נפרד ישן: ./whatsapp mcp הופך ל-./whatsapp rest, והנתיב http://localhost:8080/sse הופך ל-http://localhost:3000/mcp. ./whatsapp version מדפיס רק את מספר הגרסה. בתיעוד מופיעה לדוגמה 9.6.0. תיעוד GOWA המפורט עוקב אחרי main, כולל שינויים שאחרי v9.7.0. בתג או בבינארי נעולים בודקים את הערות הגרסה ואת GET /app/info. לפי התיעוד הרשמי נכון ל-2026-11-02, אותה פסקת מעבר אומרת ש-40 כלים גרנולריים אוחדו לחמישה כלים, והסוכן בוחר פעולה בשדה type או action. באותו עמוד טבלת הכלים המובנים מונה שבעה, כולל whatsapp_schedule ו-whatsapp_newsletter. הפרומפט ממשיך לכבות את ה-MCP המובנה ומסתמך על טבלת השבעה. כש-OAuth מופעל, /mcp מקבל טוקן Bearer או את Basic Auth. OAuth חל על /mcp בלבד. נתיבי REST והממשק נשארים עם Basic Auth.

• חשיפה מקומית: APP_HOST בתוך הקונטיינר הוא 0.0.0.0. פרסום הפורט על המארח נשאר 127.0.0.1:3100. GET /health ציבורי ותמיד רשום בשורש, גם כשמוגדר APP_BASE_PATH. Basic Auth חובה כשהשרת מאזין מחוץ ל-loopback, עם משתמש וסיסמה בכל רשומה. על loopback הממשק נשאר פתוח לפיתוח מקומי. APP_ALLOW_UNAUTHENTICATED=true חושף את ה-API בלי Basic Auth גם מחוץ ל-loopback, והתיעוד מסמן את זה כלא מאובטח ומיועד לפרוקסי הפוך. אם APP_CORS_ALLOWED_ORIGINS ריק, ברירת המחדל היא * וכל מקור מותר ב-CORS, אבל תו כללי לא מאשר בקשות שמשנות מצב או /ws. לוח בקרה בדומיין נפרד נרשם כמקור מפורש ב-APP_CORS_ALLOWED_ORIGINS או ב-APP_TRUSTED_ORIGINS. בקשות שמשנות מצב כוללות את מארח הבקשה ומקורות CORS מפורשים. פרוקסי הפוך שמשכתב Host צריך proxy_set_header Host $host, או APP_TRUSTED_PROXIES עם X-Forwarded-Host, או את המקור הציבורי ב-APP_TRUSTED_ORIGINS. מקורות כמו capacitor://localhost מותאמים כפי שנכתבו. null לא מהימן: gowa-ui שנפתח מכתובת file:// לא יכול לבצע שינויים או לפתוח /ws, ולכן מגישים אותו מ-gowa (ברירת המחדל) או ממקור http(s) שרשום ב-APP_TRUSTED_ORIGINS. מאחורי פרוקסי הפוך מגדירים APP_TRUSTED_PROXIES.

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

• תזמון הודעות מובנה: כל שליחה יכולה להידחות למועד אחד או לחזור במחזור יומי, שבועי או חודשי. מוסיפים scheduled_at (RFC3339) ו-timezone (IANA). חזרה נשלטת ב-recurrence, weekdays, day_of_month, end_at ו-occurrence_limit. הניהול בנקודות הקצה /send/schedules: רשימה, שליפה, השהיה, חידוש וביטול. ההודעות נשמרות במסד הנתונים, שורדות הפעלה מחדש וממתינות גם כשהמכשיר לא מקוון. מופע שנכשל מנוסה שוב תחת אותו מזהה הודעה של וואטסאפ, כדי ששליחה שאישור שלה אבד לא תישלח מחדש תחת זהות חדשה. ניסיונות חוזרים של סקר משתמשים באותו סוד שנשמר. מופעים בפרוטוקול החדש שהופסקו בהפעלה מחדש ממשיכים באותה דרך. ניסיונות ישנים עם תוצאה לא ידועה מדולגים או מסומנים ככישלון. זה לא מבטיח מסירה של פעם אחת בלבד.

• אזכורים בשליחה: בטקסט ההודעה ובהערות של תמונה, וידאו או קובץ כותבים @phoneNumber. אזכור רפאים מעביר מספרי טלפון בשדה mentions בלי @ גלוי בטקסט. המילה @everyone מאזכרת את כל משתתפי הקבוצה.

• ערוצים ומונים חיים: אפשר לעקוב או לבטל מעקב, לשלוף מטא דאטה לפי JID או הזמנה, לחפש במדריך הערוצים, ולהוריד מדיה מהודעת ערוץ. קריאה ב-/newsletter/messages, רענון מונים ב-/newsletter/message-updates, ומנויי מונים מתחדשים ב-/newsletter/live-updates. המנויים נשמרים בזיכרון. אחרי הפעלה מחדש נרשמים שוב. אירועי מונה מגיעים כ-webhook מסוג newsletter.message.

• מדדים, נוכחות של איש קשר, אווטאר והודעות אינטראקטיביות: GET /app/metrics מאומת ומחזיר JSON על תהליך, זיכרון, דיסק, מספר מכשירים ומטא דאטה של אחסון, בלי כותרת מכשיר. זה לא טקסט Prometheus. POST /user/presence/subscribe נרשם לעדכוני מחובר או לא מחובר של איש קשר, והם מגיעים באירוע webhook בשם presence. שליחת הנוכחות שלכם נשארת ב-/send/presence. GET /user/avatar מבחין בין 404 AVATAR_NOT_SET ל-403 AVATAR_HIDDEN. משתמשים בקוד השגיאה לפני שפוסלים תמונה מהמטמון. POST /send/interactive הוא ניסיוני, מיידי בלבד וזמין רק ב-REST, עבור כפתורי native-flow, בקשת מיקום וקרוסלת תמונות. התאמה לנמען משתנה. הפרומפט לא משתמש בנתיב הזה.

• Webhook לפי מכשיר ולפי אירוע: כתובת גלובלית נקבעת ב-WHATSAPP_WEBHOOK או ב---webhook. כשלמכשיר יש webhook משלו, האירועים שלו נשלחים לכתובת הזו. קוראים ב-GET /devices/:device_id/webhook ומעדכנים ב-PATCH /devices/:device_id/webhook עם webhook_url. מחרוזת ריקה ב-PATCH מוחקת את כתובת המכשיר ומחזירה את האירועים ל-webhook הגלובלי. WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true הופך את כתובת המכשיר לתוספת: הכתובות הגלובליות ממשיכות לקבל את אירועי המכשיר, בחתימה של הסוד הגלובלי ובסינון WHATSAPP_WEBHOOK_EVENTS, וכתובת המכשיר שומרת סוד וסינון משלה. אם WHATSAPP_WEBHOOK_EVENTS ריק, כל האירועים מועברים. ברירת המחדל הישנה secret לא בשימוש. בלי סוד, או עם ערך שפורסם (secret, super-secret-key, your-private-key), התהליך מייצר מפתח אקראי וכותב אזהרה. המפתח משתנה בהפעלה מחדש, ולכן מקלט לא צריך להסתמך עליו. מייצרים מפתח יציב פעם אחת עם openssl rand -hex 32. WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS=true מעביר את כל אישורי המסירה של המכשירים המקושרים, והצרכן מטפל בכפילויות ובעדכונים שלא לפי הסדר.

• סינון נמענים ב-webhook: WHATSAPP_WEBHOOK_IGNORE_JIDS מדלג על צ'אטים או שולחים לפני ההעברה, לדוגמה השתקת כל הקבוצות. נתמכים התווים הכלליים @g.us, @s.whatsapp.net ו-@lid, וגם JID מדויק. הסינון הזה נפרד מ-WHATSAPP_WEBHOOK_EVENTS. ל-Chatwoot יש הגדרה נפרדת, CHATWOOT_IGNORE_JIDS.
• TLS של webhook: אם מופיעה שגיאת tls: failed to verify certificate: x509: certificate signed by unknown authority, אפשר WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true או --webhook-insecure-skip-verify=true. לפי התיעוד הרשמי זה מכבה את אימות האישור, ומיועד לפיתוח ולבדיקות, או לרשת פנימית עם אישור בחתימה עצמית. מנהרת Cloudflare לא הופכת חיבור TLS יוצא בלי אימות לחיבור בטוח. בפרודקשן משתמשים באישור TLS תקין, לדוגמה מ-Let's Encrypt.
• Chatwoot ונקודות קצה נוספות: CHATWOOT_ENABLED כבוי כברירת מחדל (false). נתיבי Chatwoot נרשמים רק כשהוא דולק, והפרומפט משאיר אותו כבוי. כשהוא דולק, התיעוד כולל סנכרון היסטוריה (POST /chatwoot/sync, GET /chatwoot/sync/status), רשימת הגדרות (GET /chatwoot/configs), הגדרה לפי מכשיר (GET, PUT ו-DELETE על /devices/:device_id/chatwoot/config), ו-webhook לתשובות (POST /chatwoot/webhook ו-POST /chatwoot/webhook/:device_id). CHATWOOT_DEVICE_ID הוא גיבוי למכשיר יחיד או למשתנה סביבה. CHATWOOT_ALLOWED_HOSTS הוא רשימת מארחי Chatwoot מותרים להגדרות לפי מכשיר, כהגנת SSRF. חיבור בסיסי דורש CHATWOOT_URL, CHATWOOT_API_TOKEN, CHATWOOT_ACCOUNT_ID ו-CHATWOOT_INBOX_ID. מעבר לקטלוג שבפרומפט, התיעוד הרשמי כולל גם GET /app/passkey, POST /app/passkey/response ו-POST /app/passkey/confirm לצימוד passkey, לצד QR וקוד צימוד. מסלול הפרומפט נשאר סריקת QR. עוד בתיעוד: POST /chat/:chat_jid/history לבקשת היסטוריה ישנה יותר, ו-GET /newsletter/messages/{server_id}/download להורדת מדיה מהודעת ערוץ. התיעוד הרשמי מציין גם פרסום עדכוני סטטוס בוואטסאפ, בלי נקודת קצה נפרדת בטבלת ה-API.

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

• צומת n8n: לפי התיעוד הרשמי קיימת חבילת קהילה @aldinokemal2104/n8n-nodes-gowa. ב-n8n נכנסים ל-Settings, אחר כך ל-Community Nodes, מזינים את שם החבילה ובוחרים Install. מסלול הפרומפט לא מתקין אותה.
• מדבקות: תמונות JPG, JPEG, PNG, WebP ו-GIF מומרות ל-WebP בגודל 512x512, ושקיפות PNG נשמרת. מדבקת WebP מונפשת חייבת להיות בדיוק 512x512, מתחת ל-500KB, ולא יותר מ-10 שניות. אם היא חורגת, משנים גודל לפני ההעלאה, לדוגמה ב-ezgif.com. חבילת webp מספקת את cwebp, dwebp ו-webpmux. למדבקות מונפשות משמשים webpmux ו-dwebp, והם כלולים בנתיב ה-Docker.

#הפרומפט המלא להעתקה

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

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

אם אינך רץ בסביבה בעלת גישה לטרמינל מקומי (לדוגמה שיחת צ'אט רגילה בדפדפן): עצור מיד והנחה אותי להדביק את הפרומפט בתוך קלוד קוד.

============================================================
ארכיטקטורת המערכת
============================================================

המערכת מורכבת משני רכיבים עיקריים הפועלים בתיאום:

1. מנוע תקשורת WhatsApp Web בשם GOWA (go-whatsapp-web-multidevice), הרץ בתוך קונטיינר Docker רשמי במצב rest.
2. שרת MCP עצמאי המבוסס על FastMCP (בפייתון) העוטף את ממשק ה-REST של GOWA ומספק קטלוג כלים עשיר.

לפי התיעוד הרשמי, בגרסאות GOWA v9 שרת ה-MCP וממשק ה-REST אוחדו תחת פקודת rest אחת, ונתיב ה-MCP המובנה זמין ב-/mcp עם שבעה כלים מאוחדים, כולל whatsapp_newsletter. אנו מכבים רכיב זה (MCP_ENABLED=false או --mcp-enabled=false) וסביבת הפייתון מרימה שרת FastMCP ייעודי עם קטלוג מלא ומותאם בפורט 3300.
החל מגרסה GOWA v8 קיימת תמיכה מובנית בריבוי מכשירים דרך נתיבי /devices. כאשר מחובר מכשיר אחד בלבד, GOWA משתמשת בו כברירת מחדל ללא צורך במזהה מכשיר מפורש. ב-MCP המובנה כותרת X-Device-Id בוחרת מכשיר לכל הקריאות בחיבור, וארגומנט device_id דורס אותה בקריאה בודדת.
ברירת המחדל הרשמית מפעילה דופק נוכחות יומי (WHATSAPP_PRESENCE_PULSE_ENABLED=true) שמסמן את החשבון available למשך 5 דקות בכל 24 שעות. בפרומפט זה מכבים את הדופק.

שם השרת לתצוגה: Connecta WhatsApp
תיקיית העבודה: ~/gowa-ai (או התיקייה הנוכחית אם היא ייעודית וריקה)

============================================================
הנחיות אבטחה מחמירות
============================================================

- האזנה מקומית בלבד על 127.0.0.1 (איסור מוחלט על חשיפת 0.0.0.0 ל-GOWA או ל-MCP, למעט דרך מנהרה מוצפנת בעת הצורך). APP_HOST בתוך הקונטיינר נשאר 0.0.0.0, והמיפוי על המארח הוא 127.0.0.1 בלבד.
- יצירת סיסמת Basic Auth אקראית וחזקה ל-GOWA (איסור מוחלט על שימוש ב-admin:admin או סיסמאות ברירת מחדל).
- יצירת טוקן Bearer אקראי באורך 32 בתים לפחות ונתיב סודי עבור חיבורי מנהרה.
- הצגת הסיסמאות והטוקנים פעם אחת בלבד במסך, ושמירתם בקובץ .env מקומי בעל הרשאות מוגבלות (mode 600) המוחרג מ-git (.gitignore).
- שימוש ב-volumes קבועים עבור session storage של GOWA (מיפוי storages/ ו-statics/) כדי שהחיבור, מפתחות ההצפנה והמדיה יישמרו לאחר אתחול ולא יישמרו בזיכרון בלבד.
- הגדרת דגל --os או משתנה APP_OS עם שם מזהה ברור (לדוגמה: "Claude GOWA").
- ללא הגדרת Webhook ציבורי אוטונומי, ללא מענה אוטומטי (WHATSAPP_AUTO_REPLY=""), ללא סימון אוטומטי של הודעות כנקראו (WHATSAPP_AUTO_MARK_READ="false"), ללא דופק נוכחות יומי (WHATSAPP_PRESENCE_PULSE_ENABLED="false"), וללא פעולות דיוור המוני.
- תמונת Docker: aldinokemal2104/go-whatsapp-web-multidevice או ghcr.io/aldinokemal/go-whatsapp-web-multidevice בלבד.
- כלל ברזל לשליחת הודעות: לפני כל שיגור הודעה בוואטסאפ, חובה להציג למשתמש את תוכן ההודעה המדויק ואת שם הנמען, ולהמתין לאישור מפורש בשיחה. אין לבצע שליחה ללא אישור מראש.
- בדיקות מותרות להרצה עצמאית: בדיקות health, ספירת כלים, list_accounts (מול /devices) ו-list_chats לקריאה בלבד ללא הצגת תוכן שיחות פרטיות. GET /health של GOWA ציבורי ונשאר בשורש גם אם הוגדר APP_BASE_PATH.

============================================================
מבנה הקבצים הנדרש
============================================================

~/gowa-ai/
  docker-compose.yml     
# הגדרת שירות gowa
  .env                   
# הגדרות GOWA_BASIC_AUTH, MCP_BEARER, CONNECTOR_PATH (mode 600)
  .gitignore
  data/                  
# volume קבוע עבור אחסון GOWA (ממופה ל-app/storages/)
  statics/               
# volume קבוע עבור מדיה וקבצים סטטיים (ממופה ל-app/statics/)
  mcp/
    venv/                
# סביבת פייתון וירטואלית
    requirements.txt     
# mcp, httpx, uvicorn, starlette, pydantic
    gowa_client.py       
# לקוח REST מול GOWA עם Basic Auth
    store.py             
# מסד נתונים מקומי SQLite עבור תזמונים ואוטומציות
    server.py            
# שרת FastMCP עם מימוש כל הכלים
    jobs.py              
# מנגנון תזמון רקע
  CLAUDE.md              
# כללי הפרויקט וחובת אישור לפני שליחה
  README.md              
# תיעוד מקומי של הכתובות ואופן ההרצה

פורטים ברירת מחדל:
- GOWA REST & UI: 127.0.0.1:3100 -> קונטיינר 3000
- FastMCP Server: 127.0.0.1:3300

הגדרות GOWA ב-docker-compose.yml:
  image: aldinokemal2104/go-whatsapp-web-multidevice
  command: rest --port=3000 --basic-auth=... --os="Claude GOWA"
  environment:
    MCP_ENABLED: "false"
    APP_UI_ENABLED: "true"
    APP_UI_AUTO_UPDATE: "false"
    WHATSAPP_AUTO_REPLY: ""
    WHATSAPP_AUTO_MARK_READ: "false"
    WHATSAPP_ACCOUNT_VALIDATION: "false"
    WHATSAPP_PRESENCE_PULSE_ENABLED: "false"
  volumes:
    - ./data:/app/storages
    - ./statics:/app/statics
  restart: unless-stopped

הגדרות FastMCP ב-server.py:
  שם: "Connecta WhatsApp"
  כתובת: 127.0.0.1:3300
  stateless_http: True
  נתיבים:
    1) /mcp עם אימות Bearer (עבור סוכנים מקומיים)
    2) /{CONNECTOR_PATH}/mcp ללא כותרת (עבור מחברים בדפדפן, הנתיב משמש כאימות)
    3) /health בדיקת תקינות JSON

============================================================
קטלוג הכלים המלא למימוש
============================================================

כל הכלים ברשימה זו חייבים להיות ממומשים בשרת ה-FastMCP:

קריאה ומודיעין:
- list_accounts: רשימת חשבונות ומכשירים מחוברים (מול נתיב /devices)
- get_connection_health: סטטוס חיבור וזמינות וואטסאפ
- list_chats: רשימת שיחות אחרונות כולל זמנים והודעות אחרונות
- read_messages: קריאת הודעות בהקשר שיחה
- search_contacts: חיפוש אנשי קשר לפי שם או מספר
- get_last_interaction: פרטי האינטראקציה האחרונה מול איש קשר
- get_direct_chat_by_contact: איתור מזהה שיחה ישירה
- get_contact_chats: רשימת שיחות וקבוצות משותפות
- get_chat: מטא דאטה מורחב על שיחה
- get_message_context: קבלת הודעות לפני ואחרי הודעה ספציפית
- search_messages: חיפוש טקסט חופשי בהיסטוריית ההודעות
- get_activity_digest: סיכום שיחות פעילות והודעות הממתינות למענה
- get_unanswered_chats: רשימת שיחות בהן ההודעה האחרונה נכנסה ולא נענתה
- get_group_participants: רשימת משתתפים בקבוצה
- get_group_info: פרטי קבוצה
- get_group_info_from_link: פרטי קבוצה מתוך קישור הזמנה
- list_group_join_requests: בקשות הצטרפות ממתינות לקבוצה
- list_groups: רשימת כל הקבוצות בהן החשבון חבר (עד 500 קבוצות לפי מגבלת פרוטוקול וואטסאפ)
- list_newsletters: רשימת ערוצים וניוזלטרים במעקב
- get_newsletter_messages: קריאת הודעות מערוץ או ניוזלטר
- get_user_info: פרטי משתמש וואטסאפ
- get_business_profile: פרטי פרופיל עסקי
- get_my_privacy: הגדרות הפרטיות של החשבון
- check_on_whatsapp: בדיקה האם מספר טלפון רשום בוואטסאפ
- download_media: הורדת קובץ מדיה מהודעה
- get_media_link: הפקת קישור גישה מקומי למדיה שהורדה
- export_chat: ייצוא שיחה לקובץ טקסט או JSON לפי טווח תאריכים
- read_document: קריאת תוכן מתוך מסמכי PDF, Word ו-Excel
- transcribe_voice_message: תמלול הודעה קולית
- analyze_video: עיבוד וניתוח קובץ וידאו
- analyze_media: ניתוב אוטומטי לפי סוג המדיה

שליחה ונוכחות:
- send_message: שליחת הודעת טקסט לנמען
- send_image: שליחת תמונה עם כיתוב
- send_file: שליחת מסמך או קובץ כללי
- send_audio: שליחת קובץ אודיו או הודעה קולית
- send_video: שליחת סרטון וידאו
- send_sticker: שליחת מדבקה
- send_link: שליחת קישור עם תצוגה מקדימה
- send_location: שליחת מיקום על גבי מפה
- send_contact: שליחת כרטיס איש קשר (vCard)
- send_poll: יצירת סקר בקבוצה או בשיחה
- forward_message: העברת הודעה קיימת
- upload_chunk: העלאת קבצים בחלקים
- request_upload: הפקת קישור העלאה מקומי
- bridge_from_connector: העברת קבצים ממחברים אחרים
- hold_file: שמירת קובץ זמני
- list_held_files: רשימת קבצים מוחזקים
- send_chat_presence: שליחת חיווי הקלדה או הקלטה (typing או recording)
- set_presence: קביעת סטטוס נוכחות (available או unavailable)

תזמון ואוטומציה (בניהול מובנה מול GOWA ומסד נתונים מקומי):
- schedule_message: תזמון הודעה לשעה ותאריך מוגדרים (כולל שימוש בפרמטרי תזמון מובנים של GOWA)
- list_scheduled_messages: רשימת הודעות מתוזמנות הממתינות לשליחה
- pause_scheduled_message: השהיית הודעה מתוזמנת
- resume_scheduled_message: חידוש הודעה מתוזמנת שהושהתה
- cancel_scheduled_message: ביטול הודעה מתוזמנת
- create_automation: יצירת כלל אוטומציה מותאם
- list_automations: רשימת כללי אוטומציה
- set_automation_enabled: הפעלה או השבתה של כלל
- test_automation: בדיקת התאמת כלל ללא ביצוע שליחה
- delete_automation: מחיקת כלל אוטומציה

פעולות שיחה:
- mark_read: סימון שיחה או הודעה כנקראה
- mark_played: סימון הודעה קולית כהושמעה
- react_to_message: הוספת תגובת אימוג'י להודעה
- edit_message: עריכת הודעה שנשלחה
- revoke_message: ביטול הודעה שנשלחה (עבור כולם)
- delete_message: מחיקת הודעה מקומית
- reject_call: דחיית שיחה נכנסת
- star_message: סימון הודעה בכוכב
- unstar_message: ביטול סימון כוכב מהודעה
- pin_chat: הצמדת שיחה לראש הרשימה
- archive_chat: העברת שיחה לארכיון
- label_chat: הוספת תגית לשיחה
- set_disappearing_timer: קביעת טיימר להודעות זמניות

ניהול קבוצות:
- create_group: יצירת קבוצה חדשה
- group_invite_link: הפקת קישור הזמנה לקבוצה
- join_group_with_link: הצטרפות לקבוצה באמצעות קישור
- add_group_participants: הוספת משתתפים לקבוצה
- remove_group_participants: הסרת משתתפים מקבוצה
- promote_group_participants: מינוי משתתף למנהל קבוצה
- demote_group_participants: ביטול הרשאת מנהל למשתתף
- export_group_participants: ייצוא רשימת משתתפי קבוצה כקובץ CSV
- approve_group_join_requests: אישור בקשות הצטרפות
- reject_group_join_requests: דחיית בקשות הצטרפות
- set_group_name: שינוי שם הקבוצה
- set_group_topic: שינוי תיאור הקבוצה
- set_group_photo: עדכון תמונת הקבוצה
- set_group_locked: נעילת עריכת פרטי הקבוצה למנהלים בלבד
- set_group_announce: הגבלת שליחת הודעות בקבוצה למנהלים בלבד
- leave_group: עזיבת קבוצה

פרופיל וערוצים:
- set_my_avatar: עדכון תמונת הפרופיל של החשבון
- set_my_pushname: עדכון שם התצוגה (Push Name) של החשבון
- unfollow_newsletter: ביטול מעקב אחר ערוץ

============================================================
שלבי הביצוע המדויקים
============================================================

שלב 0: בדיקת דרישות קדם
- בדוק גרסאות docker, docker compose, python3 ו-curl.
- בדוק זמינות פורטים 3100 ו-3300. אם תפוסים, בחר פורטים פנויים ועדכן אותי.
- אם Docker אינו רץ, עצור והסבר לי כיצד להפעיל אותו בהתאם למערכת ההפעלה.

שלב 1: פריסת מנוע GOWA
- צור את תיקיית העבודה, קובץ .env, docker-compose.yml ותיקיות data/ ו-statics/.
- הרץ docker compose pull ו-docker compose up -d.
- ודא שהקונטיינר הגיע למצב healthy.
- הצג לי במפורש: כתובת דפדפן (http://127.0.0.1:3100), שם משתמש וסיסמה.
- עצור כאן! אל תמשיך להקמת שרת ה-MCP לפני שאישרתי שהברקוד נסרק והמכשיר מחובר.

שלב 2: אימות חיבור וואטסאפ (לאחר אישורי)
- בצע בדיקת GET מול /app/status או /devices לוודא שהמכשיר מחובר (logged in).
- אם אינו מחובר, דווח מה חסר והמתן.

שלב 3: הקמת שרת FastMCP
- הקם סביבת פייתון וירטואלית (venv), התקן תלויות וממש את כל הקבצים והכלים.
- הטמע לולאת רקע לתזמון הודעות וניהול תזמונים מול GOWA.
- הגדר שירות systemd --user או הרצה מנוהלת כדי שהשרת ימשיך לפעול ברקע.
- צור קובץ CLAUDE.md בתיקייה עם כלל הברזל: אישור מפורש לפני כל שליחה.
- בצע בדיקת כמות כלים ואמת שכל הכלים מופיעים בשרת.

שלב 4: רישום מקומי של השרת
- קלוד קוד: הוסף שרת באמצעות claude mcp add --transport http whatsapp http://127.0.0.1:3300/mcp --header "Authorization: Bearer <TOKEN>".
- קלוד דסקטופ: רשום בקובץ claude_desktop_config.json המתאים למערכת ההפעלה.
- קרסור: רשום בקובץ ~/.cursor/mcp.json של המשתמש.

שלב 5: חיבורי דפדפן ומנהרה (במידת הצורך)
- הפעל מנהרת Cloudflare Tunnel (במידת הצורך) המכוונת ל-http://127.0.0.1:3300.
- ודא שהנתיב המרוחק כולל את ה-CONNECTOR_PATH הסודי.
- ספק לי את הכתובת והנחיות הרישום עבור claude.ai, ChatGPT או Grok.

שלב 6: סיכום ואימות
- הצג טבלת כתובות וסטטוס של כל רכיב.
- הצג את מספר הכלים שהותקנו.
- ספק משפט בדיקה מומלץ להעתקה לצורך אימות קריאת נתונים.

התחל כעת בשלב 0.

#מה קורה לאחר שליחת הפרומפט

לאחר שתדביקו את ההודעה, קלוד קוד יחל בסדרת בדיקות ויקים את תשתית ה-Docker.

בסיום שלב 1 יוצגו בפניכם:

• כתובת הדפדפן (ברירת מחדל: http://127.0.0.1:3100)
• שם המשתמש והסיסמה הזמנית שנוצרה
• הנחיה מפורשת לפתוח את הדפדפן ולסרוק את קוד ה-QR מהטלפון

לוח הבקרה בנתיב / הוא קובץ gowa-ui שהקונטיינר מגיש מהמטמון. בפרומפט עדכון אוטומטי של הלוח כבוי (APP_UI_AUTO_UPDATE=false). אם הלוח חסר כי אין גישה ל-GitHub, מניחים מראש את gowa-ui.html בנתיב storages/ui/index.html (אצלכם: data/ui/index.html). אפשר גם לארח את אותו קובץ כאתר סטטי נפרד ולהפנות אותו לכתובת השרת, לפי ה-README של gowa-ui.

לאחר שתסרקו את הברקוד ותוודאו שהמכשיר מופיע כמחובר, השיבו לקלוד בטרמינל:

הברקוד נסרק בהצלחה והמספר מחובר. אפשר להמשיך לשלב 2.

הסוכן ימשיך באופן אוטומטי בהקמת שרת ה-FastMCP, בהגדרת הכלים ובחיבורם לקלוד קוד.

בפרק הבא נציג את המסלול המודולרי עבור מי שמעוניין בהתקנת מנוע GOWA בלבד.