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>

3. Complete the hosted onboarding URL 4. Confirm connected numbers: kapso whatsapp numbers list --output json 5. 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>

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

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

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

1. Create flow: node scripts/create-flow.js --phone-number-id <id> --name <name> 2. Update JSON: node scripts/update-flow-json.js --flow-id <id> --json-file <path> 3. Publish: node scripts/publish-flow.js --flow-id <id> 4. Test: node scripts/send-test-flow.js --phone-number-id <id> --flow-id <id> --to <phone>

Attach a data endpoint (dynamic flows)

1. Set up encryption: node scripts/setup-encryption.js --flow-id <id> 2. Create endpoint: node scripts/set-data-endpoint.js --flow-id <id> --code-file <path> 3. Deploy: node scripts/deploy-data-endpoint.js --flow-id <id> 4. 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 optional
• See 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();
  // body.data_exchange.action: INIT | data_exchange | BACK
  // body.data_exchange.screen: current screen id
  // body.data_exchange.data: user inputs
  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

Messaging and templates

Flows

OpenAPI

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

References

• references/getting-started.md - Platform onboarding
• references/platform-api-reference.md - Full endpoint reference
• references/setup-links.md - Setup link configuration
• references/detecting-whatsapp-connection.md - Connection detection methods
• references/webhooks-overview.md - Webhook types, signature verification, retries
• references/webhooks-event-types.md - Available events
• references/webhooks-reference.md - Webhook API and payload notes
• 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
• references/whatsapp-flows-spec.md - Flow JSON spec

Related skills

• automate-whatsapp - Workflows, agents, and automations
• observe-whatsapp - Debugging, logs, health checks

<!-- FILEMAP:BEGIN -->

[integrate-whatsapp file map]|root: .
|.:{package.json,SKILL.md}
|assets:{dynamic-flow.json,sample-flow.json,send-interactive-buttons.json,send-interactive-catalog-message.json,send-interactive-cta-url.json,send-interactive-list.json,send-interactive-location-request.json,send-template-order-status-update.json,template-authentication-otp.json,template-marketing-media-header.json,template-utility-named.json,template-utility-order-status-update.json,webhooks-example.json}
|references:{detecting-whatsapp-connection.md,getting-started.md,platform-api-reference.md,setup-links.md,templates-reference.md,webhooks-event-types.md,webhooks-overview.md,webhooks-reference.md,whatsapp-api-reference.md,whatsapp-cloud-api-js.md,whatsapp-flows-spec.md}
|scripts:{create-flow.js,create-function.js,create-template.mjs,create.js,delete-flow.js,delete.js,deploy-data-endpoint.js,deploy-function.js,get-data-endpoint.js,get-encryption-status.js,get-flow.js,get-function.js,get.js,list-connected-numbers.mjs,list-flow-responses.js,list-flows.js,list-function-invocations.js,list-function-logs.js,list-platform-phone-numbers.mjs,list-templates.mjs,list.js,openapi-explore.mjs,publish-flow.js,read-flow-json.js,register-data-endpoint.js,send-interactive.mjs,send-template.mjs,send-test-flow.js,set-data-endpoint.js,setup-encryption.js,submit-template.mjs,template-status.mjs,test.js,update-flow-json.js,update-function.js,update-template.mjs,update.js,upload-media.mjs,upload-template-header-handle.mjs}
|scripts/lib:{args.mjs,cli.js,env.js,env.mjs,http.js,output.js,output.mjs,request.mjs,run.js,whatsapp-flow.js}
|scripts/lib/webhooks:{args.js,kapso-api.js,webhook.js}

<!-- FILEMAP:END -->

You have two ways to detect when customers connect their WhatsApp account through setup links.

1. Project webhooks

Configure a project webhook to receive the whatsapp.phone_number.created event. This is the recommended approach for server-to-server notifications.

Setup

1. Open the sidebar and click Integrations → Webhooks 2. Go to the Platform webhooks tab 3. Click Add Webhook 4. Enter your HTTPS endpoint URL 5. Copy the auto-generated secret key 6. Subscribe to whatsapp.phone_number.created event

Webhook payload

{
  "phone_number_id": "123456789012345",
  "project": {
    "id": "990e8400-e29b-41d4-a716-446655440004"
  },
  "customer": {
    "id": "880e8400-e29b-41d4-a716-446655440003"
  }
}

Handle the webhook

app.post('/webhooks/project', async (req, res) => {
  const { event, data } = req.body;

  if (event === 'whatsapp.phone_number.created') {
    const { phone_number_id, customer } = data;

    // Update your database
    await db.customers.update(customer.id, {
      phone_number_id,
      whatsapp_connected: true,
      connected_at: new Date()
    });

    // Trigger welcome flow
    await sendWelcomeMessage(phone_number_id, customer.id);
  }

  res.status(200).send('OK');
});

See webhooks documentation for signature verification and best practices.

2. Success redirect URL

When customers complete WhatsApp setup, they're redirected to your success_redirect_url with query parameters.

Setup

When creating a setup link, provide redirect URLs:

const KAPSO_API_BASE_URL = 'https://api.kapso.ai';
const setupLink = await fetch(`${KAPSO_API_BASE_URL}/platform/v1/customers/customer-123/setup_links`, {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    setup_link: {
      success_redirect_url: 'https://your-app.com/whatsapp/success',
      failure_redirect_url: 'https://your-app.com/whatsapp/failed'
    }
  })
});

Query parameters

After successful setup, customer is redirected to:

https://your-app.com/whatsapp/success?setup_link_id=...&status=completed&phone_number_id=123456789012345&business_account_id=...&provisioned_phone_number_id=...&display_phone_number=%2B15551234567

Parameters:

• setup_link_id - UUID of the setup link
• status - Always completed for success
• phone_number_id - WhatsApp phone number ID (primary identifier)
• business_account_id - Meta WABA ID (if available)
• provisioned_phone_number_id - Kapso phone number ID (if provisioning was used)
• display_phone_number - E.164 formatted phone number (URL encoded)

Handle the redirect

app.get('/whatsapp/success', async (req, res) => {
  const {
    setup_link_id,
    status,
    phone_number_id,
    business_account_id,
    provisioned_phone_number_id,
    display_phone_number
  } = req.query;

  // Update your database
  await db.customers.update({
    phone_number_id,
    business_account_id,
    display_phone_number: decodeURIComponent(display_phone_number),
    whatsapp_connected: true,
    connected_at: new Date()
  });

  // Show success page to customer
  res.render('whatsapp-connected', {
    phoneNumber: decodeURIComponent(display_phone_number)
  });
});

<Note> These parameters are convenience identifiers to avoid extra API fetches. Use phone_number_id as the primary identifier. </Note>

Failure redirect

If setup fails, customer is redirected to your failure_redirect_url:

https://your-app.com/whatsapp/failed?setup_link_id=...&error_code=facebook_auth_failed

Error codes:

• facebook_auth_failed - Facebook login cancelled
• phone_verification_failed - Phone verification failed
• waba_limit_reached - Too many WhatsApp accounts
• token_exchange_failed - OAuth failed
• link_expired - Link expired (30 days)
• already_used - Link already used

