Migrate from another provider

Move your WhatsApp number to Kapso from any Business Solution Provider. Are you on Twilio? Use the Twilio guide instead.

Step 1: Connect your number

In WhatsApp Manager, check the WABA for other numbers, templates, or assets you still need.
Remove the phone number from the WABA.
In Meta Business Settings, open Accounts → WhatsApp accounts.
If the old WABA sits in your Business Portfolio, remove it.
Wait about five minutes.
In Kapso, start embedded signup. Create a new WABA when the flow asks.
Recreate your templates on the new WABA (see Step 5). Wait for Meta review.

The number stops sending after step 2, and it can send templates again once Meta approves them on the new WABA. Plan the migration accordingly. See Connect WhatsApp for the signup flow. If Meta blocks the WABA removal over a pending balance, your old provider may still have a credit line attached to it. Meta Direct Support has to clear that. A different number on a new WABA unblocks you in the meantime. If the reconnect fails, see coexistence troubleshooting. You can also start on a fresh number. Instant setup gives you a pre-verified US number, with no SMS verification step.

Testing first? Build against a sandbox number while your current provider still carries production traffic.

Step 2: Get your phone number IDs

curl https://api.kapso.ai/platform/v1/whatsapp/phone_numbers \
  -H "X-API-Key: YOUR_API_KEY"

{
  "data": [
    {
      "id": "1234567890",
      "phone_number_id": "1234567890",
      "name": "Support Line",
      "business_account_id": "98765432109",
      "display_phone_number": "+1 555-123-4567",
      "quality_rating": "GREEN",
      "throughput_tier": "TIER_10K",
      "status": "CONNECTED"
    }
  ]
}

Two IDs address different things:

ID	Scopes to	Use it for
`phone_number_id`	one phone number	sending messages, uploading media, registering webhooks
`business_account_id`	the WABA that owns the numbers	templates

Templates belong to the WABA, not to a number, so every number on that WABA can send them. That is why the template endpoints take the WABA ID in the path, as in POST /{waba_id}/message_templates.

Step 3: Update message sending

For every message type, Kapso uses one endpoint: POST /{phone_number_id}/messages. The type field says which kind of message you are sending, and a field of that same name carries the content. A text message sets type: "text" and puts the body in text. Some providers proxy Meta’s Cloud API. If yours did, your payloads already have this shape, and you only change the base URL and the auth header. If your provider had its own message API, use the tabs below as the target shapes.

Free-form messages, inside the 24-hour window:

curl -X POST https://api.kapso.ai/meta/whatsapp/v24.0/1234567890/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 shipped!" }
  }'

To reply to a specific message, add "context": { "message_id": "wamid..." }. To address a contact that has no phone number, use recipient with a business-scoped user ID instead of to. See Send text.

Business-initiated messages, outside the 24-hour window. Anything that starts or reopens a conversation has to be an approved template:

curl -X POST https://api.kapso.ai/meta/whatsapp/v24.0/1234567890/messages \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "15551234567",
    "type": "template",
    "template": {
      "name": "order_update",
      "language": { "code": "en_US" },
      "components": [
        {
          "type": "body",
          "parameters": [{ "type": "text", "text": "John" }]
        }
      ]
    }
  }'

Parameters are positional and must match the placeholder order. Named parameters work too. See Simple text templates.

Media is a message type, not a parameter on a text message:

curl -X POST https://api.kapso.ai/meta/whatsapp/v24.0/1234567890/messages \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "15551234567",
    "type": "image",
    "image": {
      "link": "https://example.com/receipt.png",
      "caption": "Your receipt"
    }
  }'

type is image, video, audio, document, or sticker. Documents take a filename. Public URLs work directly. To upload bytes first, use POST /{phone_number_id}/media and pass the returned id instead of link. Kapso also ingests from a URL and hands back a Meta media ID via POST /platform/v1/whatsapp/media.

Buttons, lists, and CTAs all use Meta’s interactive object:

curl -X POST https://api.kapso.ai/meta/whatsapp/v24.0/1234567890/messages \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "15551234567",
    "type": "interactive",
    "interactive": {
      "type": "button",
      "body": { "text": "Confirm your appointment?" },
      "action": {
        "buttons": [
          { "type": "reply", "reply": { "id": "btn_yes", "title": "Yes" } },
          { "type": "reply", "reply": { "id": "btn_no", "title": "No" } }
        ]
      }
    }
  }'

Taps arrive on whatsapp.message.received as an interactive message with button_reply.id. Swap interactive.type for list or cta_url. See Send buttons and Send lists.

Locations take numbers, not strings:

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

Reactions point at the message they react to:

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

See Send location and Send reaction.

Marking read and showing a typing indicator go to the same endpoint, without a to:

curl -X POST https://api.kapso.ai/meta/whatsapp/v24.0/1234567890/messages \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "status": "read",
    "message_id": "wamid.HBgNMTU1NTE0OTU5Nzg1...",
    "typing_indicator": { "type": "text" }
  }'

The indicator clears when you send a message, or after about 25 seconds. See Mark as read.

The TypeScript SDK wraps all of this, so you do not have to write the envelopes by hand.

