Si tienes Messenger instalado en tu sitio para users conectados, es esencial asegurar su uso y evitar que actores malintencionados suplanten a tus users o envíen datos no autorizados.

Para mejorar la seguridad y flexibilidad para nuestros clientes, introdujimos JSON Web Tokens (JWTs) como una forma más segura y escalable de autenticar users en Messenger.

Si actualmente usas Identity Verification (IDV) para verificar users, cambiar a JWTs te dará:

Mayor control sobre la autenticación: administra tú mismo la expiración y revocación de sesiones, en lugar de depender de configuraciones fijas.
Seguridad reforzada: los JWTs permiten tokens firmados y con tiempo limitado, reduciendo el riesgo de ataques de repetición.
Mejora en la seguridad de datos: define exactamente qué atributos de users pueden actualizarse, reduciendo la exposición de datos sensibles.
Preparación para el futuro: los JWTs son el reemplazo recomendado para IDV, asegurando que tu sistema de autenticación se mantenga alineado con las mejores prácticas.

¿Quién debería migrar?

Esta migración es relevante para todos los clientes que actualmente usan IDV, especialmente si:

✅ Necesitas mejor control sobre la expiración de sesiones y revocación de tokens

✅ Quieres aplicar actualizaciones seguras y específicas de atributos de users

✅ Manejas datos sensibles de clientes y requieres autenticación más fuerte

✅ Planeas mejoras de seguridad a largo plazo en tu espacio de trabajo

Aunque IDV seguirá funcionando por ahora, los JWTs ofrecen un enfoque más moderno y seguro que se alinea con las mejores prácticas de autenticación. Esta guía te llevará paso a paso por el proceso de migración.

Diferencias clave entre Identity Verification y Seguridad de Messenger con JWTs

	Identity Verification	Seguridad de Messenger con JWTs
*Método de verificación*	Hash firmado HMAC-SHA256	Token JWT firmado HMAC-SHA256
*¿Soporta expiración?*	No	Sí
*¿Soporta actualizaciones seguras de datos?*	No	Sí
*Recomendado para*	Verificación básica de identidad en Messenger	Autenticación segura con mejor control de sesiones y manejo seguro de datos

Pasos para la migración

Paso 1: Actualiza tu integración para generar JWTs en lugar de hashes

Deja de generar firmas HMAC-SHA256 (también llamadas user_hashes) para Identity Verification.
[opcional] Genera una nueva clave secreta para tu Messenger, eligiendo en qué plataformas deseas que se aplique
Genera un JWT usando tu clave secreta.

Si Identity Verification ya está habilitado para tu espacio de trabajo (indicado por la configuración de Messenger que dice "instalado de forma segura"), Intercom solo aceptará solicitudes que contengan un user_hash válido o un JWT válido.

Si deseas comprobar que tu implementación de JWT funciona como esperas antes de cambiar, recomendamos hacer la integración primero en tu espacio de trabajo de prueba.

Nota: los espacios de trabajo de prueba y producción tienen diferentes claves secretas de Messenger y por lo tanto generarán diferentes user_hashes y JSON web tokens.

Aquí tienes un ejemplo de configuración de código del lado del servidor para Node.js:

const jwt = require("jsonwebtoken");

const payload = {
  user_id: "USER_ID_HERE",  // Required
  email: "EMAIL_ADDRESS_HERE",  // Optional
  data_attribute: "YOUR_DATA", // Optional
  exp: Math.floor(Date.now() / 1000) + 3600  // Expires in 1hr
};

const secret = process.env.MESSENGER_SECRET_KEY || "YOUR_MESSENGER_SECRET_KEY";  // Secure key storage

const intercomUserJwt = jwt.sign(payload, secret, { algorithm: "HS256" });

Qué incluir en la carga útil (payload) de tu JWT:

user_id para identificar al user. Este es un campo obligatorio.
Una marca de tiempo opcional (exp) para la expiración
Cualquier otro atributo de datos que desees enviar de forma segura para tus users

Para instrucciones detalladas sobre cómo generar JWTs para tu espacio de trabajo, consulta nuestro artículo principal del help center o visita tus configuraciones de seguridad.

Paso 1a: Una nota sobre los atributos de datos

Si actualmente envías atributos de datos sobre tus users a través de Messenger, deberías actualizar tu integración para enviar esos atributos de forma segura dentro de tu JWT de user. Para hacer esto, añade cualquier atributo a tu carga útil y asegúrate de que cualquier solicitud insegura de Messenger sea bloqueada.

En el ejemplo de código anterior, nuestra carga útil firma el user_id y el email. También incluye una expiración, que también debe ir en la carga útil.

Para estos atributos, ahora deberíamos desactivar las actualizaciones inseguras de Messenger para esos atributos. Esto significa que solo pueden actualizarse mediante un JWT válido y nunca sin él.

Recomendamos activar este interruptor para cualquier atributo que envíes en tu JWT. Puedes ver los atributos de tu espacio de trabajo en Configuración > Datos > Personas

Nota: Este interruptor de actualización de atributos no impide que recojas datos directamente de leads con un bot. Estos datos provienen directamente del user.

Paso 2: Actualiza tu fragmento frontend para enviar JWTs para users

En lugar de pasar una firma HMAC para IDV, pasa el JWT en la configuración de Messenger como intercom_user_jwt

Para Web (JavaScript SDK):

window.Intercom("boot", {
  api_base: "https://api-iam.intercom.io",
  app_id: "<YOUR_APP_ID_HERE",
  intercom_user_jwt: "<YOUR_USER_JWT_HERE>"
};

React: Si usas el SDK de React, no es necesario api_base en la llamada de inicio como en el fragmento de JavaScript puro mostrado arriba; el SDK de React lo maneja internamente. Solo incluye api_base si usas el fragmento de JavaScript simple.

Como se indicó en la sección anterior, ahora enviamos nuestros atributos de datos dentro del JWT y han sido eliminados del fragmento.

Para instrucciones detalladas sobre cómo generar JWTs para tu espacio de trabajo, consulta nuestro artículo principal del help center o visita tus configuraciones de seguridad. Para instrucciones móviles, consulta nuestra documentación para desarrolladores para iOS y Android.

Aplicando JWTs en todas las solicitudes

Obtener un JWT válido aceptado en solicitudes individuales es un paso separado de requerir uno en cada solicitud. Para exigir un JWT válido en cada solicitud de Messenger en adelante, también debes activar Aplicar Seguridad de Messenger en Configuración > Messenger > Seguridad. Hasta que ese interruptor esté activado, la autenticación JWT puede funcionar correctamente sin aplicarse en todo el espacio de trabajo.

Solución de problemas

Hay registros detallados de fallos y herramientas de depuración de tokens en tus configuraciones de seguridad para ayudar con la migración a JWTs.

Para más información, consulta nuestra guía de instalación.

Preguntas frecuentes

¿Qué pasa si no migro?

Identity Verification seguirá funcionando por ahora, pero los JWTs ofrecen mayor seguridad y mejor control.

¿Cómo revoco una sesión JWT?

Puedes establecer una expiración corta (exp) o rotar las claves de firma para invalidar tokens antiguos.

¿Puedo usar Identity Verification y JWTs juntos?

Una vez que la autenticación JWT está habilitada para una plataforma, Identity Verification ya no es necesaria. Sin embargo, puedes usar JWTs e Identity Verification independientemente en web, iOS y Android, ya que se configuran individualmente.

Migración de la Verificación de Identidad a la Seguridad de Messenger con JWTs