Usa este artículo para configurar, gestionar y administrar conectores de datos, la función que permite a Fin obtener datos en vivo de tus sistemas externos y ofrecer respuestas personalizadas sin esperar a un compañero. Aprenderás a crear un conector desde una plantilla o desde cero, configurar su endpoint API, moldear la respuesta, controlar quién puede activarlo, manejar la seguridad, implementarlo de forma segura y monitorear su rendimiento.
Nota: Necesitas el permiso "Can access developer hub" para crear, editar o activar un conector de datos.
¿Cómo funcionan los conectores de datos?
Cada conector de datos consiste en una llamada API (application programming interface) que configuras. Fin determina automáticamente cuándo usarla para ofrecer respuestas específicas al cliente. Puedes conectar cualquier sistema con una API, incluyendo:
Herramientas internas personalizadas de backend
Plataformas de terceros (Shopify, Salesforce, Stripe, Jira, etc.)
Consejo: Los conectores de datos pueden ser usados por Fin en Procedures y otras automatizaciones, incluyendo Workflows y macros del Inbox. Aprende más sobre cómo diseñar y usar tus APIs con conectores de datos.
Cómo crear un conector de datos
Navega a Configuración > Integraciones > Data connectors y haz clic en Nuevo.
Si tienes instalada una de las apps soportadas, verás una plantilla para esa app listada bajo Crear conector de datos. Actualmente hay plantillas para Shopify, Stripe y Statuspage — consulta Desde una plantilla de terceros abajo para más detalles.
Desde una plantilla de terceros
Las plantillas de conectores de datos están disponibles cuando las siguientes apps están instaladas en tu espacio de trabajo:
Si la app no está instalada, ve a la App Store para instalarla. Una vez instalada, las plantillas de Data connector para cada app aparecerán listas para activar.
Al hacer clic en una plantilla, verás información sobre lo que hace el conector de datos y podrás probarlo en la vista previa del Messenger. Si estás satisfecho con el comportamiento del conector, solo selecciona Activar para AI Agent.
La vista previa del Messenger aquí usa datos de ejemplo por defecto. Si haces la vista previa como un usuario específico y activas "Acceder y actualizar datos reales del usuario cuando se active", el conector de datos llamará a tu sistema real y devolverá los datos reales de ese usuario — usa una cuenta de prueba, nunca un cliente real, para estas pruebas. Cuando el conector de datos está activo, Fin usa datos reales de clientes para conversaciones en vivo.
Si quieres configurar el conector de datos, puedes hacer clic en Personalizar, lo que te llevará al constructor de conectores para configuración avanzada.
Si no tienes instalada una de nuestras apps soportadas, las apps aparecerán aquí para que las instales en tu espacio de trabajo. Tras la instalación, las plantillas relevantes de Data connector aparecerán en la sección superior.
Aprende más sobre las plantillas de Data connector disponibles y casos de uso para Fin.
Desde una recomendación de IA
Para ver los conectores de datos recomendados por IA, ve a Configuración > Integraciones > Data connectors y haz clic en Nuevo Data connector.
Verás tus conectores de datos recomendados por IA únicos bajo "Crear conector de datos desde plantilla". Estos se generan según tu historial de conversaciones para ayudarte a identificar posibles conectores, ver qué porcentaje del volumen de conversaciones podrían resolver y previsualizarlos en el Messenger antes de configurarlos.
Para que aparezcan recomendaciones de IA, Fin debe estar activo en tu espacio de trabajo y debes tener suficiente volumen de conversaciones.
Al hacer clic en un conector de datos recomendado por IA, encontrarás información sobre lo que hace y podrás previsualizarlo en el Messenger (usando datos de ejemplo). Los conectores recomendados por IA son solo sugerencias basadas en tu volumen de conversaciones, pero requieren que una API se conecte manualmente para funcionar.
Para activar el conector de datos, haz clic en Configurar para configurar los detalles de la API.
Ahora solo necesitas conectar el conector de datos a tu API añadiendo la URL HTTPS.
Para personalizar aún más este conector de datos, consulta la sección Desde un conector de datos personalizado.
Crear un conector de datos personalizado desde cero
Para configurar tu propio conector de datos personalizado para Fin, navega a Configuración > Integraciones > Data connectors y haz clic en + Nuevo > + Crear desde cero.
Fase 1: API
La pestaña API define cómo Intercom se comunica con tu sistema externo.
Dale a tu conector un nombre corto y descriptivo — por ejemplo, "Obtener saldo de cuenta impago." Esto ayuda a Fin a entender cuándo usarlo. Añade una descripción interna para referencia de tu equipo.
Consulta las mejores prácticas para redactar descripciones de conectores de datos.
Nota: Los emojis no están soportados en los nombres de conectores de datos y causarán un error si se incluyen.
Entradas de datos
Las entradas de datos te permiten especificar qué información Fin necesita recopilar antes de que el conector se ejecute — por ejemplo, el número de cuenta de un cliente si no está almacenado en Intercom. Cuando Fin necesita pasar una consulta de búsqueda u otro valor a la API basado en lo que un cliente pregunta, añade una entrada de datos y configura la fuente en Dejar que Fin recopile — Fin recogerá el valor automáticamente de la conversación.
Haz clic en + Entrada de datos y elige un formato:
Texto
Número
Número decimal
Verdadero/Falso
Asigne a cada entrada un nombre y una descripción para que Fin sepa cómo recopilarla. También puede establecer un valor de reserva para casos en que la API devuelva una respuesta nula o faltante.
Para cada entrada, elija de dónde provienen los datos:
Let Fin collect — Fin lo recopila automáticamente de la conversación
People attribute — extraído de un atributo existente de Intercom
Custom value — un valor fijo que usted define
Después de seleccionar una fuente, use el interruptor Required para establecer si la entrada es obligatoria u opcional. Esto debe configurarse manualmente para cada entrada (el estado no se establece automáticamente).
La etiqueta del interruptor cambia según la fuente seleccionada:
Let Fin collect: el interruptor dice Fin debe recopilar este parámetro. Cuando está activado, Fin debe obtener este valor del cliente antes de que el conector pueda ejecutarse.
People attribute o Custom value: el interruptor dice Este parámetro debe tener un valor. Cuando está activado, el conector no se ejecutará si falta el valor.
El estado de obligatorio u opcional de cada entrada se muestra en la lista de entradas de datos.
API endpoint
Agregue la URL HTTPS (web segura) para su API endpoint y seleccione el método de solicitud HTTP: GET (recuperar datos), POST (enviar datos), PUT (reemplazar datos), DELETE (eliminar datos) o PATCH (actualizar datos parcialmente).
Use el Attribute Inserter para pasar valores dinámicos, como el ID de usuario de un cliente, directamente en la ruta de la URL o en el cuerpo de la solicitud. Siempre seleccione atributos usando el selector; nunca escriba tokens manualmente.
Nota: Si su conector llama a la Intercom Contacts API y necesita identificar un contacto, seleccione Contact ID (user.id) desde el selector, no User ID (user_id). La Contacts API espera el ID de contacto generado por Intercom (user.id). Usar user_id (el ID establecido externamente) hará que la búsqueda falle.
Importante: El editor convierte cualquier texto {{...}} en una pastilla, por lo que un token escrito manualmente se ve idéntico a un atributo válido. Si el identificador no coincide con un atributo real, como user.id o user_id, se resuelve como un valor vacío en tiempo de ejecución. Esto hace que la URL de su solicitud esté mal formada y cause errores como 404 sin indicación visible en el editor. Siempre use el selector Attribute Inserter para insertar atributos.
Autenticación y encabezados
Seleccione un token de autenticación y agregue cualquier encabezado personalizado clave-valor que su API requiera (por ejemplo, Content-Type: application/json).
Nota: Si envía un cuerpo de solicitud JSON (POST, PUT o PATCH), debe agregar explícitamente un encabezado Content-Type: application/json. Sin él, la API receptora no analizará el cuerpo de la solicitud y rechazará todos los campos como inválidos, incluso si el JSON está correctamente formateado.
Nota: Puede adjuntar múltiples tokens a un solo conector. Cada token debe usar una clave de encabezado diferente; todos los tokens adjuntos se envían con cada solicitud.
Una vez que la URL del endpoint y los detalles de autenticación estén completos, haga clic en Test connection para validar su configuración. Una prueba exitosa devuelve una confirmación verde y la respuesta API sin procesar. Una prueba fallida muestra el código de error HTTP y una descripción; resuelva cualquier error antes de continuar a la Fase 2: Datos.
Fase 2: Datos — moldeando la respuesta de la API
La pestaña Datos controla cómo se filtra y transforma la respuesta de la API antes de que Fin la use para responder a los clientes. Puede restringir qué campos ve Fin y remodelar los datos usando un editor visual o código Python.
Restringir y moldear
Por defecto, Fin tiene acceso a la respuesta completa de la API. Para limitar lo que Fin puede leer, cambie a Restringir acceso manualmente y seleccione solo los campos que desea exponer.
Nota: Al usar Restringir acceso manualmente, los campos cuyos nombres contienen caracteres especiales, como paréntesis (), signos más + o barras /, pueden excluirse silenciosamente de los datos que Fin recibe debido a un error de coincidencia de ruta. Para evitar esto, cambie el nombre de los campos afectados para eliminar caracteres especiales antes de restringir el acceso. Alternativamente, use acceso completo a los datos si la respuesta no contiene datos sensibles.
Elija cómo desea transformar la respuesta:
Vista de tabla — filtre campos, cámbieles el nombre y establezca transformaciones a nivel de campo usando un editor visual
Python — escriba código Python para limpiar, remodelar o reformatear la respuesta antes de que llegue a Fin
Mapeo de objetos
El mapeo de objetos le permite asignar campos de respuesta de la API directamente a atributos de contacto o empresa de Intercom, sincronizando automáticamente datos de su sistema externo con su espacio de trabajo de Intercom.
Haga clic en Test code para validar su lógica de transformación en Python y en Test connection para confirmar la llamada completa a la API y la forma de la respuesta. Resuelva cualquier error antes de continuar a la Fase 3: Fin.
Nota: Cuando selecciona mapeo de objetos, verá solo objetos mapeados en Workflows y Procedures; mientras que sin mapeo, todas las opciones seleccionadas en la tabla Restringir y moldear los datos se listarán. Para Python, solo se verán los valores devueltos.
Fase 3: Fin — cómo Fin activa el conector
La pestaña Fin controla si Fin activa el conector de datos automáticamente o solo cuando se llama explícitamente desde un workflow, procedure o macro. Elija el modo de activación que coincida con cuán sensible o activo en escritura es el conector.
Consejo: Antes de que Fin pueda usar un conector, asegúrese de que cada uno de los siguientes esté en su lugar:
Entradas de datos: Para cualquier valor que Fin necesite pasar a la API, como una consulta de búsqueda, nombre de producto o ID de pedido, agregue una entrada de datos con la fuente configurada en Let Fin collect. Esto indica a Fin que recopile los términos relevantes de la conversación y los pase automáticamente a la API.
Test connection: Realice una prueba exitosa usando datos reales (Fase 1). La respuesta de la prueba configura lo que Fin verá y devolverá a los clientes; los datos de ejemplo no reflejarán resultados reales.
Fin trigger: En esta pestaña Fin, configure ¿Cómo debe usar Fin este conector? en Enabled (direct trigger).
Descripción del conector: Escriba una descripción clara y enfocada de lo que hace el conector y cuándo usarlo. Así es como Fin decide cuándo llamarlo.
Activar en vivo: Complete las verificaciones de seguridad en la Fase 4, luego haga clic en Guardar y Activar en vivo.
¿Cómo debe usar Fin este conector?
Enabled (direct trigger)
Fin activa el conector automáticamente según la pregunta del cliente, sin necesidad de workflow. Ideal para conectores solo de lectura como "Check order status" y consultas repetitivas de alto volumen.
Puedes controlar quién puede acceder a este Data connector con audiencias Fin reutilizables, o creando una audiencia personalizada específicamente para este conector. Por ejemplo, podrías hacerlo disponible para clientes en tu audiencia "Plan Enterprise", o restringirlo a una audiencia personalizada como usuarios con sesión iniciada y correo electrónico verificado que preguntan sobre su saldo.
Nota: Ahora puedes usar audiencias Fin con Data connectors. Las audiencias Fin son grupos de clientes reutilizables que creas una vez y luego aplicas en múltiples conectores, facilitando mantener la coherencia.
Puedes elegir Todos, una audiencia Fin reutilizable, o una audiencia Personalizada para reglas puntuales.
Puedes seleccionar múltiples audiencias Fin, pero no puedes combinar reglas Personalizadas con una audiencia Fin.
Cualquier regla de audiencia de Data connector existente que hayas configurado se convertirá en una audiencia Personalizada para preservar la funcionalidad.
Consejo: Si quieres probar el Data connector antes de habilitarlo para clientes, usa las reglas de audiencia para habilitar el Data connector solo para ti o tus compañeros inicialmente.
Deshabilitado (activación manual)
El conector no se ejecutará automáticamente. Necesitarás añadirlo manualmente a un Workflow, Procedure o Macro. Es mejor para conectores sensibles o activos en escritura, como "Eliminar cuenta", donde quieres supervisión humana o de workflow antes de que algo se ejecute.
Usa la vista previa de Fin para ver exactamente cómo responderá Fin usando este conector antes de activarlo en vivo.
Nota: Los cambios en la configuración del disparador Fin se guardan en modo borrador y no tendrán efecto hasta que los publiques. La versión en vivo del conector sigue usando su configuración actual hasta que hagas clic en Activar en vivo. Después de hacer cambios, siempre confirma que la configuración se refleje en la versión en vivo, no solo en el borrador.
Fase 4: Seguridad — control de acceso y puesta en vivo
La pestaña Seguridad es el paso final antes de la puesta en vivo. Controla si los clientes deben estar autenticados antes de que el Data connector pueda acceder o mostrar sus datos.
Autenticación del cliente
Activa esto para hacer cumplir las reglas de autenticación de tu espacio de trabajo antes de que el conector pueda acceder o mostrar información sensible. Las reglas de autenticación se configuran en Configuración > Espacio de trabajo > Seguridad > Autenticación del cliente.
Verificación de seguridad
Ejecuta un diagnóstico para evaluar la salud y seguridad de tu configuración API. Cualquier riesgo se mostrará con recomendaciones accionables; resuélvelos antes de activar el conector en vivo.
Una vez que todas las verificaciones de seguridad pasen, haz clic en Guardar y luego en Activar en vivo. El estado del Data connector cambia a En vivo en Configuración > Integraciones > Data connectors. Fin comenzará a usarlo inmediatamente para conversaciones que coincidan con la audiencia configurada.
Importante: Existen algunas formas en que Fin podría compartir accidentalmente información de otro usuario al pasar parámetros. Consulta nuestras configuraciones recomendadas para mitigar mejor los riesgos.
Cómo implementar Data connectors de forma segura
Nota: La vista previa del Messenger aquí usa datos de ejemplo por defecto. Si haces la vista previa como un usuario específico y habilitas "Acceder y actualizar datos reales del usuario cuando se active", el Data connector llamará a tu sistema real y devolverá los datos reales de ese usuario, así que usa una cuenta de usuario de prueba, nunca un cliente real, al probar de esta manera. Cuando el Data connector está activo, Fin usa datos reales de clientes para conversaciones en vivo.
Los Data connectors requieren que AI Answers esté habilitado en el paso del workflow para que Fin los use. AI Answers no puede habilitarse en espacios de prueba, por lo que los Data connectors solo pueden probarse completamente en entornos de producción. Usa perfiles de usuario de prueba en producción para pruebas seguras.
Recomendamos usar reglas de audiencia para implementar Data connectors en fases a tu base de clientes. Esto te permite validar el rendimiento del Data connector y hacer ajustes o cambios donde sea necesario.
Cómo monitorear y gestionar Data connectors
Para encontrar Data connectors existentes, navega a Configuración > Integraciones > Data connectors. La lista de Data connectors muestra los siguientes detalles para cada conector:
Nombre y estado (en vivo o borrador)
Uso general (total de ejecuciones)
Uso Fin — tasa de resolución y la audiencia a la que está disponible
Salud — tasa de éxito de API e indicador general de salud
Estado de seguridad
Detalles de configuración
Opción duplicar — crea una copia del conector para usar como punto de partida para uno nuevo
Haz clic en una fila del conector para abrir su panel de salud, donde puedes revisar uso, métricas de rendimiento y registros de ejecución, o abrir el editor de configuración para hacer cambios.
Cómo ver la actividad del Data connector en el Inbox
Para ver la actividad del Data connector en una conversación específica, abre la conversación en el Inbox y selecciona Mostrar eventos de la conversación. El panel de eventos muestra si Fin tuvo acceso al Data connector y si se activó con éxito.
Nota:
Si hay un error con la activación del Data connector, selecciona Registros para saber por qué.
Fin puede no elegir siempre usar el Data connector a pesar de hacer una solicitud API si se determina que otro contenido es más relevante.
Fin no puede consultar atributos personalizados ni datos de eventos para respuestas. Para permitir que Fin responda con datos de activos en tiempo real, configura Data Connectors para que Fin pueda acceder a fuentes de datos externas vía API.
Las vistas de Inbox pueden crearse con el atributo “Fin AI Agent: Acción usada en la respuesta”. Este atributo se establece si Fin llama a un Data connector y usa parte o toda la respuesta en una respuesta.
Versionado de Data connectors
Los Data connectors usan un sistema de versiones borrador/en vivo para que puedas hacer ediciones de forma segura sin interrumpir el conector en ejecución.
Cada Data connector tiene una versión en vivo y una versión borrador. Las ediciones se hacen en el borrador sin afectar la versión en vivo en ejecución.
Cuando publicas un borrador, se crea una nueva instantánea de versión que se convierte en la versión en vivo. Puedes añadir notas al publicar. La versión en vivo anterior se archiva.
Cada versión registra un número de versión, quién la creó, notas de cambio (si se añadieron) y una marca de tiempo.
El historial completo de cambios es rastreable y puedes volver a cualquier versión anterior.
Nota: Esto se aplica a todas las configuraciones del conector, incluido el interruptor Fin trigger. Si cambias ¿Cómo debería Fin usar este conector? y no publicas, la versión en vivo seguirá activándose exactamente como antes. Un banner en el editor indica que tienes cambios sin guardar: siempre haz clic en Establecer en vivo para activar tus cambios.
APIs públicas para conectores de datos
Dos APIs públicas (interfaces de programación de aplicaciones) te dan acceso programático a las configuraciones y resultados de ejecución de los conectores de datos. Ambas usan OAuth (Open Authorization) para autenticación. La documentación completa está disponible en el Intercom Developer Hub.
Cómo usar la Configuration API
La Configuration API es un conjunto de endpoints CRUD (crear, leer, actualizar, eliminar) para gestionar programáticamente los conectores de datos. Úsala para crear nuevos conectores, mantenerlos sincronizados con tus sistemas internos y automatizar la gestión de conectores a gran escala. La tabla a continuación lista los endpoints disponibles y su propósito.
Método | Endpoint | Propósito |
GET | /data_connectors | Devuelve una lista paginada de todos los conectores de datos del espacio de trabajo, ordenados por el más recientemente actualizado primero. |
GET | /data_connectors/:id | Recupera el detalle completo de un conector de datos por ID, incluyendo configuración, entradas de datos, campos de respuesta y mapeos de objetos. |
POST | /data_connectors | Crea un nuevo conector de datos en estado borrador. Configura su URL, encabezados, entradas de datos y otras configuraciones, luego actívalo cuando esté listo. |
PATCH | /data_connectors/:id | Actualiza un conector de datos existente. Solo se cambian los campos proporcionados. Cambia el estado a live o draft para modificar el estado del conector. |
DELETE | /data_connectors/:id | Elimina un conector de datos existente. El conector debe estar en estado borrador y no debe estar en uso por ningún workflows o AI agents. |
La autenticación usa OAuth (Open Authorization). El acceso de lectura y escritura requiere el scope read_write_data_connectors. El acceso solo de lectura requiere el scope read_workflow_connector_execution_result.
Cómo usar la Results API
La Results API te da acceso programático a los datos de ejecución de cada conector de datos. Úsala para crear paneles personalizados, alimentar sistemas de alertas o realizar análisis más profundos que el panel de salud del producto.
GET /data_connectors/:id/execution_results — recupera registros de ejecución paginados. Por defecto, devuelve resultados de la última hora. Usa
start_tsyend_tspara personalizar el rango de tiempo. Los cuerpos de solicitud/respuesta se excluyen por defecto; usainclude_bodies=truepara incluirlos.GET /data_connectors/:id/execution_results/:result_id — recupera un único resultado de ejecución, siempre incluyendo cuerpos completos de solicitud/respuesta para depuración profunda.
Las opciones de filtrado incluyen estado de éxito, tipos específicos de error y rangos de tiempo especificados como timestamps Unix (segundos desde el 1 de enero de 1970 UTC). La paginación usa un modelo basado en cursor, devolviendo hasta 30 resultados por página. La autenticación usa OAuth con el scope read_workflow_connector_execution_result.
Limitaciones conocidas
Las siguientes limitaciones aplican a los conectores de datos. Cuando hay una solución alternativa disponible, se indica a continuación.
Fin puede no usar siempre un conector de datos aunque ejecute correctamente una solicitud API; si otro contenido se considera más relevante para la pregunta del cliente, Fin usará ese en su lugar. No hay solución; revisa el nombre y la descripción del conector para mejorar la relevancia.
Fin no puede consultar directamente atributos personalizados o datos de eventos de Intercom para responder preguntas. Usa un conector de datos para exponer estos datos vía un endpoint API externo.
Los conectores de datos requieren que AI Answers esté habilitado en el paso del workflow para que Fin los use. AI Answers no puede habilitarse en espacios de prueba, por lo que los conectores de datos solo pueden probarse completamente en un entorno de producción. Usa perfiles de usuario de prueba en producción para pruebas seguras.
El webhook de ejecución del conector de datos no se activa cuando el conector se dispara como parte de una conversación de vista previa.
Un conector de datos solo puede eliminarse vía API cuando está en estado borrador y no está referenciado por ningún workflows o AI agents.
Los emojis no son compatibles en los nombres de conectores de datos; incluir uno causará un error al guardar.
La dirección de correo electrónico del asignado no se expone como un placeholder en las solicitudes del conector de datos; solo está disponible el ID del asignado (
admin_assignee_id). Para obtener el correo electrónico, pasaadmin_assignee_idy busca el registro correspondiente vía la Admins API (GET /admins/{admin_id}), que devuelve el campo email. Alternativamente, almacena el correo en un atributo personalizado de conversación al asignar y referencia ese atributo.
Nota: No hay un campo de tiempo de espera configurable por el cliente. Cada llamada al conector de datos espera hasta 3 segundos para conectar y hasta 30 segundos para una respuesta. El mismo tiempo de espera aplica si el conector se ejecuta en Fin Procedures, Workflows o la Inbox.
Solución de problemas de conectores de datos
Cómo usar los registros del conector de datos
Todos los datos de respuesta de los conectores de datos activados por Fin se registran y almacenan hasta por 14 días. Si tu política de seguridad o cumplimiento requiere un período más corto, contacta a nuestro equipo de Soporte para solicitar retención de 7 días.
Para acceder a los registros, navega a Configuración > Integraciones > Data connectors, haz clic en el conector que quieres investigar y selecciona Registros.
Cómo usar el webhook de ejecución del conector de datos
Para señales en tiempo real sobre tasas de éxito y fallo del conector de datos, usa el webhook de ejecución del conector de datos. Esto te permite recibir eventos de ejecución desde Intercom y usarlos para crear paneles en tiempo real, alertas y monitoreo SLA (acuerdo de nivel de servicio) en tus servicios externos.
Notas:
Necesitarás crear una app, configurar Webhooks y suscribirte al webhook de ejecución del conector de datos antes de poder recibir notificaciones de conectores de datos.
El webhook de ejecución del conector de datos se omitirá si el conector de datos se dispara como parte de una conversación de vista previa.