Etiquetas e encerramento

Como classificar conversas com etiquetas (tags coloridas) e registrar justificativas ao encerrar um atendimento no PEPINO ZAP — o modelo de dados, a paleta de cores, o soft-delete e os endpoints de status e atribuição de conversa.

Duas ferramentas organizam o Inbox: etiquetas classificam conversas de forma transversal (VIP, Suporte, Vendas…) e as justificativas de encerramento registram por que cada atendimento foi resolvido. Ambas são catálogos do Projeto e podem ser geridas pela API.

Etiquetas

Uma etiqueta tem nome e cor. A relação com conversas é M:N: uma conversa pode ter várias etiquetas e uma etiqueta classifica várias conversas.

{ "id": "lbl_01HV...", "name": "VIP", "color": "amber" }

A paleta de cores é fixa (casa com o design do painel):

gray · green · blue · purple · amber · red · cyan · pink

Uma cor fora dessa lista cai para gray. O name é único no Projeto (máx. 40 caracteres) — repetir retorna 409.

Endpoints

Operação	Método e caminho
Listar	`GET /v1/inbox/labels`
Criar	`POST /v1/inbox/labels`
Atualizar	`PATCH /v1/inbox/labels/{id}`
Remover	`DELETE /v1/inbox/labels/{id}`
Aplicar à conversa	`PUT /v1/inbox/conversations/{id}/labels/{labelId}`
Remover da conversa	`DELETE /v1/inbox/conversations/{id}/labels/{labelId}`

Aplicar é idempotente — aplicar a mesma etiqueta de novo não duplica. As etiquetas de uma conversa vêm no campo labels ao detalhar a conversa.

Filtrar o Inbox por etiqueta

A listagem de conversas aceita labelId: GET /v1/inbox/conversations?labelId=lbl_01HV... traz só as conversas com aquela etiqueta — útil para montar filas segmentadas (ex.: "todas as VIP em aberto") a partir do seu sistema.

Soft-delete. Remover uma etiqueta a desativa: ela some da paleta e das conversas ativas, mas o histórico que já a referenciava não quebra. Não há "lixeira" — para voltar a usar, crie de novo.

Justificativas de encerramento

São os motivos que o atendente escolhe ao resolver uma conversa (ex.: "Resolvido", "Sem resposta do cliente", "Duplicado"). Catálogo do Projeto:

{ "id": "cr_01HV...", "name": "Resolvido", "position": 0 }

name é único (máx. 60 caracteres); position é a ordem de exibição. Mesmo soft-delete das etiquetas: remover desativa, sem quebrar conversas já encerradas com aquele motivo.

Operação	Método e caminho
Listar	`GET /v1/inbox/close-reasons`
Criar	`POST /v1/inbox/close-reasons`
Remover	`DELETE /v1/inbox/close-reasons/{id}`

Status da conversa e encerramento

Toda conversa tem um status: open, pending ou resolved. Você o muda com POST /v1/inbox/conversations/{id}/status.

Ao resolver (status: resolved), anexe a justificativa:

{
  "status": "resolved",
  "closeReasonId": "cr_01HV...",
  "closeNotes": "Cliente resolveu pelo app."
}

closeReasonId — opcional, mas precisa ser um motivo existente do Projeto; inválido retorna 400.
closeNotes — observação livre, opcional.
Reabrir (voltar para open/pending) limpa a justificativa anterior.

Atribuir a um atendente

Direcione a conversa a um atendente com POST /v1/inbox/conversations/{id}/assign:

{ "userId": "usr_01HV..." }   // null desatribui

O atendente precisa pertencer ao mesmo Projeto. A atribuição manual fixa o dono daquela conversa e convive com o roteamento automático configurado na Equipe.

Pela API key (integração), as ações de status e atribuição não checam permissão de atendente — a key tem escopo de Projeto. As permissões granulares valem para usuários do painel; veja Equipe e permissões.