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