app.get('/whatsapp/failed', (req, res) => {
  const { setup_link_id, error_code } = req.query;

  // Log failure for monitoring
  await logSetupFailure(setup_link_id, error_code);

  // Show user-friendly error message
  res.render('whatsapp-setup-failed', {
    errorMessage: getErrorMessage(error_code)
  });
});

Choosing the right method

Use project webhooks when:

• You need server-to-server notification
• Customer doesn't need immediate visual feedback
• You're building automated onboarding flows
• You need to process the connection before showing UI

Use success redirect when:

• Customer needs immediate confirmation in your app
• You want to show a custom success page
• You're building a wizard-style onboarding flow
• You need to collect additional information after connection

Use both:

• Webhook for backend processing (database updates, welcome messages)
• Redirect for frontend experience (success page, next steps)

Kapso Platform lets your customers connect their own WhatsApp Business accounts without sharing credentials. Each customer uses their own number while you handle the automation.

Quick example

// 1. Create customer
const customer = await createCustomer({ name: 'Acme Corp' });

// 2. Setup link
const setupLink = await generateSetupLink(customer.id);
console.log(`Setup link: ${setupLink.url}`);

// 3. Send message
await sendWhatsAppMessage({
  customer_id: customer.id,
  phone_number: '+1234567890',
  content: 'Order confirmed!'
});

Use cases

Perfect when you need your customers to use their own WhatsApp:

• CRM platforms - Let each client connect their WhatsApp for customer communication
• Appointment booking - Clinics and salons send reminders from their own number
• E-commerce tools - Stores send order updates using their WhatsApp Business
• Marketing platforms - Agencies manage multiple client WhatsApp accounts
• Support software - Each company provides support through their WhatsApp

Step 1: Create a customer

curl -X POST https://api.kapso.ai/platform/v1/customers \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "name": "Acme Corporation",
      "external_customer_id": "CUS-12345"
    }
  }'

Response:

{
  "data": {
    "id": "customer-abc123",
    "name": "Acme Corporation",
    "external_customer_id": "CUS-12345"
  }
}

Step 2: Generate setup link

curl -X POST https://api.kapso.ai/platform/v1/customers/customer-abc123/setup_links \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"setup_link":{}}'

Response:

{
  "data": {
    "id": "link-xyz789",
    "url": "https://app.kapso.ai/whatsapp/setup/aBcD123...",
    "expires_at": "2024-03-15T10:00:00Z"
  }
}

Share the url with your customer. They'll click it, log in with Facebook, and connect their WhatsApp in ~5 minutes.

Step 3: Send messages

After setup completes, use the customer's phone_number_id to send messages:

curl -X POST https://api.kapso.ai/meta/whatsapp/v24.0/110987654321/messages \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "15551234567",
    "type": "text",
    "text": {
      "body": "Your order has been shipped!"
    }
  }'

JavaScript example

const KAPSO_API_KEY = 'YOUR_API_KEY';
const KAPSO_API_BASE_URL = 'https://api.kapso.ai';
const PLATFORM_API_URL = `${KAPSO_API_BASE_URL}/platform/v1`;
const WHATSAPP_API_URL = `${KAPSO_API_BASE_URL}/meta/whatsapp`;

async function onboardCustomer(customerData) {
  // 1. Create customer
  const customer = await fetch(`${PLATFORM_API_URL}/customers`, {
    method: 'POST',
    headers: {
      'X-API-Key': KAPSO_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ customer: customerData })
  }).then(r => r.json());

  // 2. Generate setup link
  const setupLink = await fetch(
    `${PLATFORM_API_URL}/customers/${customer.data.id}/setup_links`,
    {
      method: 'POST',
      headers: {
        'X-API-Key': KAPSO_API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ setup_link: {} })
    }
  ).then(r => r.json());

  return setupLink.data.url;
}

async function sendMessage(phoneNumberId, recipientPhone, message) {
  return fetch(`${WHATSAPP_API_URL}/v24.0/${phoneNumberId}/messages`, {
    method: 'POST',
    headers: {
      'X-API-Key': KAPSO_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      messaging_product: 'whatsapp',
      to: recipientPhone,
      type: 'text',
      text: { body: message }
    })
  });
}

What customers see

1. Click your setup link 2. Log in with Facebook 3. Connect their WhatsApp Business 4. Verify phone number 5. Done - you can now send messages

The entire process takes ~5 minutes.

Next steps

• Setup links - Customize redirect URLs, branding, connection types
• Connection detection - Know when customers connect
• Webhooks - Handle real-time message events

Kapso Platform API Overview

Authentication

All Platform API requests require:

X-API-Key: <api_key>

Base host: https://api.kapso.ai Platform API base path: /platform/v1

Meta proxy (WhatsApp Cloud API)

Base URL: https://api.kapso.ai/meta/whatsapp/v24.0

Use Meta proxy for WhatsApp Cloud API calls (messages, templates, media, flows). Auth still uses X-API-Key.

Multi-tenant WhatsApp (Customers)

Use Customers when your end-users connect their own WhatsApp numbers.

Flow: 1. Create customer 2. Create setup link 3. Customer completes embedded signup 4. Use their phone_number_id for sending

Endpoints:

• POST /customers
• GET /customers
• GET /customers/:id
• POST /customers/:customer_id/setup_links
• POST /customers/:customer_id/whatsapp/phone_numbers
• GET /whatsapp/phone_numbers?customer_id=<uuid> (filter phone numbers by customer)

If you are only sending from your own WhatsApp number, skip Customers.

Core Platform API endpoints

Webhooks:

• Project-level: GET/POST /whatsapp/webhooks
• Config-level: GET/POST /whatsapp/phone_numbers/:id/webhooks
• Test delivery: POST /whatsapp/webhooks/:id/test

Messages and conversations:

• GET /whatsapp/messages
• GET /whatsapp/messages/:id (WAMID)
• GET /whatsapp/conversations
• GET /whatsapp/conversations/:id

Inbox embeds:

• GET /inbox_embeds
• POST /inbox_embeds
• GET /inbox_embeds/:id
• PATCH /inbox_embeds/:id
• DELETE /inbox_embeds/:id (revokes)

Inbox embed request shape:

• Envelope: inbox_embed
• scope_type: project, customer, or phone_number
• scope_id: blank for project, customer UUID for customer, WhatsApp phone_number_id for phone_number
• Create returns token and embed_url once. Store embed_url; list/get/update omit secrets.

Message list query params (use GET /whatsapp/messages):

• phone_number_id, conversation_id, phone_number
• direction (inbound|outbound), status (pending|sent|delivered|read|failed)
• message_type (text|image|audio|video|document), has_media (true|false)
• limit (max 100), after, before for cursor pagination

Example: GET /whatsapp/messages?conversation_id=<uuid>&phone_number_id=<id>&direction=inbound&limit=50

Conversation list query params (use GET /whatsapp/conversations):

• phone_number_id, phone_number
• status (active|ended)
• limit (max 100), after, before for cursor pagination

