Los Data connectors ofrecen una forma poderosa de entregar respuestas personalizadas conectándose a datos en tus sistemas de terceros. En lugar de que los clientes esperen a que los teammates busquen manualmente la información o se les dirija a encontrarla por sí mismos, Fin puede acceder instantáneamente a los datos relevantes y elaborar una respuesta personalizada.

Para asegurar que estos Data connectors funcionen correctamente y se usen en los escenarios adecuados, aquí hay algunas mejores prácticas a considerar…

Escribe indicaciones efectivas para los Data connectors

Uno de los pasos más importantes es escribir una indicación efectiva en la sección Fin de tu Data connector.

Debes escribir de 3 a 5 oraciones para describir cuándo el Fin AI Agent debe activar este Data connector. Sé lo más específico posible y asegúrate de incluir una o más de las siguientes:

Ejemplos de los tipos de consultas de clientes que serían respondidas por este Data connector.
Frases clave que los clientes podrían usar.
Escenarios comunes en los que sería apropiado activar este Data connector.

También puedes consultar las plantillas recomendadas por AI como ejemplo.

Sé descriptivo

Explica claramente cuándo debe usarse este Data connector y qué tipo de detalles debe proporcionar.

Buena práctica	Usa este Data connector para obtener detalles sobre los pedidos del cliente y ayudar a resolver cualquier problema relacionado con el pedido. Este Data connector proporcionará todos los detalles del pedido para el cliente, como estado del pedido, artículos comprados, dirección de envío, información de seguimiento u otros detalles relevantes del pedido.
Mala práctica	Usa este Data connector para obtener información sobre su pedido.

Evita usar pronombres

Reemplaza pronombres como “we”, “us” y “their” con el sustantivo propio al que te refieres, como el nombre de tu empresa.

Buena práctica	Usa este Data connector para consultar el consumo eléctrico de un cliente con Examply.
Mala práctica	Usa este Data connector para consultar su consumo eléctrico con nosotros.

Sé específico

Usa escenarios comunes en los que sería apropiado activar este Data connector.

Buena práctica	Usa este Data connector para consultar incidentes no resueltos, como cuando los clientes quieren saber cuándo comenzó un incidente, el estado actual del problema, qué productos o servicios están afectados por un incidente o si el rendimiento del sistema ha vuelto a la normalidad.
Mala práctica	Usa este Data connector para consultar incidentes no resueltos.

Incluye frases de clientes

Observa cómo los clientes han formulado sus consultas en conversaciones anteriores e incluye las palabras clave y frases que usan.

Buena práctica	Busca estas frases clave como “failed order”, “issue with orders”, “orders not appearing in the system”, “difficulty with order”.
Mala práctica	No incluir frases clave de clientes.

Elige el endpoint API correcto

Para proporcionar a los clientes los datos correctos, es importante elegir el endpoint API correcto, ya sea de una app de terceros o de un sistema externo que sea propiedad de tu empresa.

Si no estás seguro por dónde empezar, puede que quieras encontrar un ingeniero que te ayude a determinar qué API devolverá los datos requeridos.

Por ejemplo, si tienes un sistema interno de reservas que almacena los detalles de reserva de un cliente, querrás usar una API para ese sistema que pueda acceder directamente a los detalles de la reserva.

También querrás usar una API que pueda encontrar los detalles de un cliente usando un identificador único como parámetro, como un ID o una dirección de correo electrónico.

Si decides usar el nombre o correo electrónico de un cliente como parámetro de solicitud, y tiene múltiples reservas, probablemente necesitarás especificar la solicitud más detalladamente usando la fecha de la reserva. En lugar de solicitar múltiples datos, sería óptimo pedir solo uno: el Booking ID.

De esta manera puedes recopilar el Booking ID como entrada de datos, lo que hará que Fin obtenga esta información del cliente en la conversación. Luego, el ID puede insertarse en el endpoint pasando el cursor sobre el menú al final del cuadro de entrada de URL.

Consejo: Los Data connectors ahora soportan respuestas API tanto en JSON como en XML. Si tu sistema externo solo proporciona XML, aún puedes conectarlo directamente: Intercom convertirá el XML a JSON automáticamente, para que puedas usar los datos en Fin, Workflows y el Inbox sin pasos adicionales.

También querrás asegurarte de usar los encabezados HTTP correctos para la solicitud. Si estos se usarán en muchos Data connectors, puedes agregarlos como un token de autenticación almacenado, que los guardará de forma segura en tu workspace.

Usando nuestro mismo ejemplo de reservas, supongamos que un cliente quiere reprogramar su viaje para otro día. Si hay un Data connector disponible para verificar tarifas y disponibilidad de reservas, Fin lo elegirá automáticamente dentro de la misma conversación.

