Migrate from another provider

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

Step 1: Connect your number

In WhatsApp Manager, check the WABA for other numbers, templates, or assets you still need.
Turn off two-step verification, under Phone numbers → Settings → Two-step verification, or re-registration will ask for a PIN.
Remove the phone number from the WABA. Leave the WABA itself in your Business Portfolio.
Wait about 10 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 3, 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 embedded signup fails with 2655093, or Meta blocks a billing change over a pending balance, the WABA is still tied to another partner, most often through your old provider’s credit line. In Meta WhatsApp account settings, open the WABA’s Summary → Payment method. If it shows a Credit line from your old provider, ask your old provider to revoke its allocation for this WABA and confirm when it is done. Disconnecting, or disappearing from Partners, does not revoke it. Revoking changes billing for every number on that WABA. If the error remains after one retry, contact Kapso Support to escalate to Meta. A different number on a new WABA unblocks you in the meantime. See recovery steps.

On coexistence? The pairing with the WhatsApp Business app is exclusive to one provider. Do step 1, ask the old provider to revoke its credit line for the number’s WABA (see above), and disconnect the old provider in the app under Settings → Account → Business Platform if it is listed. Revoking changes billing for every number on that WABA, so if others still use the old provider’s billing, move them or give them replacement billing first. Do not remove the number or the WABA. Wait about 10 minutes, then connect through Kapso’s WhatsApp Business App flow. Coexistence always creates a new WABA, so recreate your templates. If it fails, see coexistence troubleshooting.

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, with three attempts in about 50 seconds: the first, then retries at 10s and 40s. 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, or two-step verification is still on. See Step 1, and ask the provider to release it if they hold the PIN
Signup fails with `2655093`	The WABA is still tied to another partner, most often the old provider’s credit line. See Step 1
Signup fails with `2655122`	The number is still registered on the Cloud API. Keep it as a dedicated number, or contact Kapso Support to plan the switch to coexistence. Do not remove a working registration first
Other Meta signup error codes	See coexistence troubleshooting
`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