Contatos

Contatos é o cadastro das pessoas identificadas nos canais externos da organização. Uma pessoa pode começar com um único telefone, e-mail, @ ou identificador de canal e, depois, reunir várias identidades na mesma ficha.

Abra Contatos no menu lateral do painel. A rota exige a capacidade contacts.view; editar nome ou anotações exige contacts.write; unificar e desfazer uma unificação exige contacts.merge. O pacote atual de Atendente inclui as três capacidades, mas uma função personalizada pode receber somente parte delas.

Conversas internas do Hub entre membros não criam, por si só, um contato externo. O cadastro aparece quando o SquadOS consegue associar a interação a um registro de external_contacts.

Encontrar um contato

A lista mostra 50 registros por página, do mais recente para o mais antigo. Cada linha pode trazer:

• Contato — a identidade principal, como telefone, e-mail, @ ou ID do canal;
• Canal — WhatsApp, Telegram, Instagram, E-mail, API ou Site;
• Nome — o nome recebido do canal ou salvo pela equipe;
• Listas — inscrições vinculadas a um endereço de e-mail;
• Tags — as tags do contato;
• Origem — canal, inclusão manual ou importação, conforme o tipo de contato;
• Status — eventual supressão do endereço de e-mail; sem supressão, a célula fica vazia.

Use a busca para procurar por nome ou identidade. Ela também considera identidades relacionadas, como outro telefone ou @, e avisa quando esse recorte passa do limite de 300 correspondências; nesse caso, refine o termo. Os filtros disponíveis são canal e tag. Administradores também veem o filtro por lista.

Clique na linha ou no botão Ver ficha para abrir o cadastro. Se uma consulta falhar e a tela mostrar Nenhum contato ainda ou Nenhum contato corresponde aos filtros, recarregue antes de concluir que a base está vazia: hoje a lista não diferencia erro de carregamento de resultado vazio.

Adicionar, importar e exportar

Os controles Adicionar contato, Importar CSV, Exportar CSV e o filtro por lista aparecem somente para administradores. Eles pertencem ao fluxo de campanhas de e-mail, não à criação manual de uma identidade de qualquer canal.

• Adicionar contato aceita um e-mail, nome opcional, uma lista e a origem do consentimento. O contato é criado ou resolvido pelo e-mail e inscrito na lista escolhida.
• Importar CSV abre o assistente de importação de contatos de e-mail para uma lista.
• Exportar CSV aplica a busca e os filtros atuais a todas as páginas, e não somente aos 50 registros visíveis. A exportação atual tem teto silencioso de 20.000 contatos; para bases maiores, divida o recorte com filtros antes de usar o arquivo como fonte completa.

Ler e editar a ficha

A ficha reúne:

• Nome — editável por quem tem contacts.write;
• Identidades — todos os endereços e identificadores reunidos nessa pessoa;
• Registros unificados — cadastros absorvidos que continuam preservados como ponteiros;
• Listas de e-mail — endereço, lista, situação e indicação de que a inscrição pertence a um registro absorvido;
• Tags do contato — atributos duradouros da pessoa, compartilhados entre conversas;
• Anotações — pares de chave e valor do cadastro, como plano: premium ou cidade: Campinas;
• Conversas — até as 20 conversas mais recentes da pessoa, ordenadas pela última mensagem.

Ao expandir uma conversa na ficha, o SquadOS mostra até as 30 mensagens legíveis mais recentes, somente de usuário e assistente. Use Abrir conversa para acessar o atendimento completo.

Anotações não são notas livres

As Anotações da ficha são memória estruturada do contato. A equipe pode criar, alterar ou apagar uma chave, e a ferramenta nativa manage_notes permite que o agente leia e atualize o mesmo objeto quando a conversa está ligada à pessoa. Por isso, grave fatos curtos e estáveis e não use esse campo para conteúdo sensível ou para um relato longo.

Isso é diferente de uma Nota interna: a nota interna é uma mensagem humana de texto livre na linha do tempo de uma conversa e não entra no contexto do agente.

Unificar cadastros duplicados

Use Unificar contatos quando duas fichas representam a mesma pessoa. Procure o outro cadastro, escolha qual fica e confira o resumo antes de confirmar.

A unificação:

1. transfere identidades e conversas e acrescenta as tags que ainda não existem no cadastro sobrevivente;
2. copia para o sobrevivente somente as chaves de anotação que ele ainda não possui;
3. aproveita o nome do cadastro absorvido somente se o sobrevivente ainda não tiver nome;
4. mantém o cadastro absorvido como ponteiro, com um diário exato da operação;
5. mantém inscrições, supressões e histórico de envio ligados ao endereço de e-mail original — a ficha sobrevivente apenas reúne essa visualização.

Nada é apagado. O comando Desfazer aparece na confirmação por 15 segundos e também junto dos registros unificados na ficha. Ao desfazer, edições feitas depois da unificação são preservadas sempre que já não correspondem ao valor copiado pela operação.

O SquadOS não cria cadeias de unificação. Se um cadastro já foi absorvido, já absorveu outro ou aponta para outro sobrevivente, desfaça a operação anterior ou escolha diretamente a ficha sobrevivente.

Contato, conversa e tags

Item	Escopo	Exemplo
Contato	A pessoa identificada em um ou mais canais externos	Maria, com WhatsApp e e-mail
Conversa	Um atendimento específico, em um canal	Dúvida enviada no WhatsApp
Tag do contato	Característica duradoura da pessoa	cliente, lead quente
Tag da conversa	Contexto daquele atendimento	reembolso, negociação
Anotação	Fato estruturado disponível para equipe e IA	plano: premium
Nota interna	Mensagem humana privada naquela conversa	“Confirmar comprovante amanhã”

Se o rótulo continuar verdadeiro em outras conversas, use uma tag do contato. Se descreve somente o atendimento atual, use uma tag da conversa.