Example: GET /whatsapp/conversations?phone_number_id=<id>&status=active&limit=50

Workflows:

• GET /workflows
• POST /workflows
• GET /workflows/:id
• GET /workflows/:id/definition
• PATCH /workflows/:id
• GET /workflows/:id/variables
• GET /workflows/:workflow_id/executions
• POST /workflows/:workflow_id/executions
• GET /workflow_executions/:id
• PATCH /workflow_executions/:id
• POST /workflow_executions/:id/resume
• GET /workflow_executions/:id/events
• GET /workflows/:workflow_id/triggers
• POST /workflows/:workflow_id/triggers
• PATCH /triggers/:id
• DELETE /triggers/:id

Workflow execution lists use cursor pagination:

• limit (max 100), after, before
• Responses include paging.cursors.before, paging.cursors.after, paging.next, and paging.previous

Functions:

• GET /functions
• POST /functions
• GET /functions/:id
• PATCH /functions/:id
• POST /functions/:id/deploy
• POST /functions/:id/invoke
• GET /functions/:id/invocations

Logs:

• GET /api_logs
• GET /webhook_deliveries

Use cursor pagination on log and delivery lists:

• limit (max 100), after, before
• Responses include paging.cursors.before, paging.cursors.after, paging.next, and paging.previous

Provider models:

• GET /provider_models

Guidance

• For template creation/sending, use the Meta proxy endpoints (see integrate-whatsapp skill).
• For WhatsApp Flows, use Platform API flow endpoints (see integrate-whatsapp skill).
• For workflow graph edits, use workflow definition endpoints (see automate-whatsapp skill).

Setup links let customers connect their WhatsApp Business accounts to your platform. Send a link, customer clicks, logs in with Facebook, and you're connected.

Quick start

Create a basic setup link:

curl -X POST https://api.kapso.ai/platform/v1/customers/{customer_id}/setup_links \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "setup_link": {
      "success_redirect_url": "https://your-app.com/whatsapp/success",
      "failure_redirect_url": "https://your-app.com/whatsapp/failed"
    }
  }'

Response includes a url you send to your customer. Links expire after 30 days.

See Connection detection for handling successful connections.

Connection types

Customers can connect their WhatsApp in two ways:

Coexistence - Keep using WhatsApp Business app alongside API

• 5 messages/second
• App stays active
• Good for small businesses

Dedicated - API-only access for automation

• Up to 1000 messages/second
• No app access
• Built for scale

Redirect URLs

Configure where customers land after completing or failing setup:

{
  "setup_link": {
    "success_redirect_url": "https://your-app.com/whatsapp/success",
    "failure_redirect_url": "https://your-app.com/whatsapp/failed"
  }
}

Both URLs receive query parameters with setup details. See Connection detection for handling redirects and available parameters.

Language

Set the setup page language instead of auto-detecting from browser:

{
  "setup_link": {
    "language": "es"
  }
}

Supported languages:

• en - English
• es - Spanish
• pt - Portuguese
• hi - Hindi
• id - Indonesian
• ar - Arabic

When omitted, language is auto-detected from the customer's browser.

Recommended Kapso default

For Kapso-managed onboarding, prefer a dedicated connection plus phone provisioning:

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

kapso setup and kapso whatsapp numbers new follow this default path and let you override country, area code, language, and redirect URLs when needed.

Connection type control

Show both options (default)

{
  "setup_link": {
    "allowed_connection_types": ["coexistence", "dedicated"]
  }
}

Coexistence only

For customers using WhatsApp Business app:

{
  "setup_link": {
    "allowed_connection_types": ["coexistence"]
  }
}

Dedicated only

For API-only automation:

{
  "setup_link": {
    "allowed_connection_types": ["dedicated"]
  }
}

When you provide one option, it auto-selects.

Theme customization

Match your brand colors:

{
  "setup_link": {
    "theme_config": {
      "primary_color": "#3b82f6",
      "background_color": "#ffffff",
      "text_color": "#1f2937",
      "muted_text_color": "#64748b",
      "card_color": "#f9fafb",
      "border_color": "#e5e7eb"
    }
  }
}

All colors use hex format (#RRGGBB).

Phone number provisioning

Automatically provision a phone number for customers:

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

Country support

• Default: ["US"] - US phone numbers only
• Non-US countries require custom Twilio credentials (contact sales)

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

Reconnect existing numbers

For customers whose WhatsApp connection broke (token revoked, password change, Meta de-auth), generate a setup link scoped to one of their existing numbers:

{
  "setup_link": {
    "reconnect_phone_number": "+14155551234"
  }
}

Constraints:

• The number must match an existing production WhatsApp config on the same customer.
• provision_phone_number is forced to false.
• allowed_connection_types is locked to ["dedicated"] or ["coexistence"] to match the existing config.
• During Meta's embedded signup, the customer must reconnect the same WABA + number — selecting a different one fails the setup.

The hosted onboarding page uses this to refresh credentials in place rather than create a new config.

Full example

const KAPSO_API_BASE_URL = 'https://api.kapso.ai';
const setupLink = await fetch(
  `${KAPSO_API_BASE_URL}/platform/v1/customers/${customerId}/setup_links`,
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      setup_link: {
        language: 'es',
        success_redirect_url: 'https://app.example.com/onboarding/complete',
        failure_redirect_url: 'https://app.example.com/onboarding/error',
        allowed_connection_types: ['dedicated'],
        provision_phone_number: true,
        phone_number_country_isos: ['US'],
        theme_config: {
          primary_color: '#10b981',
          background_color: '#ffffff',
          text_color: '#111827'
        }
      }
    })
  }
);

// Send link to customer
await sendEmail(customer.email, {
  subject: 'Connect your WhatsApp',
  body: `Click here to connect: ${setupLink.data.url}`
});

Link management

List all links

curl https://api.kapso.ai/platform/v1/customers/{customer_id}/setup_links \
  -H "X-API-Key: YOUR_API_KEY"

Automatic revocation

Creating a new link revokes the previous one. Only one active link per customer.

Expiration

Links expire after 30 days. Check the expires_at field.

WhatsApp Templates via Meta Proxy

Environment

Required env vars:

