Guides

Migrate from Twilio, 360dialog, YCloud or Kapso

If you send WhatsApp today with Twilio, 360dialog, YCloud or Kapso, moving to heysteff means changing one call: everything goes through the same POST /v1/messages, and that same endpoint also reaches Instagram, Messenger, SMS and email. This guide collects the endpoint, webhook and concept equivalents, and the steps to switch without downtime.

The details for each provider come from their public documentation (reviewed in November 2026). Where we could not confirm a detail, we describe it in general terms: check your provider's documentation before deleting code.

What changes#

• One format for every channel. Instead of the Meta Cloud API body (messaging_product, type, text.body) or Twilio's form parameters (To, From, Body), heysteff uses channel, to, content and content_type. Switching channel to instagram, facebook, sms or gmail sends through another channel with nothing else to change.
• Bearer authentication. Authorization: Bearer sk_live_… on every call. See Authentication.
• The number is not in the URL. With one number per channel you do not pass it; with several, send channel_connection_id.
• Idempotency on every send. The Idempotency-Key header makes sure a retry never sends the message twice.
• Beyond the API: a shared inbox on the web and in the mobile app, Shopify, an MCP server and a sandbox with no number of your own.

From the Meta Cloud API directly#

If you call graph.facebook.com today with your own Meta token, you don't have to rewrite anything: change the base URL to https://app.heysteff.com/api/meta/whatsapp/v21.0 (any version works) and the token to your heysteff API key (Authorization: Bearer sk_live_…). The phone_number_id stays the same. For your webhook receiver, create the webhook with format: "meta": the same Meta payload arrives, signed with X-Hub-Signature-256 and the webhook's secret. Details in Compatible with Meta. If you come from a provider that exposes the Cloud API (360dialog, Kapso), you can also use that same URL instead of moving to /v1.

Endpoint equivalents#

Before and after, with a text message:

curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Messages.json" \
  -u "$TWILIO_API_KEY:$TWILIO_API_SECRET" \
  --data-urlencode "From=whatsapp:+14155550100" \
  --data-urlencode "To=whatsapp:+56912345678" \
  --data-urlencode "Body=Hola Ana, tu pedido ya va en camino"

curl https://app.heysteff.com/api/v1/messages \
  -H "Authorization: Bearer $HEYSTEFF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{ "channel": "whatsapp_cloud", "to": "+56912345678", "content": "Hi Ana, your order is on its way" }'

And a template in the Cloud API format (360dialog, YCloud and Kapso use this body or one very close to it):

{
  "messaging_product": "whatsapp",
  "to": "56912345678",
  "type": "template",
  "template": {
    "name": "pedido_despachado",
    "language": { "code": "es" },
    "components": [{ "type": "body", "parameters": [
      { "type": "text", "text": "Ana" }, { "type": "text", "text": "#1042" }
    ] }]
  }
}

{
  "channel": "whatsapp_cloud",
  "to": "+56912345678",
  "content_type": "template",
  "template": { "name": "pedido_despachado", "language": "es", "body_params": ["Ana", "#1042"] }
}

If your template has an image header or buttons with variables, send template.components in the Meta Graph API shape: heysteff passes it through and it wins over body_params. More in Message types.

Webhooks and signatures#

heysteff sends one format for every channel: a JSON POST with the envelope { id, tenant_id, event, ts, data }. An inbound message carries in data everything you need to reply (channel, external_user_id, channel_connection_id).

Coming from YCloud, the signature is almost the same: change the header and the v1= prefix. Coming from Kapso, add the timestamp to the signed string. Coming from Twilio, stop signing the URL: heysteff signs the raw body.

import crypto from 'node:crypto';

// rawBody: the body exactly as received, unparsed.
function isFromHeysteff(rawBody, timestamp, signature, secret) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = 'v1=' + crypto.createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

The SDK does it for you with verifyWebhook, and heysteff webhooks trigger in the CLI sends a signed event to localhost for testing. Details in Webhooks.

Concepts#

Steps to switch#

1. Create your account and API key. Create a developer account, run curl -fsSL https://developers.heysteff.com/install.sh | bash and then heysteff setup: it takes you to the console, stores the key and sends a test message.
2. Test in the sandbox. With an sk_test_ key, switch your calls to POST /v1/messages without touching your current number.
3. Move your webhook receiver. Create the webhook in the console, store the secret and change the signature check (see above). While you migrate, your server can accept both formats.
4. Connect a number. In the console, Numbers section, connect your number through Meta's signup window or use a heysteff number. If your number lives with another provider today, follow Meta's process to move it to another account or provider, and check with your current provider what happens to its templates.
5. Check your templates. GET /v1/templates shows the approved ones for the connected number. Coming from Twilio, replace each ContentSid with the template name and language.
6. Switch to sk_live_ and turn off the old provider once your messages show up in the inbox and in the delivery log.

Using Claude Code, Cursor or Codex? Install the heysteff skill (see Coding agents) and ask it to migrate your integration with this guide.