# Etiquetas e encerramento (/docs/crm/etiquetas-encerramento)





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 [#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.

```json
{ "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 [#endpoints]

| Operação            | Método e caminho                                                                                        |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| Listar              | [`GET /v1/inbox/labels`](/docs/api/etiquetas/listLabels)                                                |
| Criar               | [`POST /v1/inbox/labels`](/docs/api/etiquetas/createLabel)                                              |
| Atualizar           | [`PATCH /v1/inbox/labels/{id}`](/docs/api/etiquetas/updateLabel)                                        |
| Remover             | [`DELETE /v1/inbox/labels/{id}`](/docs/api/etiquetas/deleteLabel)                                       |
| Aplicar à conversa  | [`PUT /v1/inbox/conversations/{id}/labels/{labelId}`](/docs/api/etiquetas/assignConversationLabel)      |
| Remover da conversa | [`DELETE /v1/inbox/conversations/{id}/labels/{labelId}`](/docs/api/etiquetas/unassignConversationLabel) |

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](/docs/api/inbox/getInboxConversation).

### Filtrar o Inbox por etiqueta [#filtrar-o-inbox-por-etiqueta]

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

<Callout type="info">
  **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.
</Callout>

## Justificativas de encerramento [#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:

```json
{ "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`](/docs/api/justificativas/listCloseReasons)          |
| Criar    | [`POST /v1/inbox/close-reasons`](/docs/api/justificativas/createCloseReason)        |
| Remover  | [`DELETE /v1/inbox/close-reasons/{id}`](/docs/api/justificativas/deleteCloseReason) |

## Status da conversa e encerramento [#status-da-conversa-e-encerramento]

Toda conversa tem um **status**: `open`, `pending` ou `resolved`. Você o muda com [`POST /v1/inbox/conversations/{id}/status`](/docs/api/inbox/setConversationStatus).

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

```json
{
  "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 [#atribuir-a-um-atendente]

Direcione a conversa a um atendente com [`POST /v1/inbox/conversations/{id}/assign`](/docs/api/inbox/assignConversation):

```json
{ "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](/docs/crm/equipe).

<Callout type="info">
  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](/docs/crm/equipe).
</Callout>