Step 4: Update webhooks

curl -X POST https://api.kapso.ai/platform/v1/whatsapp/phone_numbers/1234567890/webhooks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp_webhook": {
      "url": "https://yourapp.com/webhooks/whatsapp",
      "events": [
        "whatsapp.message.received",
        "whatsapp.message.sent",
        "whatsapp.message.delivered",
        "whatsapp.message.read",
        "whatsapp.message.failed"
      ],
      "secret_key": "your-signing-secret"
    }
  }'

Payloads carry message, conversation, and phone_number_id, with Kapso’s own fields under message.kapso. The event name arrives in the X-Webhook-Event header. Full shapes in Message events. conversation threads the messages for you, but it does not track the 24-hour window. A send can fail with 131047 while conversation.status is active. Read conversation.kapso.last_inbound_at, or handle the rejection and fall back to a template. from is not always present. WhatsApp can identify a contact with business_scoped_user_id instead. See business-scoped user IDs. For connection lifecycle events (a customer finishing a setup link, Meta disabling a WABA), use project webhooks instead. You configure those once for the whole project.

Does your current provider forward raw Meta payloads? Register the webhook with "kind": "meta" and Kapso forwards Meta’s exact payload with no reshaping. Your existing parser keeps working.

Kapso signs the raw request body with HMAC-SHA256 and sends the hex digest in X-Webhook-Signature:

const crypto = require('crypto');

// express.raw, not express.json: Kapso signs the exact bytes it sent, and
// re-serializing a parsed body does not reproduce them
app.post('/webhooks/whatsapp', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  const a = Buffer.from(expected, 'utf8');
  const b = Buffer.from(req.headers['x-webhook-signature'] ?? '', 'utf8');

  // timingSafeEqual throws on length mismatch, so compare lengths first
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  res.sendStatus(200);
});

Delivery is at-least-once, retried at 10s, 40s, and 90s. Dedupe on X-Idempotency-Key. See Security for Python and Ruby, and Advanced for buffering and ordering.

Step 5: Templates

Templates belong to the WABA at Meta, not to your provider. If you build templates in WhatsApp Manager, pull them into Kapso from WhatsApp → Templates → Sync from WhatsApp. The path takes the WABA ID, not the phone number ID:

curl -X POST https://api.kapso.ai/meta/whatsapp/v24.0/98765432109/message_templates \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_update",
    "category": "UTILITY",
    "language": "en_US",
    "components": [
      {
        "type": "BODY",
        "text": "Hi {{1}}, your order is confirmed.",
        "example": { "body_text": [["John"]] }
      }
    ]
  }'

Meta reviews them, usually within 24 hours. See Template lifecycle.

Multi-tenant setups

If you message on behalf of your own customers, each one becomes a Kapso customer that connects its own number through a setup link:

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

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",
      "meta_billing_mode": "partner_managed"
    }
  }'

Send your customer the returned url. They log in with Facebook and connect in about five minutes. You then get whatsapp.phone_number.created on your project webhook, with the customer.id and phone_number_id. See Onboard customers. One API key covers every customer. Migrate one customer at a time.

Cutover

Migrate one number at a time. A number’s WhatsApp registration and webhook routing move as a unit, so there is no gradual split per number.

Phase	Actions
Prep	Create the project and API key, build against a sandbox number, export history from your provider
Pilot	Move one low-traffic number end to end. Budget for the time the number is down, and for Meta’s template review
Rollout	Migrate remaining numbers in batches; for multi-tenant, one customer at a time
Cutoff	Stop sends on the old provider for each migrated number, then close the account

Meta bills message charges against the WABA either way, per delivered template message. See pricing.

Troubleshooting

Symptom	Fix
Number cannot be connected	It is still on the provider’s WABA. Migrate it in WhatsApp Manager, and ask the provider to release it if they hold the PIN
`401 Unauthorized`	Send `X-API-Key: YOUR_API_KEY`
`(#131047)` re-engagement message	Outside the 24-hour window. Send an approved template
Template not found	Templates are addressed by `name` + `language`, and must exist on this WABA. Sync or recreate them
Templates missing after the move	They belonged to the old WABA. Recreate them on the new one and wait for review
Webhook signature mismatch	HMAC-SHA256 over the raw body, checked against `X-Webhook-Signature`
Marketing template refused with `422`	The contact stopped marketing on that number. See marketing opt-outs
`429`	Back off on `Retry-After`; see rate limits

Getting started

WhatsApp

For your team

Onboard customers

Automations

Migrate to Kapso

Step 1: Connect your number

Step 2: Get your phone number IDs

Step 3: Update message sending

Step 4: Update webhooks

Step 5: Templates

Multi-tenant setups

Cutover

Troubleshooting

Need help

​Step 1: Connect your number

​Step 2: Get your phone number IDs

​Step 3: Update message sending

​Step 4: Update webhooks

​Step 5: Templates

​Multi-tenant setups

​Cutover

​Troubleshooting

​Need help

Step 1: Connect your number

Step 2: Get your phone number IDs

Step 3: Update message sending

Step 4: Update webhooks

Step 5: Templates

Multi-tenant setups

Cutover

Troubleshooting

Need help