Migrar
Migrar desde Evolution API
Cómo reemplazar Evolution API por Messajo y conservar tu número.
Esta página muestra qué cambia al salir de Evolution API y cómo cada ruta suya se convierte en una llamada de Messajo. Las tablas generales de cualquier proveedor están en Migrar desde otro proveedor; aquí solo van los puntos de Evolution API.
Qué cambia en el modelo
Sección titulada «Qué cambia en el modelo»Evolution API vincula un teléfono, como WhatsApp Web. Messajo usa la API oficial de Meta. En la práctica:
| En Evolution 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»Evolution API autentica con el encabezado apikey (global o de la instancia) e identifica la instancia por el nombre en la ruta. 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 “una clave por instancia”.
Consulta Tipos de clave.
Rutas lado a lado
Sección titulada «Rutas lado a lado»Las rutas de Evolution API vienen de la documentación de Evolution Foundation; todas llevan el nombre de la instancia al final.
| Ruta en Evolution API | En Messajo |
|---|---|
POST /message/sendText/{instanceName} |
POST /v1/messages con type: "text". Consulta Enviar texto |
POST /message/sendMedia/{instanceName} (imagen, video, documento y audio) |
type: "image", "video", "document" o "audio". Consulta Enviar imagen, video, documento y audio |
| Enviar sticker (sin ruta en la documentación consultada) | type: "sticker". Consulta Enviar sticker |
POST /message/sendLocation/{instanceName} |
type: "location". Consulta Enviar y pedir ubicación |
POST /message/sendContact/{instanceName} |
type: "contacts". Consulta Enviar contacto |
POST /message/sendButtons/{instanceName} |
type: "interactive", botones de respuesta. Consulta Enviar botones |
POST /message/sendList/{instanceName} |
type: "interactive", lista. Consulta Enviar lista |
POST /message/sendReaction/{instanceName} |
type: "reaction". Consulta Enviar reacción |
Opción de citar un mensaje (quoted) |
reply_to en el cuerpo del envío |
POST /chat/markMessageAsRead/{instanceName} |
POST /v1/messages/{id}/read. Consulta Marcar como leído |
| Multimedia por URL | link (URL pública) o media_id, obtenido con POST /v1/media (multipart) |
Ejemplo: enviar un texto
Sección titulada «Ejemplo: enviar un texto»El cuerpo del texto varía entre versiones de Evolution API (text directo o dentro de textMessage); revisa el de tu instalación.
curl https://TU-SERVIDOR/message/sendText/mi-instancia \ -H "apikey: $EVOLUTION_APIKEY" \ -H "Content-Type: application/json" \ -d '{ "number": "5511999999999", "text": "¡Hola! Tu pedido salió para entrega." }'curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "connection_id": "conn_...", "to": "5511999999999", "type": "text", "text": { "body": "¡Hola! Tu pedido salió para entrega." } }'import { Messajo } from "@messajo/sdk";
const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });
await messajo.messages.send({ connection_id: "conn_...", to: "5511999999999", type: "text", text: { body: "¡Hola! Tu pedido salió para entrega." },});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 @s.whatsapp.net no existen; cualquier carácter que no sea dígito se descarta.
Webhooks
Sección titulada «Webhooks»| En Evolution API | En Messajo |
|---|---|
| Evento de mensaje recibido | Evento message.received |
| Evento de actualización de estado del mensaje | Evento message.status |
| Evento de estado de la conexión de la instancia | Eventos connection.* |
| Evento de 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 de
apikeyaAuthorizationy al nuevo formato de cuerpo, con destinatarios sin sufijos. - Instancia de Evolution 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.