Los conectores de datos permiten que Fin interactúe con sistemas externos a través de endpoints API. Fin puede usar conectores de datos para:
Leer datos en vivo de un sistema externo y usarlos en el procedimiento (por ejemplo, verificar en qué plan está un cliente, consultar el estado de un pedido o recuperar detalles de la cuenta).
Escribir en un sistema externo realizando acciones durante la conversación (por ejemplo, cancelar una suscripción, actualizar un registro o procesar un reembolso mediante solicitudes POST, PUT, PATCH o DELETE).
Cuando un conector de datos se ejecuta dentro de un Procedure, la respuesta está disponible para Fin como contexto temporal durante la duración de esa conversación; no se guarda automáticamente en un atributo de contacto o conversación. Si necesitas que los datos se guarden permanentemente en Intercom (por ejemplo, en un atributo personalizado de contacto u Objeto Personalizado), deberás configurar el mapeo de objetos en la configuración del conector.
Comenzar
Agregar un conector de datos a un paso de Instruction
Dentro de un paso de Instruction, escribe @ para abrir el menú de herramientas.
Selecciona Llamar conector de datos.
Elige el conector específico que quieres ejecutar (por ejemplo, Obtener pedidos para recuperar el historial de compras de un cliente).
Consejo: Aprende cómo configurar conectores de datos para extraer información en vivo de tus sistemas internos o APIs de terceros directamente en tus Fin Procedures.
Accede a la respuesta usando atributos generados automáticamente
Una vez que se agrega un conector, puedes acceder inmediatamente a la respuesta en pasos posteriores. Esto está disponible para Fin como contexto en general, pero también analizamos los campos de respuesta en conectores de datos para permitir que te refieras explícitamente a elementos en el cuerpo de la respuesta para la máxima fiabilidad.
Nota: No es necesario mapear la respuesta al usar conectores de datos en Procedures. Fin usa la respuesta de prueba que configures en el conector de datos para entender la estructura de la respuesta API: los nombres de campo disponibles y sus tipos. Luego puedes usar lenguaje natural en las instrucciones del procedimiento para indicarle a Fin qué datos de la respuesta usar. En tiempo de ejecución, Fin realiza una llamada API en vivo y lee los valores reales de esos campos.
Escribe @ y selecciona Leer un atributo.
Verás los campos de respuesta del conector de datos listados automáticamente en la parte superior del desplegable (por ejemplo, Obtener pedido de entrega > estado, Obtener pedido de entrega > order_id).
Selecciona el atributo específico que necesitas para insertarlo en tu instrucción o condición.
El contexto se comparte a lo largo del Procedure
Cuando indicas a Fin que use un conector de datos (@ use data connector), los datos devueltos están disponibles durante todo el procedimiento.
Para mayor fiabilidad, puedes acceder a estos datos usando (@ read attributes). Fin retiene los datos del conector durante toda la duración de un Procedure, incluyendo todos los pasos y subprocedimientos. Solo necesitas llamar a cada conector una vez por Procedure a menos que explícitamente necesites datos actualizados.
Por ejemplo, si llamas a (@ use Get_Subscription_info) en el paso uno, Fin retendrá el contexto de la suscripción del cliente para todos los pasos y subprocedimientos posteriores.
Mejores prácticas
Aprovecha los conectores de datos simulados para probar y comenzar a construir tu procedimiento
No necesitas una API en vivo completamente construida para empezar a crear procedimientos. Puedes utilizar respuestas de ejemplo para simular datos.
Respuesta de ejemplo: En la configuración del conector de datos (en la pestaña "Test response"), selecciona Respuesta de ejemplo y pega una carga útil JSON simulada. Esto te permite construir y probar el flujo del procedimiento inmediatamente.
Simulación dinámica: Para escenarios más complejos, puedes usar herramientas como Beeceptor para simular respuestas dinámicas de API.
Optimiza tus respuestas API para que sean el subconjunto más pequeño posible de datos relevantes que Fin necesita para el procedimiento
Demasiados datos irrelevantes pueden afectar el rendimiento. Generalmente, mientras más pequeño y claro, mejor.
Si se requiere una transformación de datos, se recomienda encarecidamente transformar los datos ya sea seleccionando un número limitado de campos o usando bloques de código de conector de datos. Esto transformará la respuesta API antes de que Fin la vea en el procedimiento.
Optimiza para usar no más de un conector de datos por paso
Un paso está pensado para ser una unidad de trabajo única. Fin es más fiable cuando llamas solo a un conector de datos en un solo paso.
Llama a los conectores de datos una vez por contexto
En Procedures, “contexto” se refiere a toda la ejecución del Procedure. Fin reutiliza automáticamente los datos del conector en todos los pasos y subprocedimientos. No necesitas llamar a la misma API dos veces.
❌ No es necesario llamar al mismo conector dos veces en diferentes pasos:
Step 1:
… (@use Get_Subscription_info) … and include @read plan status in your response so the users knows
Step 2
… (@use Get_Subscription_info) … and include @read refund eligibility in your response so the users knows
✅ Es más simple, limpio y rápido llamar al conector solo una vez:
Step 1:
… (@use Get_Subscription_info) … include @read plan status in your response so the users knows
Step 2
… include @read refund eligibility in your response so the users knows
Si necesitas datos de múltiples sistemas, divide la lógica en varios pasos en lugar de llamar a múltiples conectores en un solo paso.
No es necesario pedir a Fin que recopile datos que ya están configurados como entradas requeridas para un conector de datos
Las entradas se preconfiguran durante la configuración del conector de datos, por lo que Fin inferirá las entradas que necesita recopilar para llamar al conector de datos sin que tengas que indicarle explícitamente que recopile esos datos.
Por ejemplo, si el conector de datos Get Order Details ya tiene configurado el campo de entrada email:
❌ Instrucción innecesariamente compleja:
First ask the customer for their email, then call @get_order_details with that email
✅ Instrucciones claras:
Call @get_order_details
Fin infiere y recopila automáticamente las entradas requeridas según la configuración del conector, a menos que la entrada ya sea proporcionada directamente por Intercom.
Nota: Si notas problemas de rendimiento o fiabilidad con la recopilación de entradas, puedes indicarle explícitamente a Fin cuándo recopilar estos datos.
Consejo profesional: Cuando un Procedure requiere datos precisos, sin modificar o seguros (por ejemplo, email, ID de usuario o información de cuenta), inyecta esos valores directamente desde Intercom en el conector. Al configurar el atributo directamente en el conector en lugar de como una entrada recopilada por Fin, los datos evitan la recopilación o razonamiento de Fin por completo y permanecen intactos.
Usa atributos temporales como entradas deterministas para los conectores de datos
Ahora puedes seleccionar un atributo temporal como fuente de entrada para un parámetro de conector de datos. Cuando un atributo temporal se asigna como entrada, Fin omite toda la lógica de recuperación de atributos y usa directamente el valor del atributo temporal: sin inferencias, sin preguntar al cliente, sin alternativas.
Esto es útil cuando un paso del Procedure anterior en el flujo recopila o establece un valor (por ejemplo, mediante una acción Actualizar: Atributo Temporal), y quieres garantizar que ese valor exacto se pase al conector.
Para configurarlo, abre el paso del conector de datos en tu Procedure, encuentra el parámetro de entrada que quieres asignar, haz clic en el desplegable Fuente y selecciona el atributo temporal de la lista.
Importante: Si el atributo temporal no se ha establecido antes de que se ejecute el paso del conector de datos, Fin mostrará un error en los eventos de la conversación. Asegúrate de que un paso previo en el Procedure establezca el atributo antes de llamar al conector.
Monitoreo de la salud del conector
Los Procedures que usan conectores de datos muestran un indicador de salud directamente en la página de lista de procedimientos, para que puedas detectar problemas de conectores de un vistazo sin abrir cada procedimiento. El sello refleja el conector con peor rendimiento usado por ese procedimiento, calculado en los últimos 14 días (con un máximo de 1,000 ejecuciones por conector).
Los Procedures sin conectores de datos no muestran indicador; los conectores con cero ejecuciones se consideran saludables.
Estados de salud
Estado | Criterio | Implicación |
🟢 Saludable | Todos los conectores tienen una tasa de éxito >95% y un tamaño promedio de respuesta menor a 50KB. | Funcionando de manera óptima. |
🟡 Degradado | Algún conector tiene una tasa de éxito entre 80–95%, o tasa de éxito >95% pero tamaño promedio de respuesta ≥50KB (~15K tokens). | Experimentando problemas o devolviendo respuestas grandes que pueden aumentar el riesgo de alucinaciones. |
🔴 No saludable | Algún conector tiene una tasa de éxito <80%, o tamaño promedio de respuesta ≥100KB (~30K tokens). | Problemas críticos o respuestas peligrosamente grandes que requieren atención inmediata. |
Desglose
Al hacer clic en el sello de salud se abre un panel con un desglose por conector: estado, tasa de éxito, tamaño promedio de respuesta, latencia P90 y principales errores. Los nombres de los conectores enlazan directamente a su página de configuración para una depuración rápida.
Consejo: Si un conector muestra Degradado o No saludable debido al tamaño de la respuesta, consulta la mejor práctica Optimiza tus respuestas API para que sean el subconjunto más pequeño posible de datos relevantes que Fin necesita arriba; filtrar campos o usar bloques de código para recortar la respuesta antes de que Fin la vea es la solución más rápida.
Manejo de arreglos
Cuando un conector de datos devuelve una lista, Fin expone solo el arreglo raíz como un atributo. Los elementos hijos dentro del arreglo no se exponen como atributos separados en el selector de atributos.
Por ejemplo, si un conector devuelve un arreglo items, verás:
Obtener pedidos > items
Pero no verás:
Obtener pedidos > items > titleObtener pedidos > items > price
Fin aún puede trabajar con el contenido de una lista. Por ejemplo, si das la siguiente instrucción: "Si el cliente pregunta qué hay en su pedido, usa Obtener pedido > items para listar los productos y sus precios."
Fin leerá el contenido completo de la lista de items y responderá con: "Tu pedido incluye un Mouse Inalámbrico ($24.99) y un Soporte para Laptop ($39.99)."
Por ejemplo: Para la carga útil de respuesta a continuación, solo el elemento raíz del arreglo items se expone como un atributo temporal y no sus hijos.
{
"order_id": "ORD-1001",
"status": "processing",
"created_at": "2025-01-12T14:23:00Z",
"items": [
{
"product_id": "PROD-200",
"name": "Wireless Mouse",
"quantity": 1,
"unit_price": 24.99
},
{
"product_id": "PROD-122",
"name": "Laptop Stand",
"quantity": 1,
"unit_price": 39.99
}
]
}
Nota: @Read Obtener pedidos > items y dile al cliente los tres primeros artículos de su pedido.
Uso de arreglos en condiciones de código
Los atributos de arreglo están disponibles bajo el objeto inputs["data_connector"], agrupados por nombre de conector de datos. Los arreglos están indexados desde cero, lo que significa que el primer elemento está en el índice 0. Siempre verifica la longitud del arreglo antes de acceder a un índice específico.
Aún puedes consultar valores dentro de un arreglo usando una condición de código.
En condiciones de código, los datos del arreglo se acceden usando expresiones Python, donde referencias explícitamente los items por índice o iteras sobre la lista.
Esta condición verifica que el pedido contenga al menos cuatro artículos, y que la cantidad del cuarto artículo sea mayor que tres.
Siempre valida la longitud del arreglo antes de acceder a un índice para evitar errores en tiempo de ejecución durante la evaluación de condiciones.
Nota: Las acciones disponibles dependen de cómo esté configurado tu conector de datos.
Los conectores de datos soportan:
Crear: Usa solicitudes POST para crear nuevos registros en un sistema externo.
Leer: Usa solicitudes GET para recuperar datos existentes.
Actualizar: Usa solicitudes PUT o PATCH para modificar registros existentes.
Eliminar: Usa solicitudes DELETE para eliminar registros.