• KAPSO_API_BASE_URL (host only, no /platform/v1, e.g. https://api.kapso.ai)
• KAPSO_API_KEY
• META_GRAPH_VERSION (optional, default: v24.0)
• KAPSO_META_BASE_URL (optional, defaults to ${KAPSO_API_BASE_URL}/meta/whatsapp)

Discover IDs (recommended)

Template CRUD requires business_account_id (WABA ID). Sending messages and uploading media require phone_number_id (Meta phone number id).

Use the Platform API to discover both:

• Script: node scripts/list-platform-phone-numbers.mjs
• Raw: GET /platform/v1/whatsapp/phone_numbers (header: X-API-Key: $KAPSO_API_KEY)

Meta proxy endpoints used

• List WABA phone numbers:
• GET /{business_account_id}/phone_numbers
• List templates:
• GET /{business_account_id}/message_templates
• Create template:
• POST /{business_account_id}/message_templates
• Update template:
• POST /{business_account_id}/message_templates?hsm_id=<template_id>
• Delete template (not scripted):
• DELETE /{business_account_id}/message_templates?name=<template_name>
• Send template message:
• POST /{phone_number_id}/messages
• Upload media for send-time headers:
• POST /{phone_number_id}/media

Template concepts

Categories:

• MARKETING: promotional content.
• UTILITY: transactional updates.
• AUTHENTICATION: OTP/verification (special rules below).

AUTHENTICATION templates:

• Require Meta business verification.
• Body text is fixed by Meta (not customizable).
• Must include an OTP button (COPY_CODE or ONE_TAP).
• Send-time still requires the OTP value in body param {{1}} and URL button param.
• If user wants custom OTP text, use UTILITY instead.

Status flow:

• Kapso does not maintain a separate draft state; create/update calls go to Meta immediately.
• Use status from Meta (APPROVED, PENDING, REJECTED, etc) via list/status scripts.

Parameter types:

• POSITIONAL: {{1}}, {{2}} (sequential).
• NAMED: {{customer_name}} (lowercase + underscores). Prefer NAMED.

Component types:

• HEADER (optional)
• BODY (required)
• FOOTER (optional)
• BUTTONS (optional)

Parameter format (creation time)

Set parameter_format:

• POSITIONAL (default): {{1}}, {{2}} with no gaps.
• NAMED (recommended): {{order_id}}.

Example requirements (creation time)

If any variables appear in HEADER or BODY, you must include examples:

• POSITIONAL: example.header_text and 2D example.body_text.
• NAMED: example.header_text_named_params and example.body_text_named_params.

Components cheat sheet (creation time)

Header (TEXT, named)

{
  "type": "HEADER",
  "format": "TEXT",
  "text": "Sale starts {{sale_date}}",
  "example": {
    "header_text_named_params": [
      { "param_name": "sale_date", "example": "December 1" }
    ]
  }
}

Header (TEXT, positional)

{
  "type": "HEADER",
  "format": "TEXT",
  "text": "Sale starts {{1}}",
  "example": {
    "header_text": ["December 1"]
  }
}

Header (IMAGE/VIDEO/DOCUMENT)

{
  "type": "HEADER",
  "format": "IMAGE",
  "example": {
    "header_handle": ["<header_handle>"]
  }
}

Body (named)

{
  "type": "BODY",
  "text": "Hi {{customer_name}}, order {{order_id}} is ready.",
  "example": {
    "body_text_named_params": [
      { "param_name": "customer_name", "example": "Alex" },
      { "param_name": "order_id", "example": "ORDER-123" }
    ]
  }
}

Body (positional)

{
  "type": "BODY",
  "text": "Order {{1}} is ready for {{2}}.",
  "example": {
    "body_text": [["ORDER-123", "Alex"]]
  }
}

Footer (no variables)

{
  "type": "FOOTER",
  "text": "Reply STOP to opt out"
}

Buttons

{
  "type": "BUTTONS",
  "buttons": [
    { "type": "QUICK_REPLY", "text": "Need help" },
    { "type": "URL", "text": "Track", "url": "https://example.com/track?id={{1}}", "example": ["https://example.com/track?id=ORDER-123"] }
  ]
}

Button ordering rules:

• Do not interleave QUICK_REPLY with URL/PHONE_NUMBER.
• Valid: QUICK_REPLY, QUICK_REPLY, URL, PHONE_NUMBER
• Invalid: QUICK_REPLY, URL, QUICK_REPLY
• Dynamic URL variables must be at the end of the URL.

URL button variables use positional placeholders in the URL (for example {{1}}). At send-time, include a button component with sub_type: "url" and the correct index.

Example (send-time URL button param):

{
  "type": "button",
  "sub_type": "url",
  "index": "0",
  "parameters": [{ "type": "text", "text": "ORDER-123" }]
}

AUTHENTICATION components

{
  "type": "BODY",
  "add_security_recommendation": true,
  "code_expiration_minutes": 10
}

{
  "type": "BUTTONS",
  "buttons": [
    { "type": "OTP", "otp_type": "COPY_CODE", "text": "Copy code" }
  ]
}

Send-time components

Named parameters:

{
  "type": "body",
  "parameters": [
    { "type": "text", "parameter_name": "order_id", "text": "ORDER-123" }
  ]
}

Positional parameters:

{
  "type": "body",
  "parameters": [
    { "type": "text", "text": "ORDER-123" }
  ]
}

AUTHENTICATION send-time:

[
  {
    "type": "body",
    "parameters": [{ "type": "text", "text": "123456" }]
  },
  {
    "type": "button",
    "sub_type": "url",
    "index": "0",
    "parameters": [{ "type": "text", "text": "123456" }]
  }
]

Media header send-time (use id or link, not both):

{
  "type": "header",
  "parameters": [
    { "type": "image", "image": { "id": "4490709327384033" } }
  ]
}

Header handle limitation

The Meta proxy does not expose resumable upload endpoints for header_handle. Use Platform media ingest (/platform/v1/whatsapp/media with delivery: meta_resumable_asset) if a header_handle is required.

{
  "type": "header",
  "parameters": [
    { "type": "image", "image": { "link": "https://example.com/header.jpg" } }
  ]
}

Rules:

• Use either id or link (never both).
• Always include the header component when the template has a media header.

All webhook payloads use v2 format with phone_number_id at the top level.

Payload structure

Webhook payloads separate message data from conversation data:

• message.kapso - Message-scoped only: direction, status, processing_status, statuses (raw status history), origin, has_media, content (text representation), transcript (for audio), media helpers (media_data, media_url, message_type_data)
• conversation - Top-level identifiers (id, phone_number, phone_number_id). Optional conversation.kapso contains summary metrics (counts, last-message metadata, timestamps)
• phone_number_id - Included at top level for routing

Project webhook events

Use project webhooks for connection lifecycle and workflow events only.

whatsapp.phone_number.created

Fires when a customer successfully connects their WhatsApp through a setup link.

See Connection detection for implementation guide.

Payload:

{
  "phone_number_id": "123456789012345",
  "project": {
    "id": "990e8400-e29b-41d4-a716-446655440004"
  },
  "customer": {
    "id": "880e8400-e29b-41d4-a716-446655440003"
  }
}

workflow.execution.handoff

Fires when a workflow execution is handed off to a human agent.

Payload:

{
  "event": "workflow.execution.handoff",
  "occurred_at": "2025-12-08T12:00:00Z",
  "project_id": "990e8400-e29b-41d4-a716-446655440004",
  "workflow_id": "880e8400-e29b-41d4-a716-446655440001",
  "workflow_execution_id": "770e8400-e29b-41d4-a716-446655440002",
  "status": "handoff",
  "tracking_id": "track-abc123",
  "channel": "whatsapp",
  "whatsapp_conversation_id": "conv_789",
  "handoff": {
    "reason": "User requested human assistance",
    "source": "agent_tool"
  }
}

workflow.execution.failed

Fires when a workflow execution fails due to an error.

Payload:

{
  "event": "workflow.execution.failed",
  "occurred_at": "2025-12-08T12:00:00Z",
  "project_id": "990e8400-e29b-41d4-a716-446655440004",
  "workflow_id": "880e8400-e29b-41d4-a716-446655440001",
  "workflow_execution_id": "770e8400-e29b-41d4-a716-446655440002",
  "status": "failed",
  "tracking_id": "track-abc123",
  "channel": "whatsapp",
  "whatsapp_conversation_id": "conv_789",
  "error": {
    "message": "Workflow execution timed out"
  }
}

WhatsApp webhook events

Use phone-number webhooks for whatsapp.message.* and whatsapp.conversation.* events only.

<CardGroup cols={2}> <Card title="Message received" icon="message"> whatsapp.message.received

Fired when a new WhatsApp message is received from a customer. Supports message buffering for batch delivery. </Card> <Card title="Message sent" icon="paper-plane"> whatsapp.message.sent

Fired when a message is successfully sent to WhatsApp </Card> <Card title="Message delivered" icon="check"> whatsapp.message.delivered

Fired when a message is successfully delivered to the recipient's device </Card> <Card title="Message read" icon="eye"> whatsapp.message.read

Fired when the recipient reads your message </Card> <Card title="Message failed" icon="triangle-exclamation"> whatsapp.message.failed

Fired when a message fails to deliver </Card> <Card title="Conversation created" icon="comments"> whatsapp.conversation.created

Fired when a new WhatsApp conversation is initiated </Card> <Card title="Conversation ended" icon="clock"> whatsapp.conversation.ended

Fired when a WhatsApp conversation ends (agent action, manual closure, or 24-hour inactivity) </Card> <Card title="Conversation inactive" icon="timer"> whatsapp.conversation.inactive

Fired when no messages (inbound/outbound) for configured minutes (1-1440, default 60) </Card> </CardGroup>

Payload structures

whatsapp.message.received

{
  "message": {
    "id": "wamid.123",
    "timestamp": "1730092800",
    "type": "text",
    "text": { "body": "Hello" },
    "kapso": {
      "direction": "inbound",
      "status": "received",
      "processing_status": "pending",
      "origin": "cloud_api",
      "has_media": false,
      "content": "Hello"
    }
  },
  "conversation": {
    "id": "conv_123",
    "phone_number": "+15551234567",
    "status": "active",
    "last_active_at": "2025-10-28T14:25:01Z",
    "created_at": "2025-10-28T13:40:00Z",
    "updated_at": "2025-10-28T14:25:01Z",
    "metadata": {},
    "phone_number_id": "123456789012345",
    "kapso": {
      "contact_name": "John Doe",
      "messages_count": 1,
      "last_message_id": "wamid.123",
      "last_message_type": "text",
      "last_message_timestamp": "2025-10-28T14:25:01Z",
      "last_message_text": "Hello",
      "last_inbound_at": "2025-10-28T14:25:01Z",
      "last_outbound_at": null
    }
  },
  "is_new_conversation": true,
  "phone_number_id": "123456789012345"
}

whatsapp.message.sent

{
  "message": {
    "id": "wamid.456",
    "timestamp": "1730092860",
    "type": "text",
    "text": { "body": "On my way" },
    "kapso": {
      "direction": "outbound",
      "status": "sent",
      "processing_status": "completed",
      "origin": "cloud_api",
      "has_media": false,
      "statuses": [
        {
          "id": "wamid.456",
          "status": "sent",
          "timestamp": "1730092860",
          "recipient_id": "15551234567"
        }
      ]
    }
  },
  "conversation": {
    "id": "conv_123",
    "phone_number": "+15551234567",
    "status": "active",
    "last_active_at": "2025-10-28T14:31:00Z",
    "created_at": "2025-10-28T13:40:00Z",
    "updated_at": "2025-10-28T14:31:00Z",
    "metadata": {},
    "phone_number_id": "123456789012345",
    "kapso": {
      "contact_name": "John Doe",
      "messages_count": 2,
      "last_message_id": "wamid.456",
      "last_message_type": "text",
      "last_message_timestamp": "2025-10-28T14:31:00Z",
      "last_message_text": "On my way",
      "last_inbound_at": "2025-10-28T14:25:01Z",
      "last_outbound_at": "2025-10-28T14:31:00Z"
    }
  },
  "is_new_conversation": false,
  "phone_number_id": "123456789012345"
}

whatsapp.message.delivered

{
  "message": {
    "id": "wamid.456",
    "timestamp": "1730092888",
    "type": "text",
    "text": { "body": "On my way" },
    "kapso": {
      "direction": "outbound",
      "status": "delivered",
      "processing_status": "completed",
      "origin": "cloud_api",
      "has_media": false,
      "statuses": [
        {
          "id": "wamid.456",
          "status": "sent",
          "timestamp": "1730092860",
          "recipient_id": "15551234567"
        },
        {
          "id": "wamid.456",
          "status": "delivered",
          "timestamp": "1730092888",
          "recipient_id": "15551234567"
        }
      ]
    }
  },
  "conversation": {
    "id": "conv_123",
    "phone_number": "+15551234567",
    "status": "active",
    "last_active_at": "2025-10-28T14:31:28Z",
    "created_at": "2025-10-28T13:40:00Z",
    "updated_at": "2025-10-28T14:31:28Z",
    "metadata": {},
    "phone_number_id": "123456789012345"
  },
  "is_new_conversation": false,
  "phone_number_id": "123456789012345"
}

whatsapp.message.failed

{
  "message": {
    "id": "wamid.789",
    "timestamp": "1730093200",
    "type": "text",
    "text": { "body": "This message failed" },
    "kapso": {
      "direction": "outbound",
      "status": "failed",
      "processing_status": "completed",
      "origin": "cloud_api",
      "has_media": false,
      "statuses": [
        {
          "id": "wamid.789",
          "status": "sent",
          "timestamp": "1730093100",
          "recipient_id": "15551234567"
        },
        {
          "id": "wamid.789",
          "status": "failed",
          "timestamp": "1730093200",
          "recipient_id": "15551234567",
          "errors": [
            {
              "code": 131047,
              "title": "Re-engagement message",
              "message": "More than 24 hours have passed since the recipient last replied"
            }
          ]
        }
      ]
    }
  },
  "conversation": {
    "id": "conv_123",
    "phone_number": "+15551234567",
    "status": "active",
    "last_active_at": "2025-10-28T15:00:00Z",
    "created_at": "2025-10-28T13:40:00Z",
    "updated_at": "2025-10-28T15:00:00Z",
    "metadata": {},
    "phone_number_id": "123456789012345"
  },
  "is_new_conversation": false,
  "phone_number_id": "123456789012345"
}

whatsapp.conversation.created

{
  "conversation": {
    "id": "conv_789",
    "phone_number": "+15551234567",
    "status": "active",
    "last_active_at": "2025-10-28T14:00:00Z",
    "created_at": "2025-10-28T14:00:00Z",
    "updated_at": "2025-10-28T14:00:00Z",
    "metadata": {},
    "phone_number_id": "123456789012345",
    "kapso": {
      "contact_name": "John Doe",
      "messages_count": 0,
      "last_message_id": null,
      "last_message_type": null,
      "last_message_timestamp": null,
      "last_message_text": null,
      "last_inbound_at": null,
      "last_outbound_at": null
    }
  },
  "phone_number_id": "123456789012345"
}

whatsapp.conversation.ended

{
  "conversation": {
    "id": "conv_789",
    "phone_number": "+15551234567",
    "status": "ended",
    "last_active_at": "2025-10-28T15:10:45Z",
    "created_at": "2025-10-28T14:00:00Z",
    "updated_at": "2025-10-28T15:10:45Z",
    "metadata": {},
    "phone_number_id": "123456789012345",
    "kapso": {
      "contact_name": "John Doe",
      "messages_count": 15,
      "last_message_id": "wamid.999",
      "last_message_type": "text",
      "last_message_timestamp": "2025-10-28T15:10:45Z",
      "last_message_text": "Thanks!",
      "last_inbound_at": "2025-10-28T15:10:45Z",
      "last_outbound_at": "2025-10-28T15:10:30Z"
    }
  },
  "phone_number_id": "123456789012345"
}

whatsapp.conversation.inactive

{
  "conversation": {
    "id": "conv_789",
    "phone_number": "+15551234567",
    "status": "active",
    "last_active_at": "2025-10-28T13:00:00Z",
    "created_at": "2025-10-28T12:00:00Z",
    "updated_at": "2025-10-28T13:00:00Z",
    "metadata": {},
    "phone_number_id": "123456789012345"
  },
  "since_message": {
    "id": "msg_anchor",
    "whatsapp_message_id": "wamid.ANCHOR",
    "direction": "inbound",
    "created_at": "2025-10-28T13:00:00Z"
  },
  "inactivity": {
    "minutes": 60
  },
  "phone_number_id": "123456789012345"
}

Multiple inactivity timeouts

Create separate webhooks for different timeout thresholds:

// First webhook: 5 minute warning
{
  "events": ["whatsapp.conversation.inactive"],
  "inactive_after_minutes": 5
}

// Second webhook: 30 minute escalation
{
  "events": ["whatsapp.conversation.inactive"],
  "inactive_after_minutes": 30
}

Each webhook fires independently when its threshold is reached.

Message origin

The message.kapso.origin field indicates how the message entered the system:

• cloud_api - Sent via Kapso API (outbound jobs, flow actions, API calls)
• business_app - Echoed from WhatsApp Business App (when using the Business App)
• history_sync - Backfilled during message history imports (only if project ran sync)

Status history

The message.kapso.statuses array contains the complete history of raw Meta status events for a message, ordered chronologically. Each entry is the unmodified payload from Meta's webhook.

Status object structure

Each status object in the array follows Meta's webhook format:

{
  "id": "<WHATSAPP_MESSAGE_ID>",
  "status": "<STATUS>",
  "timestamp": "<UNIX_TIMESTAMP>",
  "recipient_id": "<PHONE_NUMBER>",
  "pricing": {
    "billable": true,
    "pricing_model": "<PRICING_MODEL>",
    "category": "<PRICING_CATEGORY>"
  },
  "errors": [
    {
      "code": 131031,
      "title": "<ERROR_TITLE>",
      "message": "<ERROR_MESSAGE>",
      "error_data": {
        "details": "<ERROR_DETAILS>"
      },
      "href": "<ERROR_CODES_URL>"
    }
  ],
  ...
}

See Meta's status webhook reference for the complete schema.

Use this field to track the full lifecycle of outbound messages and understand failure causes. The array only appears when status events have been recorded.

Message types

The message.type field can be one of:

• text - Plain text message
• image - Image attachment
• video - Video attachment
• audio - Audio/voice message
• document - Document attachment
• location - Location sharing
• template - WhatsApp template message
• interactive - Interactive message (buttons, lists)
• reaction - Message reaction
• contacts - Contact card sharing

Message type-specific data

Media messages (image/video/document)

{
  "message": {
    "id": "wamid.789",
    "timestamp": "1730093000",
    "type": "image",
    "image": {
      "caption": "Photo description",
      "id": "media_id_123"
    },
    "kapso": {
      "direction": "inbound",
      "status": "received",
      "processing_status": "pending",
      "origin": "cloud_api",
      "has_media": true,
      "content": "Photo description Image attached (photo.jpg) [Size: 200 KB | Type: image/jpeg] URL: https://api.kapso.ai/media/...",
      "media_url": "https://api.kapso.ai/media/...",
      "media_data": {
        "url": "https://api.kapso.ai/media/...",
        "filename": "photo.jpg",
        "content_type": "image/jpeg",
        "byte_size": 204800
      },
      "message_type_data": {
        "caption": "Photo description"
      }
    }
  }
}

Audio messages

{
  "message": {
    "id": "wamid.790",
    "timestamp": "1730093100",
    "type": "audio",
    "audio": {
      "id": "media_id_456"
    },
    "kapso": {
      "direction": "inbound",
      "status": "received",
      "processing_status": "pending",
      "origin": "cloud_api",
      "has_media": true,
      "content": "[Audio attached] (voice.ogg) [Size: 50 KB | Type: audio/ogg] URL: https://api.kapso.ai/media/...\nTranscript: Hello, I need help with my order",
      "transcript": {
        "text": "Hello, I need help with my order"
      },
      "media_url": "https://api.kapso.ai/media/...",
      "media_data": {
        "url": "https://api.kapso.ai/media/...",
        "filename": "voice.ogg",
        "content_type": "audio/ogg",
        "byte_size": 51200
      }
    }
  }
}

Location messages

{
  "message": {
    "type": "location",
    "location": {
      "latitude": 37.7749,
      "longitude": -122.4194,
      "name": "San Francisco",
      "address": "San Francisco, CA, USA"
    }
  }
}

Template messages

{
  "message": {
    "type": "template",
    "template": {
      "name": "order_confirmation",
      "language": {
        "code": "en_US"
      },
      "components": [...]
    }
  }
}

Interactive messages

{
  "message": {
    "type": "interactive",
    "interactive": {
      "type": "button_reply",
      "button_reply": {
        "id": "btn_1",
        "title": "Confirm"
      }
    }
  }
}

Reaction messages

{
  "message": {
    "type": "reaction",
    "reaction": {
      "message_id": "wamid.HBgNNTU0MTIzNDU2Nzg5MA",
      "emoji": "👍"
    }
  }
}

Webhooks Overview

Webhook types

Project webhooks

Project-wide events (for example, whatsapp.phone_number.created). Use project webhooks for connection lifecycle and workflow events only.

WhatsApp webhooks

Message and conversation events for a specific phone_number_id. Use phone-number webhooks for whatsapp.message.* and whatsapp.conversation.* events only. WhatsApp message events cannot be delivered via project webhooks.

Kinds:

• Kapso webhooks (default): event-based payloads, filtering, buffering.
• Meta webhooks: raw Meta payloads, no filtering or buffering. One meta webhook per phone number.

Meta webhooks include X-Idempotency-Key (SHA256 hash of payload) for deduplication.

Response requirements

• Your endpoint must return 200 OK within 10 seconds.
• Non-200 responses trigger retries.

Retry schedule (Kapso webhooks):

• 10 seconds
• 40 seconds
• 90 seconds

Signature verification

Kapso signs webhook requests:

• Header: X-Webhook-Signature
• Value: HMAC-SHA256(webhook_secret_key, raw_request_body) as hex

Verify against raw request bytes before parsing JSON.

Headers (Kapso webhooks)

• X-Webhook-Event
• X-Webhook-Signature
• X-Idempotency-Key
• X-Webhook-Payload-Version
• Content-Type: application/json

Batched payloads may include:

• X-Webhook-Batch: true
• X-Batch-Size: <n>

Webhook Reference

Scopes

• Config-level: attach to a specific WhatsApp phone number (use phone_number_id).
• Project-level: receive lifecycle/workflow events across all numbers.
• Use config-level for any whatsapp.message.* and whatsapp.conversation.* events.
• WhatsApp message/conversation events are not delivered via project webhooks.

Signature verification

Kapso signs outbound webhook requests:

• Header: X-Webhook-Signature
• Value: HMAC-SHA256(webhook_secret_key, raw_request_body) as hex

Verify against the raw request body bytes before JSON parsing.

Event catalog

Message events (config-level):

• whatsapp.message.received
• whatsapp.message.sent
• whatsapp.message.delivered
• whatsapp.message.read
• whatsapp.message.failed

Conversation events:

• whatsapp.conversation.created
• whatsapp.conversation.ended
• whatsapp.conversation.inactive

Lifecycle events (project-level only):

• whatsapp.config.created
• whatsapp.phone_number.created
• whatsapp.phone_number.deleted

Workflow events:

• workflow.execution.handoff
• workflow.execution.failed

Payload versions

• v1: legacy payloads with nested whatsapp_config.
• v2: modern payloads with phone_number_id at root (recommended).

Buffering (message.received)

Use buffering to batch rapid inbound messages:

• buffer_enabled: true
• buffer_window_seconds: 1-60
• max_buffer_size: 1-100

WhatsApp Cloud API (Kapso Meta Proxy)

REST API reference for sending messages, managing templates, and querying history via Kapso's Meta proxy.

Base URL and auth

Base URL: ${KAPSO_API_BASE_URL}/meta/whatsapp/v24.0
Auth header: X-API-Key: <api_key>

All payloads mirror the Meta Cloud API. Kapso adds storage and query features.

Send messages

POST /{phone_number_id}/messages

All payloads require messaging_product: "whatsapp".

Text

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "text",
  "text": { "body": "Hello!", "preview_url": true }
}

