Integrate Whatsapp

Integrate WhatsApp

Setup

Preferred path:

• Kapso CLI installed and authenticated (kapso login)
• Use kapso status to confirm project access before onboarding or messaging

Fallback path: Env vars:

• KAPSO_API_BASE_URL (host only, no /platform/v1)
• KAPSO_API_KEY
• META_GRAPH_VERSION (optional, default v24.0)

Auth header (direct API calls):

X-API-Key: <api_key>

Install deps (once):

npm i

Connect WhatsApp (setup links)

Preferred onboarding path (CLI):

1. Start onboarding: kapso setup
2. If setup is blocked, resolve context with:

• kapso projects list
• kapso projects use <project-id>
• kapso customers list
• kapso customers new --name "<customer-name>" --external-id <external-id>
• kapso setup --customer <customer-id>

1. Complete the hosted onboarding URL
2. Confirm connected numbers: kapso whatsapp numbers list --output json
3. Resolve the exact number you want to operate: kapso whatsapp numbers resolve --phone-number "<display-number>" --output json

Fallback onboarding flow (direct API):

1. Create customer: POST /platform/v1/customers
2. Generate setup link: POST /platform/v1/customers/:id/setup_links
3. Customer completes embedded signup
4. Use phone_number_id to send messages and configure webhooks

Detect connection:

• Project webhook whatsapp.phone_number.created (recommended)
• Success redirect URL query params (use for frontend UX)

Recommended Kapso setup-link defaults:

{
  "setup_link": {
    "allowed_connection_types": ["dedicated"],
    "provision_phone_number": true,
    "phone_number_country_isos": ["US"]
  }
}

Notes:

• kapso setup and kapso whatsapp numbers new use dedicated plus provisioning by default.
• Keep phone_number_country_isos, phone_number_area_code, language, and redirect URLs as optional overrides.

• Platform API base: /platform/v1
• Meta proxy base: /meta/whatsapp/v24.0 (messaging, templates, media)
• Use phone_number_id as the primary WhatsApp identifier

Receive events (webhooks)

Use webhooks to receive:

• Project events (connection lifecycle, workflow events)
• Phone-number events (messages, conversations, delivery status)

Scope rules:

• Project webhooks: only project-level events (connection lifecycle, workflow events)
• Phone-number webhooks: only WhatsApp message + conversation events for that phone_number_id
• WhatsApp message/conversation events (whatsapp.message.*, whatsapp.conversation.*) are phone-number only

Create a webhook:

• Project-level: node scripts/create.js --scope project --url <https://...> --events <csv>
• Phone-number: node scripts/create.js --phone-number-id <id> --url <https://...> --events <csv>

Common flags for create/update:

• --url <https://...> - webhook destination
• --events <csv|json-array> - event types (Kapso webhooks)
• --kind <kapso|meta> - Kapso (event-based) vs raw Meta forwarding
• --payload-version <v1|v2> - payload format (v2 recommended)
• --buffer-enabled <true|false> - enable buffering for whatsapp.message.received
• --buffer-window-seconds <n> - 1-60 seconds
• --max-buffer-size <n> - 1-100
• --active <true|false> - enable/disable

Test delivery:

node scripts/test.js --webhook-id <id>

Always verify signatures. See:

• references/webhooks-overview.md
• references/webhooks-reference.md

Send and read messages

Discover IDs first

Two Meta IDs are needed for different operations:

Operate with the CLI first

Common commands:

kapso whatsapp numbers list --output json
kapso whatsapp numbers resolve --phone-number "<display-number>" --output json
kapso whatsapp messages send --phone-number-id <PHONE_NUMBER_ID> --to <wa-id> --text "Hello from Kapso"
kapso whatsapp messages list --phone-number-id <PHONE_NUMBER_ID> --limit 50 --output json
kapso whatsapp messages get <MESSAGE_ID> --phone-number-id <PHONE_NUMBER_ID> --output json
kapso whatsapp conversations list --phone-number-id <PHONE_NUMBER_ID> --output json
kapso whatsapp templates list --phone-number-id <PHONE_NUMBER_ID> --output json
kapso whatsapp templates get <TEMPLATE_ID> --phone-number-id <PHONE_NUMBER_ID> --output json

SDK setup

Install:

npm install @kapso/whatsapp-cloud-api

Create client:

import { WhatsAppClient } from "@kapso/whatsapp-cloud-api";

const client = new WhatsAppClient({
  baseUrl: "https://api.kapso.ai/meta/whatsapp",
  kapsoApiKey: process.env.KAPSO_API_KEY!
});

Send a text message

Via SDK:

await client.messages.sendText({
  phoneNumberId: "<PHONE_NUMBER_ID>",
  to: "+15551234567",
  body: "Hello from Kapso"
});

Send a template message

1. Discover IDs: node scripts/list-platform-phone-numbers.mjs
2. Draft template payload from assets/template-utility-order-status-update.json
3. Create: node scripts/create-template.mjs --business-account-id <WABA_ID> --file <payload.json>
4. Check status: node scripts/template-status.mjs --business-account-id <WABA_ID> --name <name>
5. Send: node scripts/send-template.mjs --phone-number-id <ID> --file <send-payload.json>

Send an interactive message

Interactive messages require an active 24-hour session window. For outbound notifications outside the window, use templates.

1. Discover phone_number_id
2. Pick payload from assets/send-interactive-*.json
3. Send: node scripts/send-interactive.mjs --phone-number-id <ID> --file <payload.json>

For a contact information request, use interactive.type: "request_contact_info" with action.name: "request_contact_info". Include body, but omit header and footer.

Read inbox data

Preferred path:

• CLI: kapso whatsapp messages ..., kapso whatsapp conversations ..., kapso whatsapp templates ...

Fallback path:

• Proxy: GET /{phone_number_id}/messages, GET /{phone_number_id}/conversations
• SDK: client.messages.query(), client.messages.get(), client.conversations.list(), client.conversations.get(), client.templates.get()

Embed the inbox

Use Platform API inbox embeds when the user wants to place Kapso's inbox inside their own app.

Create:

• POST /platform/v1/inbox_embeds
• Envelope: inbox_embed
• Public scopes: project, customer, phone_number
• scope_id is blank for project, a customer UUID for customer, and WhatsApp phone_number_id for phone_number
• language controls the embedded inbox UI language; supported values are en and es
• Create returns token and embed_url once. Store embed_url; list/get/update omit secrets.

Example:

{
  "inbox_embed": {
    "name": "Support inbox",
    "scope_type": "phone_number",
    "scope_id": "1234567890",
    "allowed_origins": ["https://app.example.com"],
    "default_mode": "system",
    "language": "es"
  }
}

Manage:

• GET /platform/v1/inbox_embeds
• GET /platform/v1/inbox_embeds/:id
• PATCH /platform/v1/inbox_embeds/:id
• DELETE /platform/v1/inbox_embeds/:id (revokes)

Template rules

Creation:

• Use parameter_format: "NAMED" with {{param_name}} (preferred over positional)
• Include examples when using variables in HEADER/BODY
• Use language (not language_code)
• Don't interleave QUICK_REPLY with URL/PHONE_NUMBER buttons
• URL button variables must be at the end of the URL and use positional {{1}}
• For a REQUEST_CONTACT_INFO button, omit text; WhatsApp supplies the label

Send-time:

• For NAMED templates, include parameter_name in header/body params