Migrate from Twilio

Migrate your WhatsApp numbers from Twilio to Kapso.

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 Twilio’s credit line. In Meta WhatsApp account settings, open the WABA’s Summary → Payment method. If it shows a Credit line from Twilio, ask Twilio 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 Twilio to revoke its credit line for the number’s WABA (see above), and disconnect Twilio 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 Twilio’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? The sandbox replaces Twilio’s join <code> flow. Create a session for your test phone, then send the 6-character code from WhatsApp. You can then send and receive without a production number.

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

Store the mapping from whatsapp:+E164 to phone_number_id. 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.

Template
Text
Media
Interactive
Read and typing

Business-initiated sends, outside the 24-hour window. ContentSid becomes the template name, ContentVariables becomes Meta’s components array.Twilio:

curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACxxxx/Messages.json \
  -u ACxxxx:auth_token \
  -d "To=whatsapp:+15551234567" \
  -d "From=whatsapp:+15557654321" \
  -d "ContentSid=HXxxxxxxxxxxxx" \
  -d 'ContentVariables={"1": "John", "2": "ORD-123"}'

Kapso:

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" },
            { "type": "text", "text": "ORD-123" }
          ]
        }
      ]
    }
  }'

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

Free-form replies, inside the 24-hour window.Twilio:

curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACxxxx/Messages.json \
  -u ACxxxx:auth_token \
  -d "To=whatsapp:+15551234567" \
  -d "From=whatsapp:+15557654321" \
  -d "Body=Your order shipped!"

Kapso:

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.

MediaUrl becomes a typed object. Media is a message type, not a parameter on a text message.Twilio:

curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACxxxx/Messages.json \
  -u ACxxxx:auth_token \
  -d "To=whatsapp:+15551234567" \
  -d "From=whatsapp:+15557654321" \
  -d "Body=Here's your receipt" \
  -d "MediaUrl=https://example.com/receipt.png"

Kapso:

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": "Here'\''s 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.

Twilio expresses rich messages as Content API types. Kapso takes Meta’s interactive object inline.

Twilio content type	Kapso
`twilio/text`	`type: "text"`
`twilio/media`	`type: "image"` / `video` / `document`
`twilio/quick-reply`	`interactive.type: "button"`
`twilio/list-picker`	`interactive.type: "list"`
`twilio/call-to-action`	`interactive.type: "cta_url"`
`twilio/card`	Media header + buttons, or a template
`twilio/carousel`	Carousel template
`twilio/location`	`type: "location"`
`whatsapp/authentication`	`AUTHENTICATION` template
`whatsapp/flows`	`interactive.type: "flow"`

Quick replies:

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, Twilio’s ButtonPayload. Full shapes in Send buttons and Send lists.

Twilio has no equivalent. Kapso passes Meta’s through, on the same endpoint:

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

Reactions are type: "reaction". See Mark as read and Send reaction.

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

Step 4: Update webhooks

Kapso posts JSON and expects a 200. There is no TwiML, so auto-replies move into your handler or into a workflow. Register per phone number:

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

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.

Field mapping

Twilio param	Kapso (`whatsapp.message.received`)
`MessageSid`	`message.id`
`From` (`whatsapp:+1...`) / `WaId`	`message.from`
`To`	`phone_number_id`
`ProfileName`	`conversation.contact_name`
`Body`	`message.text.body`
`NumMedia` / `MediaUrl0`	`message.kapso.has_media`, `message.kapso.media_url`
`ButtonText` / `ButtonPayload`	`message.interactive.button_reply.title` / `.id`
`Latitude` / `Longitude`	`message.location`
`MessageStatus`	The event name, plus `message.kapso.statuses`

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.

Signature verification

Twilio signs the request URL plus every form field, so verification needs all of them. Twilio’s helper assembles them for you. Kapso signs only the request body. Verification is one HMAC over the bytes you received. Twilio:

const twilio = require('twilio');

app.post('/webhooks/whatsapp', express.urlencoded({ extended: false }), (req, res) => {
  const valid = twilio.validateRequest(
    process.env.TWILIO_AUTH_TOKEN,
    req.headers['x-twilio-signature'],
    'https://yourapp.com/webhooks/whatsapp',  // must match exactly
    req.body                                  // every param, sorted for you
  );

  if (!valid) return res.status(403).send('Invalid signature');
  res.type('text/xml').send('<Response/>');
});

Kapso:

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

No URL goes into the hash, so your endpoint can move or sit behind a proxy without breaking verification.

Delivery behavior

	Twilio	Kapso
