Migrar
Migrar desde Z-API
Cómo reemplazar Z-API por Messajo y conservar tu número.
Esta página muestra qué cambia al salir de Z-API y cómo cada operación suya se convierte en una llamada de Messajo. Las tablas generales de cualquier proveedor (Cloud API, 360dialog, Twilio y APIs no oficiales) están en Migrar desde otro proveedor; aquí solo van los puntos de Z-API.
Qué cambia en el modelo
Sección titulada «Qué cambia en el modelo»Z-API vincula un teléfono, como WhatsApp Web. Messajo usa la API oficial de Meta. En la práctica:
| En Z-API | En Messajo |
|---|---|
| Leer el código QR | Alta oficial de Meta (Embedded Signup), desde el panel |
| Instancia | Conexión (conn_…) |
| Mensaje libre a cualquier hora | Mensaje libre solo dentro de las 24 h del último mensaje de la persona; fuera de eso, una plantilla aprobada |
| Contacto que nunca te escribió | Exige opt-in: la persona debe haber aceptado recibir mensajes |
| Sin cobro por mensaje de Meta | Meta cobra por mensaje de plantilla, directamente a ti. Consulta Costos de Meta |
| Número vinculado | Número oficial, con calidad y límites medidos por Meta |
Conservar el número
Sección titulada «Conservar el número»Para no perder la atención desde el celular, conecta en coexistencia: la app de WhatsApp Business sigue funcionando y Messajo importa los contactos y hasta 6 meses de historial, una sola vez, al conectar.
- Exige la app WhatsApp Business 2.24.17 o más nueva, con confirmación por código QR en la app.
- El caudal queda fijo en 20 mensajes por segundo.
- Los grupos no se sincronizan en coexistencia. Si dependes de grupos, consulta Grupos: requieren el modo solo API.
- Para más volumen o un número nuevo, usa el modo solo API.
El paso a paso está en Conectar WhatsApp; si algo se traba, consulta Problemas en la coexistencia.
Autenticación
Sección titulada «Autenticación»Z-API identifica la instancia por su ID y su token, que aparecen en el panel de Z-API. En Messajo toda llamada lleva Authorization: Bearer <clave>:
- clave de organización (
mj_…): se envía conconnection_iden el cuerpo; - clave de conexión (
mjc_…): vale solo para una conexión y no necesitaconnection_id. Es lo más parecido a “un token por instancia”.
Consulta Tipos de clave.
Operaciones lado a lado
Sección titulada «Operaciones lado a lado»Las rutas de Z-API no están aquí: consúltalas en la documentación de Z-API. La columna izquierda nombra la operación.
| Operación en Z-API | En Messajo |
|---|---|
| Enviar texto | POST /v1/messages con type: "text". Consulta Enviar texto |
| Enviar imagen | type: "image". Consulta Enviar imagen |
| Enviar video | type: "video". Consulta Enviar video |
| Enviar audio | type: "audio". Consulta Enviar audio |
| Enviar documento | type: "document". Consulta Enviar documento |
| Enviar sticker | type: "sticker". Consulta Enviar sticker |
| Enviar ubicación | type: "location". Consulta Enviar y pedir ubicación |
| Enviar contacto | type: "contacts". Consulta Enviar contacto |
| Enviar botones | type: "interactive", botones de respuesta. Consulta Enviar botones |
| Enviar lista de opciones | type: "interactive", lista. Consulta Enviar lista |
| Reaccionar a un mensaje | type: "reaction". Consulta Enviar reacción |
| Responder citando un mensaje | reply_to en el cuerpo del envío |
| Marcar como leído | POST /v1/messages/{id}/read. Consulta Marcar como leído |
| Enviar un archivo por URL | link (URL pública) o media_id, obtenido con POST /v1/media (multipart) |
El envío de texto de Z-API usa los campos phone y message (Enviar texto simple). En Messajo pasan a ser to y text.body.
Formato del destinatario
Sección titulada «Formato del destinatario»Messajo acepta el teléfono con prefijo de país, solo dígitos (por ejemplo 5511999999999), o un contacto ctc_…. Los sufijos como @c.us no existen; cualquier carácter que no sea dígito se descarta.
Webhooks
Sección titulada «Webhooks»| En Z-API | En Messajo |
|---|---|
| Retorno de mensaje recibido | Evento message.received |
| Retorno de estado del mensaje (enviado, entregado, leído) | Evento message.status |
| Retorno de estado de la instancia | Eventos connection.* |
| Retorno del código QR | Sin equivalente: la conexión se hace desde el panel |
Registras un destino de eventos y Messajo firma cada entrega con Messajo-Signature (HMAC-SHA256). Verifica la firma en tu servidor, como en Verificar la firma. En coexistencia, los mensajes enviados desde la app del celular llegan como message.echo.
Qué no tiene equivalente o funciona distinto
Sección titulada «Qué no tiene equivalente o funciona distinto»- Enviar a cualquier persona a cualquier hora. En Messajo rige la ventana de 24 h y, fuera de ella, solo plantilla aprobada. Consulta Límites.
- Grupos. No se sincronizan en coexistencia; para usar grupos, el modo es solo API. Consulta Grupos.
Checklist de cambio
Sección titulada «Checklist de cambio»- Conexión creada (coexistencia o solo API) y Activa en el panel.
- Plantillas creadas y aprobadas para los mensajes que envías fuera de la ventana.
- Destinos de eventos creados, con la firma verificada en tu servidor.
- Una clave de API por integración, con solo los permisos y conexiones necesarios.
- Prueba de punta a punta con un número tuyo: enviar, recibir, estados y plantilla.
- Integración cambiada al nuevo
Authorizationy formato de cuerpo, con destinatarios sin sufijos. - Instancia de Z-API apagada solo después de que la conexión oficial esté activa y probada, y el dispositivo vinculado por código QR desvinculado de ella.