Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt

Use this file to discover all available pages before exploring further.

You have two ways to receive WhatsApp messages and events.

​
BSUID rollout

WhatsApp can now send identity without a phone number. Kapso exposes additive identity fields like business_scoped_user_id, parent_business_scoped_user_id, and username on the relevant payloads. If you consume inbound payloads, update your parser before assuming phone_number, wa_id, from, or to are always present.

BSUID migration guide

What changes, which fields were added, and what you need to adapt.

​
1. Kapso webhooks

Kapso sends structured webhook events when messages arrive, conversations change, or delivery status updates. Events include:
  • whatsapp.message.received - New message from customer
  • whatsapp.message.sent - Message sent to WhatsApp
  • whatsapp.message.delivered - Message delivered
  • whatsapp.message.read - Message read
  • whatsapp.conversation.created - New conversation
  • whatsapp.conversation.ended - Conversation ended
  • whatsapp.conversation.inactive - No activity for X minutes
Setup:
  1. Go to Webhooks documentation
  2. Configure webhook URL and events
  3. Receive structured JSON payloads

Full webhook documentation

Complete guide to webhook events, signatures, retries, and best practices.

​
2. Forward Meta webhooks

Alternatively, forward raw Meta webhooks directly to your server. This gives you the exact payload Meta sends, without Kapso’s processing layer. Forwarded Meta payloads can now include BSUID-only identity too. For the Meta-side rollout details, see Meta: business-scoped user IDs. Setup:
  1. Go to your WhatsApp configuration in Kapso dashboard
  2. Click Edit on your connected number
  3. Add your Webhook destination URL
  4. We’ll forward all Meta webhook events to your endpoint

​
Parse forwarded webhooks

Use the TypeScript SDK to parse raw Meta webhooks: 
import express from 'express';
import { normalizeWebhook } from '@kapso/whatsapp-cloud-api/server';

const app = express();

app.post('/webhook', express.json(), (req, res) => {
  // Parse webhook
  const events = normalizeWebhook(req.body);

  // Handle messages
  events.messages.forEach((message) => {
    console.log(message.type, message.kapso?.direction);
  });

  // Handle other events
  events.raw.accountAlerts?.forEach((alert) => {
    console.log('Account alert', alert.alertInfo?.alertType);
  });

  res.sendStatus(200);
});
normalizeWebhook() converts Meta’s payload to the same structure as messages.query(), adds kapso.direction, and keeps all raw fields under events.raw.