Cómo conectar un CRM a una bandeja omnicanal con webhooks

Esta guía es para CTO, arquitectos de soluciones y administradores de CRM que necesitan que su CRM y su bandeja de entrada omnicanal compartan una única visión del cliente. Explica qué eventos sincronizar, cómo construir un receptor de webhooks que resista reintentos y duplicados, cómo cruzar contactos entre WhatsApp, Instagram y correo, y qué normas de privacidad condicionan el diseño.

¿Qué deben intercambiar un CRM y una bandeja de entrada omnicanal?

La bandeja debe decirle al CRM quién contactó con la empresa, por qué canal, sobre qué y con qué resultado. El CRM debe decirle a la bandeja quién es el cliente, quién lo gestiona y qué contexto necesitan los agentes.

Empiece por el conjunto más pequeño que sostenga un flujo de trabajo real. Sincronizar el cuerpo de cada mensaje con el CRM rara vez es necesario y aumenta la exposición en materia de privacidad.

¿A qué eventos de webhook conviene suscribirse?

Suscríbase a los eventos del ciclo de vida, no solo a los mensajes. Los nombres exactos varían entre plataformas, así que asígnelos a estas categorías:

• Conversación creada: primer mensaje de un cliente por cualquier canal.
• Mensaje recibido: mensaje entrante del cliente, con el canal y el identificador del remitente.
• Mensaje enviado: mensaje saliente de un agente o plantilla.
• Estado del mensaje: enviado, entregado, leído o fallido, cuando el canal lo informa.
• Conversación asignada: cambio de propietario o de cola.
• Conversación resuelta o reabierta: transiciones de estado.
• Contacto actualizado: identificadores o atributos modificados en la bandeja.

En WhatsApp, los webhooks de Meta entregan a la plataforma los mensajes entrantes y las actualizaciones de estado de los salientes; después, su proveedor de bandeja de entrada expone sus propios eventos a sus sistemas.

¿Cómo se construye un receptor de webhooks fiable?

Aceptar rápido, verificar, guardar una vez, procesar después. La mayoría de los problemas de entrega vienen de hacer trabajo del CRM dentro de la propia solicitud del webhook.

Diseño del receptor paso a paso

1. Exponga un endpoint HTTPS por entorno, por ejemplo /webhooks/inbox.
2. Verifique la autenticidad. Compruebe la firma (normalmente un HMAC del cuerpo sin procesar con un secreto compartido, tal como define la RFC 2104) o el token que documente el emisor. Calcúlela sobre los bytes originales antes de interpretar el JSON.
3. Compruebe la vigencia. Si se incluye una marca de tiempo, rechace los eventos fuera de una tolerancia corta para limitar las repeticiones.
4. Deduplique. Inserte el ID del evento en una tabla con restricción de unicidad. Si la inserción falla porque el ID ya existe, devuelva éxito y deténgase.
5. Encole. Ponga el evento en una cola y devuelva de inmediato una respuesta 2xx.
6. Procese de forma asíncrona. Un worker lee la cola, cruza el contacto y escribe en el CRM mediante upserts.
7. Reintente con backoff. Si el CRM está caído, reintente desde su cola con backoff exponencial; no dependa de los reintentos del emisor.
8. Dead-letter. Tras varios fallos, mueva el evento a una cola de mensajes fallidos (dead-letter) y avise a una persona.
9. Concilie. Ejecute una tarea periódica que compare las conversaciones recientes de la bandeja con los registros del CRM y rellene los huecos con la API de la bandeja.

Por qué importan la idempotencia y el orden

Los emisores de webhooks suelen reintentar cuando no reciben una respuesta de éxito a tiempo, lo que hace que la entrega sea «al menos una vez». El mismo evento puede llegar dos veces, y un evento «resuelta» puede llegar antes que el último «mensaje recibido». Para gestionarlo:

• Use el ID del evento como clave de deduplicación.
• Use upserts con clave en el ID de la conversación o del mensaje en el CRM.
• Compare las marcas de tiempo o los números de secuencia de los eventos e ignore los estados más antiguos.

Cuando su flujo del CRM llame a la API de la bandeja para enviar un mensaje, pase una clave de idempotencia si la API la admite; el borrador del IETF sobre una cabecera HTTP Idempotency-Key describe el patrón habitual.

