Runbook - Etiquetas do Sagazchat

Manual operacional para uma IA ou pessoa gerenciar Configurações > Etiquetas no Sagazchat. Etiquetas sao marcadores reutilizaveis (texto + cor) aplicados em conversas e contatos para classificacao e segmentacao.

Status: validado em 2026-05-11 na conta exemplo. Foi criado e excluido o registro LAB - Etiqueta Teste (id=754) para mapeamento.

1. Onde fica

• Sidebar: Configurações > Etiquetas
• URL: https://app.sagazchat.com/tags
• Endpoint backend: /tags (mesmo nome da rota UI).

2. Estrutura da lista

A tela /tags mostra:

• breadcrumb Painel de controle > Etiquetas;
• botao Nova Etiqueta (canto superior direito);
• campo de busca (mesmo padrao das outras telas);
• tabela com colunas Cor, Nome e Registros etiquetados (contador de usos);
• kebab ⋮ em cada linha.

Estado real da conta exemplo (2026-05-11): ~20 etiquetas, incluindo 8 orfas criadas em sessao antiga (ver memoria reference_sagaz_conta.md):

Etiqueta	Status
Depilação, Massagem, Limpeza de pele	reais (servicos)
Cliente Petshop, cliente_ativo, Cliente Ativo, Novo orçamento, Atendente 1, Comercial - Equipe	reais
5-financeiro, int-financeiro, 3-aguardando-vendedora, int-atendente, int-depilacao, int-massagem, 2-qualificado, int-limpeza	orfas (criadas erradas)

3. Criar etiqueta

3.1 Passo a passo via UI

1. Clicar Nova Etiqueta.

2. Modal Adicionar etiqueta abre com:

   • Informações básicas + campo Nome (input[name="name"], placeholder “Digite o nome da etiqueta”);
   • Defina a cor: 15 swatches predefinidos + botao + (cor customizada);
   • botoes Cancelar / Criar etiqueta.

   

3. Preencher nome.

4. Clicar swatch ou +.

   

5. Clicar Criar etiqueta. O modal fecha, a nova etiqueta entra na lista.

3.2 Endpoint

POST https://backend.sagazchat.com/tags
Authorization: Bearer <jwt>
Content-Type: application/json

{ "name": "LAB - Etiqueta Teste", "color": "#A855F7" }

Resposta validada (id=754):

{
  "id": 754,
  "name": "LAB - Etiqueta Teste",
  "color": "#A855F7",
  "companyId": 39,
  "createdAt": "2026-05-11T14:55:46.379Z",
  "updatedAt": "2026-05-11T14:55:46.379Z"
}

Diferente de departamentos, o payload aqui e simples — nao tem schedules, greetingMessage, etc.

3.3 Cores predefinidas