Image

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "image",
  "image": { "link": "https://example.com/photo.jpg", "caption": "Photo" }
}

Use id instead of link for uploaded media.

Video

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "video",
  "video": { "link": "https://example.com/clip.mp4", "caption": "Video" }
}

Audio

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "audio",
  "audio": { "link": "https://example.com/audio.mp3" }
}

Voice message

Voice messages require .ogg files with OPUS codec. Set voice: true:

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "audio",
  "audio": { "id": "<MEDIA_ID>", "voice": true }
}

Document

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "document",
  "document": { "link": "https://example.com/file.pdf", "filename": "report.pdf", "caption": "Report" }
}

Sticker

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "sticker",
  "sticker": { "id": "<MEDIA_ID>" }
}

Location

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "location",
  "location": { "latitude": 37.7749, "longitude": -122.4194, "name": "SF Office", "address": "123 Main St" }
}

Contacts

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "contacts",
  "contacts": [{
    "name": { "formatted_name": "John Doe", "first_name": "John", "last_name": "Doe" },
    "phones": [{ "phone": "+15551234567", "type": "MOBILE", "wa_id": "15551234567" }],
    "emails": [{ "email": "john@example.com", "type": "WORK" }]
  }]
}

Reaction

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "reaction",
  "reaction": { "message_id": "wamid......", "emoji": "👍" }
}