Cuando elijas endpoints API para usar con Data connectors, puede que quieras pensar en casos donde los datos que tus clientes necesitan estén distribuidos en múltiples endpoints.

Para asegurar que el cliente pueda ver las tarifas y la disponibilidad, puedes crear otro Data connector a un endpoint que contenga esa información.

Crea conexiones seguras y protegidas

Verificación de identidad

Para la llamada más segura, recomendamos usar ‘Email’ o ‘User ID’ en el People Object para coincidir con el user en tu sistema.

Intercom actualmente solo te permite verificar los valores de correo electrónico o ID de usuario que provienen de Messenger. Te recomendamos encarecidamente que autentiques users en Messenger con JSON web tokens (JWTs).

Verificación de correo electrónico con código de un solo uso (OTP)

Usa la verificación de correo electrónico para data connectors con OTP para proporcionar un paso adicional de verificación antes de que un data connector sea usado, requiriendo que los clientes verifiquen su identidad mediante un código único y sensible al tiempo enviado por correo electrónico.

Protección contra fugas de datos

Generalmente hay dos formas en que los datos pueden ser comprometidos:

Un user actualiza maliciosamente uno de sus propios atributos - Por ejemplo, estableciendo "user_shopify_id=123", donde 123 es el Shopify ID de una víctima. Luego estos datos se envían o extraen de Shopify para el ID 123, y se asocian con el user malicioso en Intercom.
Un user manipula datos en un tercero, y un data connector extrae datos comprometidos a Intercom - Por ejemplo, un user se registra en un tercero usando el número de teléfono de una víctima. Luego un data connector consulta al tercero y sincroniza ese número de teléfono con un atributo de personas en Intercom. Ahora el user ha sobrescrito su número de teléfono con el de la víctima.

Para evitar que esto suceda, siempre prueba tu data connector primero antes de ponerlo en vivo para asegurarte de que esté configurado correctamente.

Aspectos clave a revisar:

Asegúrate de que tu data connector esté devolviendo datos relevantes para el user coincidente.
Asegúrate de que tus datos se almacenen correctamente en tus atributos mapeados de Intercom.

Usa transformación de datos para restringir datos

Las cargas útiles no estructuradas o demasiado grandes de APIs pueden causar que las respuestas basadas en AI (como Fin u otros agentes AI) alucinen, malinterpreten o simplemente no entreguen respuestas claras. Usando bloques de código en data connectors, puedes preprocesar, filtrar o modificar programáticamente las respuestas de API antes de enviarlas a Fin o mapearlas a objetos de Intercom sin necesidad de cambios en el backend o integraciones de terceros.

Consejos:

Usa siempre return para tu resultado principal.
Imprime solo para depuración (por ejemplo, print('Procesando orden', order['id'])).
Manténlo simple: Evita transformar todo a la vez—una transformación clara por bloque de código es lo mejor.
Valida la forma de la salida: Asegúrate de que la salida sea lo que Fin (o tu paso de mapeo) espera.
No importes más allá de los módulos aprobados: Módulos estándar de Python (math, decimal, re, datetime, datetime.timezone, json, random, time). Añadiremos más módulos con el tiempo según se necesiten.

Ejemplos prácticos

Aquí hay 4 patrones comunes, cada uno con un ejemplo realista usando los últimos requisitos (incluyendo return).

1. Reduciendo cargas grandes para Fin

Las APIs a menudo devuelven demasiados datos. Digamos que tu respuesta incluye 1,000 productos, pero solo quieres los primeros 5 para Fin para evitar alucinaciones.

api_response = inputs['data'] 
# Reduce payload to just the first 5 products 
result = api_response[:5] 
return result

2. Manejo de fechas en respuestas de API

A veces, los LLMs (como Fin) malinterpretan cadenas de fecha, especialmente con zonas horarias. Usa Python para convertir todas las cadenas de fecha a un formato ISO uniforme con UTC explícito.

import datetime 

def to_iso_utc(date_str): 
    try: # Adjust this format as needed! 
        dt = datetime.datetime.strptime(date_str, "%Y-%m-%d %H:%M:%S") 
        dt = dt.replace(tzinfo=datetime.timezone.utc) 
        return dt.isoformat() 
    except Exception as e: 
        print(f"Error parsing {date_str}: {e}") 
        return date_str 

api_response = inputs['data'] 
for item in api_response: 
    if 'created_at' in item: 
        item['created_at'] = to_iso_utc(item['created_at']) 
return api_response

3. Filtrando resultados de API para un valor de campo específico

Supongamos que solo quieres devolver autos donde make sea 'toyota' (¡mira tus capturas de pantalla!).

api_response = inputs['data'] 
filtered = [car for car in api_response if car.get('make', '').lower() == 'toyota'] 
return filtered

4. Aplanando ítems anidados para órdenes recientes

