whatsapp-agent

WhatsApp Agent Builder（AI Master）

このスキルでできること

WhatsApp のスマートエージェントを自動で構築し、デプロイします：

• 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. API を使って Kapso と Maton から必要な ID を取得します
4. ENV を Vercel にプッシュします（CLI ではなく REST API）
5. 本番環境にデプロイします
6. 本番環境を参照する webhook を Kapso に作成します
7. /api/test を使ったテストでエンドツーエンドを検証します

必要な入力

開始する前に、3 つのキーと基本情報が必要です。不足しているものがあれば、開始前に簡潔に質問してください（質問は 1 つだけ！）。それ以外がすべて明確な場合に限り、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 — 前提条件の確認

node、npm、npx、接続済みの vercel CLI（npx vercel whoami）がインストールされていることを確認します。CLI が未接続の場合は、npx vercel login を実行するよう依頼してください。

ステップ 1 — フォルダーの作成とテンプレートのコピー

• フォルダーを作成します（存在しない場合）
• このスキルの templates/* をすべてフォルダーにコピーします（Next.js 15 + TypeScript の準備済みプロジェクトです）
• npm install
• ⚠️ 警告： ASCII 以外の文字（ヘブライ語、スペース）を含むフォルダーは作成しないでください。Next.js のビルドが失敗します。

ステップ 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 では OAuth が 2 段階必要です。まず read スコープで初回接続し、次に write スコープで再接続します。

# רשימת חיבורים קיימים
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）は、新しい接続を作成（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 — デプロイ

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 で再デプロイ

npx vercel deploy --prod --yes

ステップ 8 — 検証

# בריאות
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

形式とスタイル

エージェントの説明（system prompt）

• ヘブライ語のみ、ホルモズ風で率直な文体（30 語ではなく 3 行）
• North Star：AI Master Club、コミュニティ、ソーシャルネットワークでの活動
• 「בשמחה」／「בוודאי」／「אני אשמח」は使わない
• 実際の日付のみを使います（必ず get_current_time）

デフォルトの下書きについては、templates/lib/prompts.ts を参照してください。

ツール選択ルール

• 「Zoom ミーティング／ビデオ／オンライン」→ create_zoom_and_calendar_event
• 単に「ミーティング」→「対面ですか、それとも Zoom ですか？」と質問します
• 「対面／オフィス／カフェでのミーティング」→ create_calendar_event

すべてのツールについては、templates/lib/tools.ts を参照してください。

最初のビルドで分かった重要事項

1. Vercel serverless はバックグラウンドの promise を終了します — void processMessage(...) の fire-and-forget は使用しないでください。必ず await してください。
2. Kapso v2 の webhook payload は Meta と異なります — フィールドは単数形の message で、messages という名前の配列ではありません。lib/kapso.ts:extractTextMessages を参照してください。
3. Vercel Deployment Protection は webhooks をブロックします — Disabled にする（または custom domain を使用する）必要があります。
4. Maton の複数接続には、使用する OAuth を選択するための header Maton-Connection: <id> が必要です。
5. Zoom OAuth scopes — 最初のリクエストでは通常、read のみが付与されます。書き込み（ミーティングの作成／更新／削除）には、Maton に scopes meeting:write:meeting、meeting:write:meeting:admin を明示的にリクエストする必要があります。
6. Vercel の ENV は REST API ですぐに設定できます — CLI ではなく REST API を使用してください。
7. WhatsApp のテンプレート — 過去24時間以内に会話していない相手にメッセージを送る場合は必須です。Meta の承認が必要です（PENDING は約15分）。

リファレンス

• references/kapso.md — Kapso API エンドポイント、認証、webhook payload、署名検証
• references/gemini.md — Gemini の function calling、Node.js SDK、複数ターンのループ
• references/maton.md — Maton の接続と gateway、Zoom と Calendar のパス

テンプレート

templates/ には、デプロイ可能な Next.js プロジェクト一式が含まれています。内容は以下のとおりです。

• Webhook ハンドラー（app/api/whatsapp/webhook/route.ts）
• テスト用エンドポイント（app/api/test/route.ts）
• Gemini の複数ターンループ（lib/gemini.ts）
• ツールの宣言と実行処理（lib/tools.ts）
• Maton ラッパー（カレンダー用の lib/maton.ts、Zoom 用の lib/zoom.ts）
• Kapso ラッパー（lib/kapso.ts — メッセージの送信、署名の検証、Kapso v2 payload の抽出）
• ストレージ（local または upstash ドライバーを使用する lib/storage.ts）
• ブランドボイスのプロンプト（lib/prompts.ts）
• .env.example
• package.json、tsconfig.json、next.config.js

初回バージョンの対象外

• メディア（画像／音声／動画）→ 後で追加
• マルチテナント（各ユーザーが自分のカレンダーを使用）→ ユーザーごとの OAuth が必要
• 長期的な永続メモリ（Upstash）→ コードは用意済み。ドライバーを切り替えるだけです
• プッシュ通知による先回り（リマインダーの cron）→ Vercel Cron を追加

North Star のリマインダー

これは単なるツールではなく、クラブ向けのコンテンツ商品です。動作したら、必ず以下を提案してください。

• 実際の会話を30秒の動画にした LinkedIn 投稿
• Instagram Reel／TikTok の画面分割動画
• クラブイベント「ビジネス向け WhatsApp エージェントの作り方」（90分）
• 公開 GitHub テンプレートと、リードマグネットとしてのヘブライ語 README
• クラブ向けメール：月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>