Note: Reactions only trigger sent status webhook (not delivered/read).

Reply to a message

Add context to reply to a specific message:

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "text",
  "context": { "message_id": "wamid......" },
  "text": { "body": "Thanks for your message!" }
}

Interactive messages

Require an active 24-hour session window. Use templates for outbound notifications outside the window.

Buttons

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": { "text": "Choose an option" },
    "action": {
      "buttons": [
        { "type": "reply", "reply": { "id": "yes", "title": "Yes" } },
        { "type": "reply", "reply": { "id": "no", "title": "No" } }
      ]
    }
  }
}

Max 3 buttons. Button titles max 20 chars.

List

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": { "type": "text", "text": "Shipping Options" },
    "body": { "text": "Choose your preferred shipping" },
    "footer": { "text": "Estimates may vary" },
    "action": {
      "button": "View Options",
      "sections": [{
        "title": "Fast",
        "rows": [
          { "id": "express", "title": "Express", "description": "1-2 days" },
          { "id": "priority", "title": "Priority", "description": "2-3 days" }
        ]
      }]
    }
  }
}

Max 10 sections, 10 rows total. Button text max 20 chars.

CTA URL

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "body": { "text": "Track your order" },
    "action": {
      "name": "cta_url",
      "parameters": { "display_text": "Track Order", "url": "https://example.com/track/123" }
    }
  }
}

