SuperAPI AI Directory
Partner中文AI newsFavorites
Skillswhatsapp-agent

whatsapp-agent

Agents & models

View repository

Updated 10-15 17:30

About this skill

WhatsApp Agent Builder (AI Master)

What this skill does

Automatically builds and deploys a smart WhatsApp agent:

  • Receives WhatsApp messages through Kapso (Webhook → Vercel function)
  • Thinks with Gemini Flash Lite 3.1 + function calling
  • Manages Google Calendar + Zoom (and any other integration) through Maton
  • Responds in Hebrew in the voice of Amichai Shaked / AI Master (humorous tone, direct, North-Star for the club)
  • Saves conversation history (local or Upstash Redis)

The skill Performs all the steps:

  1. Creates a Next.js project in a working directory
  2. Copies all the files fromtemplates/
  3. Retrieves the necessary IDs from Kapso and Maton through their API
  4. Pushes ENV to Vercel (REST API, not CLI)
  5. Deploys to production
  6. Creates a webhook in Kapso that points to the production
  7. Verifies end-to-end with a test of /api/test

Required Inputs

Before starting, 3 keys + basic details are needed. If something is missing — ask briefly (one question!) before starting. Use AskUserQuestion only if everything else is clear.

Variable What it is How to obtain it
KAPSO_API_KEY Kapso key Kapso dashboard → Project Settings → API Keys
GEMINI_API_KEY Gemini key https://aistudio.google.com/apikey
MATON_API_KEY Maton key https://maton.ai dashboard → Settings
Project folder Where to build Default: ~/projects/whatsapp-agent

Optional:

  • Project name in Vercel (default: whatsapp-agent)
  • Which integrations from Maton to enable (default: Zoom + Calendar)

Automatic Workflow

Stage 0 — prerequisites check

Make sure these are installed: node, npm, npx, vercel CLI is connected (npx vercel whoami). If the CLI is not connected — request npx vercel login.

Stage 1 — creating a folder and copying templates

  • Create a folder (if it does not exist)
  • Copy all thetemplates/* of the skill into the folder (this is Next.js 15 + TypeScript ready)
  • npm install
  • ⚠️ Warning: Do not create a folder with non-ASCII characters (Hebrew, spaces) — Next.js will break at build

Stage 2 — discovering IDs from Kapso

Through REST API (see references/kapso.md):

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

Extract:

  • phone_number_id (numeric, 15 digits) → to ENV
  • business_account_id → to templates (optional)

Stage 3 — discovering / creating a Maton connection (Zoom)

Critical: Zoom requires 2 stages of OAuth — an initial connection with read scopes, and then a reconnection with 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}"

Give the user the URL → they will go through OAuth → the status will become ACTIVE.

If there is already an ACTIVE connection but write does not work (code:4711, missing scopes) — create a new connection (POST) and save theconnection_id new one asMATON_ZOOM_CONNECTION_ID. The code sends header Maton-Connection: <id> to bypass the old one.

Step 4 — Push ENV to Vercel

Do not use the CLI (vercel env add) — slow and gets locks. Use the 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"]}, ...]'

Required ENV — see templates/.env.example.

Step 5 — Deploy

npx vercel deploy --prod --yes

Mandatory: disable Vercel Deployment Protection (otherwise Kapso will get 401). If the user hasn't disabled it yet — explain to them in 30 seconds how: https://vercel.com/<team>/<project>/settings/deployment-protection → Disabled.

Besides that, the system blocks disabling protection via CLI automatically — it needs to come from the user.

Step 6 — Create 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"]
    }
  }'

⚠️ Save thesecret_key — this is theKAPSO_WEBHOOK_SECRET ב-ENV.

The stable Vercel URL: fetch fromhttps://api.vercel.com/v9/projects/$PROJECT_ID/domains (always looks like <project>-<adjective>-<color>.vercel.app).

Step 7 — Re-deploy with updated ENV

npx vercel deploy --prod --yes

Step 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":"..."}

Explain to the user:

  • Send a real message to<display_phone_number> (מ-whatsapp_configs)
  • Viewing logs: Vercel dashboard → Logs

Format & Style

Agent description (system prompt)

  • Hebrew only, direct-humorous style (3 lines > 30)
  • North Star: AI Master Club club, community, activity on social networks
  • No "gladly" / "certainly" / "I'd be happy to"
  • Real dates only (always get_current_time)

See templates/lib/prompts.ts for a default draft.

Tool selection rules

  • "Zoom / video / online meeting" → create_zoom_and_calendar_event
  • "Meeting" plain → ask "physical or Zoom?"
  • "Physical / office / cafe meeting" → create_calendar_event

See templates/lib/tools.ts for all the tools.

Important discoveries from the first build

  1. Vercel serverless kills background promises — do not usevoid processMessage(...) fire-and-forget. Always await.
  2. Kapso v2 webhook payload differs from Meta — one field message (singular), not an array named messages. See lib/kapso.ts:extractTextMessages.
  3. Vercel Deployment Protection blocks webhooks — must be Disabled (or custom domain).
  4. Maton multi-connection requires header Maton-Connection: <id> to choose which OAuth to use.
  5. Zoom OAuth scopes — the first request usually gives only read. For writing (create/update/delete meetings) you need to request explicit scopes from Maton: meeting:write:meeting, meeting:write:meeting:admin.
  6. ENV in Vercel quickly — REST API, not CLI.
  7. WhatsApp Templates — mandatory if you want to send a message to someone who hasn't talked to you in 24 hours. They need Meta approval (PENDING ~ 15 min).

References

  • 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/ contains a complete Next.js project, ready to deploy, including:

  • 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 for the calendar, lib/zoom.ts ל-Zoom)
  • Kapso wrappers (lib/kapso.ts — sending messages + verify signature + extract Kapso v2 payload)
  • Storage (lib/storage.ts with driver local or upstash)
  • Brand voice prompts (lib/prompts.ts)
  • .env.example
  • package.json, tsconfig.json, next.config.js

Out of scope for first version

  • Media (images / audio / video) → add later
  • Multi-tenant (each user with their own calendar) → requires OAuth per-user
  • Persistent long-term memory (Upstash) → code ready, just switch driver
  • Push proactivity (reminders cron) → add Vercel Cron

North Star reminder

It's not just a tool — it's content asset for the club. Once it works, always suggest:

  • LinkedIn post with a 30-second video of a real conversation
  • Instagram Reel / TikTok split-screen
  • Club meetup "How to build a WhatsApp agent for your business" (90 min)
  • Public GitHub template + Hebrew README as a Lead Magnet
  • Email to the club: case study saving of 10 meetings/month

Summary to the user at the end

✅ 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>