whatsapp-agent

WhatsApp Agent Builder (AI Master)

What this skill does

בונה ופורס אוטומטית סוכן וואטסאפ חכם:

• מקבל הודעות WhatsApp דרך Kapso (Webhook → Vercel function)
• חושב עם Gemini Flash Lite 3.1 + function calling
• מנהל יומן Google + Zoom (וכל אינטגרציה אחרת) דרך Maton
• עונה בעברית בקול של עמיחי שקל / AI Master (טון הורמוזי, ישיר, North-Star למועדון)
• שומר היסטוריית שיחה (local או Upstash Redis)

הסקיל מבצע את כל הצעדים:

1. יוצר פרויקט Next.js בתיקיית עבודה
2. מעתיק את כל הקבצים מ-templates/
3. שואב את ה-IDs ההכרחיים מ-Kapso ו-Maton דרך ה-API שלהם
4. דוחף ENV ל-Vercel (REST API, לא CLI)
5. פורס לפרודקשן
6. יוצר webhook ב-Kapso שמצביע על הפרודקשן
7. מאמת end-to-end עם בדיקת /api/test

Inputs נדרשים

לפני שמתחילים, צריך 3 מפתחות + פרטים בסיסיים. אם משהו חסר — שאל בקצרה (שאלה אחת!) לפני שמתחילים. השתמש ב-AskUserQuestion רק אם כל השאר ברור.

משתנה	מה זה	איך משיגים
KAPSO_API_KEY	מפתח Kapso	Kapso dashboard → Project Settings → API Keys
GEMINI_API_KEY	מפתח Gemini	https://aistudio.google.com/apikey
MATON_API_KEY	מפתח Maton	https://maton.ai dashboard → Settings
תיקיית פרויקט	איפה לבנות	ברירת מחדל: ~/projects/whatsapp-agent

אופציונלי:

• שם פרויקט ב-Vercel (ברירת מחדל: whatsapp-agent)
• איזה אינטגרציות מ-Maton להפעיל (ברירת מחדל: זום + יומן)

Workflow אוטומטי

שלב 0 — בדיקת prerequisites

ודא שמותקנים: node, npm, npx, vercel CLI מחובר (npx vercel whoami). אם CLI לא מחובר — בקש npx vercel login.

שלב 1 — יצירת תיקייה והעתקת templates