Retries	None by default	3 attempts in about 50 seconds: the first, then 10s and 40s later
Timeout	15s	10s
Dedup	`MessageSid`	`X-Idempotency-Key` header
Batching	None	Optional buffering on `whatsapp.message.received`

Delivery is at-least-once. Dedupe on X-Idempotency-Key. See Advanced for buffering and ordering, and Security for verification in Python and Ruby.

Do you parse raw Meta payloads elsewhere? Register the webhook with "kind": "meta" and Kapso forwards Meta’s exact payload with no reshaping.

Step 5: Templates

Twilio needs two calls: create the content, then request WhatsApp approval. Kapso submits on create. Twilio:

curl -X POST https://content.twilio.com/v1/Content \
  -u ACxxxx:auth_token \
  -H "Content-Type: application/json" \
  -d '{
    "friendly_name": "order_update",
    "language": "en",
    "variables": {"1": "John"},
    "types": {"twilio/text": {"body": "Hi {{1}}, your order is confirmed."}}
  }'

curl -X POST https://content.twilio.com/v1/Content/HXxxxx/ApprovalRequests/whatsapp \
  -u ACxxxx:auth_token \
  -d '{"name": "order_update", "category": "UTILITY"}'

Kapso:

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

The path takes the WABA ID, not the phone number ID. If you build templates in WhatsApp Manager, pull them into Kapso from WhatsApp → Templates → Sync from WhatsApp. See Template lifecycle.

Multi-tenant setups

Twilio subaccounts become customers, and each customer connects their own number through a setup link instead of you provisioning a sender per subaccount:

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 and Connection detection. One API key covers every customer, so there is no per-subaccount credential juggling.

Bulk sends

If you loop over recipients yourself, or drive bulk sends from Studio, use broadcasts instead. Create, add recipients with per-recipient template parameters, send, poll:

POST /platform/v1/whatsapp/broadcasts
POST /platform/v1/whatsapp/broadcasts/{id}/recipients
POST /platform/v1/whatsapp/broadcasts/{id}/send
GET  /platform/v1/whatsapp/broadcasts/{id}

Kapso paces broadcasts internally to stay inside Meta’s throughput limits, so you do not throttle them yourself. POST /{id}/schedule sends later, POST /{id}/cancel stops one in flight.

Keep your Twilio account for numbers

You do not have to leave Twilio to leave Twilio’s WhatsApp API. Point Kapso at your Twilio credentials and it provisions new numbers into your Twilio account, billed to you. You choose the countries, and each one can keep a pool of reusable pre-verified numbers. This covers provisioning, not the numbers your Twilio WhatsApp senders already use. Those still follow Step 1. This is an Enterprise feature, or a paid add-on on other plans. See Provide local numbers.

Feature map

Feature	Twilio	Kapso
WhatsApp messaging	Messages + Content API	Meta-shaped API
Interactive messages	Content types	Buttons, lists, CTAs
Templates	Content API + approval requests	`/{waba_id}/message_templates`
WhatsApp Flows	`whatsapp/flows` content type	Full Flows API, including hosted data endpoints
Bulk messaging	Your own loop	Broadcasts, with CSV upload and scheduling
Conversation automation	Studio	Workflows with AI steps and human handoff
Team inbox	Flex, a separate contract	Included, plus an embeddable iframe
Multi-tenant onboarding	Subaccounts you provision	Setup links your customer completes
Message history	Messages resource	`/whatsapp/messages`, `/whatsapp/conversations`
Marketing opt-outs	Advanced Opt-Out keywords	Automatic, from WhatsApp’s native control
WhatsApp calling	Supported	Supported, with call logs
Business profile	API	Display names, usernames
Sandbox	`join <code>` on a shared number	6-character code
Serverless code	Twilio Functions	Functions on Cloudflare Workers, as workflow steps, agent tools, or plain endpoints
Rate limits	Per-number throughput	100-4,000 req/min by plan

Things Kapso adds:

An inbox for your team
CTWA attribution and contact properties
Automatic voice-note transcription
An MCP server and a CLI
Findings, which reads ended conversations with AI and groups the recurring problems

What does not map

Messaging Services. No sender pools, sticky sender, or geomatch. You send from a specific phone_number_id.
TwiML. Auto-replies move into your webhook handler or a workflow.
Link shortening and click tracking.
Conversation tags. Organize in the inbox UI, not the API.

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 message history from Twilio
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 Twilio sends for each migrated number, then release the sender in Twilio

One thing needs no migration. Meta bills message charges against the WABA on either platform, per delivered template message, at category and market rates. See pricing.

