Utiliza 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 a los clientes sin esperar a un compañero. Aprenderás a crear un conector desde una plantilla o desde cero, configurar su endpoint API, dar forma a 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" permiso 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 (interfaz de programación de aplicaciones) 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 > Conectores de datos y haz clic en Nuevo.
Si tienes instalada una de las apps soportadas, verás una plantilla para esta app listada bajo Crear conector de datos. Actualmente hay plantillas disponibles 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 conectores de datos para cada app aparecerán como un conector de datos listo para activar.
Cuando haces clic en una plantilla, verás información sobre lo que hace el conector de datos y puedes probarlo en la vista previa del Messenger. Si estás satisfecho con el comportamiento del conector de datos, solo selecciona Activar para AI Agent.
La vista previa del Messenger aquí usa datos de ejemplo. Al activar el conector de datos, Fin usará tus datos reales de clientes.
Si quieres configurar el conector de datos, puedes hacer clic en Personalizar, lo que te llevará al constructor de conectores de datos para configuración avanzada.
Si no tienes una de nuestras apps soportadas instaladas, las apps aparecerán aquí para que las instales en tu espacio de trabajo. Después de la instalación, las plantillas relevantes de conectores de datos aparecerán en la sección anterior.
Aprende más sobre las plantillas de conectores de datos disponibles y casos de uso para Fin.
Desde una recomendación de AI
Para ver los conectores de datos recomendados por AI, ve a Configuración > Integraciones > Conectores de datos y haz clic en Nuevo conector de datos.
Verás tus conectores de datos recomendados por AI únicos bajo "Crear conector de datos desde plantilla". Estos se generan basándose en tu historial de conversaciones para ayudarte a identificar posibles conectores de datos, ver qué porcentaje del volumen de conversaciones podrían resolver y previsualizarlos en el Messenger, antes de configurar algo.
Para que aparezcan recomendaciones de AI, Fin debe estar activo en tu espacio de trabajo y debes tener suficiente volumen de conversaciones.
Cuando haces clic en un conector de datos recomendado por AI, encontrarás información sobre lo que hace el conector de datos y puedes previsualizarlo en el Messenger (usando datos de ejemplo). Los conectores de datos recomendados por AI 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 > Conectores de datos 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 escribir descripciones de conectores de datos.
Nota: Los emojis no son compatibles 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 ya 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 establece 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 respaldo 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 must collect this parameter. Cuando está activado, Fin debe recopilar 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) del 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 en 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 de 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: Data.
Fase 2: Data — moldeando la respuesta de la API
La pestaña Data 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 bug 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 a 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 seleccione mapeo de objetos, verá solo objetos mapeados en Workflows y Procedures; mientras que sin mapeo, se listarán todas las opciones seleccionadas en la tabla Restringir y moldear los datos. 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 qué tan 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 determina qué verá Fin y qué devolverá a los clientes; los datos de ejemplo no reflejarán resultados reales.
Fin trigger: En esta pestaña Fin, configure How should Fin use this connector? 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 Save y Set live.
¿Cómo debería Fin usar 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 conector de datos 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 conectores de datos. 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 conector de datos existente que hayas configurado se convertirá en una audiencia Personalizada para preservar la funcionalidad.
Consejo: Si quieres probar el conector de datos antes de habilitarlo para los clientes, usa las reglas de audiencia para habilitar el conector solo para ti o tus compañeros inicialmente.
Deshabilitado (disparador manual)
El conector no se ejecutará automáticamente. Necesitarás agregarlo 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 existente 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 activación en vivo
La pestaña Seguridad es el paso final antes de activar en vivo. Controla si los clientes deben estar autenticados antes de que el conector de datos 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 conector de datos cambia a En vivo en Configuración > Integraciones > Conectores de datos. 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 conectores de datos de forma segura
Nota: La vista previa del Messenger aquí usa datos de ejemplo. Al activar el conector de datos en vivo, Fin usará los datos reales de tus clientes.
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 entornos de producción. Usa perfiles de usuario de prueba en producción para pruebas seguras.
Recomendamos usar reglas de audiencia para implementar conectores de datos en fases a tu base de clientes. Esto te permite validar el rendimiento del conector de datos y hacer ajustes o cambios donde sea necesario.
Cómo monitorear y gestionar conectores de datos
Para encontrar conectores de datos existentes, navega a Configuración > Integraciones > Conectores de datos. La lista de conectores de datos muestra los siguientes detalles para cada conector:
Nombre y estado (en vivo o borrador)
Uso general (total de ejecuciones)
Uso de Fin — tasa de resolución y la audiencia a la que está disponible
Salud — tasa de éxito de API y un indicador general de salud
Estado de seguridad
Detalles de configuración
Opción de 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 el 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 conector de datos en el Inbox
Para ver la actividad del conector de datos en una conversación específica, abre la conversación en el Inbox y selecciona Mostrar eventos de conversación. El panel de eventos muestra si Fin tuvo acceso al conector de datos y si se activó con éxito.
Nota:
Si hay un error con la activación del conector de datos, selecciona Registros para saber por qué.
Fin puede no siempre elegir usar el conector de datos 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 conectores de datos para que Fin pueda acceder a fuentes de datos externas vía API.
Las vistas del Inbox pueden crearse con el atributo “Fin AI Agent: Acción usada en la respuesta”. Este atributo se establece si Fin llama a un conector de datos y usa parte o toda la respuesta en una respuesta.
Versionado de conectores de datos
Los conectores de datos usan un sistema de versionado borrador/en vivo para que puedas hacer ediciones de forma segura sin interrumpir el conector en ejecución.
Cada conector de datos 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 instantánea de la nueva versión que se convierte en la versión en vivo. Puedes agregar 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 agregaron) y una marca de tiempo.
El historial completo de cambios es rastreable y puedes revertir 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 Set live 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 API de Configuración
La API de Configuración 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 para el espacio de trabajo, ordenados por el más recientemente actualizado primero. |
GET | /data_connectors/:id | Recupera el detalle completo de un solo 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 draft y no debe estar en uso por ningún workflows o agentes AI. |
La autenticación usa OAuth (Open Authorization). El acceso de lectura y escritura requiere el ámbito read_write_data_connectors. El acceso solo de lectura requiere el ámbito read_workflow_connector_execution_result.
Cómo usar la API de Resultados
La API de Resultados 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, se devuelven 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 solo resultado de ejecución, siempre incluyendo cuerpos completos de solicitud/respuesta para una depuración profunda.
Las opciones de filtrado incluyen estado de éxito, tipos específicos de error y rangos de tiempo especificados como marcas de tiempo Unix (segundos transcurridos 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 ámbito read_workflow_connector_execution_result.
Limitaciones conocidas
Las siguientes limitaciones se 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 incluso si ejecuta 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 alternativa; revisa el nombre y la descripción del conector para mejorar la coincidencia de 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 a través de 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 activa como parte de una conversación de vista previa.
Un conector de datos solo puede eliminarse vía API cuando está en estado draft y no está referenciado por ningún workflows o agentes AI.
Los emojis no son compatibles en los nombres de conectores de datos; incluir uno causará un error al guardar.
Nota: No hay un campo de tiempo de espera configurable por el cliente. El tiempo de espera predeterminado es de 15 segundos. Para conectores de datos usados dentro de Fin Procedures en espacios de trabajo elegibles, el tiempo de espera se extiende a 30 segundos.
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 una 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 Logs.
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 de 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 activa como parte de una conversación de vista previa.