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_KEYMETA_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):
Start onboarding: kapso setup
If setup is blocked, resolve context with:
kapso projects listkapso projects use <project-id>kapso customers listkapso customers new --name "<customer-name>" --external-id <external-id>kapso setup --customer <customer-id>
Complete the hosted onboarding URL
Confirm connected numbers: kapso whatsapp numbers list --output json
Resolve the exact number you want to operate: kapso whatsapp numbers resolve --phone-number "<display-number>" --output json
Fallback onboarding flow (direct API):
Create customer: POST /platform/v1/customers
Generate setup link: POST /platform/v1/customers/:id/setup_links
Customer completes embedded signup
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_idWhatsApp 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.mdreferences/webhooks-reference.md
Send and read messages
Discover IDs first
Two Meta IDs are needed for different operations:
ID
Used for
How to discover
business_account_id (WABA)Template CRUD
kapso whatsapp numbers resolve --phone-number "<display-number>" --output json or node scripts/list-platform-phone-numbers.mjs
phone_number_idSending messages, media upload
kapso whatsapp numbers resolve --phone-number "<display-number>" --output json or node scripts/list-platform-phone-numbers.mjs
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
Discover IDs: node scripts/list-platform-phone-numbers.mjs
Draft template payload from assets/template-utility-order-status-update.json
Create: node scripts/create-template.mjs --business-account-id <WABA_ID> --file <payload.json>
Check status: node scripts/template-status.mjs --business-account-id <WABA_ID> --name <name>
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.
Discover phone_number_id
Pick payload from assets/send-interactive-*.json
Send: node scripts/send-interactive.mjs --phone-number-id <ID> --file <payload.json>
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()
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)
WhatsApp Flows
Use Flows to build native WhatsApp forms. Read references/whatsapp-flows-spec.md before editing Flow JSON.
Create and publish a flow
Create flow: node scripts/create-flow.js --phone-number-id <id> --name <name>
Update JSON: node scripts/update-flow-json.js --flow-id <id> --json-file <path>
Publish: node scripts/publish-flow.js --flow-id <id>
Test: node scripts/send-test-flow.js --phone-number-id <id> --flow-id <id> --to <phone>
Attach a data endpoint (dynamic flows)
Set up encryption: node scripts/setup-encryption.js --flow-id <id>
Create endpoint: node scripts/set-data-endpoint.js --flow-id <id> --code-file <path>
Deploy: node scripts/deploy-data-endpoint.js --flow-id <id>
Register: node scripts/register-data-endpoint.js --flow-id <id>
Flow JSON rules
Static flows (no data endpoint):
Use version: "7.3"
routing_model and data_api_version are optionalSee assets/sample-flow.json
Dynamic flows (with data endpoint):
Use version: "7.3" with data_api_version: "3.0"
routing_model is required (defines valid screen transitions)See assets/dynamic-flow.json
Data endpoint rules
Handler signature:
async function handler ( request, env ) {
const body = await request. json ( ) ;
return Response . json ( {
version : "3.0" ,
screen : "NEXT_SCREEN_ID" ,
data : { }
} ) ;
}
Do not use export or module.exports
Completion uses screen: "SUCCESS" with extension_message_response.params
Do not include endpoint_uri or data_channel_uri (Kapso injects these)
Troubleshooting
Preview shows "flow_token is missing": flow is dynamic without a data endpoint. Attach one and refresh.
Encryption setup errors: enable encryption in Settings for the phone number/WABA.
OAuthException 139000 (Integrity): WABA must be verified in Meta security center.
Scripts
Webhooks
Script
Purpose
list.jsList webhooks
get.jsGet webhook details
create.jsCreate a webhook
update.jsUpdate a webhook
delete.jsDelete a webhook
test.jsSend a test event
Messaging and templates
Script
Purpose
Required ID
list-platform-phone-numbers.mjsDiscover business_account_id + phone_number_id
—
list-connected-numbers.mjsList WABA phone numbers
business_account_id
list-templates.mjsList templates (with filters)
business_account_id
template-status.mjsCheck single template status
business_account_id
create-template.mjsCreate a template
business_account_id
update-template.mjsUpdate existing template
business_account_id
send-template.mjsSend template message
phone_number_id
send-interactive.mjsSend interactive message
phone_number_id
upload-media.mjsUpload media for send-time headers
phone_number_id
Flows
Script
Purpose
list-flows.jsList all flows
create-flow.jsCreate a new flow
get-flow.jsGet flow details
read-flow-json.jsRead flow JSON
update-flow-json.jsUpdate flow JSON (creates new version)
publish-flow.jsPublish a flow
get-data-endpoint.jsGet data endpoint config
set-data-endpoint.jsCreate/update data endpoint code
deploy-data-endpoint.jsDeploy data endpoint
register-data-endpoint.jsRegister data endpoint with Meta
get-encryption-status.jsCheck encryption status
setup-encryption.jsSet up flow encryption
send-test-flow.jsSend a test flow message
delete-flow.jsDelete a flow
list-flow-responses.jsList stored flow responses
list-function-logs.jsList function logs
list-function-invocations.jsList function invocations
OpenAPI
Script
Purpose
openapi-explore.mjsExplore OpenAPI (search/op/schema/where)
Examples:
node scripts/openapi-explore.mjs --spec whatsapp search "template"
node scripts/openapi-explore.mjs --spec whatsapp op sendMessage
node scripts/openapi-explore.mjs --spec whatsapp schema TemplateMessage
node scripts/openapi-explore.mjs --spec platform ops --tag "WhatsApp Flows"
node scripts/openapi-explore.mjs --spec platform op setupWhatsappFlowEncryption
node scripts/openapi-explore.mjs --spec platform search "setup link"
Assets
File
Description
template-utility-order-status-update.jsonUTILITY template with named params + URL button
<✓
Make data-driven prioritization decisions faster
Stakeholder Communication Draft PRDs, status updates, and stakeholder presentations
Example
Create executive summary of Q3 roadmap, monthly progress report, feature launch announcement
✓ Save 3-5 hours/week on communication overhead
Implementation Guide Prerequisites
› Claude Desktop or compatible AI client › Access to product documentation and roadmap tools (Jira, Notion, etc.) › Understanding of product management frameworks (RICE, Jobs-to-be-Done, etc.) › Stakeholder contact information and communication channels Time Estimate
30-60 minutes to see productivity improvements
Steps
1 Install product management skill 2 Start with user story generation for known feature 3 Progress to competitive analysis: research 2-3 competitors 4 Use for roadmap prioritization: apply RICE/ICE scoring 5 Draft stakeholder communications and refine based on feedback 6 Build template library for recurring PM tasks 7 Share effective prompts with product team Common Pitfalls
⚠ Not validating competitive research—verify facts before sharing ⚠ Accepting user stories without involving engineering team ⚠ Over-relying on frameworks without qualitative judgment ⚠ Not customizing outputs to company culture and communication style ⚠ Skipping stakeholder validation of generated requirements Best Practices ✓ Do
+ Validate research and competitive analysis with real data + Collaborate with engineering when generating technical requirements + Customize frameworks and templates to your company context + Use skill for first drafts, refine with stakeholder input + Document successful prompt patterns for PM tasks + Combine AI efficiency with human judgment and intuition ✗ Don't
− Don't publish competitive analysis without fact-checking − Don't finalize user stories without engineering review − Don't make prioritization decisions solely on AI scoring − Don't skip customer validation of generated requirements − Don't ignore company-specific context and culture 💡 Pro Tips
★ Provide context: company goals, constraints, customer feedback ★ Ask for alternatives: 'Show 3 ways to prioritize this roadmap' ★ Request stakeholder-specific formatting: 'Executive summary vs. engineering spec' ★ Use skill for 70% generation + 30% customization to company needs When to Use This ✓ Use when
Use for user story writing, competitive research, roadmap prioritization, stakeholder communication, and PRD drafting. Best for reducing repetitive documentation and research work.
✗ Avoid when
Avoid for strategic product vision (requires deep customer empathy), pricing decisions (needs market and financial expertise), or when face-to-face customer discovery is more valuable than speed.
Learning Path 1 Basic: user stories, feature specs, status updates 2 Intermediate: competitive analysis, prioritization frameworks, PRDs 3 Advanced: product strategy, go-to-market planning, OKR setting 4 Expert: product vision, market positioning, business model innovation Reviews 4.6 ★ ★ ★ ★ ★ 25 reviews
I
Isabella Tandon ★ ★ ★ ★ ★ Dec 20, 2024
integrate-whatsapp fits our agent workflows well — practical, well scoped, and easy to wire into existing repos.
G
Ganesh Mohane ★ ★ ★ ★ ★ Dec 16, 2024
integrate-whatsapp fits our agent workflows well — practical, well scoped, and easy to wire into existing repos.
N
Noor Martinez ★ ★ ★ ★ ★ Nov 27, 2024
integrate-whatsapp reduced setup friction for our internal harness; good balance of opinion and flexibility.
H
Henry Gill ★ ★ ★ ★ ★ Nov 11, 2024
integrate-whatsapp is among the better-maintained entries we tried; worth keeping pinned for repeat workflows.
R
Rahul Santra ★ ★ ★ ★ ★ Nov 7, 2024
integrate-whatsapp is among the better-maintained entries we tried; worth keeping pinned for repeat workflows.
P
Pratham Ware ★ ★ ★ ★ ★ Oct 26, 2024
Keeps context tight: integrate-whatsapp is the kind of skill you can hand to a new teammate without a long onboarding doc.
E
Emma Singh ★ ★ ★ ★ ★ Oct 18, 2024
Registry listing for integrate-whatsapp matched our evaluation — installs cleanly and behaves as described in the markdown.
N
Noor Harris ★ ★ ★ ★ ★ Oct 2, 2024
Keeps context tight: integrate-whatsapp is the kind of skill you can hand to a new teammate without a long onboarding doc.
P
Piyush G ★ ★ ★ ★ ★ Sep 17, 2024
I recommend integrate-whatsapp for anyone iterating fast on agent tooling; clear intent and a small, reviewable surface area.
B
Benjamin Tandon ★ ★ ★ ★ ★ Sep 9, 2024
Useful defaults in integrate-whatsapp — fewer surprises than typical one-off scripts, and it plays nicely with `npx skills` flows.
showing 1-10 of 25
prev 1 / 3 next
Discussion Comments — not star reviews No comments yet — start the thread.
