Cada conector de datos consiste en una llamada API que puedes configurar detrás de escena. Fin elegirá automáticamente cuándo usarlo y entregará una respuesta personalizada al cliente.
Puedes conectar cualquier sistema que tenga una API; puede ser tu herramienta interna única que has construido para tu negocio, o una aplicación de terceros que estés usando como Shopify, Salesforce, Stripe, Jira y más.
Nota:
La autenticación de usuarios debe configurarse para activar un conector de datos para users. Esto evita que alguien suplante a tus users conectados o vea sus conversaciones. Aprende cómo configurar JWTs para la autenticación de users.
Crear un conector de datos
Para configurar un conector de datos personalizado para Fin, navega a Configuración > Integraciones > Conectores de datos y haz clic en + Nuevo.
Fase 1: API
El editor de configuración está organizado en cuatro pestañas: API, Datos, Fin y Seguridad. Trabaja en cada pestaña para construir tu conector antes de activarlo.
Identidad
Primero, proporciona un nombre corto para describir lo que hace este conector de datos, como “Obtener saldo de cuenta impago”. Luego, proporciona una descripción detallada explicando cuándo Fin debería usarlo.
Incluye ejemplos de los datos que este conector de datos proporciona y las consultas de los clientes que ayuda a responder.
Por ejemplo:
Usa este conector de datos para recuperar transacciones recientes de un cliente. Este conector de datos proporciona información clave como… Las consultas de clientes incluyen… “¿Puedes verificar si tengo algún saldo pendiente en mi cuenta?” “¿Hay algún pago pendiente en mi cuenta ahora mismo?” “¿Debo algo en mi cuenta?” “¿Puedes decirme si tengo facturas o cargos impagos?” “¿Hay algún saldo que necesite liquidar en mi cuenta?” “¿Puedes confirmar si mi cuenta está completamente pagada?”
Conexión API
Si quieres, puedes especificar si Fin debe recopilar datos antes de usar este conector de datos. Esto puede ser útil en casos donde necesitas asegurarte de que existen datos antes de ejecutar el conector. Por ejemplo, podrías pedir al cliente su número de cuenta si no está almacenado en su perfil de user en Intercom.
Para recopilar entradas de datos, haz clic en + Agregar entrada de datos y elige el formato de los datos que se deben recopilar (texto, número, número decimal o verdadero/falso) y asígnale un nombre y descripción para que Fin sepa cómo recopilarlo.
Nota:
Cuando esté disponible, Fin recopilará la información del contexto de la conversación.
Puedes conectar conectores de datos a APIs que devuelven XML. Intercom convertirá automáticamente las respuestas XML a JSON, por lo que no necesitas hacer ninguna conversión manual ni usar una herramienta de terceros. Esto significa que puedes conectar a una gama más amplia de sistemas externos, incluso si no soportan JSON de forma nativa.
Luego, debes especificar la URL HTTPS de tu API y seleccionar el método de solicitud: GET, POST, PUT, DELETE o PATCH.
Puede que quieras usar atributos disponibles dentro de tu espacio de trabajo, como el ID de user o correo electrónico de un cliente, para realizar una búsqueda. También debes asegurarte de especificar el token de autenticación correcto y especificar los encabezados correctos (por ejemplo: Accept: application/json o Content-Type: application/json).
Una vez hecho, prueba tu conexión para validar la configuración antes de pasar a la pestaña Datos.
Probar respuesta
Necesitarás probar esta acción para asegurarte de que está obteniendo los datos correctos de la API a la que te conectas. Puedes probar tu conector de datos usando dos métodos:
Respuesta en vivo: Prueba con datos de respuesta en vivo de tu solicitud API para asegurar la configuración correcta. La respuesta en vivo hará una llamada API real a tu endpoint, así que ten cuidado en caso de que esta solicitud afecte datos reales.
Respuesta de ejemplo: Proporciona datos JSON de ejemplo que son útiles si tu API aún no está completamente desarrollada o necesitas simular/fingir una respuesta particular.
Si todo se ve bien, continúa a la pestaña Datos para configurar cómo se formatea la respuesta.
Fase 2: Datos
Esta pestaña controla cómo se formatea la respuesta de la API antes de que Fin la use.
Restringir y dar forma
Por defecto, Fin puede acceder a todos los datos de la respuesta para generar respuestas. Selecciona Restringir acceso manualmente si deseas limitar los datos a los que Fin puede acceder. Luego marca los campos de datos a los que quieres dar acceso a Fin.
También puedes editar los elementos de datos individuales haciendo clic en el ícono de editar para darle a tus datos de respuesta un nombre visible para el cliente, así como especificar cualquier transformación de los datos.
Por ejemplo, si la respuesta de la API devuelve un saldo de 0, en lugar de que Fin diga que el saldo impago es 0, puede responder diciendo que actualmente no queda saldo impago.
Usa código para filtrar o transformar la respuesta
Con bloques de código para conectores de datos, te damos el poder de transformar y manipular directamente las respuestas API usando Python, justo dentro de la configuración de tu conector.
Las cargas no estructuradas o demasiado grandes de APIs pueden causar que las respuestas basadas en IA (como Fin u otros agentes IA) alucinen, malinterpreten o simplemente no entreguen respuestas claras. Ahora, puedes preprocesar, filtrar o modificar programáticamente las respuestas API antes de enviarlas a Fin o mapearlas a objetos de Intercom sin necesidad de cambios en el backend o integraciones de terceros.
Cómo funciona
returnstatement: El resultado principal que produce tu bloque de código debe ser devuelto con una sentenciareturn. Solo lo que se devuelve será enviado a Fin o al resto de tu conector.print()statements: Úsalos solo para depuración o registro de progreso. Estas salidas se capturan por separado y NO se envían como resultado de la API.Módulos estándar solamente: Estás limitado a un conjunto de 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.
Nota:
Respuestas de prueba no JSON: Los bloques de código requieren que la respuesta de prueba de tu API sea un objeto o arreglo JSON válido. No se soportan cargas no JSON (y causarán fallos).
Solicitudes API no exitosas: Los bloques de código solo pueden transformar respuestas API exitosas (código de estado 200). No se soportan respuestas de error con códigos como 400, 404 o 500 para la transformación de bloques de código.
Cómo configurar bloques de código para conectores de datos
Ve a Configuración > Integraciones > conectores de datos y selecciona el conector de datos con el que quieres usar bloques de código. Luego haz clic en Transformación de datos y selecciona la opción "Usar código para filtrar o transformar la respuesta".
Accede a los datos de entrada (Respuesta API) en tu bloque de código
Para acceder a los datos devueltos por tu API (la respuesta de prueba), usa la variable inputs['data'] dentro de tu bloque de código. Normalmente, esto te da toda la respuesta de tu API, lista para transformar como quieras.
Por ejemplo, al inicio de tu bloque de código, normalmente escribes:
api_response = inputs['data']
Esto asigna la respuesta de la API (un diccionario, lista o cadena de Python, según tu API) a la variable api_response para su procesamiento posterior.
Obtén sugerencias automáticas para bloques de código
Cuando navegas a la pestaña Transformación de datos, la respuesta del conector de datos se analiza automáticamente para identificar sugerencias que mejorarán el rendimiento de Fin.
Esto detecta problemas comunes como marcas de tiempo Unix y cargas útiles sobredimensionadas: datos no estructurados o demasiado grandes que pueden hacer que las respuestas basadas en IA alucinen, malinterpreten o no entreguen respuestas claras.
Cuando se encuentra una sugerencia, verás un banner con un botón Ver sugerencia que muestra el código Python recomendado para que tus datos sean más limpios y confiables para Fin. Selecciona Probar código para ver el resultado que devuelve.
Si estás satisfecho con la instrucción return, selecciona Aceptar sugerencia para mejorar significativamente la calidad y precisión de las respuestas de Fin a partir de los datos de tu conector.
Mapeo de objetos
Al crear conectores de datos para Fin, no es necesario mapear los datos de respuesta a atributos u objetos de Intercom. En cambio, Fin interpreta directamente la respuesta JSON y puede usarla para resolver preguntas. La respuesta se genera según la sección ‘Respuesta de prueba’. Cada línea corresponde a un punto de datos en la respuesta JSON.
Una vez que hayas configurado la pestaña Datos, continúa con la Fase 3: Fin para definir cómo Fin usa este conector, y la Fase 4: Seguridad para configurar la autenticación y realizar verificaciones de seguridad antes de ponerlo en producción.
Fase 3: Fin
Esta pestaña determina cómo Fin interactúa con el conector.
¿Cómo debería Fin usar este conector?
Elige entre dos modos:
Habilitado (activación directa) — Fin activa el conector automáticamente según la pregunta del cliente. Ideal para conectores de solo lectura como "Consultar estado del pedido" y consultas repetitivas de alto volumen.
Deshabilitado (activación manual) — El conector no se ejecutará automáticamente. Deberás agregarlo manualmente a un Flujo de trabajo, Tarea, Procedimiento o Macro. Ideal para conectores sensibles o activos en escritura donde se desea supervisión humana o de flujo de trabajo antes de ejecutar cualquier acción.
Audiencia
Controla para quién está disponible este conector usando audiencias reutilizables de Fin, o crea una audiencia personalizada para reglas puntuales. Por ejemplo, hazlo disponible para clientes en tu audiencia 'Plan Enterprise' o restríngelo a usuarios registrados con correo electrónico verificado.
Consejo: Puedes elegir Todos, una audiencia de Fin reutilizable o una audiencia Personalizada para reglas puntuales. Puedes seleccionar múltiples audiencias de Fin, pero no puedes combinar reglas Personalizadas con una audiencia de Fin. Cualquier regla de audiencia existente que hayas configurado se convertirá en una audiencia Personalizada para preservar la funcionalidad.
Vista previa de Fin
Usa la vista previa de Fin para ver exactamente cómo responderá Fin usando este conector antes de ponerlo en producción.
Fase 4: Seguridad
El paso final antes de ponerlo en producción. Esta pestaña maneja el control de acceso a los datos del cliente.
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 seguridad de la configuración de tu API. Cualquier riesgo se mostrará con recomendaciones prácticas: resuélvelos antes de poner el conector en producción.
Importante: Hay 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.
Una vez que todas las verificaciones pasen, guarda tu conector y ponlo en producción.
Despliegue de conectores de datos
Recomendamos usar reglas de audiencia para desplegar conectores de datos en fases a tu base de clientes. Esto te permite validar el rendimiento de los conectores de datos y hacer ajustes o cambios cuando sea necesario.
Si tienes problemas donde tu conector de datos no se activa para un usuario, asegúrate de haber eliminado cualquier regla de audiencia específica de tu empresa que hayas agregado en la fase de prueba.
Solución de problemas
Para propósitos de solución de problemas, todos los datos de respuesta generados por conectores de datos activados por Fin se registran hasta por 14 días. Puedes acceder a estos registros en la pestaña Conector de datos > Registros. Puedes ver los datos de respuesta según el tipo de datos a los que Fin tenga acceso.
Respuesta completa – Respuesta completa y sin modificar
Respuesta redactada y formateada – Después de la transformación
Sin datos de respuesta
Preguntas frecuentes
¿Puedo usar conectores de datos para enviar atributos al transferir una conversación de Fin a una plataforma de terceros (no Zendesk/Salesforce)?
¿Puedo usar conectores de datos para enviar atributos al transferir una conversación de Fin a una plataforma de terceros (no Zendesk/Salesforce)?
Si intentas enviar una solicitud POST (por ejemplo, con una estructura como la siguiente), usa las opciones de transferencia de flujo de trabajo de Fin en su lugar:
{
"body": "the conversation with Fin",
"from": "users_email_address",
"to": "our_ticketing_email_address"
}
Las opciones de transferencia de flujo de trabajo incluyen transferencia con JavaScript y transferencia a URL, con la capacidad de incluir contexto de conversación mediante resúmenes generados por IA.
1. Transferencia con JavaScript
Esto te permite definir una función handoff_with_javascript en tu aplicación Messenger que puede:
Recopilar el resumen de la conversación (a través de “AI Add Summary Note”)
Acceder al correo electrónico del usuario (usando atributos)
Enviar un fetch() o XMLHttpRequest a tu endpoint externo con la estructura que deseas
Aprende más aquí 👉 Transferencia con JavaScript
2. Transferencia a URL
Esta opción solo redirige al usuario a una página específica, no envía una solicitud POST ni lleva datos de conversación. Por lo tanto, no sería adecuada para tu caso si intentas enviar JSON mediante POST.
Configuración recomendada
Utilice el JavaScript hand-off e incluya lógica como:
handoff_with_javascript = function (params) {
const userEmail = params.user.email;
const summary = params.conversation_summary;
fetch('https://your-endpoint.com/api', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
body: summary,
from: userEmail,
to: 'your_support@company.com'
})
});
}