Mesmo conjunto de 15 cores do modulo Departamentos (#3B82F6 azul, #A855F7 roxo, #14B8A6 teal, #64748B cinza, #6366F1 indigo, #EC4899 rosa, #06B6D4 cyan, #8B5CF6 violeta, #D946EF magenta, #0EA5E9 sky, #D1F349 lime, #3563FF azul forte, #4CCB4A verde, #E24C37 vermelho, #F5C539 amarelo) + botao + custom.

4. Editar etiqueta

1. Kebab ⋮ > Editar.

   

2. Modal Editar etiqueta com Nome preenchido + cor atual destacada.

   

3. Botoes: Cancelar / Salvar.

Endpoint inferido:

PUT https://backend.sagazchat.com/tags/{id}

5. Excluir etiqueta

1. Kebab ⋮ > Excluir.

2. Modal de confirmacao:

   • Titulo: “Você tem certeza que quer excluir esta Etiqueta?”
   • Texto: “Esta ação não pode ser revertida.”
   • Botoes: Cancelar / Deletar

   

3. Clicar Deletar confirma.

Endpoint validado:

DELETE https://backend.sagazchat.com/tags/{id}
→ 200 { "message": "Tag deleted" }

Observacao: ao excluir uma etiqueta, ela some das conversas/contatos onde estava aplicada. O contador “Registros etiquetados” vai a zero antes de remover.

6. Acoes seguras e perigosas

Acao	Impacto	Regra
Abrir lista	Leitura	Seguro.
Buscar	Leitura	Seguro.
Criar LAB - *	Cria registro	OK para teste, lembrar cleanup.
Editar etiqueta real	Afeta visual em todas as conversas	Nao fazer sem ordem.
Excluir etiqueta real com uso	Perde marcacao em conversas	Nao fazer sem ordem.
Excluir etiqueta orfa (0 registros)	Limpa baguca	OK se o administrador autorizar previamente.
Excluir LAB criada para teste	Cleanup	Sempre fazer ao final.

7. Quirks vs Departamentos (importantes)

Etiquetas e Departamentos tem UI parecida (lista + Adicionar + kebab + modal Nome/Cor), mas com diferencas que pegam automacao desprevenida:

Aspecto	Etiquetas	Departamentos
Rota UI	/tags	/department
Endpoint backend	/tags	/queue
Botao topo	”Nova Etiqueta"	"Adicionar”
Botao submit modal	”Criar etiqueta"	"Adicionar”
Placeholder do nome	”Digite o nome da etiqueta”	(sem placeholder)
Titulo modal Excluir	”Você tem certeza que quer excluir esta Etiqueta?"	"Excluir {nome}?”
Payload extra	so name + color	+ schedules, greetingMessage, outOfHoursMessage
Coluna extra na lista	Registros etiquetados (contador)	—

Heuristica: nao supor que dois modulos com UI parecida tem mesmos seletores. Sempre inspecionar o botao real e o titulo do modal.

8. Onde as etiquetas sao usadas

• Bate Papo ao vivo — atendente aplica/remove etiquetas na conversa (painel lateral).
• Audiência — etiquetas sao filtros de segmentacao.
• Fluxos de Conversa — bloco Etiqueta (ou subtipo de Ação) aplica etiquetas automaticamente.
• Remarketing/Transmissão — listas baseadas em etiquetas.
• Kanban — colunas podem ser vinculadas a etiquetas (vinculo NAO move cartoes existentes — ver runbook kanban).

9. Snippets

9.1 Listar etiquetas via API

const v = localStorage.getItem('token');
const token = v?.startsWith('"') ? JSON.parse(v) : v;
const res = await fetch('https://backend.sagazchat.com/tags', {
  headers: { Authorization: `Bearer ${token}` },
});
const list = await res.json();
console.table(list.map((t) => ({ id: t.id, name: t.name, color: t.color })));

9.2 Criar etiqueta via API

const v = localStorage.getItem('token');
const token = v?.startsWith('"') ? JSON.parse(v) : v;
await fetch('https://backend.sagazchat.com/tags', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Nova Etiqueta', color: '#A855F7' }),
});

9.3 Excluir orfa via API (cuidado)

// Verificar que registros etiquetados = 0 antes!
const v = localStorage.getItem('token');
const token = v?.startsWith('"') ? JSON.parse(v) : v;
await fetch(`https://backend.sagazchat.com/tags/${tagId}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${token}` },
});

10. Imagens

• public/media/nova-ui/etiquetas-lista.png
• public/media/nova-ui/etiquetas-modal-add.png
• public/media/nova-ui/etiquetas-modal-add-preenchido.png
• public/media/nova-ui/etiquetas-kebab.png
• public/media/nova-ui/etiquetas-modal-edit.png
• public/media/nova-ui/etiquetas-modal-excluir.png

11. Scripts validados

node scripts/sagaz-tags-mapear.mjs       # lista + cabecalho
node scripts/sagaz-tags-inspect.mjs      # modal Nova Etiqueta + kebab
node scripts/sagaz-tags-criar-lab.mjs    # cria LAB, inspect Editar, Excluir + cleanup