Use este artigo para configurar, ajustar e gerenciar conectores de Dados — o recurso que permite ao Fin recuperar dados em tempo real dos seus sistemas externos e fornecer aos clientes respostas personalizadas sem esperar por um colega. Você aprenderá como criar um conector a partir de um modelo ou do zero, configurar seu endpoint API, formatar a resposta, controlar quem pode acioná‑lo, lidar com segurança, implementá‑lo com segurança e monitorar seu desempenho.
Observação: Você precisa da permissão "Can access developer hub" permission 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 back‑end
Plataformas de terceiros (Shopify, Salesforce, Stripe, Jira, etc.)
Dica: Conectores de Dados podem ser usados pelo Fin em Procedures e em 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é Settings > Integrations > Data connectors e clique em New.
Se você tiver um dos apps compatíveis instalados, verá um modelo para esse app listado em Create Data connector. Modelos estão disponíveis atualmente para Shopify, Stripe e Statuspage — veja From a 3rd party template abaixo para detalhes.
A partir de um modelo de terceiros
Modelos de conector de Dados estão disponíveis quando os seguintes apps estão instalados no seu workspace:
Se o app não estiver instalado, vá para a App Store para instalar. Depois de instalado, os templates de Data connector templates para cada app aparecerão como um Data connector pronto para ativar.
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, selecione Set live for 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 Customize, que o levará ao construtor de conectores de Dados para configuração avançada.
Se você não tiver um dos nossos apps compatíveis instalado, os apps aparecerão aqui para que você os instale no seu workspace. Após a instalação, os templates relevantes de Data connector aparecerão na seção acima.
Saiba mais sobre os templates de Data connector disponíveis e casos de uso para o Fin.
A partir de uma recomendação de IA
Para ver conectores de Dados recomendados pela IA, vá para Settings > Integrations > Data connectors e clique em New Data connector.
Você verá seus conectores de Dados recomendados pela IA exclusivos em "Create Data connector from template". Eles são gerados com base no histórico de conversas para ajudar a identificar potenciais conectores de Dados, ver qual porcentagem do volume de conversas eles poderiam resolver e pré‑visualizá‑los no Messenger, antes de configurar qualquer coisa.
Para que 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 pela IA, encontrará informações sobre o que o conector faz e poderá pré‑visualizá‑lo no Messenger (usando dados de exemplo). Os conectores recomendados pela 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 Set up para configurar os detalhes da API.
Agora tudo o que você precisa fazer é conectar o conector de Dados à sua API adicionando a HTTPS URL.
Para personalizar ainda mais este conector de Dados, veja a seção From a custom Data connector.
Criar um conector de Dados personalizado do zero
Para configurar seu próprio conector de Dados personalizado para o Fin, navegue até Settings > Integrations > Data connectors e clique em + New > + Create from scratch.
Fase 1: API
A aba API define como o 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.
Observação: Emojis não são suportados em nomes de conectores de Dados e gerarão um erro se incluídos.
Entradas de dados
As 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 de um cliente, caso não esteja armazenado no Intercom. Quando o Fin precisa passar uma consulta de pesquisa ou outro valor para a API com base no que um cliente pede, adicione uma entrada de dados e defina a origem como Let Fin collect — o Fin coletará o valor automaticamente a partir da conversa.
Clique em + Data input e escolha um formato:
Texto
Número
Número decimal
Verdadeiro/Falso
Dê a cada entrada um nome e uma descrição para que 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 os coleta automaticamente a partir da conversa
People attribute — extraído de um atributo existente do Intercom
Custom value — um valor fixo que você define
Depois de selecionar uma fonte, use o botão de alternância Obrigatório para definir se a entrada é obrigatória ou opcional. Isso deve ser configurado manualmente para cada entrada (o estado não é definido automaticamente).
O rótulo do alternador muda com base na fonte selecionada:
Let Fin collect: o alternador mostra Fin must collect this parameter. Quando ativado, Fin deve obter esse valor do cliente antes que o conector possa ser executado.
People attribute ou Custom value: o alternador mostra This parameter must have a value. Quando ativado, o conector não será executado se o valor estiver ausente.
O status de obrigatório ou opcional de cada entrada é exibido na lista de entradas de dados.
API endpoint
Adicione a URL HTTPS (web segura) do seu endpoint de 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 parcialmente dados).
Use o Attribute Inserter para passar valores dinâmicos — como o user ID do cliente — diretamente no caminho da URL ou no corpo da requisição. Sempre selecione atributos usando o seletor — nunca digite tokens manualmente.
Nota: Se seu conector chamar a Intercom Contacts API e precisar identificar um contato, selecione Contact ID (user.id) no seletor — não User ID (user_id). A Contacts API espera o ID de contato gerado pelo Intercom (user.id). Usar user_id (o ID definido externamente) fará com que a busca falhe.
Importante: O editor converte qualquer texto {{...}} em um cápsula, então um token digitado manualmente fica idêntico a um atributo válido. Se o identificador não corresponder a um atributo real — como user.id ou user_id — ele resolve para um valor vazio em tempo de execução. Isso torna sua URL de requisição malformada e causa erros como 404 sem indicação visível no editor. Sempre use o seletor Attribute Inserter para inserir atributos.
Authenticação e cabeçalhos
Selecione um token de autenticação e adicione quaisquer cabeçalhos personalizados chave-valor que sua API exija (por exemplo, Content-Type: application/json).
Nota: Se você estiver enviando um corpo de requisição JSON (POST, PUT ou PATCH), deve adicionar explicitamente um cabeçalho Content-Type: application/json. Sem ele, a API receptora não analisará o corpo da requisição e rejeitará todos os campos como inválidos — mesmo se o JSON estiver corretamente formatado.
Nota: Você pode anexar vários tokens a um único conector. Cada token deve usar uma chave de cabeçalho diferente — todos os tokens anexados são enviados com todas as requisições.
Depois que 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 que falha exibe o código de erro HTTP e uma descrição — corrija quaisquer erros antes de prosseguir para a Fase 2: Dados.
Fase 2: Dados — formato da resposta da API
A guia Dados controla como a resposta da API é filtrada e transformada antes que Fin a use para responder aos clientes. Você pode restringir quais campos Fin vê e remodelar os dados usando um editor visual ou código Python.
Restringir e modelar
Por padrão, Fin tem acesso à resposta completa da API. Para limitar o que Fin pode ler, altere para Manually restrict access e selecione apenas os campos que deseja expor.
Nota: Ao usar Manually restrict access, campos cujos nomes contêm caracteres especiais — como parênteses (), sinais de mais + ou barras / — podem ser silenciosamente excluídos dos dados que Fin recebe, devido a um bug de correspondência de caminho. Para contornar isso, renomeie os campos afetados para remover caracteres especiais antes de restringir o acesso. Como alternativa, use acesso completo aos dados se a resposta não contiver dados sensíveis.
Escolha como você gostaria de transformar a resposta:
Exibição em Tabela — filtrar campos, renomeá‑los e definir 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 de 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 Test connection para confirmar a chamada completa da API e o formato da resposta. Corrija quaisquer erros antes de prosseguir para a Fase 3: Fin.
Nota: Ao selecionar mapeamento de objeto, você verá apenas objetos mapeados em Workflows e Procedures; sem mapeamento, todas as opções selecionadas em a tabela Restrict and shape the data serão listadas. Para Python, apenas valores retornados serão vistos
Fase 3: Fin — como o Fin aciona o conector
A guia Fin controla se Fin aciona o conector automaticamente ou apenas quando chamado explicitamente de um workflow, procedure, ou macro. Escolha o modo de acionamento que corresponda ao quão sensível ou ativo em escrita o conector é.
Dica: Antes que Fin possa usar um conector, certifique‑se de que cada um dos seguintes esteja em vigor:
Data inputs: Para qualquer valor que o Fin precise passar para a API — como uma consulta de pesquisa, nome de produto ou ID do pedido — adicione uma entrada de dados com a fonte definida como Let Fin collect. Isso diz ao Fin para coletar os termos relevantes da conversa e passá‑los automaticamente para a API.
Test connection: Execute um teste bem‑sucedido usando dados reais (Fase 1). A resposta do teste molda o que o Fin verá e retornará aos clientes — dados de exemplo não refletem resultados reais.
Fin trigger: Nesta guia Fin, defina How should Fin use this connector? para Enabled (direct trigger).
Connector description: Escreva uma descrição clara e focada do que o conector faz e quando usá‑lo. É assim que o Fin decide quando chamá‑lo.
Set live: Complete as verificações de segurança na Fase 4, depois clique em Save e Set live.
How should Fin use this connector?
Enabled (direct trigger)
Fin aciona o conector automaticamente com base na pergunta do cliente — sem workflow necessário. Melhor para conectores somente leitura como "Check order status" e consultas repetitivas de alto volume.
Você pode controlar quem tem acesso a este conector de Dados com reusable Fin audiences, ou criando um público personalizado especificamente para este conector. Por exemplo, você pode disponibilizá‑lo para clientes no seu público "Enterprise plan", ou restringi‑lo a um público personalizado como usuários logados com e‑mail verificado que perguntam sobre o saldo da conta.
Nota: Agora você pode usar Fin audiences com Data connectors. Fin audiences são grupos de clientes reutilizáveis que você cria uma vez e aplica em vários conectores — facilitando manter a consistência.
Você pode escolher Everyone, um Fin audience reutilizável ou um público Custom para regras pontuais.
Você pode selecionar múltiplos Fin audiences, mas não pode combinar Custom rules com um Fin audience.
Quaisquer regras de público existentes do conector de Dados que você configurou se tornarão um público Custom para preservar a funcionalidade.
Dica: Se quiser testar o conector de Dados antes de ativá‑lo para clientes, use as regras de público para habilitar o conector apenas para você ou seus colegas inicialmente.
Disabled (manual trigger)
O conector não será executado automaticamente. Você precisará adicioná‑lo manualmente a um Workflow, Procedure ou Macro. Melhor para conectores sensíveis ou que escrevem dados — como "Delete account" — quando você quer supervisão humana ou de workflow antes de qualquer execução.
Use a visualização do Fin para ver exatamente como o Fin responderá usando este conector antes de colocá‑lo em produção.
Nota: Alterações na configuração do gatilho do Fin são salvas em modo rascunho e não entrarão em vigor até você publicá‑las. A versão ativa do conector continua usando as configurações existentes até você clicar em Set live. Após fazer alterações, confirme sempre se a configuração está refletida na versão ativa — e não apenas no rascunho.
Fase 4: Segurança — controle de acesso e publicação
A aba Security é o passo final antes da publicação. Ela controla se os clientes devem ser autenticados antes que o conector de Dados possa acessar ou exibir seus dados.
Autenticação do cliente
Ative isso 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 Settings > Workspace > Security > Customer authentication.
Verificação de segurança
Execute um diagnóstico para avaliar a integridade e segurança da sua configuração de API. Quaisquer riscos são apresentados com recomendações acionáveis — resolva‑os antes de publicar o conector.
Uma vez que todas as verificações de segurança passarem, clique em Save e depois em Set live. O status do conector de Dados muda para Live em Settings > Integrations > Data connectors. Fin começará a usá‑lo imediatamente em conversas que correspondam ao público configurado.
Importante: Existem algumas formas pelas quais o Fin pode acidentalmente compartilhar informações de outro usuário ao passar parâmetros. Veja nossas configurações recomendadas para mitigar melhor os riscos.
Como implantar os Data connectors com segurança
Nota: A pré‑visualização do Messenger aqui usa dados de exemplo. Ao colocar o conector de Dados em produção, o Fin usará seus dados reais de clientes.
Data connectors exigem que o AI Answers esteja ativado na etapa do workflow para que o Fin os utilize. O AI Answers não pode ser ativado em workspaces de teste, portanto os Data connectors só podem ser totalmente testados em ambientes de produção. Use perfis de usuário de teste em produção para testes seguros.
Recomendamos usar audience rules para lançar os Data connectors em fases para sua base de clientes. Isso permite validar o desempenho do conector de Dados e fazer ajustes quando necessário.
Como monitorar e gerenciar os Data connectors
Para encontrar os Data connectors existentes, navegue até Settings > Integrations > Data connectors. A lista de Data connectors mostra os seguintes detalhes para cada conector:
Nome e status (live ou draft)
Uso geral (total de execuções)
Fin usage — taxa de resolução e o público ao qual está disponível
Integridade — taxa de sucesso da API e um indicador geral de integridade
Status de segurança
Detalhes de configuração
Clique na linha de um conector para abrir seu painel de integridade, 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 ver a atividade do Data connector na Inbox
Para ver a atividade do Data connector em uma conversa específica, abra a conversa na Inbox e selecione Show conversation events. O painel de eventos mostra se o 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.
O Fin pode nem sempre optar por usar o Data connector apesar de fazer uma solicitação API se outro conteúdo for considerado mais relevante.
O Fin não pode consultar atributos personalizados ou dados de eventos para respostas. Para permitir que o Fin responda com dados de ativos em tempo real, configure os Data Connectors para que o Fin possa acessar fontes externas de dados via API.
Inbox views podem ser criadas com o atributo “Fin AI Agent: Action used in reply”. Esse atributo é definido se o Fin chamar um Data connector e usar parte ou toda a resposta em uma resposta.
Versionamento dos Data connectors
Os 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.
Ao publicar um rascunho, uma nova snapshot de versão é 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.
Nota: Isso se aplica a todas as configurações do conector, incluindo o alternador Fin trigger. Se você alterar How should Fin use this connector? e não publicar, a versão ativa continuará acionando exatamente como antes. Um banner no editor indica que você tem alterações não salvas — sempre clique em Set live para tornar suas alterações ativas.
Public APIs for Data connectors
Duas Public APIs (application programming interfaces) dão acesso programático às configurações e aos resultados de execução dos Data connectors. 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 os Data connectors. Use-a para criar novos connectors, manter os connectors sincronizados com seus sistemas internos e automatizar o gerenciamento de connectors 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 do espaço de trabalho, ordenada pelos mais recentemente atualizados primeiro. |
GET | /data_connectors/:id | Recupera os detalhes completos 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, e então coloque-o em live quando estiver pronto. |
PATCH | /data_connectors/:id | Atualiza um Data connector existente. Apenas os campos fornecidos são alterados. Defina o estado como live ou draft para alterar o estado do connector. |
DELETE | /data_connectors/:id | Exclui um Data connector existente. O connector deve estar em estado de rascunho e não deve estar sendo usado por quaisquer workflows ou AI agents. |
A autenticação usa OAuth (Open Authorization). Acesso de leitura e escrita requer o escopo read_write_data_connectors. Acesso somente leitura requer o escopo read_workflow_connector_execution_result.
Como usar a Results API
A Results API dá acesso programático aos dados de execução de cada Data connector. Use-a para construir painéis personalizados, alimentar sistemas de alerta ou realizar análises mais profundas do que o painel de integridade do produto fornece.
GET /data_connectors/:id/execution_results — recupera logs de execução paginados. Resultados da última hora são retornados por padrão. Use
start_tseend_tspara customizar 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 aprofundada.
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). 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 aplicam-se aos Data connectors. Quando houver uma solução alternativa disponível, ela é indicada abaixo.
Fin may not always use a Data connector even if it successfully runs an API request — if other content is judged more relevant to the customer's question, Fin will use that instead. No workaround; review connector naming and description to improve relevance matching.
Fin cannot query Intercom custom attributes or event data directly to answer questions. Use a Data connector to expose this data via an external API endpoint instead.
Data connectors require AI Answers to be enabled in the workflow step for Fin to use them. AI Answers cannot be enabled in test workspaces, so Data connectors can only be fully tested in a production environment. Use test user profiles in production for safe testing.
The Data connector execution webhook is not fired when the connector is triggered as part of a preview conversation.
A Data connector can only be deleted via the API when it is in draft state and not referenced by any workflows or AI agents.
Emojis are not supported in Data connector names — including one will cause an error when saving.
Nota: Não há um campo de tempo limite configurável pelo cliente. O tempo limite padrão é 15 segundos. Para Data connectors usados dentro de Fin Procedures em workspaces elegíveis, o tempo limite é estendido para 30 segundos.
Solução de problemas dos Data connectors
Como usar os logs dos Data connectors
Todos os dados de resposta dos Data connectors acionados por Fin são registrados e armazenados por até 14 dias. Se sua política de segurança ou conformidade exigir uma janela mais curta, contate nossa equipe de Support para solicitar retenção de 7 dias em vez disso.
Para acessar os logs, navegue até Settings > Integrations > Data connectors, clique no connector que você deseja investigar e selecione Logs.
Como usar o Data connector execution webhook
Para sinais em tempo real sobre taxas de sucesso e falha dos Data connectors, use o Data connector execution webhook. Isso permite que você receba eventos de execução do Intercom e os use para construir painéis em tempo real, alertas e monitoramento de SLA (service level agreement) em seus serviços externos.
Observações:
Você precisará create an app, set up Webhooks e se inscrever no Data connector execution webhook antes de poder receber quaisquer notificações de Data connector.
O Data connector execution webhook será ignorado se o Data connector for acionado como parte de uma preview conversation.