# Whatsapp Agent

> בונה אוטומטית סוכן וואטסאפ חכם בעברית עם Kapso (WhatsApp Business), Gemini (LLM + tools), ו-Maton (Google Calendar / Zoom / Gmail / כל אינטגרציה). פורס ל-Vercel, מגדיר webhooks, מסנכרן ENV — בלי שאתה צריך לגעת בקונסול. השתמש בסקיל בכל פעם שמישהו מבקש: "בנה לי בוט וואטסאפ", "סוכן וואטסאפ", "WhatsApp agent", "תקבע פגישות מהוואטסאפ", או רוצה לחבר Kapso + Gemini + Maton יחד.

- Skill: `amichaiai/whatsapp-agent` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add amichaiai/whatsapp-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/amichaiai/whatsapp-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: amichaiai (https://skillmd.com/u/amichaiai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/amichaiai/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`):
```bash
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.

```bash
# רשימת חיבורים קיימים
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.

```bash
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
```bash
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
```bash
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 מעודכן
```bash
npx vercel deploy --prod --yes
```

### שלב 8 — Verification
```bash
# בריאות
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>
```