Actualizado el 25/10/2026
En la coexistencia de WhatsApp se sincronizan con la API tres cosas: los contactos de la app que tienen WhatsApp, el historial de chats individuales de los últimos seis meses (si la empresa lo autoriza) y, a partir de ahí, cada mensaje que la empresa envía desde el celular, mediante el webhook smb_message_echoes. No se sincronizan grupos, llamadas, catálogo, estados, etiquetas, respuestas rápidas ni listas de difusión. La sincronización inicial debe pedirse dentro de las 24 horas posteriores a la integración, y cada tipo solo puede pedirse una vez.
Este artículo detalla qué entra, qué queda fuera, cómo llegan los datos al webhook y qué cambia en la app después de la integración. La coexistencia es la función que permite seguir usando el número en la app WhatsApp Business y, al mismo tiempo, conectarlo a la Cloud API.
Resumen: qué se sincroniza y qué no
La tabla sigue la comparación de funciones de la página oficial Onboard WhatsApp Business app users:
| Elemento | ¿Se sincroniza con la API? | Cómo llega |
|---|---|---|
| Contactos con número de WhatsApp | Sí | Webhook smb_app_state_sync |
| Chats individuales de los últimos 6 meses | Sí, si la empresa lo autoriza | Webhook history |
| Multimedia de chats antiguos | Solo ID de archivos de los últimos 14 días | Webhooks history separados |
| Mensajes nuevos enviados desde la app | Sí | Webhook smb_message_echoes |
| Mensajes nuevos recibidos | Sí | Webhook messages |
| Edición y eliminación de mensajes | Sí (pasa a estar soportado) | Eventos de edición y revocación |
| Grupos | No | — |
| Llamadas de voz y video | No | — |
| Catálogo, pedidos, estados | No | — |
| Saludo, ausencia, respuestas rápidas, etiquetas | No | — |
| Perfil comercial y canales | No | — |
| Listas de difusión | No; quedan solo de lectura en la app | — |
Contactos: smb_app_state_sync
La sincronización de contactos se pide con la API de datos de la app (smb_app_data), justo después de la integración:
curl -X POST "https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/smb_app_data" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ "messaging_product": "whatsapp", "sync_type": "smb_app_state_sync" }'La respuesta trae un request_id, que Meta recomienda guardar para casos de soporte. Luego llegan webhooks smb_app_state_sync con los contactos de la app. Cada contacto trae full_name, first_name, phone_number y action:
add: contacto agregado o editado;remove: contacto eliminado (sin los campos de nombre).
Después de la carga inicial, el mismo webhook se sigue disparando cada vez que la empresa agrega, edita o elimina un contacto en la app. Solo entran contactos con número de WhatsApp.
¿Quieres probar mientras lees? Crea tu cuenta en Vectalk y envía el primer mensaje por la API oficial. Crear cuenta gratis →
Historial: webhook history
El historial se pide con la misma API, cambiando el sync_type:
curl -X POST "https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/smb_app_data" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ "messaging_product": "whatsapp", "sync_type": "history" }'Lo que dice la documentación sobre el contenido:
- Período: mensajes enviados y recibidos hasta 180 días antes de la integración.
- Solo chats individuales: los mensajes de grupos no entran.
- Multimedia: los mensajes multimedia llegan sin el ID del archivo; los ID llegan en webhooks separados y solo para archivos de los últimos 14 días.
- Consentimiento: la empresa elige en la app si comparte el historial. Si lo rechaza, llega un webhook
historycon el error2593109.
Fases y bloques
El historial llega dividido en tres fases, contadas desde el día de la integración (día 0):
| Fase | Período |
|---|---|
| 0 | Día 0 al día 1 |
| 1 | Día 1 al día 90 |
| 2 | Día 90 al día 180 |
Cada fase puede llegar en varios bloques, no necesariamente en orden. Usa chunk_order para ordenarlos, phase para seguir la fase y progress para el total: 100 indica que la sincronización terminó. Si una fase no tiene mensajes, no se envía ningún webhook para ella.
Meta advierte que un solo webhook puede describir miles de mensajes. La recomendación es guardar el payload primero y procesarlo de forma asíncrona, para que el endpoint no exceda el tiempo de respuesta.
Mensajes nuevos: smb_message_echoes
Después de la integración, el dueño del número sigue respondiendo desde el celular. Cada mensaje enviado desde la app (o desde un dispositivo vinculado compatible) genera un webhook smb_message_echoes, que debes guardar en la conversación del contacto. Ejemplo de la documentación:
{
"object": "whatsapp_business_account",
"entry": [{
"id": "102290129340398",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"message_echoes": [{
"from": "15550783881",
"to": "16505551234",
"id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0N0FCNjMA",
"timestamp": "1700255121",
"type": "text",
"text": { "body": "Here's the info you requested! https://www.meta.com/quest/quest-3/" }
}]
},
"field": "smb_message_echoes"
}]
}]
}Fíjate en que el arreglo se llama message_echoes (no messages) y en que incluye el campo to, con el número del cliente. Sin este webhook, tu sistema solo ve los mensajes recibidos y los enviados por la API: la mitad de la conversación. Esto pesa sobre todo en la atención con varios agentes, donde el agente necesita ver lo que el dueño respondió desde el celular.
Cómo enrutar los eventos en tu endpoint
Un esqueleto en Node.js para separar los campos:
export async function recibirWebhook(body, cola) {
for (const entry of body.entry ?? []) {
for (const change of entry.changes ?? []) {
const { field, value } = change;
switch (field) {
case 'messages':
await cola.add('mensaje', value); // recibidos y estados
break;
case 'smb_message_echoes':
await cola.add('eco_app', value.message_echoes);
break;
case 'history':
await cola.add('historial', value); // procesar asíncrono
break;
case 'smb_app_state_sync':
await cola.add('contactos', value);
break;
case 'account_update':
await cola.add('cuenta', value); // ej.: PARTNER_REMOVED
break;
}
}
}
}Responde 200 rápido y procesa desde la cola. Para probar estos eventos antes de pasar a producción, consulta cómo probar el webhook en local.
Dispositivos vinculados: dónde falla la sincronización
La app admite hasta cuatro dispositivos vinculados. En la integración se desvinculan todos, y la empresa puede volver a vincular los compatibles. WhatsApp para Windows y WhatsApp para WearOS no son compatibles.
Consecuencias documentadas:
- los mensajes de clientes que usan un dispositivo vinculado no compatible no disparan el webhook
messages, así que no aparecen en tu sistema; - en esos casos puede llegar un webhook de mensaje no soportado con el error
131060. El mismo error aparece cuando alguien escribe por primera vez (común tras un clic en un anuncio) y suele resolverse en segundos.
Cuando recibas 131060, pide a la empresa que revise el mensaje en la app.
Qué cambia en la app después de la integración
Algunas funciones de la app se apagan o cambian:
- Mensajes temporales: desactivados en los chats individuales.
- Ver una vez: desactivado en los chats individuales.
- Ubicación en tiempo real: desactivada en los chats individuales.
- Listas de difusión: desactivadas; no se pueden crear nuevas y las existentes quedan solo de lectura.
- Edición y eliminación de mensajes: pasan a estar soportadas y reflejadas.
Lo demás (grupos, llamadas, catálogo, estados, mensajes de saludo y ausencia, respuestas rápidas, etiquetas, perfil y canales) sigue igual en la app, pero no existe en la API. Si tu operación depende de las etiquetas de la app para organizar clientes, por ejemplo, tendrás que recrear esa lógica en tu sistema.
Plazo de 24 horas: checklist
La sincronización inicial tiene reglas estrictas: la empresa debe sincronizarse dentro de las 24 horas posteriores a la integración, y cada solicitud (contactos e historial) solo puede hacerse una vez. ¿Se venció el plazo o hay que repetir? La empresa tiene que desconectarse y pasar de nuevo por el flujo.
- Suscríbete a
account_update,history,smb_app_state_syncysmb_message_echoesantes de abrir el flujo al cliente. - Asegúrate de que el endpoint guarda el payload y responde rápido.
- Pide contactos e historial justo después de la integración.
- Avisa al cliente que la sincronización está en curso y pídele que mantenga la app abierta.
- Sigue
progresshasta 100 y avisa al cliente cuando termine. - Guarda los
request_idde las dos llamadas.
Para comprobar si el número está en coexistencia, consulta is_on_biz_app y platform_type en el número; true y CLOUD_API indican app y API al mismo tiempo. Si el número no está en la app Business y quieres llevarlo directo a la API, consulta cómo liberar un número que ya está en WhatsApp.
Coexistencia con Vectalk
Vectalk ofrece coexistencia: el número sigue en la app WhatsApp Business y también funciona en la API. Los webhooks son los de la documentación de Meta, así que smb_message_echoes, history y smb_app_state_sync llegan a las URL que registres con POST /api/webhooks, en el mismo formato mostrado arriba. Los detalles de autenticación y webhooks están en la documentación; las dudas sobre la sincronización inicial de tu cuenta se pueden resolver en el Centro de ayuda.
Preguntas frecuentes
¿Cuántos meses de historial trae la coexistencia?
Hasta seis meses (180 días) de chats individuales anteriores a la integración, si la empresa autoriza compartirlos en la app. Los grupos no entran.
¿Las fotos y audios antiguos también llegan?
Solo en parte. Los mensajes multimedia del historial llegan sin el archivo; los ID llegan en webhooks separados y solo para archivos de los últimos 14 días antes de la integración.
¿Puedo volver a sincronizar el historial después?
No por la API. Cada sincronización solo puede pedirse una vez. Para repetirla, la empresa debe desconectarse y rehacer el flujo de integración.
¿Los mensajes que envío desde el celular aparecen en el sistema?
Sí, mediante el webhook smb_message_echoes, siempre que se envíen desde la app o desde un dispositivo vinculado compatible. Los mensajes enviados desde la app no abren ni extienden la ventana de atención de la API; lo explicamos en coexistencia con CRM y límites.
¿Los grupos de la app pasan a la API?
No. Los grupos siguen funcionando en la app, pero no se sincronizan ni están disponibles por la API.
Fuentes oficiales consultadas el 25/10/2026: Onboard WhatsApp Business app users (Coexistence), Usar un número de WhatsApp existente, Referencia del webhook messages.
Pon a funcionar el WhatsApp oficial de tu empresa
Crea tu cuenta, conecta tu número a la API oficial (puedes mantener la app con coexistencia) y empieza a atender y enviar mensajes.