Guías

Migrar desde Twilio, 360dialog, YCloud o Kapso

Si hoy mandas WhatsApp con Twilio, 360dialog, YCloud o Kapso, pasar a heysteff es cambiar una llamada: todo sale por el mismo POST /v1/messages, y con ese mismo endpoint también llegas a Instagram, Messenger, SMS y correo. Esta guía junta las equivalencias de endpoints, webhooks y conceptos, y los pasos para cambiarte sin cortar el servicio.

Los datos de cada proveedor salen de su documentación pública (revisada en noviembre de 2026). Donde no pudimos confirmar un detalle, lo decimos de forma general: revisa la documentación de tu proveedor antes de borrar código.

Lo que cambia#

• Un formato para todos los canales. En vez del cuerpo de la Cloud API de Meta (messaging_product, type, text.body) o de los parámetros de formulario de Twilio (To, From, Body), heysteff usa channel, to, content y content_type. Cambiar channel a instagram, facebook, sms o gmail manda por otro canal sin tocar nada más.
• Autenticación con Bearer. Authorization: Bearer sk_live_… en todas las llamadas. Ver Autenticación.
• El número no va en la URL. Con un solo número por canal no hace falta indicarlo; con varios, pasa channel_connection_id.
• Idempotencia en cada envío. El header Idempotency-Key hace que un reintento nunca mande el mensaje dos veces.
• Además de la API: bandeja compartida en la web y en la app móvil, Shopify, servidor MCP y sandbox sin número propio.

Desde la Cloud API de Meta directa#

Si hoy llamas a graph.facebook.com con tu propio token de Meta, no tienes que reescribir nada: cambia la URL base a https://app.heysteff.com/api/meta/whatsapp/v21.0 (sirve cualquier versión) y el token por tu API key de heysteff (Authorization: Bearer sk_live_…). El phone_number_id sigue siendo el mismo. Para tu receptor de webhooks, crea el webhook con format: "meta": llega el mismo payload de Meta, firmado con X-Hub-Signature-256 y el secreto del webhook. Detalle en Compatible con Meta. Si vienes de un proveedor que expone la Cloud API (360dialog, Kapso), también puedes usar esa misma URL en vez de pasar a /v1.

Equivalencias de endpoints#

Antes y después, con un texto:

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: pedido-1042-en-camino" \
  -d '{ "channel": "whatsapp_cloud", "to": "+56912345678", "content": "Hola Ana, tu pedido ya va en camino" }'

Y una plantilla en el formato de la Cloud API (360dialog, YCloud y Kapso usan este cuerpo o uno muy parecido):

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

Si tu plantilla lleva encabezado con imagen o botones con variables, manda template.components con la forma de la Graph API de Meta: heysteff la respeta y gana sobre body_params. Más en Tipos de mensaje.

Webhooks y firma#

heysteff manda un solo formato para todos los canales: un POST JSON con el sobre { id, tenant_id, event, ts, data }. El mensaje entrante trae en data todo lo que necesitas para contestar (channel, external_user_id, channel_connection_id).

Si vienes de YCloud, la firma es casi igual: cambia el header y el prefijo v1=. Si vienes de Kapso, suma el timestamp al string firmado. Si vienes de Twilio, deja de firmar la URL: heysteff firma el cuerpo crudo.

import crypto from 'node:crypto';

// rawBody: el cuerpo tal como llegó, sin parsear.
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);
}

El SDK lo hace por ti con verifyWebhook, y heysteff webhooks trigger de la CLI te manda un aviso firmado a localhost para probar. Detalle en Webhooks.

Conceptos#

Pasos para cambiarte#

1. Crea tu cuenta y tu API key. Crea una cuenta developer y corre curl -fsSL https://developers.heysteff.com/install.sh | bash y después heysteff setup: te lleva a la consola, guarda la key y manda un mensaje de prueba.
2. Prueba en el sandbox. Con una key sk_test_ cambia tus llamadas a POST /v1/messages sin tocar tu número actual.
3. Mueve tu receptor de webhooks. Crea el webhook en la consola, guarda el secreto y cambia la verificación de la firma (ver arriba). Mientras migras, tu servidor puede aceptar los dos formatos.
4. Conecta un número. En la consola, sección Números, conecta tu número con la ventana de alta de Meta o usa un número de heysteff. Si tu número hoy está en otro proveedor, sigue el proceso de Meta para llevarlo a otra cuenta o proveedor, y revisa con tu proveedor actual qué pasa con sus plantillas.
5. Revisa tus plantillas. GET /v1/templates muestra las aprobadas del número conectado. Si venías de Twilio, reemplaza cada ContentSid por el nombre y el idioma de la plantilla.
6. Cambia a sk_live_ y apaga el proveedor anterior cuando veas pasar tus mensajes en la bandeja y en el registro de entregas.

¿Usas Claude Code, Cursor o Codex? Instala la skill de heysteff (ver Agentes de código) y pídele que migre tu integración con esta guía.