Migrar
Migrar desde otro proveedor
Qué cambia al traer tu integración desde otro proveedor a Messajo.
Cuánto cambia
Sección titulada «Cuánto cambia»El esfuerzo depende de dónde vienes. Si ya usas la API oficial, cambia poco; si vienes de una API no oficial, cambia el modelo.
| Vienes de | Envío | Webhooks | Esfuerzo |
|---|---|---|---|
| Cloud API directa | Mismo cuerpo en la capa espejo; cambia la URL base y el token | Formato meta: el mismo value que ya procesas |
Pequeño |
| 360dialog | Mismo cuerpo en la capa espejo; cambia la URL, quita el D360-API-KEY y pon el phone_number_id en la ruta |
Formato meta |
Pequeño |
| Twilio | Reescribir: capa simple o espejo | Los estados pasan a message.status |
Medio |
| Evolution, WAHA, Z-API, uazapi | Reescribir y adoptar las reglas de Meta (ventana, plantillas, opt-in) | Formato normalized o meta |
Grande |
Las dos capas de la API (espejo de Meta y simple) usan la misma clave. Ver Conceptos.
Desde la Cloud API o 360dialog
Sección titulada «Desde la Cloud API o 360dialog»La capa espejo recibe el mismo cuerpo que Meta, campo por campo. El código que arma el mensaje queda igual; cambian la URL y la autenticación.
| Antes | En Messajo | |
|---|---|---|
| Cloud API | POST https://graph.facebook.com/<versión>/{phone_number_id}/messages |
POST https://api.messajo.com/v1/whatsapp/{phone_number_id}/messages |
| 360dialog | POST https://waba-v2.360dialog.io/messages |
POST https://api.messajo.com/v1/whatsapp/{phone_number_id}/messages |
| Autenticación | Authorization: Bearer <token de Meta> o D360-API-KEY: <clave> |
Authorization: Bearer mj_... |
curl -X POST "https://api.messajo.com/v1/whatsapp/$PHONE_NUMBER_ID/messages" \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "messaging_product": "whatsapp", "to": "5491155555555", "type": "text", "text": { "body": "Hola desde Messajo" } }'- En 360dialog la clave ya identifica el número. En Messajo la clave es de la organización, así que el
phone_number_idva en la ruta. Aparece en la página de la conexión. - La cabecera
D360-API-KEYsale; entraAuthorization: Bearercon una clave de API con el permisosend. - El token de Meta ya no vive en tu código: Messajo guarda el token de la conexión, cifrado.
- La respuesta y los errores de Meta vuelven como llegaron, con el mismo cuerpo
{ "error": { "code", … } }que tu código ya trata. Solo los errores del propio Messajo (clave, permiso, límite) usan el formato único. - En los webhooks, elige el formato
metaen el destino para recibir el mismovalueque manda Meta, dentro del sobre de Messajo. Ver Eventos.
Qué acepta el espejo
Sección titulada «Qué acepta el espejo»La ruta es /v1/whatsapp/{id}/<resto de la ruta de Meta>, con el método, la query y el cuerpo de Meta. La versión de la Graph API es la del servidor.
{id} |
Va a | Ejemplo |
|---|---|---|
phone_number_id de una conexión tuya |
el número | POST /v1/whatsapp/{phone_number_id}/messages, GET …/whatsapp_business_profile, POST …/media |
waba_id (cuenta de mensajes) de una conexión tuya |
la cuenta | GET /v1/whatsapp/{waba_id}/message_templates |
phone_number_id + nodes/{node_id} |
un nodo suelto de Meta | GET /v1/whatsapp/{phone_number_id}/nodes/{media_id}, DELETE …/nodes/{template_id} |
El waba_id aparece en la página de la conexión, en Cuenta de mensajes (WABA). Los nodos sueltos (multimedia, plantilla por id) pasan por el número, para que Messajo sepa de qué conexión es el pedido.
- Permiso de la clave:
POST …/messagespidesend;message_templatesy los nodos de plantilla pidentemplates; los demásGET,read; los demás cambios,admin. Una clave limitada a algunas conexiones solo alcanza esas. - Bloqueados con
403mirror_path_blocked, porque tumban la conexión:register,deregister,request_code,verify_code,smb_app_data,DELETE …/subscribed_appsyPOST …/subscribed_appsconoverride_callback_uri. - Envío:
POST …/messagespasa por el mismo límite por número que la capa simple (Envío por número), guarda el mensaje en los registros, emitemessage.senty devuelve el id de Messajo en el encabezadoX-Messajo-Message-Id. Messajo no repite el envío cuando Meta falla. - Respuesta: el estado, el cuerpo y el
content-typede Meta, másX-Request-Id. ElAuthorizationque envías nunca sigue hacia Meta.
Desde Twilio
Sección titulada «Desde Twilio»Twilio tiene formato propio (From, To y Body con el prefijo whatsapp:, en formulario), así que la llamada de envío se reescribe:
- capa simple (
POST /v1/messages), para texto, multimedia, plantillas y botones con el mismo formato en los 3 canales; - capa espejo, para usar cualquier recurso de Meta con su propio cuerpo.
Los estados de Twilio (queued, sent, delivered, read, failed) llegan como el evento message.status, y los mensajes recibidos como message.received. Cambia el StatusCallback y el webhook de entrada por un destino de eventos y pasa a verificar la firma de Messajo en lugar de la X-Twilio-Signature. Las plantillas aprobadas están en tu cuenta de Meta: sincronízalas o recréalas en Messajo.
Desde una API no oficial
Sección titulada «Desde una API no oficial»Evolution, WAHA, Z-API y uazapi simulan un teléfono. Messajo usa la API oficial de Meta, y eso cambia el modelo:
| En la API no oficial | En Messajo |
|---|---|
| Escanear el código QR | Registro oficial de Meta (Embedded Signup), desde el panel |
| Instancia | Conexión |
| Enviar cualquier mensaje a cualquier hora | Fuera de la ventana de 24 h, solo plantilla aprobada |
| Listas compradas o contactos que nunca te escribieron | Opt-in: la persona tiene que haber aceptado recibir mensajes |
| Sin costo por mensaje | Meta cobra por mensaje de plantilla, directo a ti |
| Riesgo de bloqueo del número | Número oficial, con calidad y límite medidos por Meta |
Para no perder la atención en el teléfono, conecta en coexistencia: la app de WhatsApp Business sigue funcionando y Messajo trae los contactos y hasta 6 meses de historial, una sola vez, al conectar. Los grupos no se sincronizan en la coexistencia. Ver Conectar WhatsApp.
Apaga la API anterior solo cuando la conexión oficial esté activa y probada, y desvincula de ella el dispositivo emparejado por el código QR.
El número ya está con otro socio
Sección titulada «El número ya está con otro socio»Depende del modo:
- Solo API: en el nuevo modelo de cuenta de Meta, el número puede tener varios socios a la vez. Conecta por Messajo sin quitarlo del socio actual, migra de a poco y apaga el anterior cuando termines. Ver la guía de Meta sobre el nuevo modelo de cuenta.
- Coexistencia: un socio a la vez. Desconecta en la app del teléfono y vuelve a conectar por Messajo, como en Cambiar de socio en coexistencia.
Checklist del cambio
Sección titulada «Checklist del cambio»- Plantillas sincronizadas o recreadas en Messajo, y aprobadas.
- Destinos de eventos creados, con la firma verificada en tu servidor.
- Una clave de API por integración, solo con los permisos y conexiones necesarios.
- Una prueba de punta a punta con un número tuyo: enviar, recibir, estado y plantilla.
- Integración anterior apagada solo después de la prueba, y el número desconectado del proveedor anterior, si corresponde.