¿Cómo se cruzan los contactos entre canales?

Cruce con identificadores normalizados, priorice las coincidencias deterministas y derive la ambigüedad a una persona.

Reglas de decisión:

1. Una coincidencia exacta: vincúlela.
2. Ninguna coincidencia: cree un lead o un «contacto sin cruzar» con el canal de origen.
3. Varias coincidencias: márquelas para un agente; no las fusione automáticamente.
4. El cliente confirma otro identificador en la conversación: vincúlelo anotando la evidencia.

¿Cómo se gestiona la privacidad de los datos en una integración con un CRM?

Mueva solo lo que cada sistema necesita, documente el porqué y haga que la supresión funcione en ambos sistemas.

• Minimización de datos. Guarde en el CRM enlaces a conversaciones, resultados y resúmenes; mantenga las transcripciones completas en la bandeja salvo que exista una finalidad definida.
• Base legal y consentimiento. Registre el consentimiento de marketing por canal; una conversación de soporte no es consentimiento para plantillas de marketing.
• Conservación. Alinee los plazos de conservación de la bandeja, el CRM, las colas y los registros; los registros de cargas de webhooks suelen olvidarse.
• Control de acceso. Limite quién puede ver el contenido de los mensajes y los adjuntos en el CRM.
• Solicitudes de supresión y acceso. Haga que una solicitud en un sistema se propague al otro.
• Transferencias internacionales. Compruebe dónde almacena los datos cada sistema. El RGPD se aplica a los datos personales de las personas en la UE, y tanto Emiratos Árabes Unidos como Arabia Saudí tienen sus propias leyes de protección de datos personales; confirme las obligaciones vigentes con el regulador correspondiente y con su equipo jurídico.

¿Qué aspecto tiene una arquitectura de referencia?

En texto, el flujo es: canales a la bandeja, bandeja al receptor, receptor a la cola, cola al worker, worker al CRM y flujos del CRM de vuelta a la API de la bandeja.

Ejemplo práctico: un grupo de clínicas en Yeda

«Wahat Clinics», un grupo sanitario ficticio de Arabia Saudí, usa un CRM para las citas de los pacientes y una bandeja de entrada para WhatsApp y correo.

• Un paciente escribe por WhatsApp. La bandeja emite un evento de conversación creada; el receptor lo verifica, lo guarda y lo encola.
• El worker normaliza el número a E.164, encuentra un único registro de paciente y registra una actividad con un enlace a la conversación, no con el texto del mensaje.
• El CRM indica que el idioma preferido del paciente es el árabe y lo envía a la bandeja, que lo enruta a la cola en árabe.
• Cuando la cita se reserva en el CRM, un flujo llama a la API de la bandeja para enviar una confirmación con una plantilla de utilidad aprobada, pasando el ID de la cita como clave de idempotencia para que un reintento no pueda enviar dos confirmaciones.
• El evento «mensaje entregado» de la bandeja actualiza el registro de la cita.

¿Cuáles son los errores más comunes?

• Escribir en el CRM dentro de la solicitud del webhook, lo que causa tiempos de espera, reintentos y duplicados.
• No deduplicar, con lo que se crean actividades y contactos duplicados.
• Cruzar teléfonos sin normalizar, de modo que los formatos +971 y con 0 nunca coinciden.
• Fusionar automáticamente por nombre o por coincidencias parciales.
• Copiar todo el contenido de los mensajes al CRM sin finalidad ni regla de conservación.
• No conciliar, de forma que un evento perdido se convierte en una desviación permanente.
• Secretos en el código fuente y sin plan de rotación.

Cómo ayuda OmniChannels.ai

OmniChannels.ai, con la tecnología de BroadNet Technologies, reúne las conversaciones de WhatsApp, Instagram, Messenger, Telegram y correo en una única Omni Inbox con asignación de agentes y etiquetado, además de el alta en WhatsApp mediante el registro integrado de Meta (Embedded Signup) y plantillas aprobadas con variables, multimedia y botones. Para la integración con el CRM, la API REST está documentada públicamente con una especificación OpenAPI 3.1, y los webhooks notifican los estados de entrega (SENT, DELIVERED, READ, FAILED y otros) en un único formato normalizado. Los informes de entrega (DLR), con filtros y exportación a CSV, facilitan la conciliación. Empiece por la página de desarrolladores.