WhatsApp bot

The WhatsApp bot receives messages through Kapso, a proxy for the Meta WhatsApp Cloud API, via a signed webhook, so you need a publicly reachable URL. Do the shared bot setup first. You also need:

A Kapso account with a connected WhatsApp Business number
A public URL that reaches the bot. During development, a tunnel such as ngrok gives your local port one

Step 1: Set up Kapso

Create a Kapso project and connect your WhatsApp Business phone number
Copy your API key and Phone Number ID
Configure a webhook pointing to your bot’s /webhook endpoint (the bot listens on port 3203 by default; override with BOT_SERVER_PORT)
Copy the webhook secret: Kapso signs every request with HMAC-SHA256, and the bot rejects requests with invalid signatures

Step 2: Add the credentials

In apps/bots/.env:

KAPSO_API_KEY=your_kapso_api_key
KAPSO_PHONE_NUMBER_ID=your_phone_number_id
KAPSO_WEBHOOK_SECRET=your_webhook_secret

WHATSAPP_PHONE_NUMBER (your number in E.164 format without the +, for example 15551234567) belongs in apps/api/.env, not here: the API uses it to build wa.me links.

Step 3: Start the bot

nx dev bot-whatsapp

Platform behavior

User-facing limits (no streaming, 4,096 characters, media) are in the WhatsApp guide. Two details matter when developing:

Commands are matched by text prefix. There is no native slash-command registration.
Images GAIA sends back over 5 MB arrive as documents.

Troubleshooting

Problem	Solution
Webhook returns 401/403	Verify `KAPSO_WEBHOOK_SECRET` matches the secret configured in Kapso
Bot doesn’t respond	Check the webhook URL is publicly reachable and points to `/webhook` on the bot’s port
Authentication fails	Check that `GAIA_BOT_API_KEY` is identical in `apps/bots/.env` and `apps/api/.env`, and the API is reachable

Start here

Everyday work

Go deeper

Reference

Step 1: Set up Kapso

Step 2: Add the credentials

Step 3: Start the bot

Platform behavior

Troubleshooting

​Step 1: Set up Kapso

​Step 2: Add the credentials

​Step 3: Start the bot

​Platform behavior

​Troubleshooting

Step 1: Set up Kapso

Step 2: Add the credentials

Step 3: Start the bot

Platform behavior

Troubleshooting