Ir al contenido

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.

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

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.

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 con connection_id en el cuerpo;
  • clave de conexión (mjc_…): vale solo para una conexión y no necesita connection_id. Es lo más parecido a “un token por instancia”.

Consulta Tipos de clave.

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.

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.

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.
  • 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 Authorization y 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.