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 (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 este app listado em Criar conector de dados. Modelos estão disponíveis atualmente para Shopify, Stripe e Statuspage — veja A partir de um modelo de terceiros abaixo para detalhes.
A partir 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.
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 do cliente.
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.
A partir de uma recomendação de AI
Para ver os conectores de dados recomendados por AI, vá para Configurações > Integrações > Conectores de dados e clique em Novo conector de dados.
Você verá seus conectores de dados recomendados por AI exclusivos em "Criar conector de dados a partir de modelo". Eles são gerados com base no seu 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 AI 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 AI, encontrará informações sobre o que o conector faz e poderá pré-visualizá-lo no Messenger (usando dados de exemplo). Conectores de dados recomendados por AI 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 A partir 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 não estiver armazenado no Intercom. Quando o Fin precisa passar uma consulta de pesquisa ou outro valor para a API com base no que o cliente pergunta, adicione uma entrada de dados e defina a origem para 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 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 Intercom existente
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, 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 ID do usuário 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 chama a Intercom Contacts API e precisa 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 pílula, 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 do 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 formatado corretamente.
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 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 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 moldar
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. 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 objeto
O mapeamento de objeto permite mapear campos da resposta da API diretamente para atributos de contato ou empresa do Intercom, sincronizando automaticamente os 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 o mapeamento de objeto, você verá apenas objetos mapeados em Workflows e Procedures; enquanto 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 Fin aciona o conector
A aba Fin controla se 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 a quão sensível ou ativo para 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 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 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 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).
Connector description: Escreva uma descrição clara e focada do que o conector faz e quando usá-lo. É assim que Fin decide quando chamá-lo.
Set live: Complete as verificações de segurança na Fase 4, depois clique em Save e Set live.
Como Fin deve usar este conector?
Enabled (direct trigger)
Fin aciona o conector automaticamente com base na pergunta do cliente — nenhum workflow é necessário. Melhor para conectores somente leitura como "Check order status" e consultas repetitivas de alto volume.
Você pode controlar para quem este conector de dados está disponível com públicos Fin reutilizáveis, ou criando um público personalizado especificamente para este conector. 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 conectores de dados. Públicos Fin 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 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 de conector de dados existentes que você configurou se tornarão um público Personalizado para preservar a funcionalidade.
Dica: Se quiser testar o conector de dados antes de habilitá-lo para clientes, use as regras de público para habilitar o conector de dados apenas para você ou seus colegas inicialmente.
Desabilitado (gatilho 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 ação de escrita — como "Excluir conta" — 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 conector antes de ativá-lo ao vivo.
Nota: As 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 ao vivo do conector continua usando as configurações existentes até você clicar em Ativar ao vivo. Após fazer alterações, sempre confirme se a configuração está refletida na versão ao vivo — não apenas no rascunho.
Fase 4: Segurança — controle de acesso e ativação ao vivo
A aba Segurança é a etapa final antes de ativar ao vivo. Ela controla se os clientes devem estar autenticados antes que o conector de dados 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 apresentados com recomendações acionáveis — resolva-os antes de ativar o conector ao vivo.
Quando todas as verificações de segurança forem aprovadas, clique em Salvar e depois em Ativar ao vivo. O status do conector de dados muda para Ao vivo em Configurações > Integrações > Conectores de dados. O 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 conectores de dados com segurança
Nota: A pré-visualização do Messenger aqui usa dados de exemplo. Ao ativar o conector de dados ao vivo, o Fin usará seus dados reais de clientes.
Conectores de dados requerem 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 conectores de dados 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 conectores de dados em fases para sua base de clientes. Isso permite validar o desempenho do conector de dados e fazer ajustes/mudanças quando necessário.
Como monitorar e gerenciar conectores de dados
Para encontrar conectores de dados existentes, navegue até Configurações > Integrações > Conectores de dados. A lista de conectores de dados mostra os seguintes detalhes para cada conector:
Nome e status (ao vivo 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
Opção de duplicar — crie uma cópia do conector para usar como ponto de partida para um novo
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 conector de dados no Inbox
Para ver a atividade do conector de dados para uma conversa específica, abra a conversa no Inbox e selecione Mostrar eventos da conversa. O painel de eventos mostra se o Fin teve acesso ao conector de dados e se ele foi acionado com sucesso.
Nota:
Se houver um erro ao acionar o conector de dados, selecione Logs para descobrir o motivo.
O Fin pode não escolher sempre usar o conector de dados 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 Conectores de dados para que o Fin possa acessar fontes de dados externas via API.
Visualizações do Inbox podem ser criadas com o atributo “Fin AI Agent: Action used in reply”. Este atributo é definido se o Fin chamar um conector de dados e usar parte ou toda a resposta em uma resposta.
Versionamento de conectores de dados
Conectores de dados usam um sistema de versionamento rascunho/ao vivo para que você possa fazer edições com segurança sem interromper o conector em execução.
Cada conector de dados tem uma versão ao vivo e uma versão rascunho. As edições são feitas no rascunho sem afetar a versão ao vivo em execução.
Quando você publica um rascunho, uma nova versão instantânea é criada e se torna a versão ao vivo. Você pode adicionar notas no momento da publicação. A versão ao vivo 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 para live ou draft 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 construir 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. 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 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.
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, 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.
Fin não pode consultar diretamente atributos personalizados do Intercom ou dados de eventos 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 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.
Nota: Não há campo de timeout configurável pelo cliente. O timeout padrão é de 15 segundos. Para conectores de Dados usados dentro de Fin Procedures em workspaces elegíveis, o timeout é estendido para 30 segundos.
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. 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 construir painéis 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 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.