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, ou excluir contatos, 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, telefone, e-mail ou identificador de canal. O seletor de recorte tem dois grupos: Por cadastro (Com telefone, Com e-mail) filtra pelo que a pessoa tem registrado, e Por canal filtra por onde ela falou. São eixos diferentes — quem chegou pelo WhatsApp e informou o e-mail depois aparece nos dois. O filtro de tag vale sempre; 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, que carrega uma planilha para o cadastro em quatro etapas. A lista de destino é opcional: sem ela, os contatos entram somente no cadastro. Arquivos grandes sobem em blocos, com um contador de linhas processadas durante a espera.
• 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.

Iniciar conversa abre um atendimento com essa pessoa por uma caixa de WhatsApp, já atribuído a você e com a IA desabilitada. Veja Gerenciando Conversas.

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.

Excluir contatos

Use Excluir contato quando a organização precisa eliminar os dados de uma pessoa, e Excluir todos os contatos quando precisa eliminar os de todo o cadastro. É diferente de tirar o contato de uma lista, que mantém a ficha e o histórico. Os dois caminhos seguem o mesmo processo, pessoa por pessoa.

Não dá para desfazer

Depois que o pedido é aceito, o que foi removido não volta. A tela não tem lixeira nem opção de cancelar. Decida antes de confirmar se a organização precisa conservar algum dado, por obrigação legal ou outro motivo: essa decisão é dela, como controladora dos dados, e o SquadOS não tem uma opção para manter o conteúdo de um contato específico.

Liberação gradual

A função está sendo liberada aos poucos. Se você tem a permissão e os botões abaixo não aparecem, ela ainda não chegou à sua organização.

Onde fica e quem pode

• Um contato: abra a ficha e escolha Excluir contato. A exclusão alcança as identidades e os registros unificados da pessoa, e a unificação deixa de poder ser desfeita.
• Todos os contatos: na tela Contatos, abra Mais ações (o botão de três pontos) e escolha Excluir todos os contatos.

As duas ações exigem a permissão de editar contatos (contacts.write), a mesma que permite alterar o nome e as anotações da ficha. Nos pacotes padrão, ela está no papel Administrador e no proprietário, além do pacote de Atendente citado no início deste artigo; uma função personalizada pode ou não incluí-la. Em organizações que usam departamentos, quem tem Gerenciar contatos também pode excluir.

Confirmar a exclusão

1. A janela mostra a Organização e quantos contatos e Conversas serão afetados, e resume o que acontece com os dados.
2. Copie o texto indicado e digite-o no campo: EXCLUIR para um contato, EXCLUIR TODOS para todos. O texto é o mesmo com a interface em inglês.
3. Confirme no botão da janela, Excluir contato ou Excluir todos os contatos.

Se a quantidade mudar entre abrir a janela e confirmar — por exemplo, porque chegou um contato novo —, nada é excluído: a janela mostra o número novo e pede que você digite o texto e confirme de novo.

Excluir todos os contatos funciona assim:

• inclui todas as páginas da lista e não depende da pesquisa nem dos filtros aplicados;
• conta pessoas: registros unificados contam como uma só;
• fecha o conjunto na confirmação. Contatos que chegarem depois não entram no lote, e os canais continuam recebendo mensagens normalmente.

O que é removido

• os dados da ficha: nome, identidades, anotações, tags e inscrições em listas;
• o conteúdo das conversas: mensagens, anexos, notas internas, resumos e avaliações de satisfação;
• os arquivos dessas conversas.

Envios de e-mail, automações e webhooks pendentes para a pessoa são interrompidos. Se uma automação tinha essa pessoa escolhida como contato fixo, por nome ou por identificador, no passo Escolher contato (veja Ações), essa escolha sai do passo, que precisa ser configurado de novo. O restante da automação não muda.

O que pode permanecer

• Contagens para relatórios e cobrança, como tokens, créditos e métricas, sem texto pessoal.
• Proteções de descadastramento. Elas continuam impedindo novos envios no mesmo alcance de antes: o descadastro de uma lista vale para aquela lista, e a supressão de e-mail continua valendo para a organização. Importar a pessoa de novo ou ela voltar a falar com você não remove a proteção.
• Uma referência técnica, quando o contato tinha histórico. Ela não guarda os dados da pessoa e aparece como Contato excluído. Ao abrir uma conversa antiga dessa pessoa, o conteúdo não aparece e não é possível enviar mensagens.

Esses itens têm finalidade própria — relatórios, cobrança e proteção contra novos envios — e não são uma cópia da ficha.

Acompanhar o andamento

Depois da confirmação, a ficha fecha e a tela Contatos mostra um cartão com Total, Concluídos, Pendentes e Falhas. O título mostra em que estado está o pedido:

Estado	O que significa
Exclusão na fila	O pedido foi aceito e aguarda para ser processado
Exclusão em andamento	O SquadOS está removendo os dados. Abaixo do título aparece a etapa: Registrando o pedido, Interrompendo envios e automações, Removendo arquivos, Removendo dados e conteúdo ou Conferindo a remoção
Exclusão concluída	Todos os contatos do pedido foram processados. O cartão resume o que foi eliminado e, quando houver, as proteções de descadastramento mantidas e os procedimentos externos pendentes
Exclusão requer atenção	Algum contato não foi concluído

Você pode fechar a tela: o servidor continua a exclusão. Falhas temporárias são repetidas sozinhas. Se o pedido ficar em Exclusão requer atenção, o cartão mostra o Código do pedido; informe esse código ao suporte.

Ao voltar à tela Contatos, o cartão reaparece enquanto o pedido estiver na fila, em andamento ou precisar de atenção. Um pedido concluído deixa de ser listado depois que a tela é recarregada, então anote os procedimentos externos pendentes antes de recarregar ou de usar Fechar.

Enquanto a exclusão de uma pessoa roda, a ficha dela mostra o aviso Exclusão em andamento e não pode ser editada, unificada nem usada para Iniciar conversa. Os outros contatos e conversas continuam funcionando.

Se a pessoa voltar a falar com você

Se a pessoa escrever de novo por um canal, o SquadOS cria um contato novo e uma conversa nova, sem o histórico anterior e sem restaurar inscrições em campanhas. Uma proteção de descadastramento mantida continua valendo para esse contato novo.

O que a exclusão não alcança

O SquadOS elimina o que está sob o controle dele. Outras cópias dependem da organização ou de quem as recebeu:

• Mensagens já entregues continuam no aparelho ou na caixa de quem as recebeu, no WhatsApp, no e-mail e nos demais canais. O SquadOS não apaga conversas dentro desses serviços.
• Arquivos exportados ou baixados e cópias salvas em Arquivos a partir de uma conversa são independentes dos arquivos da conversa, e a organização precisa tratá-los. O cartão de conclusão avisa quantos procedimentos externos ficaram pendentes: hoje, esse número conta as cópias salvas em Arquivos. O que saiu do SquadOS por outros caminhos, como exportações e downloads, não entra na contagem.
• Webhooks já entregues a sistemas externos não são desfeitos. Trate os dados nesses sistemas por lá.
• Cópias de segurança (backups) do SquadOS expiram no ciclo próprio de cada uma. Se um backup for restaurado, o SquadOS aplica a exclusão de novo a partir do registro do pedido, sem ação da organização.

A conclusão da exclusão no SquadOS não substitui a avaliação da organização sobre essas cópias externas.

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.