Si la respuesta de tu API está profundamente anidada (órdenes, con ítems dentro de cada una), aplánala para Fin:

orders = inputs['data']['orders'] 
result = [] 
for order in orders: 
    for item in order['line_items']: 
        result.append({ 
            "order_id": order['id'], 
            "item_name": item['name'] 
        }) 
return result

Devuelve enlaces profundos clicables desde tu Data Connector

Si tu Data Connector devuelve una URL que quieres que Fin presente como un enlace clicable, tienes dos opciones.

Opción 1: Formatea el enlace en tu respuesta de API

Incluye la sintaxis de enlace markdown directamente en el texto que devuelve tu API. Fin lo mostrará como un enlace clicable en la conversación.

Usa este formato para mostrar texto de enlace personalizado:

[View Dashboard](beyond://account/dashboard)

O este formato si quieres que la URL misma sea visible y clicable:

[beyond://account/dashboard](beyond://account/dashboard)

Opción 2: Usa la guía de Fin para formatear el enlace

Si tu API devuelve una URL simple en un atributo de datos, puedes indicar a Fin que la formatee como un enlace clicable usando la guía. Referencia el nombre del Data Connector y el atributo que contiene el enlace profundo, y dile a Fin que lo presente usando la sintaxis de enlace markdown.

Nota: El enlace profundo es compatible con algunos tipos de mensajes móviles. Consulta la documentación de enlace profundo para iOS y Android para detalles sobre lo que se soporta.

Utiliza reglas de audiencia

Si recién comienzas con data connectors, puede que quieras experimentar con qué configuraciones de data connectors conducen a más resoluciones. Una forma de hacerlo es activar primero el data connector para un subconjunto de users para ver cómo funciona. Puedes hacer esto usando audience rules.

Las audience rules pueden seleccionarse de una lista de atributos de empresa o contacto que ya están disponibles en tu espacio de trabajo. Si tienes Shopify, Statuspage o Stripe instalados, también puedes acceder a atributos específicos de la app.

Si un atributo que quieres usar no existe, puedes configurar custom data attributes para identificar users que cumplan con los criterios que quieres dirigir para el data connector.

Una vez que hayas creado la regla, puedes ver una vista previa de los users que pueden recibir una respuesta impulsada por el data connector.

Usa verificaciones de seguridad para proteger tus connectors

Antes de poner un connector en vivo, ejecuta las verificaciones de seguridad integradas en la pestaña Seguridad. Estas muestran riesgos potenciales con recomendaciones accionables para que puedas tomar decisiones informadas antes de ponerlo en vivo.

Las verificaciones pueden incluir:

Los atributos de datos del cliente no están verificados — si los atributos de datos del cliente pueden actualizarse sin verificación de user, añade verificación de user.
Los datos recopilados por Fin para este connector necesitan revisión — si Fin recopila información de los clientes antes de llamar a tu API, valida la entrada primero en tu backend.
Los Workflows que usan este data connector necesitan revisión — si ciertos workflows representan un riesgo de exponer datos sensibles del cliente, revísalos para validarlos en tu backend.
Un encabezado de solicitud para este data connector necesita revisión — si los detalles del cliente se envían con cada solicitud, asegúrate de que tu API verifique el valor.

Cada verificación incluye pasos claros para resolver el problema. Resuelve todos los riesgos señalados antes de activar el conector.

Analiza conversaciones para impulsar optimizaciones

Cada conector de datos tiene un panel de salud dedicado donde puedes evaluar el impacto y detectar oportunidades para mejorar el rendimiento. Navega a Settings > Integrations > data connectors y haz clic en cualquier conector para abrir su panel. Desde allí puedes revisar tasas de éxito, latencia de ejecución, desglose de estados HTTP y categorización de tipos de fallos, todo filtrable por ventana de tiempo (1h, 6h, 24h, 7d o 14d). Para detalles de ejecuciones individuales, selecciona la pestaña Logs. Más allá del panel, revisa las conversaciones donde se usó un conector de datos para ver qué funcionó bien o qué falló.

Si estás usando atributos de datos personalizados para delimitar la audiencia, puedes utilizar ese atributo para filtrar a través del inbox y ver cómo funcionó, y si es necesario hacer ajustes.

Algunas preguntas a considerar incluyen:

¿El conector de datos se activó en el caso correcto?
¿Tuvo que intervenir un compañero, y si es así, en qué etapa?
¿El conector de datos proporcionó la información correcta al cliente según lo solicitado, pero la pregunta del cliente realmente era sobre otra cosa?
¿La respuesta podría haberse apoyado con información adicional de tu Knowledge Hub?

Fin no puede consultar atributos personalizados ni datos de eventos para respuestas. Para 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.

Mejores prácticas al usar Data connectors con Fin