Message history does not transfer. Twilio keeps it in its Messages resource. Export what you need before you close the account.

Troubleshooting

Symptom	Twilio equivalent	Fix
`401 Unauthorized`	Basic auth credentials	Send `X-API-Key: YOUR_API_KEY`
Body rejected	Form-encoded params	Send JSON with `Content-Type: application/json`
`(#131047)` re-engagement message	Error 63016	Outside the 24-hour window. Send an approved template
Number cannot be connected	None	It is still on Twilio’s WABA, or two-step verification is still on. See Step 1
Signup fails with `2655093`	None	The WABA is still tied to another partner, most often Twilio’s credit line. See Step 1
Signup fails with `2655122`	None	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	None	See coexistence troubleshooting
Template variables ignored	`ContentVariables` JSON string	Use Meta `components` with a `parameters` array, in placeholder order
Template not found	`ContentSid`	Templates are addressed by `name` + `language`, and must exist on this WABA
Webhook signature mismatch	URL + sorted params, HMAC-SHA1	HMAC-SHA256 over the raw body, checked against `X-Webhook-Signature`
Webhook keeps retrying	TwiML response expected	Return `200` within 10 seconds; the body is ignored
Marketing template refused with `422`	Advanced Opt-Out	The contact stopped marketing on that number. Check marketing preferences
`429`	`429 Too Many Requests`	Back off on `Retry-After`; see rate limits

Node.js example

const crypto = require('crypto');
const express = require('express');

const app = express();

// Any durable queue works. The point is that the job outlives the request.
const queue = require('./queue');

const KAPSO = 'https://api.kapso.ai/meta/whatsapp/v24.0';
const headers = {
  'X-API-Key': process.env.KAPSO_API_KEY,
  'Content-Type': 'application/json',
};

// Twilio: client.messages.create({ to, from, contentSid, contentVariables })
async function sendTemplate({ phoneNumberId, to, name, params = [] }) {
  const res = await fetch(`${KAPSO}/${phoneNumberId}/messages`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      messaging_product: 'whatsapp',
      to,
      type: 'template',
      template: {
        name,
        language: { code: 'en_US' },
        components: [
          {
            type: 'body',
            parameters: params.map((text) => ({ type: 'text', text })),
          },
        ],
      },
    }),
  });
  const body = await res.json();
  return body.messages[0].id; // wamid...
}

// Twilio: client.messages.create({ to, from, body })
async function sendText({ phoneNumberId, to, text }) {
  const res = await fetch(`${KAPSO}/${phoneNumberId}/messages`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      messaging_product: 'whatsapp',
      to,
      type: 'text',
      text: { body: text },
    }),
  });
  const body = await res.json();
  return body.messages[0].id;
}

// Twilio: form-encoded POST, reply with TwiML.
// express.raw, not express.json: the signature covers the bytes Kapso sent.
app.post('/webhooks/whatsapp', express.raw({ type: 'application/json' }), async (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');

  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).send('Invalid signature');
  }

  if (req.headers['x-webhook-event'] !== 'whatsapp.message.received') {
    return res.sendStatus(200);
  }

  const { message, conversation, phone_number_id } = JSON.parse(req.body);

  // Enqueue before acknowledging. A 200 tells Kapso the event is handled, so
  // anything that throws after this point is lost rather than retried.
  await queue.add('inbound', {
    idempotencyKey: req.headers['x-idempotency-key'],
    from: message.from,
    text: message.text?.body,
    conversationId: conversation.id,
    phoneNumberId: phone_number_id,
  });

  res.sendStatus(200);
});

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

Field mapping

Signature verification

Delivery behavior

Step 5: Templates

Multi-tenant setups

Bulk sends

Keep your Twilio account for numbers

Feature map

What does not map

Cutover

Troubleshooting

Node.js example

Need help

​Step 1: Connect your number

​Step 2: Get your phone number IDs

​Step 3: Update message sending

​Step 4: Update webhooks

​Field mapping

​Signature verification

​Delivery behavior

​Step 5: Templates

​Multi-tenant setups

​Bulk sends

​Keep your Twilio account for numbers

​Feature map

​What does not map

​Cutover

​Troubleshooting

​Node.js example

​Need help

Step 1: Connect your number

Step 2: Get your phone number IDs

Step 3: Update message sending

Step 4: Update webhooks

Field mapping

Signature verification

Delivery behavior

Step 5: Templates

Multi-tenant setups

Bulk sends

Keep your Twilio account for numbers

Feature map

What does not map

Cutover

Troubleshooting

Node.js example

Need help