Data connectors permitem que o Fin acesse dados ao vivo dos seus sistemas externos durante a conversa, como detalhes de pedidos, status da conta e informações de assinatura, sem precisar que um humano pesquise. Este artigo é seu índice para o processo completo de configuração. Siga as seções na ordem se estiver começando do zero, ou vá direto a um tópico específico se precisar de uma revisão.
Antes de começar
Leia primeiro a visão geral conceitual. Ela explica o que são data connectors e custom objects, como eles se relacionam e quando você precisa de um ou de outro:
Data connectors and Custom Objects explained — cobre os conceitos principais, a relação entre connectors e custom objects, e a diferença entre Fin connectors e Workflow connectors.
Passo 1: Projete APIs e configure seu conector
Comece projetando suas APIs, depois crie o Data connector e defina como ele chama sua API.
Designing and using your APIs with Data connectors — explica como estruturar seus endpoints de API para funcionar bem com Fin data connectors, antes de iniciar a configuração do conector.
How to set up Data connectors — cobre detalhadamente as quatro fases da configuração, incluindo a API (entradas de dados e endpoints da API), dados (formatação da resposta da API), Fin (como o Fin aciona o conector) e segurança (controle de acesso e ativação).
Use Data connector templates — comece rapidamente a partir de um template de data connector usando apps de terceiros instalados no seu workspace.
Passo 2: Autenticação e segurança
Antes de ativar, configure como seu conector autentica com sua API externa e se os clientes devem ser verificados antes que os dados sejam expostos a eles.
Setting up Data connectors authentication — cobre tipos de tokens de autenticação (texto, OAuth, JWT), a página de Credenciais e como habilitar a autenticação do cliente em conectores individuais.
Secure Data connectors with One-Time Passcode — aplica verificação OTP antes que o Fin exponha dados do cliente.
Best practices when using Data connectors with Fin — cobre as verificações de segurança integradas na aba Security, riscos comuns e recomendações antes de ativar o conector.
Importante: Se você não aplicar autenticação do cliente, agentes maliciosos podem se passar por seus users e acessar seus dados. No mínimo, revise as verificações integradas da aba Security antes de ativar qualquer conector.
Passo 3: Esquemas de resposta, objetos e arrays
A forma da resposta da sua API determina como o Fin lê e usa os dados retornados. Esta seção explica como lidar com diferentes estruturas de resposta.
JSON objects and arrays supported for Data connectors response mapping — cobre objetos planos, objetos aninhados, arrays e respostas XML (convertidas automaticamente para JSON). Leia se sua API retorna dados complexos ou aninhados.
Passo 4: Custom objects e propriedades
Custom objects permitem armazenar dados estruturados com múltiplas propriedades no Intercom, como pedidos, assinaturas ou compromissos, que não são capturados pelos atributos padrão de contato ou conversa. Normalmente, você os preenche mapeando os dados da resposta de um conector para o objeto.
Setting up a Custom Object — cobre criação de tipos de objetos, definição de propriedades, preenchimento do objeto via data connector e configuração de referências para objetos People e Conversation.
Passo 5: Mapeamento de objetos
O mapeamento de objetos indica ao conector onde armazenar os dados da resposta da API no Intercom. Você pode mapear para objetos padrão (atributos de contato e conversa) ou custom objects.
Setting up references with Custom Objects — explica como mapear campos da resposta da API diretamente para atributos de contato ou empresa no Intercom, sincronizando automaticamente dados do seu sistema externo para seu workspace Intercom.
How to set up Data connectors for Workflows and Inbox — contém detalhes adicionais sobre mapeamento para custom objects, incluindo o requisito external_id.
Passo 6: Testes
Cada conector tem uma ferramenta de teste integrada que permite validar a chamada da API e a forma da resposta antes de ativar. Use o botão Test connection na aba Data do conector para confirmar a requisição e resposta completas. Para testes de ponta a ponta de como o Fin usa o conector numa conversa, use regras de audiência para direcionar o conector ao seu próprio email de user.
How to roll out Data connectors safely — explica como monitorar e gerenciar seus data connectors, e visualizar a atividade dos data connectors na inbox.
Passo 7: Usando data connectors em procedimentos Fin
O Fin pode chamar um Data connector diretamente para responder a uma pergunta do cliente, mas os connectors também são um bloco fundamental para procedimentos mais complexos e em múltiplas etapas — por exemplo, consultar um pedido, depois oferecer para atualizá-lo, e então confirmar a alteração.
How to use Data connectors in Fin Procedures — ensina como o Fin pode ler e agir sobre dados de API externos e executar ações automatizadas durante conversas com clientes.
Solução de problemas e FAQs
Se seu conector não estiver funcionando como esperado, comece pelo artigo de solução de problemas. Para dúvidas sobre segurança e privacidade, o artigo de FAQs cobre as preocupações mais comuns.
Understanding Data connector errors — ensina como ler e interpretar logs de data connectors, identificar causas de erros e tomar as medidas corretas para resolvê-los.
Troubleshooting Fin Procedures and Data connectors — cobre os padrões mais comuns de falhas, incluindo conectores que passam no teste mas falham em procedimentos ao vivo, erros de entrada e problemas de análise de resposta.
Data connectors FAQs — cobre privacidade de dados, segurança, riscos de personificação e outras perguntas frequentes.
Referência rápida: todos os artigos de Data connector
Use esta tabela para ir diretamente a qualquer artigo na documentação de Data connectors.
Artigo | O que cobre |
Conceitos principais e quando usar cada um | |
Estruturando seus endpoints de API para funcionar bem com o Fin | |
Guia principal de configuração do conector, cobre detalhadamente as quatro fases da configuração | |
Templates para início rápido usando apps de terceiros | |
Tokens de autenticação, credenciais, autenticação do cliente | |
Verificações de segurança, melhores práticas antes de ativar | |
Esquemas de resposta, objetos aninhados, arrays, XML | |
Tipos de custom objects, propriedades, preenchimento via conector | |
Mapeamento da resposta da API para atributos do Intercom | |
Uso do Fin e indicadores de saúde | |
Casos de uso e exemplos de Data connectors | |
Permite que o Fin leia e aja sobre dados de API externos | |
Caso de uso Workflow/Inbox, detalhes do mapeamento de objetos | |
Logs e erros de data connectors | |
Falhas comuns e correções | |
Privacidade, segurança e perguntas comuns |