> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lfautomatiza.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Labels (etiquetas)

> CRUD de labels usadas em conversas e contatos.

Labels (também chamadas de tags ou etiquetas) são marcadores reutilizáveis para
organizar conversas e contatos. Cada label tem cor própria e pode aparecer em
filtros, automações e relatórios.

## Listar labels

```http theme={null}
GET /api/v1/accounts/{account_id}/labels
```

```bash theme={null}
curl https://chat.lfautomatiza.com/api/v1/accounts/1/labels \
  -H "api_access_token: $TOKEN"
```

### Resposta

```json theme={null}
{
  "payload": [
    {
      "id": 1,
      "title": "financeiro",
      "description": "Tickets relacionados a boleto, NF, pagamento",
      "color": "#9333ea",
      "show_on_sidebar": true
    },
    {
      "id": 2,
      "title": "vip",
      "color": "#f59e0b",
      "show_on_sidebar": true
    }
  ]
}
```

## Criar label

```http theme={null}
POST /api/v1/accounts/{account_id}/labels
```

| Campo             | Tipo    | Obrigatório | Descrição                                         |
| ----------------- | ------- | ----------- | ------------------------------------------------- |
| `title`           | string  | ✅           | Nome da label (sem espaço, lowercase recomendado) |
| `description`     | string  |             | Tooltip / contexto                                |
| `color`           | string  |             | Hex (ex: `#00B86B`)                               |
| `show_on_sidebar` | boolean |             | Aparece como atalho no menu lateral               |

```bash theme={null}
curl -X POST https://chat.lfautomatiza.com/api/v1/accounts/1/labels \
  -H "api_access_token: $TOKEN" \
  -d '{
    "title": "urgente",
    "description": "Casos que precisam de SLA <30min",
    "color": "#dc2626",
    "show_on_sidebar": true
  }'
```

## Detalhe / atualizar / excluir

```http theme={null}
GET    /api/v1/accounts/{account_id}/labels/{id}
PATCH  /api/v1/accounts/{account_id}/labels/{id}
DELETE /api/v1/accounts/{account_id}/labels/{id}
```

<Note>
  Excluir uma label remove ela de todas as conversas e contatos que estavam marcados.
  Não há "undo" — considere arquivar (renomear pra `_zarchive_xxx`) em vez de excluir.
</Note>

## Aplicar label numa conversa

Não use o endpoint `/labels` direto pra isso — use o endpoint de conversa:

```http theme={null}
POST /api/v1/accounts/{account_id}/conversations/{id}/labels
```

```bash theme={null}
curl -X POST https://chat.lfautomatiza.com/api/v1/accounts/1/conversations/1287/labels \
  -H "api_access_token: $TOKEN" \
  -d '{ "labels": ["financeiro", "vip"] }'
```

O array enviado **substitui** todas as labels atuais da conversa.

## Aplicar label num contato

```http theme={null}
POST /api/v1/accounts/{account_id}/contacts/{id}/labels
```

Mesma estrutura — array substitui o conjunto atual.

## Filtrar conversas por label

```bash theme={null}
curl "https://chat.lfautomatiza.com/api/v1/accounts/1/conversations?labels[]=vip&labels[]=urgente" \
  -H "api_access_token: $TOKEN"
```

Múltiplas labels = combinação **AND** (a conversa precisa ter todas as labels listadas).

## Códigos de resposta

| Código                     | Quando acontece           |
| -------------------------- | ------------------------- |
| `200 OK`                   | Listagem / leitura        |
| `201 Created`              | Label criada              |
| `204 No Content`           | Excluído com sucesso      |
| `422 Unprocessable Entity` | Título já existe na conta |