Location request

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "interactive",
  "interactive": {
    "type": "location_request_message",
    "body": { "text": "Please share your location for delivery." },
    "action": { "name": "send_location" }
  }
}

Flow

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "interactive",
  "interactive": {
    "type": "flow",
    "header": { "type": "text", "text": "Book Appointment" },
    "body": { "text": "Schedule your visit" },
    "action": {
      "name": "flow",
      "parameters": {
        "flow_message_version": "3",
        "flow_id": "123456789",
        "flow_cta": "Book Now",
        "mode": "published",
        "flow_token": "session_abc123",
        "flow_action": "navigate",
        "flow_action_payload": {
          "screen": "WELCOME_SCREEN",
          "data": { "customer_id": "cust_123" }
        }
      }
    }
  }
}

Product

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "interactive",
  "interactive": {
    "type": "product",
    "body": { "text": "Check out this item" },
    "action": {
      "catalog_id": "CATALOG_ID",
      "product_retailer_id": "SKU_1234"
    }
  }
}

Product list

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "interactive",
  "interactive": {
    "type": "product_list",
    "header": { "type": "text", "text": "Our Bestsellers" },
    "body": { "text": "Choose a product" },
    "action": {
      "catalog_id": "CATALOG_ID",
      "sections": [{
        "title": "Popular",
        "product_items": [
          { "product_retailer_id": "SKU_1234" },
          { "product_retailer_id": "SKU_2345" }
        ]
      }]
    }
  }
}

Max 10 sections, 30 products total.

Catalog message

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "interactive",
  "interactive": {
    "type": "catalog_message",
    "body": { "text": "Browse our catalog." },
    "action": {
      "name": "catalog_message",
      "parameters": { "thumbnail_product_retailer_id": "SKU_THUMBNAIL" }
    }
  }
}

Template messages

