Whatsapp Messaging

WhatsApp Messaging

When to use

Use this skill when working with WhatsApp messaging via Kapso: sending messages, creating/managing templates, uploading media, or reading inbox history.

Setup

Env vars:

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

Discover IDs first

Two Meta IDs are needed for different operations:

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!
});

How to

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>

Read inbox data

Use Meta proxy or SDK:

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

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

Send-time:

• For NAMED templates, include parameter_name in header/body params
• URL buttons need a button component with sub_type: "url" and index
• Media headers use either id or link (never both)

Scripts

Assets

References

• references/templates-reference.md - Template creation rules, components cheat sheet, send-time components
• references/whatsapp-api-reference.md - Meta proxy payloads for messages and conversations
• references/whatsapp-cloud-api-js.md - SDK usage for sending and reading messages

Related skills

• kapso-automation - Workflow automation
• whatsapp-flows - WhatsApp Flows
• kapso-api - Platform API and customers