whatsapp-agent

WhatsApp Agent Builder（AI Master）

此技能的功能

自动构建并部署智能 WhatsApp Agent：

• 通过 Kapso 接收 WhatsApp 消息（Webhook → Vercel 函数）
• 使用 Gemini Flash Lite 3.1 + function calling 进行思考
• 通过 Maton 管理 Google 日历 + Zoom（以及其他集成）
• 以 עמיחי שקל / AI Master 的口吻用希伯来语回复（霍尔木兹风格，直接，俱乐部的 North-Star）
• 保存对话历史（本地或 Upstash Redis）

此技能会执行所有步骤：

1. 在工作目录中创建 Next.js 项目
2. 从 templates/ 复制所有文件
3. 通过 Kapso 和 Maton 的 API 获取必要的 ID
4. 将 ENV 推送到 Vercel（REST API，而非 CLI）
5. 部署到生产环境
6. 在 Kapso 中创建指向生产环境的 webhook
7. 使用 /api/test 测试端到端流程并进行验证

所需输入

开始前，需要 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 集成（默认：Zoom + 日历）

自动化工作流

步骤 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 — 从 Kapso 获取 ID

通过 REST API（参见 references/kapso.md）：

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

提取：

• phone_number_id（数字，15 位）→ 用于 ENV
• business_account_id → 用于模板（可选）

步骤 3 — 发现 / 创建 Maton 连接（Zoom）

重要： Zoom 需要 2 个 OAuth 步骤 — 先使用 read scopes 建立初始 connection，然后使用 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 连接，但写入操作不起作用（code:4711, missing scopes）— 创建新的 connection（POST），并将新的 connection_id 保存为 MATON_ZOOM_CONNECTION_ID。代码会发送 header Maton-Connection: <id>，以绕过旧连接。

步骤 4 — 将 ENV 推送到 Vercel

不要使用 CLI（vercel env add）— 速度慢且会获取锁。请使用 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

必须： 禁用 Vercel Deployment Protection（否则 Kapso 会收到 401）。如果用户尚未关闭，请用 30 秒向其说明操作方法： https://vercel.com/<team>/<project>/settings/deployment-protection → Disabled。

除此之外，系统会自动阻止通过 CLI 关闭 protection — 需要用户手动操作。

步骤 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 — 它是 ENV 中的 KAPSO_WEBHOOK_SECRET。

Vercel 的稳定 URL：从 https://api.vercel.com/v9/projects/$PROJECT_ID/domains 获取（始终类似 <project>-<adjective>-<color>.vercel.app）。

步骤 7 — 使用更新后的 ENV 重新 Deploy

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

格式与风格

Agent 描述（system prompt）

• 仅使用希伯来语，霍尔木兹风格，直接简洁（3 行 > 30）
• North Star：AI Master Club 俱乐部、社群、社交媒体活动
• 不要使用“בשמחה” / “בוודאי” / “אני אשמח”
• 只使用真实日期（始终调用 get_current_time）

默认草稿参见 templates/lib/prompts.ts。

工具选择规则

• “Zoom / 视频 / online 会议” → create_zoom_and_calendar_event
• 只说“会议” → 询问“线下还是 Zoom？”
• “线下会议 / 办公室 / 咖啡馆” → create_calendar_event

所有工具参见 templates/lib/tools.ts。

首次构建的重要发现

1. Vercel serverless 会终止后台 promise——不要使用 void processMessage(...) 这种即发即忘的方式。务必 await。
2. Kapso v2 webhook payload 与 Meta 不同——使用单个 message 字段，而不是名为 messages 的数组。参见 lib/kapso.ts:extractTextMessages。
3. Vercel Deployment Protection 会阻止 webhooks——必须设为 Disabled（或使用 custom domain）。
4. Maton 多连接需要 header Maton-Connection: <id>，以选择要使用的 OAuth。
5. Zoom OAuth scopes——首次请求通常只会获得读取权限。要进行写入操作（创建／更新／删除会议），需向 Maton 明确请求 scopes：meeting:write:meeting、meeting:write:meeting:admin。
6. 在 Vercel 中设置 ENV 很快——使用 REST API，而不是 CLI。
7. WhatsApp 模板——如果要向 24 小时内没有与你交谈过的人发送消息，就必须使用模板。需要获得 Meta 批准（PENDING 约 15 分钟）。

参考资料

• references/kapso.md——Kapso API endpoints、身份验证、webhook payload、签名验证
• references/gemini.md——Gemini 函数调用、Node.js SDK、多轮循环
• references/maton.md——Maton connections + gateway、Zoom + Calendar 路径

模板

templates/ 包含一个完整的 Next.js 项目，可直接部署，其中包括：

• Webhook handler（app/api/whatsapp/webhook/route.ts）
• 测试 endpoint（app/api/test/route.ts）
• Gemini 多轮循环（lib/gemini.ts）
• 工具声明 + 执行器（lib/tools.ts）
• Maton wrappers（lib/maton.ts 用于日历，lib/zoom.ts 用于 Zoom）
• Kapso wrappers（lib/kapso.ts——发送消息 + verify signature + 提取 Kapso v2 payload）
• 存储（lib/storage.ts，支持 local 或 upstash 驱动程序）
• 品牌语气提示词（lib/prompts.ts）
• .env.example
• package.json、tsconfig.json、next.config.js

首个版本不包含的内容

• 媒体（图片／音频／视频）→ 后续添加
• 多租户（每位用户使用自己的日历）→ 需要为每位用户配置 OAuth
• 长期持久记忆（Upstash）→ 代码已准备好，只需更换驱动程序
• 主动推送（提醒 cron）→ 添加 Vercel Cron

北极星提醒

这不只是一个工具——它还是俱乐部的内容产品。完成后，务必提出：

• 发布一篇 LinkedIn 帖子，附上 30 秒真实对话视频
• 制作 Instagram Reels／TikTok 分屏视频
• 举办俱乐部活动“如何为你的业务构建 WhatsApp Agent”（90 分钟）
• 发布 GitHub 公共模板 + 希伯来语 README，作为 Lead Magnet
• 给俱乐部发送邮件：介绍每月节省 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>