Cada conector de dados consiste em uma chamada API que você pode configurar nos bastidores. Fin escolherá automaticamente quando usá-lo e fornecerá uma resposta personalizada ao cliente.
Você pode conectar qualquer sistema que tenha uma API; pode ser sua ferramenta interna exclusiva que você criou para seu negócio, ou um aplicativo de terceiros que você está usando como Shopify, Salesforce, Stripe, Jira e mais.
Nota:
A autenticação do usuário deve ser configurada para ativar um conector de dados para users. Isso impede que alguém se passe por seus users logados ou veja suas conversas. Saiba como configurar JWTs para autenticação de users.
Criar um conector de dados
Para configurar um conector de dados personalizado para Fin, navegue até Configurações > Integrações > Conectores de dados e clique em + Novo.
Fase 1: API
O editor de configuração está organizado em quatro abas: API, Dados, Fin e Segurança. Trabalhe em cada aba para construir seu conector antes de ativá-lo.
Identidade
Primeiro, forneça um nome curto para descrever o que este conector de dados faz, como “Obter saldo de conta não pago”. Em seguida, forneça uma descrição detalhada explicando quando o Fin deve usá-lo.
Inclua exemplos dos dados que este conector de dados fornece e das consultas dos clientes que ele ajuda a responder.
Por exemplo:
Use este conector de dados para recuperar transações recentes de um cliente. Este conector de dados fornece informações chave como… Exemplos de consultas de clientes incluem… "Você pode verificar se tenho algum saldo pendente na minha conta?" "Há algum pagamento devido na minha conta agora?" "Devo algo na minha conta?" "Você pode me dizer se tenho alguma conta ou cobrança não paga?" "Existe algum saldo que preciso quitar na minha conta?" "Você pode confirmar se minha conta está totalmente paga?"
Conexão API
Se desejar, você pode especificar se o Fin deve coletar algum dado antes de usar este conector de dados. Isso pode ser útil em casos onde você precisa garantir que os dados existam antes que o conector de dados seja executado. Por exemplo, você pode querer pedir ao cliente o número da conta se isso não estiver armazenado no perfil do user no Intercom.
Para coletar entradas de dados, clique em + Adicionar entrada de dados e escolha o formato dos dados que devem ser coletados (texto, número, número decimal ou verdadeiro/falso) e dê um nome e descrição para que o Fin saiba como coletá-los.
Nota:
Quando disponível, o Fin coletará as informações do contexto da conversa.
Você pode conectar conectores de dados a APIs que retornam XML. O Intercom converterá automaticamente respostas XML para JSON, então você não precisa fazer nenhuma conversão manual ou usar uma ferramenta de terceiros. Isso significa que você pode conectar a uma gama maior de sistemas externos, mesmo que eles não suportem JSON nativamente.
Em seguida, você deve especificar a URL HTTPS da sua API e selecionar o método de requisição: GET, POST, PUT, DELETE ou PATCH.
Você pode querer usar atributos disponíveis dentro do seu workspace, como o ID do user ou e-mail de um cliente, para realizar uma busca. Você também precisa garantir que especifique o token de autenticação correto e especificar os cabeçalhos corretos (por exemplo: Accept: application/json ou Content-Type: application/json).
Quando terminar, teste sua conexão para validar a configuração antes de passar para a aba Dados.
Testar resposta
Você precisará testar esta ação para garantir que está buscando os dados corretos da API à qual está se conectando. Você pode testar seu conector de dados usando dois métodos:
Resposta ao vivo: Teste com dados de resposta ao vivo da sua requisição API para garantir a configuração correta. A resposta ao vivo fará uma chamada real à sua API, então tenha cuidado caso essa requisição afete dados reais.
Resposta de exemplo: Forneça dados JSON de exemplo que são úteis se sua API ainda não estiver totalmente desenvolvida ou se você precisar simular/fingir uma resposta específica.
Se tudo estiver correto, continue para a aba Dados para configurar como a resposta será formatada.
Fase 2: Dados
Esta aba controla como a resposta da API é formatada antes do Fin usá-la.
Restringir e formatar
Por padrão, o Fin pode acessar todos os dados da resposta para gerar respostas. Selecione Restringir acesso manualmente se desejar limitar os dados que o Fin pode ler. Então, marque os campos de dados aos quais deseja dar acesso ao Fin.
Você também pode editar os itens de dados individuais clicando no ícone editar para dar um nome voltado ao cliente para seus dados de resposta, bem como especificar quaisquer transformações nos dados.
Por exemplo, se a resposta da API retornar um saldo de 0, em vez de o Fin informar que o saldo não pago é 0, ele pode responder dizendo que atualmente não há saldo não pago restante.
Use código para filtrar ou transformar a resposta
Com blocos de código para conectores de dados, estamos capacitando você a transformar e manipular diretamente respostas de API usando Python — diretamente na configuração do seu conector.
Payloads não estruturados ou excessivamente grandes de APIs podem fazer com que respostas baseadas em IA (como Fin ou outros agentes de IA) alucinem, interpretem mal ou simplesmente falhem em fornecer respostas claras. Agora, você pode pré-processar, filtrar ou ajustar programaticamente respostas de API antes que elas sejam enviadas ao Fin ou mapeadas para objetos do Intercom sem precisar de alterações no backend ou integrações de terceiros.
Como funciona
returnstatement: O resultado principal que seu bloco de código produz deve ser retornado com uma instruçãoreturn. Apenas o que for retornado será enviado para o Fin ou para o restante do seu conector.print()statements: Use-os apenas para depuração ou registro de progresso. Essas saídas são capturadas separadamente e NÃO são enviadas como resultado da API.Módulos padrão apenas: Você está limitado a um conjunto de módulos padrão do Python (
math,decimal,re,datetime,datetime.timezone,json,random,time). Adicionaremos mais módulos ao longo do tempo conforme necessário.
Nota:
Respostas de teste não JSON: Blocos de código exigem que a resposta de teste da sua API seja um objeto ou array JSON válido. Payloads não JSON não são suportados (e causarão falhas).
Requisições API não bem-sucedidas: Blocos de código só podem transformar respostas de API bem-sucedidas (código de status 200). Respostas de erro com códigos de status como 400, 404 ou 500 não são suportadas para transformação em blocos de código.
Como configurar blocos de código para conectores de dados
Vá para Configurações > Integrações > conectores de dados e selecione o conector de dados que deseja usar com blocos de código. Em seguida, clique em Transformação de dados e selecione a opção "Usar código para filtrar ou transformar a resposta".
Acesse dados de entrada (Resposta da API) no seu bloco de código
Para acessar os dados retornados pela sua API (a resposta de teste), use a variável inputs['data'] dentro do seu bloco de código. Normalmente, isso fornece toda a resposta da sua API, pronta para ser transformada como desejar.
Por exemplo, no início do seu bloco de código, normalmente você escreve:
api_response = inputs['data']
Isso atribui a resposta da API (um dicionário Python, lista ou string, dependendo da sua API) à variável api_response para processamento posterior.
Obtenha sugestões automáticas para blocos de código
Quando você navega até a aba Transformação de dados, a resposta do seu conector de dados é automaticamente analisada para identificar sugestões que melhorarão o desempenho do Fin.
Isso detecta problemas comuns como timestamps Unix e cargas excessivamente grandes — dados não estruturados ou muito volumosos que podem fazer com que respostas baseadas em AI alucinem, interpretem mal ou não forneçam respostas claras.
Quando uma sugestão é encontrada, você verá um banner com um botão Ver sugestão mostrando o código Python recomendado que tornará seus dados mais limpos e confiáveis para o Fin. Selecione Testar código para ver o resultado retornado.
Se você estiver satisfeito com a instrução de retorno, selecione Aceitar sugestão para melhorar significativamente a qualidade e precisão das respostas do Fin a partir dos dados do seu conector.
Mapeamento de objetos
Ao criar conectores de dados para o Fin, não é necessário mapear os dados da resposta para atributos ou objetos do Intercom. Em vez disso, o Fin interpreta diretamente a resposta JSON e pode usá-la para resolver perguntas. A resposta é gerada com base na seção ‘Test response’. Cada item corresponde a um ponto de dados na resposta JSON.
Depois de configurar a aba Dados, continue para a Fase 3: Fin para definir como o Fin usa este conector, e a Fase 4: Segurança para configurar autenticação e executar verificações de segurança antes de entrar no ar.
Fase 3: Fin
Esta aba determina como o Fin interage com o conector.
Como o Fin deve usar este conector?
Escolha entre dois modos:
Ativado (gatilho direto) — O Fin aciona o conector automaticamente com base na pergunta do cliente. Ideal para conectores somente leitura, como "Verificar status do pedido" e consultas repetitivas de alto volume.
Desativado (gatilho manual) — O conector não será executado automaticamente. Você precisará adicioná-lo manualmente a um Workflow, Task, Procedure ou Macro. Ideal para conectores sensíveis ou ativos em escrita, onde você deseja supervisão humana ou de workflow antes de qualquer execução.
Público
Controle quem pode acessar este conector usando públicos reutilizáveis do Fin, ou crie um público personalizado para regras pontuais. Por exemplo, disponibilize para clientes no seu público ‘Enterprise plan’ ou restrinja a usuários logados com e-mail verificado.
Dica: Você pode escolher Todos, um público reutilizável do Fin ou um público Personalizado para regras pontuais. É possível selecionar múltiplos públicos do Fin, mas não combinar regras Personalizadas com um público do Fin. Quaisquer regras de público existentes que você configurou se tornarão um público Personalizado para preservar a funcionalidade.
Pré-visualização do Fin
Use a pré-visualização do Fin para ver exatamente como o Fin responderá usando este conector antes de ativá-lo.
Fase 4: Segurança
A etapa final antes de entrar no ar. Esta aba gerencia o controle de acesso aos dados do cliente.
Autenticação do cliente
Ative esta opção para aplicar as regras de autenticação do seu workspace antes que o conector possa acessar ou exibir informações sensíveis. As regras de autenticação são configuradas em Configurações > Workspace > Segurança > Autenticação do cliente.
Verificação de segurança
Execute um diagnóstico para avaliar a segurança da configuração da sua API. Quaisquer riscos serão apresentados com recomendações práticas — resolva-os antes de ativar o conector.
Importante: Existem algumas formas potenciais de o Fin compartilhar acidentalmente informações de outro usuário ao passar parâmetros. Veja nossas configurações recomendadas para mitigar melhor os riscos.
Depois que todas as verificações forem aprovadas, salve seu conector e ative-o.
Implementando conectores de dados
Recomendamos usar regras de público para implementar conectores de dados em fases para sua base de clientes. Isso permite validar o desempenho dos conectores de dados e fazer ajustes quando necessário.
Se você estiver enfrentando problemas em que seu conector de dados não está acionando para um usuário, certifique-se de ter removido quaisquer regras de público específicas da sua empresa que possam ter sido adicionadas na fase de testes.
Solução de problemas
Para fins de solução de problemas, todos os dados de resposta gerados por conectores de dados acionados pelo Fin são registrados por até 14 dias. Você pode acessar esses logs na aba Conector de Dados > Logs. É possível visualizar os dados de resposta com base no tipo de dados que o Fin tem acesso.
Resposta completa – Resposta completa e não modificada
Resposta redigida e formatada – Após transformação
Sem dados de resposta
Perguntas frequentes
Posso usar conectores de dados para enviar atributos ao transferir uma conversa do Fin para uma plataforma de terceiros (não Zendesk/Salesforce)?
Posso usar conectores de dados para enviar atributos ao transferir uma conversa do Fin para uma plataforma de terceiros (não Zendesk/Salesforce)?
Se você está tentando enviar uma requisição POST (por exemplo, com uma estrutura como a abaixo), use suas opções de transferência do workflow do Fin em vez disso:
{
"body": "the conversation with Fin",
"from": "users_email_address",
"to": "our_ticketing_email_address"
}
As opções de transferência do workflow incluem transferência com JavaScript e transferência para URL, com a capacidade de incluir o contexto da conversa por meio de resumos gerados por AI.
1. Transferência com JavaScript
Isso permite definir uma função handoff_with_javascript no seu app Messenger que pode:
Coletar o resumo da conversa (via “AI Add Summary Note”)
Acessar o e-mail do usuário (usando atributos)
Enviar um fetch() ou XMLHttpRequest para seu endpoint externo com a estrutura desejada
Saiba mais aqui 👉 Transferência com JavaScript
2. Transferência para URL
Esta opção apenas redireciona o usuário para uma página específica, não envia um POST nem carrega dados da conversa. Portanto, não é adequada para seu caso se você estiver tentando enviar JSON via POST.
Configuração recomendada
Use o JavaScript hand-off, e inclua 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'
})
});
}