​
Overview

Kapso’s Meta proxy allows you to use Meta’s WhatsApp Cloud API directly while benefiting from Kapso’s data synchronization, analytics, and conversation management. All requests are forwarded to Meta, and all data is automatically synced to Kapso.

​
Connecting WhatsApp numbers

Before using the proxy, connect your WhatsApp number to Kapso. Go to Connected numbers in the sidebar and use one of the buttons at the top right:
  • Embedded signup (recommended) - One-click connection through Meta’s embedded flow
  • Manual setup - Use if you have your own Meta app configured

​
Base URL

https://app.kapso.ai/api/meta/{graph_version}/{endpoint}

​
Authentication

Option 1: WhatsApp access token 
Authorization: Bearer YOUR_WHATSAPP_ACCESS_TOKEN
Option 2: Kapso project API key 
X-API-Key: YOUR_PROJECT_API_KEY
When using X-API-Key, the WhatsApp configuration is resolved from the IDs in your request URL.

​
Example: send a message

curl -X POST "https://app.kapso.ai/api/meta/v21.0/PHONE_NUMBER_ID/messages" \
  -H "X-API-Key: YOUR_PROJECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "1234567890",
    "type": "text",
    "text": {
      "body": "Hello from Kapso proxy!"
    }
  }'

​
Supported endpoints

  • /{phone_number_id}/messages - Send messages
  • /{phone_number_id}/settings - Manage settings
  • /{phone_number_id}/media - Upload media
  • /{business_account_id}/message_templates - Manage templates
  • All other Meta WhatsApp Cloud API endpoints

​
Webhook configuration

​
Option 1: chain webhooks

Receive at your endpoint, then forward to Kapso. Configure Meta webhook to your endpoint, then forward to Kapso with required headers: 
// Your webhook endpoint (Express.js example)
app.post('/webhook', async (req, res) => {
  // Process webhook locally
  await processWebhook(req.body);

  // Forward to Kapso - MUST include signature header
  await fetch('https://meta-webhooks.kapso.ai/whatsapp', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Hub-Signature-256': req.headers['x-hub-signature-256'] // Required for verification
    },
    body: JSON.stringify(req.body)
  });

  res.sendStatus(200);
});

​
Option 2: direct webhook with custom URL

Kapso forwards to your endpoint.
  1. In Kapso WhatsApp configuration, add your webhook URL
  2. Configure Meta webhook to: https://meta-webhooks.kapso.ai/whatsapp
  3. Use your verify token from Kapso configuration
Kapso will receive webhooks from Meta, process the data, and forward to your endpoint.

​
Benefits of using the proxy

  • Zero code changes - Keep your existing Meta API integration
  • Automatic data sync - All messages and events stored in Kapso
  • Conversation management - Track conversations and customer interactions
  • Analytics - Message metrics and conversation insights
  • Debugging - View all API calls and webhook events in Kapso dashboard

​
Alternative: Kapso native API

For an enriched experience, consider using Kapso’s native WhatsApp API with simplified message sending, conversation context, customer management, and automatic retry logic. Example: 
# Send message with Kapso API
curl -X POST "https://app.kapso.ai/api/v1/whatsapp_messages" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "1234567890",
    "message": "Hello from Kapso!",
    "message_type": "text"
  }'
See WhatsApp API documentation for complete native API reference.

​
Complete examples

Sending a template: 
# Using Meta proxy
curl -X POST "https://app.kapso.ai/api/meta/v21.0/PHONE_NUMBER_ID/messages" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "1234567890",
    "type": "template",
    "template": {
      "name": "hello_world",
      "language": {
        "code": "en_US"
      }
    }
  }'
Webhook forwarding: 
// Node.js Express example
const express = require('express');
const fetch = require('node-fetch');

const app = express();
app.use(express.json());

app.post('/webhook', async (req, res) => {
  // Get webhook data
  const data = req.body;

  // Get the signature header for verification
  const signature = req.headers['x-hub-signature-256'];

  // Your business logic
  const entry = data.entry?.[0];
  const changes = entry?.changes?.[0];
  const messages = changes?.value?.messages;

  if (messages) {
    console.log('New message received');
  }

  // Forward to Kapso with required headers
  const headers = {
    'Content-Type': 'application/json'
  };

  // IMPORTANT: Include signature header if present
  if (signature) {
    headers['X-Hub-Signature-256'] = signature;
  }

  await fetch('https://meta-webhooks.kapso.ai/whatsapp', {
    method: 'POST',
    headers,
    body: JSON.stringify(data)
  });

  res.sendStatus(200);
});