Data connectors oferecem uma maneira poderosa de fornecer respostas personalizadas conectando-se aos dados em seus sistemas de terceiros. Em vez de os clientes esperarem que colegas procurem manualmente a informação ou serem direcionados a encontrá-la sozinhos, Fin pode acessar instantaneamente os dados relevantes e criar uma resposta personalizada.
Para garantir que esses data connectors funcionem corretamente e sejam usados nos cenários certos, aqui estão algumas melhores práticas a considerar…
Escreva prompts eficazes para data connectors
Uma das etapas mais importantes é escrever um prompt eficaz na seção Fin do seu data connector.
Você deve escrever de 3 a 5 frases para descrever quando o Fin AI Agent deve acionar este data connector. Seja o mais específico possível e certifique-se de incluir uma ou mais das seguintes opções:
Exemplos dos tipos de consultas dos clientes que seriam respondidas por este data connector.
Frases-chave que os clientes podem usar.
Cenários comuns em que acionar este data connector seria apropriado.
Você também pode conferir os modelos recomendados de IA como exemplo.
Seja descritivo
Explique claramente quando este data connector deve ser usado e os tipos de detalhes que ele deve fornecer.
Boa prática | Use este data connector para obter detalhes sobre os pedidos do cliente e ajudar a solucionar quaisquer problemas relacionados a pedidos. Este data connector fornecerá todos os detalhes do pedido para o cliente, como status do pedido, itens comprados, endereço de entrega, informações de rastreamento ou outros detalhes relevantes do pedido. |
Prática ruim | Use este data connector para obter informações sobre o pedido deles. |
Evite usar pronomes
Substitua pronomes como “nós”, “nos” e “deles” pelo substantivo próprio ao qual você está se referindo, como o nome da sua empresa.
Boa prática | Use este data connector para consultar o consumo de eletricidade de um cliente com Examply. |
Prática ruim | Use este data connector para consultar o consumo de eletricidade deles conosco. |
Seja específico
Use cenários comuns em que acionar este data connector seria apropriado.
Boa prática | Use este data connector para consultar incidentes não resolvidos, como quando os clientes querem saber quando um incidente começou, o status atual do problema, quais produtos ou serviços são afetados por um incidente ou se o desempenho do sistema voltou ao normal. |
Prática ruim | Use este data connector para consultar incidentes não resolvidos. |
Inclua frases dos clientes
Observe como os clientes formularam suas consultas em conversas anteriores e inclua as palavras-chave e frases que eles usam.
Boa prática | Procure por essas frases-chave como “failed order”, “issue with orders”, “orders not appearing in the system”, “difficulty with order”. |
Prática ruim | Não incluir frases-chave dos clientes. |
Escolha o endpoint API correto
Para fornecer aos clientes os dados corretos, é importante escolher o endpoint API correto, seja de um aplicativo de terceiros ou de um sistema externo pertencente à sua empresa.
Se você não souber por onde começar, pode querer encontrar um engenheiro para ajudar a descobrir qual API retornará os dados necessários.
Por exemplo, se você tiver um sistema interno de reservas que armazena os detalhes da reserva de um cliente, você vai querer usar uma API desse sistema que possa acessar os detalhes da reserva diretamente.
Você também vai querer usar uma API que possa encontrar os detalhes de um cliente usando um identificador único como parâmetro, como um ID ou um endereço de e-mail.
Se você decidir usar o nome ou o endereço de e-mail de um cliente como parâmetro de solicitação, e ele tiver várias reservas, provavelmente precisará especificar a solicitação com mais detalhes usando a data da reserva. Em vez de solicitar vários dados, o ideal seria pedir apenas um — o Booking ID.
Dessa forma, você pode coletar o Booking ID como entrada de dados, o que fará com que Fin solicite essa informação ao cliente na conversa. Então o ID pode ser inserido no endpoint passando o mouse sobre o menu no final da caixa de entrada da URL.
Dica: Data connectors agora suportam respostas API em JSON e XML. Se seu sistema externo fornecer apenas XML, você ainda pode conectá-lo diretamente — Intercom converterá o XML para JSON automaticamente, para que você possa usar os dados no Fin, Workflows e no Inbox sem etapas extras.
Você também vai querer garantir que está usando os cabeçalhos HTTP corretos para a solicitação. Se eles forem usados em muitos data connectors, você pode adicioná-los como um token de autenticação armazenado, que os salvará com segurança no seu workspace.
Usando nosso mesmo exemplo de reserva, digamos que um cliente queira remarcar sua viagem para outro dia. Se houver um data connector disponível para verificar tarifas e disponibilidade de reservas, Fin o escolherá automaticamente dentro da mesma conversa.
Ao escolher endpoints API para usar em data connectors, você pode querer pensar em casos onde os dados que seus clientes precisam estariam em vários endpoints.
Para garantir que o cliente possa ver as tarifas e a disponibilidade, você pode criar outro data connector para um endpoint que contenha essa informação.
Crie conexões seguras e protegidas
Verificação de identidade
Para a chamada mais segura, recomendamos usar ‘Email’ ou ‘User ID’ no People Object para corresponder ao usuário no seu sistema.
Intercom atualmente só permite que você verifique os valores de email ou ID do usuário provenientes do Messenger. Recomendamos fortemente que você autentique users no Messenger com JSON web tokens (JWTs).
Verificação de email com Código de Uso Único (OTP)
Use verificação de email para data connectors com OTP para fornecer uma etapa adicional de verificação antes que um data connector seja usado, exigindo que os clientes verifiquem sua identidade por meio de um código único e sensível ao tempo enviado por email.
Proteção contra vazamentos de dados
Geralmente, existem duas formas de os dados serem comprometidos:
Um user atualiza maliciosamente um de seus próprios atributos - Por exemplo, definindo "user_shopify_id=123", onde 123 é o ID Shopify da vítima. Então esses dados são enviados ou puxados do Shopify para o ID 123, e ficam associados ao user malicioso no Intercom.
Um user manipula dados em um terceiro, e um data connector puxa dados comprometidos para o Intercom - Por exemplo, um user se cadastra em um terceiro usando o número de telefone de uma vítima. Então um data connector consulta o terceiro e sincroniza esse número de telefone para um atributo de pessoas no Intercom. Agora o user substituiu seu número de telefone pelo da vítima.
Para evitar que isso aconteça, sempre teste seu data connector primeiro antes de colocá-lo no ar para garantir que está configurado corretamente.
Principais pontos a observar:
Certifique-se de que seu data connector está retornando dados relevantes para o user correspondente.
Certifique-se de que seus dados estão sendo armazenados corretamente nos atributos mapeados do Intercom.
Use transformação de dados para restringir dados
Payloads não estruturados ou excessivamente grandes de APIs podem fazer com que respostas baseadas em AI (como Fin ou outros agentes AI) alucinem, interpretem mal ou simplesmente falhem em fornecer respostas claras. Usando blocos de código em data connectors, você pode pré-processar, filtrar ou ajustar programaticamente as respostas da API antes que sejam enviadas para Fin ou mapeadas para objetos do Intercom sem precisar de mudanças no backend ou integrações de terceiros.
Dicas:
Sempre use
returnpara seu resultado principal.Imprima apenas para depuração (por exemplo,
print('Processando pedido', order['id'])).Mantenha simples: Evite transformar tudo de uma vez — uma transformação clara por bloco de código é o ideal.
Valide o formato da saída: Certifique-se de que a saída é o que Fin (ou sua etapa de mapeamento) espera.
Sem importações além dos módulos aprovados: Módulos padrão do Python (
math,decimal,re,datetime,datetime.timezone,json,random,time). Adicionaremos mais módulos conforme necessário.
Exemplos práticos
Aqui estão 4 padrões comuns, cada um com um exemplo realista usando os requisitos mais recentes (incluindo return).
1. Reduzindo payloads grandes para Fin
APIs frequentemente retornam dados demais. Digamos que sua resposta inclua 1.000 produtos, mas você quer apenas os primeiros 5 para Fin evitar alucinações.
api_response = inputs['data']
# Reduce payload to just the first 5 products
result = api_response[:5]
return result
2. Tratando datas em respostas de API
Às vezes, LLMs (como Fin) interpretam mal strings de data, especialmente com fusos horários. Use Python para converter todas as strings de data para um formato ISO uniforme com UTC explícito.
import datetime
def to_iso_utc(date_str):
try: # Adjust this format as needed!
dt = datetime.datetime.strptime(date_str, "%Y-%m-%d %H:%M:%S")
dt = dt.replace(tzinfo=datetime.timezone.utc)
return dt.isoformat()
except Exception as e:
print(f"Error parsing {date_str}: {e}")
return date_str
api_response = inputs['data']
for item in api_response:
if 'created_at' in item:
item['created_at'] = to_iso_utc(item['created_at'])
return api_response
3. Filtrando resultados de API para um valor específico de campo
Suponha que você queira retornar apenas carros onde make é 'toyota' (veja suas capturas de tela!)
api_response = inputs['data']
filtered = [car for car in api_response if car.get('make', '').lower() == 'toyota']
return filtered
4. Achatar itens de linha aninhados para pedidos recentes
Se sua resposta de API for profundamente aninhada (pedidos, com itens de linha dentro de cada um), achate-a para Fin:
orders = inputs['data']['orders']
result = []
for order in orders:
for item in order['line_items']:
result.append({
"order_id": order['id'],
"item_name": item['name']
})
return result
Retorne links profundos clicáveis do seu Data Connector
Se seu Data Connector retornar uma URL que você quer que Fin apresente como um link clicável, você tem duas opções.
Opção 1: Formate o link na sua resposta de API
Inclua a sintaxe de link markdown diretamente no texto que sua API retorna. Fin irá renderizá-lo como um link clicável na conversa.
Use este formato para exibir texto de link personalizado:
[View Dashboard](beyond://account/dashboard)
Ou este formato se você quiser que a URL em si seja visível e clicável:
[beyond://account/dashboard](beyond://account/dashboard)
Opção 2: Use a orientação do Fin para formatar o link
Se sua API retornar uma URL simples em um atributo de dados, você pode instruir o Fin a formatá-la como um link clicável usando orientação. Referencie o nome do Data Connector e o atributo contendo o link profundo, e diga ao Fin para apresentá-lo usando a sintaxe de link markdown.
Utilize regras de audiência
Se você está começando com data connectors, pode querer experimentar quais configurações de data connectors levam a mais resoluções. Uma forma de fazer isso é ativar primeiro o data connector para um subconjunto de users para ver como ele performa. Você pode fazer isso usando regras de audiência.
Regras de audiência podem ser selecionadas a partir de uma lista de atributos de empresa ou contato que já estão disponíveis no seu workspace. Se você tem Shopify, Statuspage ou Stripe instalados, também pode acessar atributos específicos do app.
Se um atributo que você quer usar não existir, você pode configurar atributos de dados personalizados para identificar users que atendam aos critérios que você quer direcionar para o data connector.
Depois de criar a regra, você pode ver uma prévia dos users que podem receber uma resposta alimentada pelo data connector.
Use verificações de segurança para proteger seus connectors
Antes de colocar um connector no ar, execute as verificações de segurança integradas na aba Segurança. Elas mostram riscos potenciais com recomendações acionáveis para que você possa tomar decisões informadas antes de ir ao vivo.
As verificações podem incluir:
Atributos de dados do cliente não são verificados — se atributos de dados do cliente podem ser atualizados sem verificação do user, adicione verificação do user.
Dados coletados pelo Fin para este connector precisam de revisão — se Fin coleta informações dos clientes antes de chamar sua API, valide a entrada no seu backend primeiro.
Workflows usando este data connector precisam de revisão — se certos workflows apresentam risco de expor dados sensíveis do cliente, revise-os para validar no seu backend.
Um cabeçalho de requisição para este data connector precisa de revisão — se detalhes do cliente são enviados com cada requisição, assegure que sua API verifica o valor.
Cada verificação inclui etapas claras para resolver o problema. Resolva todos os riscos sinalizados antes de ativar o conector.
Analise conversas para impulsionar otimizações
Cada conector de dados possui um painel de saúde dedicado onde você pode avaliar o impacto e identificar oportunidades para melhorar o desempenho. Navegue até Settings > Integrations > data connectors e clique em qualquer conector para abrir seu painel. A partir daí, você pode revisar taxas de sucesso, latência de execução, detalhamento do status HTTP e categorização do tipo de falha — tudo filtrável por janela de tempo (1h, 6h, 24h, 7d ou 14d). Para detalhes de execução individual, selecione a aba Logs. Além do painel, dê uma olhada nas conversas onde um data connector foi usado para ver o que funcionou bem ou o que não deu certo.
Se você estiver usando atributos de dados personalizados para restringir o público, pode então utilizar o atributo para filtrar através do inbox e verificar como ele performou, e se algum ajuste precisa ser feito.
Algumas perguntas para considerar incluem:
O data connector foi acionado no caso correto?
Um colega precisou se envolver, e se sim, em que estágio?
O data connector forneceu a informação correta ao cliente com base no que foi perguntado, mas a pergunta do cliente era realmente sobre outra coisa?
A resposta poderia ter sido apoiada com informações adicionais do seu Knowledge Hub?
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.