Use este artigo para configurar, configurar e gerenciar conectores de Dados — o recurso que permite ao Fin recuperar dados ao vivo dos seus sistemas externos e fornecer respostas personalizadas aos clientes sem esperar por um colega. Você aprenderá como criar um conector a partir de um modelo ou do zero, configurar seu endpoint API, moldar a resposta, controlar quem pode acioná-lo, lidar com segurança, implementá-lo com segurança e monitorar seu desempenho.
Nota: Você precisa da permissão "Can access developer hub" para criar, editar ou ativar um conector de Dados.
Como funcionam os conectores de Dados?
Cada conector de Dados consiste em uma chamada API (application programming interface) que você configura. O Fin determina automaticamente quando usá-lo para fornecer respostas específicas ao cliente. Você pode conectar qualquer sistema com uma API, incluindo:
Ferramentas internas personalizadas de backend
Plataformas de terceiros (Shopify, Salesforce, Stripe, Jira, etc.)
Dica: Conectores de Dados podem ser usados pelo Fin em Procedures e outras automações, incluindo Workflows e macros da Inbox. Saiba mais sobre como projetar e usar suas APIs com conectores de Dados.
Como criar um conector de Dados
Navegue até Configurações > Integrações > Conectores de Dados e clique em Novo.
Se você tiver um dos apps suportados instalados, verá um modelo para este app listado em Criar conector de Dados. Modelos estão disponíveis atualmente para Shopify, Stripe e Statuspage — veja De um modelo de terceiros abaixo para detalhes.
De um modelo de terceiros
Modelos de conectores de Dados estão disponíveis quando os seguintes apps estão instalados no seu workspace:
Se o app ainda não estiver instalado, vá até a App Store para instalar. Uma vez instalado, os modelos de conectores de Dados para cada app aparecerão como um conector de Dados pronto para ser ativado.
Quando você clicar em um modelo, verá algumas informações sobre o que o conector de Dados faz e poderá testá-lo na pré-visualização do Messenger. Se estiver satisfeito com o comportamento do conector de Dados, basta selecionar Ativar para AI Agent.
A pré-visualização do Messenger aqui usa dados de exemplo. Ao ativar o conector de Dados, o Fin usará seus dados reais de clientes.
Se quiser configurar o conector de Dados, você pode clicar em Personalizar, que o levará ao construtor de conectores de Dados para configuração avançada.
Se você não tiver um dos nossos apps suportados instalados, os apps aparecerão aqui para que você os instale no seu workspace. Após a instalação, os modelos relevantes de conectores de Dados aparecerão na seção acima.
Saiba mais sobre os modelos de conectores de Dados disponíveis e casos de uso para o Fin.
De uma recomendação de IA
Para ver os conectores de Dados recomendados por IA, vá para Configurações > Integrações > Conectores de Dados e clique em Novo conector de Dados.
Você verá seus conectores de Dados recomendados por IA exclusivos em "Criar conector de Dados a partir de modelo". Eles são gerados com base no histórico de conversas para ajudar a identificar potenciais conectores de Dados, ver a porcentagem do volume de conversas que podem resolver e pré-visualizá-los no Messenger antes de configurar qualquer coisa.
Para que as recomendações de IA apareçam, o Fin precisa estar ativo no seu workspace e você deve ter volume suficiente de conversas.
Quando você clicar em um conector de Dados recomendado por IA, encontrará informações sobre o que o conector de Dados faz e poderá pré-visualizá-lo no Messenger (usando dados de exemplo). Conectores de Dados recomendados por IA são apenas sugestões baseadas no volume de conversas, mas exigem que uma API seja conectada manualmente para funcionar.
Para ativar o conector de Dados, clique em Configurar para configurar os detalhes da API.
Agora tudo o que você precisa fazer é conectar o conector de Dados à sua API adicionando a URL HTTPS.
Para personalizar ainda mais este conector de Dados, veja a seção De um conector de Dados personalizado.
Criar um conector de Dados personalizado do zero
Para configurar seu próprio conector de Dados personalizado para o Fin, navegue até Configurações > Integrações > Conectores de Dados e clique em + Novo > + Criar do zero.
Fase 1: API
A aba API define como a Intercom se comunica com seu sistema externo.
Dê ao seu conector um nome curto e descritivo — por exemplo, "Obter saldo de conta não pago." Isso ajuda o Fin a entender quando usá-lo. Adicione uma descrição interna para referência da sua equipe.
Veja as melhores práticas para escrever descrições de conectores de Dados.
Nota: Emojis não são suportados em nomes de conectores de Dados e causarão erro se incluídos.
Entradas de dados
Entradas de dados permitem especificar quais informações o Fin precisa coletar antes que o conector seja executado — por exemplo, o número da conta do cliente, se ainda não estiver armazenado na Intercom.
Clique em + Entrada de dados e escolha um formato:
Texto
Número
Número decimal
Verdadeiro/Falso
Dê a cada entrada um nome e uma descrição para que o Fin saiba como coletá-la. Você também pode definir um valor de fallback para casos em que a API retorna uma resposta nula ou ausente.
Para cada entrada, escolha de onde vêm os dados:
Let Fin collect — Fin coleta automaticamente da conversa
People attribute — extraído de um atributo Intercom existente
Custom value — um valor fixo que você define
Endpoint da API
Adicione a URL HTTPS (web segura) para seu endpoint da API e selecione o método de requisição HTTP: GET (recuperar dados), POST (enviar dados), PUT (substituir dados), DELETE (remover dados) ou PATCH (atualizar dados parcialmente).
Use o Attribute Inserter para passar valores dinâmicos — como o ID do usuário do cliente — diretamente no caminho da URL ou no corpo da requisição.
Autenticação e cabeçalhos
Selecione um token de autenticação e adicione quaisquer cabeçalhos personalizados de chave-valor que sua API exigir (por exemplo, Content-Type: application/json).
Nota: Você pode anexar múltiplos tokens a um único conector. Cada token deve usar uma chave de cabeçalho diferente — todos os tokens anexados são enviados com cada requisição.
Quando a URL do endpoint e os detalhes de autenticação estiverem completos, clique em Test connection para validar sua configuração. Um teste bem-sucedido retorna uma confirmação verde e a resposta bruta da API. Um teste falho exibe o código de erro HTTP e uma descrição — resolva quaisquer erros antes de prosseguir para a Fase 2: Data.
Fase 2: Data — moldando a resposta da API
A aba Data controla como a resposta da API é filtrada e transformada antes que o Fin a use para responder aos clientes. Você pode restringir quais campos o Fin vê e remodelar os dados usando um editor visual ou código Python.
Restrict and shape
Por padrão, o Fin tem acesso à resposta completa da API. Para limitar o que o Fin pode ler, mude para Manually restrict access e selecione apenas os campos que deseja expor.
Escolha como você gostaria de transformar a resposta:
Table view — filtre campos, renomeie-os e defina transformações a nível de campo usando um editor visual
Python — escreva código Python para limpar, remodelar ou reformatar a resposta antes que ela chegue ao Fin
Mapeamento de objeto
O mapeamento de objeto permite mapear campos da resposta da API diretamente para atributos de contato ou empresa do Intercom, sincronizando automaticamente dados do seu sistema externo para seu workspace Intercom.
Clique em Test code para validar sua lógica de transformação em Python, e em Test connection para confirmar a chamada completa da API e o formato da resposta. Resolva quaisquer erros antes de prosseguir para a Fase 3: Fin.
Fase 3: Fin — como o Fin aciona o conector
A aba Fin controla se o Fin aciona o conector de dados automaticamente ou apenas quando explicitamente chamado de um workflow, procedure ou macro. Escolha o modo de acionamento que corresponde à sensibilidade ou atividade de escrita do conector.
Como o Fin deve usar este conector?
Habilitado (acionamento direto)
O Fin aciona o conector automaticamente com base na pergunta do cliente — sem necessidade de workflow. Ideal para conectores somente leitura como "Check order status" e consultas repetitivas de alto volume.
Você pode controlar para quem este conector de Data está disponível com reusable Fin audiences, ou criando uma audiência customizada especificamente para este conector. Por exemplo, você pode torná-lo disponível para clientes na sua audiência "Enterprise plan", ou restringi-lo a uma audiência customizada como usuários logados com e-mail verificado que perguntam sobre o saldo da conta.
Nota: Agora você pode usar Fin audiences com conectores de Data. Fin audiences são grupos reutilizáveis de clientes que você cria uma vez e aplica em múltiplos conectores — facilitando manter a consistência.
Você pode escolher Everyone, uma Fin audience reutilizável, ou uma audiência Custom para regras pontuais.
Você pode selecionar múltiplas Fin audiences, mas não pode combinar regras Custom com uma Fin audience.
Quaisquer regras de audiência existentes para conectores de Data que você configurou se tornarão uma audiência Custom para preservar a funcionalidade.
Dica: Se quiser testar o conector de Data antes de habilitá-lo para clientes, use as regras de audiência para habilitar o conector de Data apenas para você ou seus colegas inicialmente.
Desabilitado (acionamento manual)
O conector não será executado automaticamente. Você precisará adicioná-lo manualmente a um Workflow, Procedure ou Macro. Ideal para conectores sensíveis ou com atividade de escrita — como "Delete account" — onde você quer supervisão humana ou de workflow antes de qualquer execução.
Use a pré-visualização do Fin para ver exatamente como o Fin responderá usando este conector antes de colocá-lo no ar.
Fase 4: Segurança — controle de acesso e ativação
A aba Segurança é o passo final antes de ativar. Ela controla se os clientes devem estar autenticados antes que o conector de Data possa acessar ou exibir seus dados.
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 saúde e segurança da sua configuração de API. Quaisquer riscos são identificados com recomendações acionáveis — resolva-os antes de ativar o conector.
Depois que todas as verificações de segurança forem aprovadas, clique em Salvar e depois em Ativar. O status do Data connector muda para Ativo em Configurações > Integrações > Data connectors. Fin começará a usá-lo imediatamente para conversas que correspondam ao público configurado.
Importante: Existem algumas maneiras potenciais pelas quais Fin poderia compartilhar informações de outro usuário acidentalmente ao passar parâmetros. Veja nossas configurações recomendadas para mitigar melhor os riscos.
Como implementar Data connectors com segurança
Nota: A pré-visualização do Messenger aqui usa dados de exemplo. Ao ativar o Data connector, Fin usará seus dados reais de clientes.
Data connectors exigem que AI Answers esteja habilitado na etapa do workflow para que Fin os utilize. AI Answers não pode ser habilitado em ambientes de teste, então Data connectors só podem ser totalmente testados em ambientes de produção. Use perfis de usuários de teste em produção para testes seguros.
Recomendamos usar regras de público para implementar Data connectors em fases para sua base de clientes. Isso permite validar o desempenho do Data connector e fazer ajustes/mudanças quando necessário.
Como monitorar e gerenciar Data connectors
Para encontrar Data connectors existentes, navegue até Configurações > Integrações > Data connectors. A lista de Data connectors mostra os seguintes detalhes para cada conector:
Nome e status (ativo ou rascunho)
Uso geral (total de execuções)
Uso do Fin — taxa de resolução e o público ao qual está disponível
Saúde — taxa de sucesso da API e um indicador geral de saúde
Status de segurança
Detalhes da configuração
Clique em uma linha do conector para abrir seu painel de saúde, onde você pode revisar uso, métricas de desempenho e logs de execução, ou abrir o editor de configuração para fazer alterações.
Como visualizar a atividade do Data connector na Inbox
Para ver a atividade do Data connector para uma conversa específica, abra a conversa na Inbox e selecione Mostrar eventos da conversa. O painel de eventos mostra se Fin teve acesso ao Data connector e se ele foi acionado com sucesso.
Nota:
Se houver um erro ao acionar o Data connector, selecione Logs para descobrir o motivo.
Fin pode não escolher sempre usar o Data connector apesar de fazer uma solicitação API se outro conteúdo for considerado mais relevante.
Fin não pode consultar atributos personalizados ou dados de eventos para respostas. Para permitir que Fin responda com dados de ativos em tempo real, configure Data Connectors para que Fin possa acessar fontes de dados externas via API.
Visualizações da Inbox podem ser criadas com o atributo “Fin AI Agent: Action used in reply”. Este atributo é definido se Fin chamar um Data connector e usar parte ou toda a resposta em uma resposta.
Versionamento do Data connector
Data connectors usam um sistema de versionamento rascunho/ativo para que você possa fazer edições com segurança sem interromper o conector em execução.
Cada Data connector tem uma versão ativa e uma versão rascunho. As edições são feitas no rascunho sem afetar a versão ativa em execução.
Quando você publica um rascunho, uma nova versão instantânea é criada e se torna a versão ativa. Você pode adicionar notas no momento da publicação. A versão ativa anterior é arquivada.
Cada versão registra um número de versão, quem a criou, notas de alteração (se adicionadas) e um carimbo de data/hora.
O histórico completo de alterações é rastreável e você pode reverter para qualquer versão anterior.
APIs públicas para Data connectors
Duas APIs públicas (application programming interfaces) oferecem acesso programático às configurações e resultados de execução do Data connector. Ambas usam OAuth (Open Authorization) para autenticação. Documentação completa de referência está disponível no Intercom Developer Hub.
Como usar a Configuration API
A Configuration API é um conjunto de endpoints CRUD (create, read, update, delete) para gerenciar programaticamente Data connectors. Use-a para criar novos conectores, manter conectores sincronizados com seus sistemas internos e automatizar o gerenciamento de conectores em escala. A tabela abaixo lista os endpoints disponíveis e seus propósitos.
Método | Endpoint | Propósito |
GET | /data_connectors | Retorna uma lista paginada de todos os Data connectors para o workspace, ordenada pelo mais recentemente atualizado primeiro. |
GET | /data_connectors/:id | Recupera o detalhe completo de um único Data connector por ID, incluindo configuração, entradas de dados, campos de resposta e mapeamentos de objetos. |
POST | /data_connectors | Cria um novo Data connector em estado de rascunho. Configure sua URL, cabeçalhos, entradas de dados e outras configurações, depois ative-o quando estiver pronto. |
PATCH | /data_connectors/:id | Atualiza um conector de Dados existente. Apenas os campos fornecidos são alterados. Defina o estado para live ou draft para mudar o estado do conector. |
EXCLUIR | /data_connectors/:id | Exclui um conector de Dados existente. O conector deve estar em estado draft e não pode estar em uso por nenhum workflows ou agentes de AI. |
A autenticação usa OAuth (Open Authorization). O acesso de leitura e escrita requer o escopo read_write_data_connectors. O acesso somente leitura requer o escopo read_workflow_connector_execution_result.
Como usar a Results API
A Results API oferece acesso programático aos dados de execução de cada conector de Dados. Use-a para criar painéis personalizados, alimentar sistemas de alerta ou realizar análises mais profundas do que o painel de saúde do produto oferece.
GET /data_connectors/:id/execution_results — recupera logs de execução paginados. Os resultados da última hora são retornados por padrão. Use
start_tseend_tspara personalizar o intervalo de tempo. Corpos de requisição/resposta são excluídos por padrão — useinclude_bodies=truepara incluí-los.GET /data_connectors/:id/execution_results/:result_id — recupera um único resultado de execução, sempre incluindo corpos completos de requisição/resposta para depuração profunda.
As opções de filtragem incluem status de sucesso, tipos específicos de erro e intervalos de tempo especificados como timestamps Unix (segundos desde 1 de janeiro de 1970 UTC). A paginação usa um modelo baseado em cursor, retornando até 30 resultados por página. A autenticação usa OAuth com o escopo read_workflow_connector_execution_result.
Limitações conhecidas
As seguintes limitações se aplicam aos conectores de Dados. Quando uma solução alternativa está disponível, ela é indicada abaixo.
Fin pode não usar sempre um conector de Dados mesmo que ele execute com sucesso uma requisição API — se outro conteúdo for considerado mais relevante para a pergunta do cliente, Fin usará esse conteúdo em vez disso. Sem solução alternativa; revise a nomeação e descrição do conector para melhorar a correspondência de relevância.
Fin não pode consultar atributos personalizados do Intercom ou dados de eventos diretamente para responder perguntas. Use um conector de Dados para expor esses dados via um endpoint API externo.
Conectores de Dados exigem que AI Answers esteja habilitado na etapa do workflow para que Fin os utilize. AI Answers não pode ser habilitado em workspaces de teste, então conectores de Dados só podem ser totalmente testados em ambiente de produção. Use perfis de usuários de teste em produção para testes seguros.
O webhook de execução do conector de Dados não é acionado quando o conector é disparado como parte de uma conversa de pré-visualização.
Um conector de Dados só pode ser excluído via API quando estiver em estado draft e não for referenciado por nenhum workflows ou agentes de AI.
Emojis não são suportados em nomes de conectores de Dados — incluir um causará erro ao salvar.
Solução de problemas de conectores de Dados
Como usar logs de conectores de Dados
Todos os dados de resposta dos conectores de Dados acionados pelo Fin são registrados e armazenados por até 14 dias. Para acessar os logs, navegue até Configurações > Integrações > conectores de Dados, clique no conector que deseja investigar e selecione Logs.
Como usar o webhook de execução do conector de Dados
Para sinais em tempo real sobre taxas de sucesso e falha do conector de Dados, use o webhook de execução do conector de Dados. Isso permite receber eventos de execução do Intercom e usá-los para criar painéis em tempo real, alertas e monitoramento de SLA (acordo de nível de serviço) em seus serviços externos.
Notas:
Você precisará criar um app, configurar Webhooks e se inscrever no webhook de execução do conector de Dados antes de poder receber quaisquer notificações de conector de Dados.
O webhook de execução do conector de Dados será ignorado se o conector de Dados for acionado como parte de uma conversa de pré-visualização.