Fontes de dados do contato

Com uma fonte de dados do contato, o atendente consulta um sistema da sua empresa sem sair da conversa. Na aba Contato, ele seleciona Consultar e o SquadOS pergunta ao seu endpoint o que existe sobre aquela pessoa: plano, pedidos, cobranças, estágio no funil, histórico de eventos. A resposta aparece como um cartão organizado em campos, listas e uma linha do tempo.

A consulta só acontece quando o atendente clica. Nada é enviado à sua fonte quando uma conversa chega ou quando a aba é aberta.

Permissões

Ação	Capacidade
Criar, editar, testar, gerar novo segredo e excluir fontes	`contact_data_sources.write`
Ver os cartões na conversa e selecionar Consultar	`contacts.view`

contact_data_sources.write começa no papel Administrador e é considerada sensível, porque define para onde os dados do contato são enviados. contacts.view já faz parte do pacote de Atendente.

Cadastrar uma fonte

Abra Configurações e, em Desenvolvedores, escolha Fontes de dados.
Selecione Nova fonte.
Preencha Nome, com até 60 caracteres. É o nome que o atendente vê na conversa, por exemplo “CRM” ou “Pedidos”.
Preencha URL. Ela precisa começar com https://.
Selecione Salvar.

Depois de salvar, o SquadOS mostra o segredo da fonte. Copie com Copiar segredo e guarde no seu endpoint: ele não aparece de novo. É com ele que o endpoint confere que a consulta veio do SquadOS (veja Verificar a assinatura).

Cada organização pode ter até 5 fontes. Quando o limite é atingido, o botão Nova fonte deixa de aparecer.

Testar, editar e excluir

Cada fonte da lista tem quatro ações:

Testar envia uma consulta real, assinada, com um contato fictício (Maria Exemplo, +5511999990000, [email protected]) e mostra o resultado: Resposta válida., Resposta válida (contato de exemplo não encontrado)., demora acima de 8 segundos, recusa da assinatura ou o caminho exato do campo fora do formato. O teste funciona mesmo com a fonte desativada.
Editar muda nome e URL e liga ou desliga a fonte em Ativa. Uma fonte desativada continua na lista, marcada como Desativada, e some das conversas.
Gerar novo segredo substitui o segredo atual na hora. As consultas falham até você colar o novo segredo no seu endpoint.
Excluir remove a fonte, e os atendentes deixam de ver o cartão dela nas conversas.

Consultar na conversa

Na tela da conversa, abra a aba Contato. Cada fonte ativa aparece como uma faixa recolhida com o nome da fonte e um resumo do estado: Não consultado, Consultando…, Encontrado (ou o título que a sua fonte devolveu), Não encontrado ou Erro. Se a organização não tem nenhuma fonte ativa, a área não aparece.

Abra a faixa e selecione Consultar. Depois do resultado, o mesmo botão vira Atualizar; depois de um erro, vira Tentar de novo.

O resultado fica só na tela de quem consultou. Ele não é salvo na conversa, não aparece para outros atendentes e não entra no contexto do agente de IA. Ao reabrir a conversa, consulte de novo.

Linha do tempo e Carregar mais

Quando a sua fonte devolve uma linha do tempo, os eventos aparecem agrupados por dia, com ícone por categoria (compra, cobrança, vendas, conversa, mensagem, ciclo de vida), título, até duas linhas de subtítulo e horário. Um evento com link abre a página correspondente em nova aba.

Se a sua fonte indicar que há mais eventos, o botão Carregar mais busca a página seguinte e a acrescenta ao fim da lista. Atualizar traz o cartão de novo e descarta as páginas extras já carregadas.

Mensagens de erro

Mensagem	O que verificar
”[nome da fonte] demorou para responder.”	O endpoint precisa responder em até 8 segundos.
”Não foi possível falar com [nome da fonte].”	URL, DNS, certificado, status HTTP diferente de 2xx ou redirecionamento. O SquadOS não segue redirecionamentos nem chama endereços de rede interna.
”[nome da fonte] recusou a consulta. Confira o segredo em Configurações › Fontes de dados.”	O endpoint respondeu `401` ou `403`. Confira se ele usa o segredo atual.
”[nome da fonte] respondeu num formato que o SquadOS não entende.”	Use Testar na configuração: ele mostra o caminho do campo que não segue o formato.

Formato da consulta

O SquadOS faz um POST na URL cadastrada com Content-Type: application/json e estes cabeçalhos:

