Utiliza este artículo para configurar tu entorno de desarrollo de Intercom, configurar un dominio personalizado de Help Center con SSL, autenticar tu app mediante tokens de acceso u OAuth, y gestionar contactos, conversaciones y tickets a través de la API de Intercom (Application Programming Interface). También cubre webhooks, paginación, creación de apps para Messenger e Inbox, y solución de problemas comunes de API y SSL. Destinado a desarrolladores que crean integraciones con Intercom.

Puedes crear un nuevo espacio de trabajo para desarrolladores para desarrollar apps. Los espacios de trabajo para desarrolladores son gratuitos y están destinados solo para fines de desarrollo. Una vez creado el nuevo espacio, puedes seguir esta guía para crear una app y hacer tu primera llamada a la API.

Puedes crear una nueva app para tu espacio de trabajo de producción y obtener el token de acceso para la app yendo a https://app.intercom.com/a/apps/{your-workspace-id}/developer-hub/

Cuando activas tu Help Center de Artículos, tu contenido está disponible por defecto a través de intercom.help. Tu URL se verá así: intercom.help/exampleapp.

Si deseas usar una URL diferente, puedes crear una configurando manualmente un dominio personalizado. Esto implica ingresar el dominio personalizado en la configuración de tu Help Center, crear un registro CNAME personalizado y opcionalmente configurar SSL. Encuentra las instrucciones completas en nuestra documentación para desarrolladores. Si tu Help Center muestra un error de "no encontrado" después de configurar un dominio personalizado, verifica tu registro CNAME para asegurarte de que tu subdominio apunte al host correcto de Intercom: • Para configuración rápida HTTPS: us.intercomhelpcenter.com (región US) • Para configuración manual/HTTP: custom.intercom.help (región US) También verifica que el protocolo de seguridad seleccionado en la configuración de tu Help Center coincida con tu configuración DNS.

SSL (o TLS) es la forma más utilizada para asegurar la conexión entre tu servidor y tu navegador. Garantiza que la conexión entre el servidor y el navegador esté cifrada y sea segura, y aparece como HTTPS.

Hay dos formas de configurar SSL con Artículos en tu dominio personalizado:

¡Sí! Si activas “HTTPS (quick setup)” en la configuración de tu Help Center, Intercom aprovisionará y gestionará automáticamente un certificado SSL para tu dominio personalizado (como https://help.ourdomain.com). No es necesario configurar SSL manualmente: solo apunta tu CNAME a us.intercomhelpcenter.com y nosotros nos encargamos del resto.

Si deseas cambiar tu dominio personalizado a HTTPS:

Puedes configurar SSL para tu dominio personalizado para mantener la información sensible cifrada. Si deseas hacerlo, asegúrate de haber configurado tu CNAME con un proveedor DNS que soporte SSL, como Cloudflare.

Sigue la guía en nuestra documentación para desarrolladores para configurar SSL. Ten en cuenta que los pasos pueden variar según el proveedor que hayas elegido.

Si los pasos estándar de configuración de SSL y HTTPS no han resuelto tu problema, los siguientes escenarios cubren casos comunes para dominios personalizados de Help Center:

1. Dominio no seguro

Error ERR_SSL_VERSION_OR_CIPHER_MISMATCH

2. Configuración HTTPS atascada en pendiente

3. Opción de configuración rápida HTTPS no disponible

4. Error de acceso denegado

Si una URL de artículo migrado ya no funciona después de mover contenido a Intercom:

Si su Help Center muestra un error "No encontrado" en la URL pública pero los artículos aparecen correctamente en su espacio de trabajo:

La versión actual de la API es 2.15. Puede encontrar la documentación de la API en nuestro sitio de documentación para desarrolladores. También puede cambiar la versión que usa su app en su Developer Hub siguiendo los pasos listados en esta guía.

Si está usando la API de Intercom, también puede cambiar la versión dentro del encabezado HTTP de su solicitud.

Los siguientes endpoints están disponibles en la versión 2.15 de la API de Intercom:

Sí, si desea activar un artículo en el Messenger, puede usar el método showArticle del API de JavaScript. El artículo se abrirá dentro del Messenger y al hacer clic en el botón de retroceso del Messenger volverá al contexto anterior. Si el Messenger está cerrado cuando se llama al método, primero se abrirá y luego se mostrará el artículo. Esto está disponible en todas las plataformas del Messenger.

En Intercom, los users se clasifican como contacts. No hay un endpoint para crear contacts en masa usando la API, pero puedes usar el endpoint create contacts para crear un script que importe users o seguir este tutorial que te dará ejemplos de código para comenzar.

Asegúrate de configurar una verificación de limitación de tasa para asegurarte de no superar el límite, que actualmente es de 10,000 llamadas API por minuto para cada app y 25,000 llamadas API por minuto por workspace.

La API de Intercom no ofrece un endpoint dedicado para crear contacts en masa. Para importar contacts a gran escala, usa el endpoint create contact en un bucle con manejo adecuado de limitación de tasa. Asegúrate de que tu script respete los límites de tasa (10,000 llamadas API por minuto por app; 25,000 por minuto por workspace).

Las siguientes operaciones en masa no están disponibles vía API y deben manejarse mediante solicitudes individuales en bucle o exportación/importación manual:

Para recuperar los datos de un contact archivado primero debes desarchivar el contact, lo cual puedes hacer con el endpoint unarchive contact API si tienes el ID del contact.

Luego podrás acceder nuevamente a los datos del contact a través del endpoint get a contact API y a sus conversaciones mediante el endpoint retrieve a conversation API.

No, actualmente no hay forma de eliminar notas individuales o eliminar notas en masa de contacts vía API. Si esta funcionalidad es importante para tus operaciones, por favor visita el Product Wishlist para crear, comentar o votar una solicitud de función. Las notas pueden eliminarse manualmente dentro del workspace, pero solo una a la vez.

Si deseas asignar una conversación a un equipo usando la API, tienes dos opciones.

La primera opción es asignar una conversación directamente a un admin o a un equipo usando el endpoint manage a conversation API. Necesitas tener acceso al ID provisionado de Intercom para la conversación, así como al admin_id y al assignee_id.

La otra opción es ejecutar reglas de asignación que ya hayas configurado en la conversación usando el endpoint run assignment rules on a conversation API. Necesitas tener acceso al ID provisionado de Intercom para la conversación.

Puedes probar la funcionalidad desde la función "Try It" en nuestra documentación para desarrolladores, la colección Intercom Postman, o en tu propio terminal o IDE (Entorno de Desarrollo Integrado). No olvides usar tu token de acceso de Intercom como token bearer.

Una nota es un comentario interno visible solo para compañeros de equipo. Para agregar una nota a una conversación puedes usar el endpoint reply to a conversation API. Necesitarás elegir un message_type de nota y un tipo "admin" junto con el admin_id desde el cual debe provenir la nota.

Puedes probar la funcionalidad desde la función "Try It" en nuestra documentación para desarrolladores, la colección Intercom Postman, o en tu propio terminal o IDE. No olvides usar tu token de acceso de Intercom como token bearer.

Si ya has creado una etiqueta en la UI, puedes usar esa etiqueta para aplicarla a conversaciones. También puedes crear una nueva etiqueta usando la API.

Para usar el endpoint add tag to a conversation API, necesitarás tener acceso al conversation_id de la conversación a etiquetar, al ID provisionado de Intercom de la etiqueta y al admin_id.

Puedes probar la funcionalidad desde la función "Try It" en nuestra documentación para desarrolladores, la colección Intercom Postman, o en tu propio terminal o IDE. No olvides usar tu token de acceso de Intercom como token bearer.

Puedes crear una conversación desde la API que haya sido iniciada por un contact (es decir, user o lead) usando el endpoint create a conversation API. La conversación puede ser solo un mensaje dentro de la app.

También necesitarás el ID provisionado de Intercom para el contact y el texto del cuerpo para usar como cuerpo del mensaje al hacer la solicitud.

Puedes probar la funcionalidad desde la función "Try It" en nuestra documentación para desarrolladores, la colección Intercom Postman, o en tu propio terminal o IDE. No olvides usar tu token de acceso de Intercom como token bearer.

Para cerrar una conversación usando la API puedes usar el endpoint manage a conversation API. Necesitarás tener el ID provisionado de Intercom de la conversación, tu admin_id y usar un message_type de "close".

Si necesitas redactar solo una parte de la conversación, usa el endpoint redact a conversation part API.

Puedes probar la funcionalidad desde la función "Try It" en nuestra documentación para desarrolladores, la colección Intercom Postman, o en tu propio terminal o IDE. No olvides usar tu token de acceso de Intercom como token bearer.

Para configurar una notificación personalizada cuando se realiza una acción, como que un compañero sea asignado a una conversación, puedes usar webhooks.

Querrás usar el tema conversation.admin.assigned. Puedes encontrar todos los temas de conversación en nuestra documentación para desarrolladores.

Luego puedes suscribirte a este tema de webhook en el centro de desarrolladores siguiendo los pasos en esta guía aquí. También necesitarás tener una URL de endpoint accesible públicamente para que la acción se realice una vez que se active el webhook y entregue la notificación a tu canal preferido.

Las conversaciones laterales no tienen un endpoint dedicado, por lo que no puedes recuperarlas directamente. Sin embargo, cuando recuperas una conversación a la que está adjunta la conversación lateral, verás partes de la conversación que aparecen como "part_type": "side_conversation_reply" con el contenido de los mensajes del user en la conversación lateral.

Para crear un ticket usando la API de Intercom, primero necesitarás crear u obtener el tipo de ticket para etiquetar el nuevo ticket. Luego puedes crear el ticket usando una solicitud curl o con un lenguaje de programación de tu elección.

Sigue esta guía de nuestra documentación para desarrolladores para crear un tipo de ticket y crear un nuevo ticket.

Si estás usando la API para recuperar tickets y datos de tickets, puedes usar el endpoint de búsqueda de tickets de la API. Para excluir los tipos de tickets de back office, configura el campo en ticket_type_id y usa el operador != para excluir el ticket_type_id asignado a los tipos de tickets de back office.

Si estás usando la API para recuperar una conversación o listar conversaciones con tickets de back office asociados y quieres excluirlos, puedes filtrar de manera similar cualquier resultado que tenga el tipo de ticket de back office como atributo. Los tickets vinculados se pueden encontrar en el parámetro tickets en la respuesta o bajo linked_objects.

Otra opción disponible es usar la API para etiquetar conversaciones con un ticket de back office asociado. Luego puedes usar la etiqueta para filtrar por categoría de ticket.

Si recibes un mensaje 403 API Plan restricted en una respuesta, significa que la API que intentas usar no está disponible en el plan de tu app.

Para acceder a la API necesitarás actualizar tu plan. Puedes obtener más información sobre los planes de Intercom en esta página. Puedes encontrar una lista completa de códigos de error y respuestas HTTP en nuestra documentación para desarrolladores.

Si recibes un mensaje 409 conflict en una respuesta, significa que hay datos existentes en tu espacio de trabajo de Intercom que chocan con los datos de la solicitud. Esto puede ocurrir si intentas crear un contacto y ya existe un contacto con esa dirección de correo electrónico en tu app.

Para evitar este error, puedes usar el endpoint de actualización o crear un nuevo contacto por user_id. Puedes encontrar una lista completa de códigos de error y respuestas HTTP en nuestra documentación para desarrolladores.

Si recibes un mensaje 429 significa que el cliente ha alcanzado o superado un límite de tasa, o que el servidor está sobrecargado. Cada app tiene un límite de tasa predeterminado de 10,000 llamadas API por minuto por app y 25,000 llamadas API por minuto por espacio de trabajo. Más información sobre límites de tasa está disponible en nuestra documentación para desarrolladores.

Para evitar este error, puedes configurar una verificación de límite de tasa para asegurarte de no alcanzar el límite. Puedes encontrar una lista completa de códigos de error y respuestas HTTP en nuestra documentación para desarrolladores.

Las apps privadas tienen un límite de tasa predeterminado de 10,000 llamadas API por minuto por app y 25,000 llamadas API por minuto por espacio de trabajo. Esto significa que si un espacio de trabajo tiene varias apps privadas instaladas, cada una contribuye al número total de solicitudes.

Las apps públicas tienen un límite de tasa predeterminado de 10,000 llamadas API por minuto por app y 25,000 llamadas API por minuto por espacio de trabajo. Esto significa que si un espacio de trabajo tiene varias apps públicas instaladas, cada una tiene su propio límite de solicitudes sin contribuir a las otras. Más información sobre límites de tasa está disponible en nuestra documentación para desarrolladores.

Si estás creando tus propios informes usando la API, puedes notar algunas diferencias entre los dos informes. Esto puede suceder por varias razones.

Un problema común es cuando las fechas y horas no coinciden. Esto suele ser porque la zona horaria que usas en tu espacio de trabajo de Intercom es diferente a la zona horaria que usas para consultar la API. Para solucionarlo, ajusta los parámetros de consulta de la API para que coincidan con la zona horaria de tu espacio de trabajo o cambia la zona horaria de tu informe personalizado.

Otro problema es que puedes estar usando métricas que no se alinean con las métricas de la interfaz de informes de Intercom. Algunas métricas disponibles en la interfaz de informes no están disponibles vía API porque son métricas calculadas. Algunas de ellas pueden crearse usando la API y realizando los cálculos por tu cuenta. Consulta la guía para crear tus propios informes en la documentación para desarrolladores de Intercom.

Si comparas los informes de conversaciones disponibles en la interfaz con los informes extraídos usando la API de conversaciones, puedes notar una diferencia en el número de conversaciones. Esto se debe a que los tickets de back office asociados con una conversación se incluyen cuando se extraen desde la API.

Para solucionar esto, puedes filtrar los resultados después de recuperarlos mediante la list conversations, retrieve a conversation o search for conversations API, y separar los tickets de las conversaciones usando el campo ticket en la respuesta de la API de conversación. El campo ticket estará poblado con un objeto si es un ticket y será nulo si es una conversación.

Los webhooks te permiten suscribirte a notificaciones en tiempo real de eventos que ocurren en Intercom, como cuando se crea un contacto o se recibe un mensaje entrante.

Puedes ver los webhooks disponibles para cada versión en nuestra documentación para desarrolladores. Una vez que identifiques qué webhook necesitas, sigue esta guía para configurarlos.

No hay planes para agregar nuevos webhooks en nuestra hoja de ruta, pero si tu equipo necesita un webhook, por favor envía una solicitud al equipo o agrégalo a la lista de deseos del producto en la comunidad de Intercom.

Al construir sobre los webhooks de Intercom, ten en cuenta lo siguiente:

Las APIs de Intercom para listar y buscar recursos ofrecen paginación basada en cursor. Esto está disponible para que cuando solicites una gran cantidad de datos — como muchas conversaciones con todas sus partes — puedas recibirlos y procesarlos en fragmentos más pequeños.

Para ejemplos sobre cómo usar la paginación con las APIs de lista de Intercom, que aceptan parámetros de ruta, y las APIs de búsqueda, que usan parámetros de consulta, consulta nuestra guía de paginación.

Para la paginación basada en cursor, Intercom usa un puntero que se refiere a un registro específico basado en el límite que establezcas por el número de páginas que especifiques por solicitud.

Cuando se devuelve en un objeto, el puntero se verá algo así como 'WzXXXXXXXXXXXXXX'.

Luego puedes usar el puntero de la respuesta para hacer la solicitud siguiente para el próximo lote de datos.

El formato de paginación en la solicitud difiere ligeramente entre las APIs de lista y las APIs de búsqueda, pero las respuestas funcionan igual.

Puedes ver ejemplos de solicitudes curl en nuestra página de Paginación, y tutoriales sobre cómo usar APIs de lista y APIs de búsqueda.

Cualquier app que interactúe con datos de espacios de trabajo de terceros y apps construidas con Canvas Kit requieren que OAuth esté implementado. Nunca debes pedir a los users su token de acceso y solo usar OAuth para interactuar con sus datos.

Consulta la documentación para instrucciones sobre cómo configurar OAuth.

Necesitarás configurar OAuth si estás creando una integración con Intercom que accede a datos de Intercom de otras personas. Esto incluye apps públicas que planeas listar en la tienda de apps de Intercom, así como apps e integraciones que pedirás a los usuarios instalar a través de tu propio sitio web. Aprende más sobre OAuth en nuestra documentación para desarrolladores.

Si solo accedes a datos dentro de tu propio espacio de trabajo de Intercom, puedes usar un token de acceso.

Si estás creando una app privada que solo accede a datos en tu espacio de trabajo de Intercom, puedes usar tu token de acceso de Intercom para la autenticación. Encuentra tu token de acceso en tu developer hub y aprende más sobre autenticación aquí.

Puedes usar tu token de acceso de Intercom si usas la API para acceder a datos en tu propio espacio de trabajo de Intercom. Encuentra tu token de acceso en tu developer hub y aprende más sobre autenticación aquí.

Para encontrar tu token de acceso API, sigue estos pasos:

Sí, Intercom Support puede rotar el OAuth Client Secret de tu app a petición. Una vez rotado, el secreto antiguo se invalida inmediatamente y el nuevo secreto está disponible en el Developer Hub.

Para solicitar una rotación, contacta a Intercom Support con los detalles de tu app. Asegúrate de que tu equipo esté preparado para actualizar la configuración de tu integración con el nuevo secreto de inmediato, ya que el secreto antiguo no será válido en el momento de la rotación.

Puedes construir una app para tu Intercom Inbox usando Canvas Kit, un conjunto de herramientas que te permite crear apps que funcionan directamente dentro de la interfaz de Intercom.

Sigue este tutorial para aprender a construir tu primera app para Inbox. También puedes aprender más sobre Canvas Kit y encontrar documentación de referencia en nuestra documentación para desarrolladores.

Puedes construir una app para tu Intercom Messenger usando Canvas Kit, un conjunto de herramientas que te permite crear apps que funcionan directamente dentro de la interfaz de Intercom.

Ten en cuenta que las personalizaciones están limitadas a lo que es posible mediante Canvas Kit y deben crearse dentro del Messenger: no es posible recrear o cambiar la apariencia del Messenger.

Sigue este tutorial para aprender a construir tu primera app para Inbox. También puedes aprender más sobre Canvas Kit y encontrar documentación de referencia en nuestra documentación para desarrolladores.

Si visitas la página Test & Publish > Your Workspaces de tu app en el Developer Hub, deberías ver todos los espacios de trabajo de los que eres miembro como compañero de Intercom.

Puedes hacer clic en Instalar app junto al espacio de trabajo donde quieres instalar la app dada. Esta app se instalará y se proporcionará un Access Token para ese espacio de trabajo para que puedas acceder a sus datos a través de la API.

Para instrucciones de instalación de terceros, consulta nuestra documentación para desarrolladores.

Cuando estés listo para publicar tu app, puedes seguir los pasos en el developer hub. Puedes encontrar una guía sobre cómo publicar tu app en nuestra documentación para desarrolladores.

El Intercom SDK (Software Development Kit) para iOS te permite usar el Intercom Messenger en tu app, tener conversaciones con tus clientes, enviar mensajes enriquecidos, mostrar tu Help Center y rastrear eventos.

Puedes instalar Intercom para iOS usando Cocoapods, Swift Package Manager o manualmente. Lee la guía completa de instalación para iOS. Puedes encontrar Intercom para iOS en GitHub junto con una app de ejemplo para explorar el SDK.

El Intercom SDK para Android te permite usar el Intercom Messenger en tu app, tener conversaciones con tus clientes, enviar mensajes enriquecidos, mostrar tu Help Center y rastrear eventos.

Puedes instalar Intercom para Android usando Gradle o manualmente. Lee la guía completa de instalación para Android. Puedes encontrar Intercom para Android en GitHub junto con una app de ejemplo para explorar el SDK.

El wrapper de Intercom para React Native te permite usar Intercom para iOS y Intercom para Android en tus apps React Native. Sigue la guía de instalación para React Native para comenzar.