Utilice este artículo para configurar su entorno de desarrollo de Intercom, configurar un dominio personalizado de Help Center con SSL, autenticar su aplicación 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 aplicaciones Messenger e Inbox, y solución de errores comunes de API y SSL. Destinado a desarrolladores que construyen integraciones con Intercom.

Puede crear un nuevo espacio de trabajo para desarrolladores para desarrollar aplicaciones. Los espacios de trabajo para desarrolladores son gratuitos y están destinados solo para fines de desarrollo. Una vez que haya creado el nuevo espacio de trabajo, puede seguir esta guía para crear una aplicación y hacer su primera llamada API.

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

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

Si desea usar una URL diferente, puede crear una configurando manualmente un dominio personalizado. Esto implicará ingresar el dominio personalizado en la configuración de su Help Center, crear un registro CNAME personalizado y, opcionalmente, configurar SSL. Encuentre las instrucciones completas para la configuración en nuestra documentación para desarrolladores. Si su Help Center muestra un error de "no encontrado" después de configurar un dominio personalizado, verifique su registro CNAME para asegurarse de que su 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 verifique que el protocolo de seguridad seleccionado en la configuración de su Help Center coincida con su configuración DNS.

SSL (o TLS) es la forma más utilizada para asegurar la conexión entre su servidor y su 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 su dominio personalizado:

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

Si desea cambiar su dominio personalizado a HTTPS:

Puede configurar SSL para su dominio personalizado para mantener la información sensible cifrada. Si desea hacerlo, asegúrese de haber configurado su CNAME con un proveedor DNS que soporte SSL, como Cloudflare.

Siga la guía en nuestra documentación para desarrolladores para configurar SSL. Tenga en cuenta que, dependiendo del proveedor que haya elegido, los pasos de configuración pueden variar.

Si los pasos estándar de configuración de SSL y HTTPS no han resuelto su 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:

Si encuentra un comportamiento inesperado en su Help Center, comience con estos pasos antes de investigar la configuración:

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 su aplicación usa en su Developer Hub siguiendo los pasos indicados 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 deseas activar un artículo en el Messenger, puedes usar el showArticle método 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ás 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 usuarios están bajo la etiqueta de contactos. No hay un endpoint para crear contactos en masa usando el API, pero puedes usar el endpoint de crear contactos para crear un script que importe usuarios o sigue este tutorial que te dará los 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 espacio de trabajo.

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

Luego podrás recuperar el acceso a los datos del contacto a través del endpoint de obtener un contacto del API y sus conversaciones a través del endpoint de recuperar una conversación del API.

No, actualmente no hay forma de eliminar notas individuales o eliminar notas en masa de contactos vía el 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 espacio de trabajo, pero solo una a la vez.

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

La primera opción es asignar una conversación directamente a un administrador o a un equipo usando el endpoint de administrar una conversación del API. Necesitas tener acceso al ID provisionado por 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 de ejecutar reglas de asignación en una conversación del API. Necesitas tener acceso al ID provisionado por 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 de responder a una conversación del API. Necesitarás elegir un message_type de nota y un tipo de "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 interfaz de usuario, puedes usar esa etiqueta para aplicarla a conversaciones. También puedes crear una nueva etiqueta usando el API.

Para usar el endpoint de agregar etiqueta a una conversación del API, necesitarás tener acceso al conversation_id de la conversación a etiquetar, al ID provisionado por 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 el API que haya sido iniciada por un contacto (es decir, usuario o lead) usando el endpoint de crear una conversación del API. La conversación puede ser solo un mensaje dentro de la app.

También necesitarás el ID provisionado por Intercom para el contacto 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 el API puedes usar el endpoint de administrar una conversación del API. Necesitarás tener el ID provisionado por 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 de redactar una parte de la conversación del 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 realice una acción, como que un compañero de equipo 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 . 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 usuario en la conversación lateral.

Para crear un ticket usando el 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 usas el API para recuperar tickets y datos de tickets, puedes usar el endpoint de búsqueda de tickets del API. Para excluir 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 usas el API para recuperar una conversación o listar conversaciones con tickets de back office asociados a las conversaciones y deseas 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 ese 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 workspace. 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 workspace. Esto significa que si un workspace tiene varias apps privadas instaladas, cada una contribuye al 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 workspace. Esto significa que si un workspace tiene varias apps públicas instaladas, cada una tiene su propio límite de solicitudes sin afectar a las demás. 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, puede que notes algunas diferencias entre ambos informes. Esto puede suceder por varias razones.

Un problema común es cuando las fechas y horas no coinciden. Esto suele deberse a que la zona horaria que usas en tu workspace de Intercom es diferente a la 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 workspace o cambia la zona horaria de tu informe personalizado.

Otro problema es que puedes estar usando métricas que no coinciden con las métricas de la interfaz de informes de Intercom. Algunas métricas disponibles en la interfaz 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, puede que notes una diferencia en el número de conversaciones. Esto se debe a que los tickets de back office asociados a una conversación se incluyen cuando se extraen desde la API.

Para solucionar esto, puedes filtrar los resultados después de obtenerlos vía 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 se llenará 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 el webhook que 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.

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 partes más pequeñas.

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 tendrá un aspecto similar a '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 el uso de APIs de lista y APIs de búsqueda.

Cualquier app que interactúe con datos de workspace de terceros y apps construidas con Canvas Kit requieren OAuth. 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 para configurar OAuth.

Necesitarás configurar OAuth si estás construyendo 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 users 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 workspace de Intercom, puedes usar un token de acceso.

Si estás construyendo una app privada que solo accede a datos en tu workspace de Intercom, puedes usar tu token de acceso de Intercom para autenticación. Encuentra tu token de acceso en tu centro de desarrolladores 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 workspace de Intercom. Encuentra tu token de acceso en tu centro de desarrolladores 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 bajo solicitud. 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 workspaces de los que eres miembro como integrante de Intercom.

Puedes hacer clic en Install app junto al workspace donde quieres instalar la app dada. Esta app se instalará y se proporcionará un Access Token para ese workspace 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 salientes, 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 salientes, 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.