Cabeçalho	Conteúdo
`X-Squados-Event`	`contact.lookup` na consulta; `contact.timeline` em Carregar mais
`X-Squados-Delivery`	ID único da chamada
`X-Squados-Timestamp`	Momento da chamada, em segundos Unix
`X-Squados-Signature`	HMAC no formato `sha256=<hexadecimal>`

Corpo de contact.lookup:

{
  "version": 1,
  "event": "contact.lookup",
  "organization_id": "…",
  "locale": "pt",
  "contact": {
    "id": "…",
    "display_name": "Maria Exemplo",
    "phone": "+5511999990000",
    "email": "[email protected]",
    "identities": [{ "type": "whatsapp", "value": "+5511999990000" }]
  }
}

locale é o idioma da tela do atendente; use-o para devolver rótulos no idioma certo. phone, email e display_name podem vir null. identities traz todas as identidades conhecidas do contato, como WhatsApp, e-mail e @ do Instagram.

contact.timeline usa o mesmo corpo, com "event": "contact.timeline" e o campo cursor que a sua fonte devolveu.

Verificar a assinatura

A assinatura segue o mesmo esquema dos webhooks de eventos: HMAC-SHA256(segredo, "<timestamp>.<corpo cru>"). Se você já verifica os webhooks do SquadOS, o mesmo código serve. Confira a assinatura sobre o corpo cru, antes de fazer JSON.parse.

Formato da resposta

Responda 200 com JSON. Contato não encontrado:

{ "version": 1, "found": false }

Contato encontrado:

{
  "version": 1,
  "found": true,
  "title": "Maria Exemplo",
  "subtitle": "Cliente desde 2024",
  "link": { "label": "Abrir no CRM", "url": "https://crm.exemplo.com/contatos/123" },
  "sections": [
    {
      "kind": "fields",
      "title": "Assinatura",
      "items": [
        { "label": "Plano", "type": "badge", "value": "Pro", "tone": "success" },
        { "label": "Mensalidade", "type": "currency", "value": 199.9, "currency": "BRL" },
        { "label": "Renovação", "type": "date", "value": "2026-10-15" }
      ]
    },
    {
      "kind": "list",
      "title": "Pedidos abertos",
      "items": [
        { "title": "Pedido #4821", "subtitle": "2 itens", "meta": "Em separação", "url": "https://loja.exemplo.com/pedidos/4821" }
      ]
    },
    {
      "kind": "timeline",
      "title": "Histórico",
      "items": [
        { "at": "2026-09-20T14:32:00Z", "category": "purchase", "tone": "success", "title": "Compra aprovada", "subtitle": "Plano Pro anual" }
      ],
      "next_cursor": "pagina-2"
    }
  ]
}

Tipos de seção:

fields: pares rótulo e valor. type aceita text, number, date, currency (com currency em código ISO de três letras, como BRL), link (URL https) e badge (com tone: neutral, success, warning ou danger). Sem type, o campo é tratado como text.
list: itens com title obrigatório e subtitle, meta e url opcionais.
timeline: eventos com at (data ISO 8601) e title obrigatórios, e category (purchase, billing, sales, conversation, messaging, lifecycle ou other), tone, subtitle e url opcionais. Só a primeira seção timeline do cartão é exibida.

title, subtitle e link do cartão são opcionais. Todo texto é exibido como texto puro; HTML não é interpretado.

Paginar a linha do tempo

Para oferecer Carregar mais, inclua next_cursor na seção timeline. É uma string opaca de até 500 caracteres que só a sua fonte entende. Quando o atendente pedir mais, o SquadOS envia contact.timeline com esse cursor, e a sua fonte responde com a próxima página:

{
  "version": 1,
  "items": [
    { "at": "2026-08-02T09:10:00Z", "category": "billing", "title": "Fatura paga" }
  ],
  "next_cursor": null
}

next_cursor nulo ou ausente encerra a paginação e o botão some.

Limites e tolerância

Tempo de resposta: 8 segundos.
Tamanho da resposta: 64 KB.
Até 20 seções por cartão e 50 itens por seção ou página.
Textos com mais de 500 caracteres são cortados.
Links só são exibidos quando usam https.

Estrutura inválida, como version diferente de 1, found ausente ou items que não é lista, recusa a resposta inteira e mostra o erro de formato. Um item isolado inválido, como uma data que não pode ser lida ou um campo currency sem código, é descartado sozinho, e o restante do cartão aparece normalmente. Seções com kind desconhecido são ignoradas.