Use este artigo para configurar, ajustar 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, formatar 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 (interface de programação de aplicações) 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 esse 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 ativação.
Ao clicar em um modelo, você 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 por padrão. Se você visualizar como um usuário específico e ativar "Access and update real user data when triggered," o conector de dados chamará seu sistema real e retornará os dados reais desse usuário — então use uma conta de teste, nunca um cliente real, ao testar dessa forma. Quando o conector de dados estiver ativo, o Fin usará dados reais do cliente para conversas ao vivo.
Se quiser configurar o conector de dados, 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, eles aparecerão aqui para que você possa instalá-los 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 pela IA, vá para Configurações > Integrações > Conectores de dados e clique em Novo conector de dados.
Você verá seus conectores de dados recomendados pela 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.
Ao clicar em um conector de dados recomendado pela IA, você encontrará informações sobre o que o conector faz e poderá pré-visualizá-lo no Messenger (usando dados de exemplo). Conectores de dados 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 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 ele não estiver armazenado no Intercom. Quando o Fin precisar passar uma consulta de pesquisa ou outro valor para a API com base no que o cliente pedir, adicione uma entrada de dados e defina a origem como Deixe o Fin coletar — o Fin coletará o valor automaticamente da conversa.
Clique em + Entrada de dados e escolha um formato:
Texto
Número
Número decimal
Verdadeiro/Falso
Dê a cada entrada um nome e descrição para que o Fin saiba como coletá-la. Você também pode definir um valor padrão 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 existente do Intercom
Custom value — um valor fixo que você define
Após selecionar uma fonte, use o botão Required 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 botão muda com base na fonte selecionada:
Let Fin collect: o botão lê Fin must collect this parameter. Quando ativado, o Fin deve coletar esse valor do cliente antes que o conector possa ser executado.
People attribute ou Custom value: o botão lê This parameter must have a value. Quando ativado, o conector não será executado se o valor estiver ausente.
O status obrigatório ou opcional de cada entrada é exibido na lista de entradas de dados.
API endpoint
Adicione a URL HTTPS (web segura) para seu API endpoint 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 user ID de um 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á a busca falhar.
Importante: O editor converte qualquer texto {{...}} em um pill, então um token digitado manualmente parece 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.
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: 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 que o JSON esteja corretamente formatado.
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 em 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: Dados.
Fase 2: Dados — moldando a resposta da API
A aba Dados 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.
Restringir e moldar
Por padrão, o Fin tem acesso à resposta completa da API. Para limitar o que o Fin pode ler, altere para Restringir acesso manualmente e selecione apenas os campos que deseja expor.
Nota: Ao usar Restringir acesso manualmente, campos cujos nomes contêm caracteres especiais — como parênteses (), sinais de mais + ou barras / — podem ser silenciosamente excluídos dos dados que o 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. Alternativamente, use acesso total aos dados se a resposta não contiver dados sensíveis.
Escolha como você gostaria de transformar a resposta:
Visualização em tabela — 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 objetos
O mapeamento de objetos 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 Python e 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.
Nota: Ao selecionar mapeamento de objetos, você verá apenas objetos mapeados em Workflows e Procedures; enquanto sem mapeamento, todas as opções selecionadas em a tabela Restringir e moldar os dados serão listadas. Para Python, apenas valores retornados serão vistos
Fase 3: Fin — como o Fin dispara o conector
A aba Fin controla se o Fin dispara o conector automaticamente ou somente quando chamado explicitamente de um workflow, procedure ou macro. Escolha o modo de disparo que corresponde ao quão sensível ou ativo em escrita o conector é.
Dica: Antes que o Fin possa usar um conector, certifique-se de que cada um dos seguintes esteja em vigor:
Entradas de dados: Para qualquer valor que o Fin precise passar para a API — como uma consulta de busca, nome do produto ou ID do pedido — adicione uma entrada de dados com a fonte definida para Let Fin collect. Isso informa 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 aba Fin, defina How should Fin use this connector? para Enabled (direct trigger).
Descrição do conector: Escreva uma descrição clara e focada do que o conector faz e quando usá-lo. É assim que o Fin decide quando chamá-lo.
Colocar em produção: Complete as verificações de segurança na Fase 4, depois clique em Save e Set live.
Como o Fin deve usar este conector?
Enabled (direct trigger)
Fin dispara 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 Data connector está disponível com públicos Fin reutilizáveis, ou criando um público personalizado especificamente para este connector. Por exemplo, você pode disponibilizá-lo para clientes no seu público "Plano Enterprise" 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 públicos Fin com Data connectors. Públicos Fin são grupos de clientes reutilizáveis que você cria uma vez e aplica em vários connectors — facilitando manter a consistência.
Você pode escolher Todos, um público Fin reutilizável ou um público Personalizado para regras pontuais.
Você pode selecionar múltiplos públicos Fin, mas não pode combinar regras Personalizadas com um público Fin.
Quaisquer regras de público existentes para Data connector que você configurou se tornarão um público Personalizado para preservar a funcionalidade.
Dica: Se quiser testar o Data connector antes de habilitá-lo para clientes, use as regras de público para habilitar o Data connector apenas para você ou seus colegas inicialmente.
Desabilitado (gatilho manual)
O connector não será executado automaticamente. Você precisará adicioná-lo manualmente a um Workflow, Procedure ou Macro. Ideal para connectors sensíveis ou ativos em escrita — como "Delete account" — onde você quer supervisão humana ou de workflow antes de qualquer execução.
Use a pré-visualização Fin para ver exatamente como o Fin responderá usando este connector antes de ativá-lo.
Nota: Alterações na configuração do gatilho Fin são salvas em modo rascunho e não terão efeito até que você as publique. A versão ativa do connector continua usando as configurações existentes até você clicar em Ativar. Após fazer alterações, sempre confirme se a configuração está refletida na versão ativa — não apenas no rascunho.
Fase 4: Segurança — controle de acesso e ativação
A aba Segurança é o passo final antes da ativação. Ela controla se os clientes devem estar autenticados antes que o Data connector 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 connector 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 apresentados com recomendações acionáveis — resolva-os antes de ativar o connector.
Quando 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 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.
Como implementar Data connectors com segurança
Nota: A pré-visualização do Messenger aqui usa dados de exemplo por padrão. Se você pré-visualizar como um usuário específico e ativar "Acessar e atualizar dados reais do usuário quando acionado", o Data connector chamará seu sistema real e retornará os dados reais desse usuário — então use uma conta de usuário de teste, nunca um cliente real, ao testar dessa forma. Quando o Data connector estiver ativo, o Fin usará dados reais dos clientes para conversas ao vivo.
Data connectors exigem que AI Answers esteja habilitado na etapa do workflow para que o Fin possa usá-los. AI Answers não pode ser habilitado em workspaces de teste, então 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 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 connector:
Nome e status (ativo ou rascunho)
Uso geral (total de execuções)
Uso 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
Opção de duplicar — crie uma cópia do connector para usar como ponto de partida para um novo
Clique em uma linha do connector 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 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 não escolher sempre 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 Data Connectors para que o Fin possa acessar fontes externas de dados via API.
Visualizações da Inbox podem ser criadas com o atributo “Fin AI Agent: Action used in reply”. Este atributo é definido se o Fin chamar um Data connector e usar parte ou toda a resposta em uma resposta.
Versionamento de Data connector
Data connectors usam um sistema de versionamento rascunho/ativo para que você possa fazer edições com segurança sem interromper o connector 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.
Nota: Isso se aplica a todas as configurações do conector, incluindo o toggle Fin trigger. Se você alterar Como o Fin deve usar este conector? 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 Definir como ativo para tornar suas alterações efetivas.
APIs públicas para conectores de Dados
Duas APIs públicas (application programming interfaces) oferecem acesso programático às configurações e resultados de execução dos conectores de Dados. Ambas usam OAuth (Open Authorization) para autenticação. A documentação completa 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 conectores de Dados. Use-a para criar novos conectores, manter os conectores sincronizados com seus sistemas internos e automatizar a gestão 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 conectores de Dados para o workspace, ordenada pelo mais recentemente atualizado primeiro. |
GET | /data_connectors/:id | Recupera o detalhe completo de um único conector de Dados por ID, incluindo configuração, entradas de dados, campos de resposta e mapeamentos de objetos. |
POST | /data_connectors | Cria um novo conector de Dados em estado de rascunho. Configure sua URL, cabeçalhos, entradas de dados e outras configurações, depois defina como ativo quando estiver pronto. |
PATCH | /data_connectors/:id | Atualiza um conector de Dados existente. Apenas os campos fornecidos são alterados. Defina o estado como ativo ou rascunho para alterar o estado do conector. |
DELETE | /data_connectors/:id | Exclui um conector de Dados existente. O conector deve estar em estado de rascunho e não pode estar em uso por nenhum workflows ou agentes de IA. |
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 dashboards personalizados, alimentar sistemas de alerta ou realizar análises mais profundas do que o dashboard 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. Os 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 filtro 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.
O Fin pode não usar sempre um conector de Dados mesmo que ele execute uma requisição API com sucesso — se outro conteúdo for considerado mais relevante para a pergunta do cliente, o Fin usará esse conteúdo. Sem solução alternativa; revise o nome e a descrição do conector para melhorar a correspondência de relevância.
O 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.
Os conectores de Dados exigem que AI Answers esteja habilitado na etapa do workflow para que o Fin os utilize. AI Answers não pode ser habilitado em workspaces de teste, então os 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 de rascunho e não for referenciado por nenhum workflows ou agentes de IA.
Emojis não são suportados em nomes de conectores de Dados — incluir um causará erro ao salvar.
O endereço de e-mail do responsável não é exposto como placeholder nas requisições do conector de Dados — apenas o ID do responsável (
admin_assignee_id) está disponível. Para obter o e-mail do responsável, passeadmin_assignee_ide consulte o registro correspondente via Admins API (GET /admins/{admin_id}), que retorna o campo de e-mail. Alternativamente, armazene o e-mail em um atributo personalizado da conversa no momento da atribuição e faça referência a esse atributo.
Nota: Não há campo de timeout configurável pelo cliente. Cada chamada do conector de Dados espera até 3 segundos para conectar e até 30 segundos por uma resposta. O mesmo timeout se aplica se o conector rodar em Fin Procedures, Workflows ou na Inbox.
Solução de problemas dos conectores de Dados
Como usar os logs do conector de Dados
Todos os dados de resposta dos conectores de Dados acionados pelo Fin são registrados e armazenados por até 14 dias. Se sua política de segurança ou conformidade exigir um período menor, entre em contato com nossa equipe de Suporte para solicitar retenção de 7 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 dashboards em tempo real, alertas e monitoramento de SLA (service level agreement) 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 do 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.