Tags de Contato

Tags de contato são rótulos coloridos para classificar uma pessoa — por exemplo, “lead quente”, “cliente” ou “aguardando pagamento”. O catálogo é compartilhado pela organização, e cada tag pode ser ligada a vários contatos.

Elas pertencem ao cadastro do contato, não a uma conversa. Por isso, aparecem em todas as conversas ligadas ao mesmo contato unificado. Canais ou identidades que ainda estejam em cadastros separados não compartilham tags até que os contatos sejam unificados. A interface do cliente não renderiza esses rótulos; eles servem à operação interna.

Cuidado

Não confunda Tag do contato com Tag da conversa. A primeira descreve a pessoa em todos os atendimentos; a segunda descreve somente o assunto daquela conversa. Os dois recursos usam o mesmo catálogo de nomes e cores, mas gravam associações diferentes.

Onde encontrar as tags

Em /admin/conversations:

1. Abra uma conversa que tenha contato externo.
2. No painel Contexto, selecione a aba Contato.
3. Localize Tags do contato na ficha da pessoa. O bloco mostra os rótulos atuais, Adicionar e o × de remoção quando a interface permite edição.

Conversas sem externalContactId, como uma conversa interna sem pessoa externa vinculada, não mostram tags de contato. Na lista de conversas, os chips aparecem junto aos demais indicadores: a visualização atual exibe até duas tags e resume o restante como +N.

Aplicar ou criar uma tag

No bloco Tags do contato:

1. Clique em Adicionar.
2. Use Buscar ou criar tag….
3. Se o nome já existir, selecione a tag encontrada.
4. Se não existir, selecione Criar “nome” para criar e aplicar na mesma operação.

A comparação de nomes não diferencia maiúsculas de minúsculas. Criar VIP quando vip já existe reutiliza a tag armazenada. Uma tag nova recebe deterministicamente uma das oito cores do catálogo; reaplicar a mesma tag não cria duplicata nem troca sua cor.

Para retirar a associação, clique no × do chip. Isso remove a tag apenas daquele contato: o rótulo continua no catálogo e nos outros contatos.

Filtrar conversas por tags do contato

1. Em Conversas, clique em Filtros.
2. Abra Tag do contato.
3. Pesquise e marque uma ou mais tags.

Quando várias tags de contato estão selecionadas, a lista inclui contatos que tenham qualquer uma delas. Outros filtros — como caixa, canal, agente e Tag da conversa — continuam sendo aplicados em conjunto. A seleção fica no parâmetro tags da URL, então o link preserva o filtro.

Cuidado

Hoje, uma falha ao consultar as associações de tags pode ser apresentada como lista vazia. Se um filtro conhecido devolver zero conversas inesperadamente, recarregue e confirme sem o filtro antes de concluir que não há resultados.

Aplicar em lote

Na lista atual é possível selecionar até 50 conversas visíveis por ação. Depois da seleção:

1. Abra Ações.
2. Em Organização, escolha Adicionar tag ou Remover tag.
3. Selecione uma tag já existente e confirme.

A ação altera o contato ligado a cada conversa, não a conversa em si. Cada item é validado separadamente: conversas sem contato externo ou sem permissão podem falhar enquanto as demais continuam. Para marcar o assunto das conversas selecionadas, use Adicionar tag nas conversas.

Gerenciar o catálogo

O produto possui o diálogo Gerenciar tags, capaz de mostrar o número de contatos, renomear, recolorir e excluir. Porém, a interface atual de Conversas monta o filtro com essa ação desativada e não oferece outro botão para abrir o diálogo.

Portanto, não procure Gerenciar tags no filtro atual. Criação continua disponível ao aplicar uma tag individualmente. Para listar, renomear, recolorir ou excluir o catálogo, use os endpoints documentados em Tags na API. Excluir uma tag do catálogo a remove de todos os contatos e não pode ser desfeito.

Agentes, API e Automações

Todos estes caminhos usam o catálogo de tags de contato:

• A ferramenta nativa Tags do contato (manage_tags) lista, aplica/cria por nome e remove no contato externo da conversa atual.
• A API de Tags gerencia o catálogo e associações por UUID.
• Em Automações, o gatilho Tag do contato reage a uma tag aplicada ou removida, e a ação Aplicar tag adiciona ou remove tags do contato. O recurso de Automações pode ainda estar restrito ao rollout da organização.

Permissões e atualização da tela

O contrato granular separa contacts.view, para ler contatos e o catálogo, de contacts.write, para alterar o cadastro. A rota de Conversas exige conversations.view.

Cuidado

Há uma inconsistência conhecida no produto: o painel atual pode mostrar controles de edição sem verificar contacts.write, enquanto as RPCs de tag ainda verificam o papel legado de colaborador ou superior. Assim, alguém com o controle visível pode receber Falha ao aplicar a tag, e uma função granular pode não produzir o resultado esperado. Trate isso como problema de permissão do produto e peça ao administrador para revisar a função; não recrie a tag repetidamente.

Uma alteração feita por você invalida os caches locais e costuma aparecer imediatamente. Eventos externos atualizam a lista de conversas e o catálogo, mas hoje não invalidam a consulta específica do painel de contato já aberto. Se um agente, automação ou colega alterou a tag e o painel não acompanhou, troque de conversa e volte ou recarregue antes de agir novamente.

Boas práticas

• Use poucos nomes canônicos e confira o catálogo antes de criar uma variação.
• Explique no prompt do agente exatamente quando manage_tags deve aplicar ou remover cada rótulo.
• Combine Tag do contato com Tag da conversa quando precisar cruzar perfil da pessoa e assunto do atendimento.
• Não use tags para segredos ou dados pessoais desnecessários: elas são visíveis a quem pode consultar contatos na organização.