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

# Etiquetas

> Marque contatos e grupos com etiquetas no escopo do tenant, pelo painel ou pela API de envio.

## O que são Etiquetas

Etiquetas marcam destinos (telefone E.164 ou grupo do WhatsApp `...@g.us`) no escopo do **tenant**. Gerencie-as em **Config → Etiquetas** (`/labels`): crie etiquetas, importe CSV/Excel, edite nome/destino, copie um contato de uma etiqueta para outra.

<Frame caption="A página de Labels — organize contatos e grupos em labels, importe de CSV/Excel e passe labels em POST /v1/messages/send.">
  <img src="https://mintcdn.com/iaxp/-5uf_maz35Nxf9St/images/dashboard/labels.png?fit=max&auto=format&n=-5uf_maz35Nxf9St&q=85&s=18385bcde95a06e4cf4bd847b7f3814c" alt="Página de Labels do Pilot Status" width="1920" height="896" data-path="images/dashboard/labels.png" />
</Frame>

## API Pública — enviar mensagem

Em `POST /v1/messages/send`, opcionalmente envie:

```json theme={null}
"labels": ["vip", "customers"]
```

* Funciona com `destinationNumber` ou `groupId`.
* O processamento de etiquetas é **assíncrono**: faz upsert das Etiquetas por nome e associa o destino.
* A plataforma pode tentar preencher o **nome de exibição** do contato a partir dos dados do WhatsApp na instância conectada quando ainda estiver vazio.

### Exemplo

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
    -H "Content-Type: application/json" \
    -H "x-api-key: ps_your_key_here" \
    -d '{
      "destinationNumber": "+5511999999999",
      "templateId": "order_update",
      "labels": ["vip", "customers"]
    }'
  ```

  ```json Response (202) theme={null}
  {
    "id": "cmm04obm46zz0qv4ycjp8x6r2",
    "correlationId": "b3f1c2a4-9e7d-4c5a-8f21-0a1b2c3d4e5f",
    "status": "QUEUED",
    "createdAt": "2026-07-04T12:00:00.000Z",
    "origin": "api"
  }
  ```
</CodeGroup>

## Retenção (PII)

A retenção é regida pelo **modo PII do número** — alterado no painel, na página API Keys (painel Privacidade & retenção) ou nas configurações do número em Números:

* **`STORE_INDEFINITE`** (padrão) — conversas e mensagens são armazenadas indefinidamente.
* **`STORE_X_DAYS`** — apenas os últimos N dias de registros de chat são mantidos; registros mais antigos são apagados diariamente.
* **`RELAY_ONLY`** — as conversas não são persistidas. As Etiquetas em si ainda são criadas quando você passa `labels` na API de envio, mas nenhum conteúdo de conversa é armazenado.

Para o comportamento completo de cada modo, veja [Retenção de Dados e Modos PII](/pt-BR/trust/data-retention).

## Importação pela interface

* Colunas de telefone: iguais às de Mensagens (`number`, `destinationnumber`, `phone`, etc.).
* Coluna de grupo opcional: `groupId`, `group` — se terminar com `@g.us`, a linha é tratada como **GRUPO**.
* Se o mesmo destino já existir na etiqueta com um **nome vazio** e a importação fornecer um nome, o **nome é atualizado**.

## Copiar contato

Use **Copiar para…** para duplicar o vínculo em outra etiqueta (deduplicação por destino; preenche o nome no destino quando estiver vazio).