Send with named parameters

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "template",
  "template": {
    "name": "order_confirmation",
    "language": { "code": "en_US" },
    "components": [{
      "type": "body",
      "parameters": [
        { "type": "text", "parameter_name": "customer_name", "text": "Jessica" },
        { "type": "text", "parameter_name": "order_number", "text": "ORD-12345" }
      ]
    }]
  }
}

Send with positional parameters

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "template",
  "template": {
    "name": "order_confirmation",
    "language": { "code": "en_US" },
    "components": [{
      "type": "body",
      "parameters": [
        { "type": "text", "text": "Jessica" },
        { "type": "text", "text": "ORD-12345" }
      ]
    }]
  }
}

Send with media header

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "template",
  "template": {
    "name": "seasonal_promotion",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "header",
        "parameters": [{ "type": "image", "image": { "link": "https://example.com/promo.jpg" } }]
      },
      {
        "type": "body",
        "parameters": [
          { "type": "text", "parameter_name": "sale_name", "text": "Summer Sale" },
          { "type": "text", "parameter_name": "discount", "text": "25%" }
        ]
      }
    ]
  }
}

Send with URL button variable

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "template",
  "template": {
    "name": "order_tracking",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "body",
        "parameters": [{ "type": "text", "parameter_name": "order_id", "text": "ORD-123" }]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [{ "type": "text", "text": "ORD-123" }]
      }
    ]
  }
}

See templates-reference.md for full component rules.

Template CRUD

List templates

GET /{business_account_id}/message_templates

Create template

POST /{business_account_id}/message_templates

{
  "name": "order_confirmation",
  "language": "en_US",
  "category": "UTILITY",
  "parameter_format": "NAMED",
  "components": [
    {
      "type": "BODY",
      "text": "Thank you, {{customer_name}}! Your order {{order_number}} is confirmed.",
      "example": {
        "body_text_named_params": [
          { "param_name": "customer_name", "example": "Pablo" },
          { "param_name": "order_number", "example": "ORD-12345" }
        ]
      }
    }
  ]
}

Response includes id and status (usually PENDING).

Update template

PUT /{business_account_id}/message_templates?hsm_id=<template_id>

Same body structure as create.

Delete template

DELETE /{business_account_id}/message_templates?name=<name> or ?hsm_id=<template_id>

Mark as read

POST /{phone_number_id}/messages

{
  "messaging_product": "whatsapp",
  "status": "read",
  "message_id": "wamid......"
}

With typing indicator

{
  "messaging_product": "whatsapp",
  "status": "read",
  "message_id": "wamid......",
  "typing_indicator": { "type": "text" }
}

Typing indicator dismisses on send or after ~25s.

Media

Upload

POST /{phone_number_id}/media (multipart/form-data)

Returns { "id": "<MEDIA_ID>" } for use in send payloads.

Get URL

GET /{media_id}?phone_number_id=<phone_number_id>

Returns temporary download URL (valid 5 minutes).

Delete

DELETE /{media_id}?phone_number_id=<phone_number_id>

Format limits

Query history (Kapso)

These endpoints are Kapso-specific for stored conversation data.

List messages

GET /{phone_number_id}/messages

List conversations

GET /{phone_number_id}/conversations

Get conversation

GET /{phone_number_id}/conversations/{conversation_id}

List contacts

GET /{phone_number_id}/contacts

Get contact

GET /{phone_number_id}/contacts/{wa_id}

Response format

Successful send returns:

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "15551234567", "wa_id": "15551234567" }],
  "messages": [{ "id": "wamid.HBgN..." }]
}

Errors

Kapso extensions

Add fields=kapso(...) to list endpoints:

• kapso(default) or kapso(*) - all default fields
• kapso(direction,media_url,contact_name) - specific fields
• kapso() - omit Kapso fields

Common fields: direction, status, media_url, contact_name, flow_response, flow_token, content, message_type_data.

Notes

• Discover phone_number_id + business_account_id via node scripts/list-platform-phone-numbers.mjs
• All send payloads require messaging_product: "whatsapp"
• Graph version controlled by META_GRAPH_VERSION (default v24.0)

whatsapp-cloud-api-js

Use the @kapso/whatsapp-cloud-api SDK for typed WhatsApp Cloud API calls.

Install

npm install @kapso/whatsapp-cloud-api

Create a client

Kapso proxy setup:

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

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

Direct Meta setup:

const client = new WhatsAppClient({
  accessToken: process.env.WHATSAPP_TOKEN!
});

Send a text message

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

Send a raw payload

await client.messages.sendRaw({
  phoneNumberId: "<PHONE_NUMBER_ID>",
  payload: {
    messaging_product: "whatsapp",
    recipient_type: "individual",
    to: "+15551234567",
    type: "text",
    text: { body: "Hello from a raw payload" }
  }
});

Send a template message

await client.messages.sendTemplate({
  phoneNumberId: "<PHONE_NUMBER_ID>",
  to: "+15551234567",
  template: {
    name: "order_ready_named",
    language: { code: "en_US" },
    components: [
      {
        type: "body",
        parameters: [
          { type: "text", parameterName: "order_id", text: "ORDER-123" }
        ]
      }
    ]
  }
});

Send an interactive button message

await client.messages.sendInteractiveButtons({
  phoneNumberId: "<PHONE_NUMBER_ID>",
  to: "+15551234567",
  bodyText: "Choose an option",
  buttons: [
    { id: "accept", title: "Accept" },
    { id: "decline", title: "Decline" }
  ]
});

List conversations

const conversations = await client.conversations.list({
  phoneNumberId: "<PHONE_NUMBER_ID>",
  status: "active",
  limit: 20
});

Get a conversation

const conversation = await client.conversations.get({
  conversationId: "123e4567-e89b-12d3-a456-426614174000"
});

List messages

const messages = await client.messages.query({
  phoneNumberId: "<PHONE_NUMBER_ID>",
  conversationId: "123e4567-e89b-12d3-a456-426614174000",
  limit: 50
});

Get a single message

const message = await client.messages.get({
  phoneNumberId: "<PHONE_NUMBER_ID>",
  messageId: "wamid.HBgL..."
});

List messages for a conversation (shortcut)

const messages = await client.messages.listByConversation({
  phoneNumberId: "<PHONE_NUMBER_ID>",
  conversationId: "123e4567-e89b-12d3-a456-426614174000",
  limit: 50
});

Get a template

const template = await client.templates.get({
  businessAccountId: "<BUSINESS_ACCOUNT_ID>",
  templateId: "564750795574598"
});

Notes

• Use phoneNumberId from the connected WhatsApp number (discover via kapso whatsapp numbers resolve --phone-number "<display-number>" --output json or node scripts/list-platform-phone-numbers.mjs).
• With Kapso proxy, keep baseUrl and kapsoApiKey set.
• Template rules still apply (examples, button ordering, media headers).
• History endpoints (messages.query, messages.get, messages.listByConversation, conversations.list/get) require Kapso proxy; they are not available with a direct Meta access token.
• Requests use camelCase keys and the SDK converts to snake_case for the API; responses come back camelCase.