• צור תיקייה (אם לא קיימת)
• העתק את כל ה-templates/* של הסקיל לתוך התיקייה (זה Next.js 15 + TypeScript מוכן)
• npm install
• ⚠️ אזהרה: אל תיצור תיקייה עם תווים לא-ASCII (עברית, רווחים) — Next.js יישבר ב-build

שלב 2 — גילוי IDs מ-Kapso

דרך REST API (ראה references/kapso.md):

curl -H "X-API-Key: $KAPSO_API_KEY" "https://api.kapso.ai/api/v1/whatsapp_configs"

חלץ:

• phone_number_id (numeric, 15 ספרות) → ל-ENV
• business_account_id → לטמפלטים (אופציונלי)

שלב 3 — גילוי / יצירת חיבור Maton (Zoom)

קריטי: Zoom דורש 2 שלבי OAuth — connection ראשונית עם read scopes, ואז reconnection עם write scopes.

# רשימת חיבורים קיימים
curl -H "Authorization: Bearer $MATON_API_KEY" "https://api.maton.ai/connections"

# אם אין חיבור Zoom פעיל — צור חדש
curl -X POST -H "Authorization: Bearer $MATON_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.maton.ai/connections" -d '{"app":"zoom"}'

# קבל URL ל-OAuth
curl -H "Authorization: Bearer $MATON_API_KEY" \
  "https://api.maton.ai/connections/{connection_id}"

תן למשתמש את ה-URL → הוא יעבור OAuth → הסטטוס יהפוך ACTIVE.

אם יש כבר חיבור ACTIVE אבל ב-write לא עובד (code:4711, missing scopes) — צור connection חדש (POST) ושמור את ה-connection_id החדש כ-MATON_ZOOM_CONNECTION_ID. הקוד שולח header Maton-Connection: <id> כדי לעקוף את הישן.

שלב 4 — דחיפת ENV ל-Vercel

אל תשתמש ב-CLI (vercel env add) — איטי ומקבל locks. השתמש ב-REST API.

TOKEN=$(jq -r '.token' ~/Library/Application\ Support/com.vercel.cli/auth.json)
PROJECT_ID="..."  # אחרי vercel link
TEAM_ID="..."

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "https://api.vercel.com/v10/projects/$PROJECT_ID/env?teamId=$TEAM_ID" \
  -d '[{"key":"...","value":"...","type":"encrypted","target":["production"]}, ...]'

ENV נדרשים — ראה templates/.env.example.

שלב 5 — Deploy

npx vercel deploy --prod --yes

חובה: disable Vercel Deployment Protection (אחרת Kapso יקבל 401). אם המשתמש עוד לא כיבה — הסבר לו ב-30 שניות איך: https://vercel.com/<team>/<project>/settings/deployment-protection → Disabled.

חוץ מזה ה-system חוסם את כיבוי ה-protection דרך CLI אוטומטית — צריך מהמשתמש.

שלב 6 — יצירת Kapso webhook

curl -X POST -H "X-API-Key: $KAPSO_API_KEY" -H "Content-Type: application/json" \
  "https://api.kapso.ai/platform/v1/whatsapp/webhooks" \
  -d '{
    "whatsapp_webhook": {
      "url": "https://<vercel-stable-url>/api/whatsapp/webhook",
      "phone_number_id": "<phone_number_id>",
      "secret_key": "<generated-secret>",
      "webhook_type": "kapso",
      "events": ["whatsapp.message.received"]
    }
  }'

⚠️ שמור את ה-secret_key — זה ה-KAPSO_WEBHOOK_SECRET ב-ENV.

ה-URL היציב של Vercel: שלוף מ-https://api.vercel.com/v9/projects/$PROJECT_ID/domains (תמיד נראה כמו <project>-<adjective>-<color>.vercel.app).

שלב 7 — Re-deploy עם ENV מעודכן

npx vercel deploy --prod --yes

שלב 8 — Verification

# בריאות
curl https://<stable-url>/api/whatsapp/webhook
# → {"ok":true,"service":"whatsapp-agent"}

# בדיקת agent (בלי וואטסאפ)
curl "https://<stable-url>/api/test?phone=%2B972500000000&text=hi"
# → {"phone":"...","role":"user","reply":"..."}

הסבר למשתמש:

• שלח הודעה אמיתית ל-<display_phone_number> (מ-whatsapp_configs)
• צפייה בלוגים: Vercel dashboard → Logs

Format & Style

תיאור הסוכן (system prompt)

• עברית בלבד, סגנון הורמוזי-ישיר (3 שורות > 30)
• North Star: מועדון AI Master Club, קהילה, פעילות ברשתות
• בלי "בשמחה" / "בוודאי" / "אני אשמח"
• תאריכים אמיתיים בלבד (תמיד get_current_time)

ראה templates/lib/prompts.ts לטיוטת ברירת מחדל.

Tool selection rules

• "פגישת זום / וידאו / online" → create_zoom_and_calendar_event
• "פגישה" סתם → לשאול "פיזית או בזום?"
• "פגישה פיזית / במשרד / בקפה" → create_calendar_event

ראה templates/lib/tools.ts לכל הכלים.

גילויים חשובים מהבנייה הראשונה

1. Vercel serverless הורג background promises — לא להשתמש ב-void processMessage(...) fire-and-forget. תמיד await.
2. Kapso v2 webhook payload שונה מ-Meta — שדה אחד message (יחיד), לא array בשם messages. ראה lib/kapso.ts:extractTextMessages.
3. Vercel Deployment Protection חוסם webhooks — חובה Disabled (או custom domain).
4. Maton multi-connection דורש header Maton-Connection: <id> כדי לבחור איזה OAuth לשימוש.
5. Zoom OAuth scopes — בקשה ראשונה לרוב נותנת רק read. לכתיבה (create/update/delete meetings) צריך לבקש scopes מפורשות מ-Maton: meeting:write:meeting, meeting:write:meeting:admin.
6. ENV ב-Vercel מהר — REST API, לא CLI.
7. Templates של WhatsApp — חובה אם רוצים לשלוח הודעה למישהו שלא דיבר איתך ב-24 שעות. צריכים אישור Meta (PENDING ~ 15 דק').

רפרנסים

• references/kapso.md — Kapso API endpoints, auth, webhook payload, signature verification
• references/gemini.md — Gemini function calling, Node.js SDK, multi-turn loop
• references/maton.md — Maton connections + gateway, Zoom + Calendar paths

Templates

templates/ מכיל פרויקט Next.js שלם, מוכן לפריסה, כולל:

• Webhook handler (app/api/whatsapp/webhook/route.ts)
• Test endpoint (app/api/test/route.ts)
• Gemini multi-turn loop (lib/gemini.ts)
• Tool declarations + executors (lib/tools.ts)
• Maton wrappers (lib/maton.ts ליומן, lib/zoom.ts ל-Zoom)
• Kapso wrappers (lib/kapso.ts — שליחת הודעות + verify signature + extract Kapso v2 payload)
• Storage (lib/storage.ts עם driver local או upstash)
• Brand voice prompts (lib/prompts.ts)
• .env.example
• package.json, tsconfig.json, next.config.js

Out of scope לגרסה ראשונה

• מדיה (תמונות / אודיו / וידאו) → להוסיף בהמשך
• Multi-tenant (כל משתמש עם יומן משלו) → דורש OAuth per-user
• Persistent memory לטווח ארוך (Upstash) → קוד מוכן, רק להחליף driver
• Push proactivity (cron של תזכורות) → להוסיף Vercel Cron

North Star reminder

זה לא רק כלי — זה תוצר תוכן למועדון. אחרי שעובד, הצע תמיד:

• פוסט לינקדין עם וידאו 30 שניות של שיחה אמיתית
• ריל אינסטגרם / טיקטוק split-screen
• מפגש מועדון "איך בונים סוכן WhatsApp לעסק שלך" (90 דק')
• GitHub template ציבורי + README בעברית כ-Lead Magnet
• מייל למועדון: case study חיסכון של 10 פגישות/חודש

סיכום למשתמש בסוף

✅ Vercel: <stable-url>
✅ Kapso webhook: <id>
✅ Phone: <display_phone_number>
✅ ENV: 12+ keys טעונים
✅ Health check: 200
✅ Agent test: <reply preview>

📱 שלח עכשיו הודעה ל-<display_phone_number> ותראה איך זה רץ.
🪵 לוגים: <vercel-logs-url>