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

# Etichette

> Crea e gestisci le etichette di WhatsApp Business per organizzare le tue chat e i tuoi contatti.

# Etichette

Le etichette sono una funzionalita di WhatsApp Business che ti permette di categorizzare e organizzare le tue chat. Tramite l'API Wappfy, puoi creare etichette personalizzate, assegnarle alle chat e recuperare le chat per etichetta.

<Note>
  Le etichette sono disponibili solo sugli account WhatsApp Business. Gli account WhatsApp personali non supportano le etichette.
</Note>

Tutti gli endpoint delle etichette sono associati a un'istanza specifica:

```
/api/instances/{instanceId}/labels/...
```

***

## Creare un'etichetta

Crea una nuova etichetta con un nome e un colore.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wappfy.io/api/instances/inst_abc123/labels \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "VIP Customer",
      "color": 1
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/labels",
    {
      method: "POST",
      headers: {
        "X-Api-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "VIP Customer",
        color: 1,
      }),
    }
  );

  const label = await response.json();
  console.log(label.data.id);
  ```
</CodeGroup>

**Risposta:**

```json theme={null}
{
  "data": {
    "id": "1",
    "name": "VIP Customer",
    "color": 1
  }
}
```

### Colori delle etichette

WhatsApp Business supporta un set fisso di colori per le etichette identificati da un numero:

| ID colore | Colore        |
| --------- | ------------- |
| `0`       | Grigio chiaro |
| `1`       | Verde         |
| `2`       | Blu           |
| `3`       | Giallo        |
| `4`       | Rosa/Rosso    |

***

## Elencare le etichette

Recupera tutte le etichette dell'istanza.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.wappfy.io/api/instances/inst_abc123/labels \
    -H "X-Api-Key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/labels",
    {
      headers: { "X-Api-Key": "YOUR_API_KEY" },
    }
  );

  const { data } = await response.json();
  data.forEach((label) => {
    console.log(`${label.id}: ${label.name} (color: ${label.color})`);
  });
  ```
</CodeGroup>

**Risposta:**

```json theme={null}
{
  "data": [
    { "id": "1", "name": "New Customer", "color": 0 },
    { "id": "2", "name": "VIP Customer", "color": 1 },
    { "id": "3", "name": "Pending Payment", "color": 3 },
    { "id": "4", "name": "Resolved", "color": 2 }
  ]
}
```

***

## Aggiornare un'etichetta

Aggiorna il nome o il colore di un'etichetta esistente.

```bash theme={null}
curl -X PUT https://api.wappfy.io/api/instances/inst_abc123/labels/2 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Customer",
    "color": 2
  }'
```

***

## Eliminare un'etichetta

Elimina definitivamente un'etichetta. Questo rimuove l'etichetta da tutte le chat a cui era assegnata.

```bash theme={null}
curl -X DELETE https://api.wappfy.io/api/instances/inst_abc123/labels/2 \
  -H "X-Api-Key: YOUR_API_KEY"
```

<Warning>
  L'eliminazione di un'etichetta la rimuove da tutte le chat associate. Questa azione non puo essere annullata.
</Warning>

***

## Etichette delle chat

### Ottenere le etichette di una chat

Recupera tutte le etichette assegnate a una chat specifica.

```bash theme={null}
curl https://api.wappfy.io/api/instances/inst_abc123/labels/chats/5511999998888@s.whatsapp.net \
  -H "X-Api-Key: YOUR_API_KEY"
```

**Risposta:**

```json theme={null}
{
  "data": [
    { "id": "1", "name": "New Customer", "color": 0 },
    { "id": "3", "name": "Pending Payment", "color": 3 }
  ]
}
```

### Impostare le etichette su una chat

Assegna una o piu etichette a una chat. Questo sostituisce tutte le etichette esistenti sulla chat.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT https://api.wappfy.io/api/instances/inst_abc123/labels/chats/5511999998888@s.whatsapp.net \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "label_ids": ["1", "2"]
    }'
  ```

  ```javascript Node.js theme={null}
  await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/labels/chats/5511999998888@s.whatsapp.net",
    {
      method: "PUT",
      headers: {
        "X-Api-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        label_ids: ["1", "2"],
      }),
    }
  );
  ```
</CodeGroup>

<Tip>
  Per rimuovere tutte le etichette da una chat, passa un array vuoto: `{"label_ids": []}`.
</Tip>

### Ottenere le chat per etichetta

Recupera tutte le chat che hanno una specifica etichetta assegnata.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.wappfy.io/api/instances/inst_abc123/labels/2/chats \
    -H "X-Api-Key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/labels/2/chats",
    {
      headers: { "X-Api-Key": "YOUR_API_KEY" },
    }
  );

  const { data } = await response.json();
  console.log(`${data.length} chats with the "VIP Customer" label`);
  ```
</CodeGroup>

**Risposta:**

```json theme={null}
{
  "data": [
    {
      "chat_id": "5511999998888@s.whatsapp.net",
      "name": "Maria Silva"
    },
    {
      "chat_id": "5511888887777@s.whatsapp.net",
      "name": "Carlos Oliveira"
    }
  ]
}
```

***

## Casi d'uso comuni

<AccordionGroup>
  <Accordion title="Etichettare automaticamente i nuovi lead">
    Usa un webhook per ascoltare gli eventi `message.received`. Quando un messaggio arriva da un contatto sconosciuto, assegna l'etichetta "Nuovo Lead" tramite l'API. Questo aiuta il tuo team a identificare e dare priorita rapidamente alle nuove conversazioni.
  </Accordion>

  <Accordion title="Monitorare lo stato dei ticket di supporto">
    Crea etichette come "Aperto", "In corso" e "Risolto". Aggiorna l'etichetta man mano che il tuo team gestisce le richieste di supporto. Usa l'endpoint "Ottieni chat per etichetta" per creare una semplice coda di supporto.
  </Accordion>

  <Accordion title="Segmentare i clienti per le comunicazioni broadcast">
    Etichetta i clienti per categoria (es. "VIP", "Ingrosso", "Dettaglio"). Quando invii messaggi broadcast, recupera tutte le chat di un'etichetta e invia i messaggi in sequenza.
  </Accordion>
</AccordionGroup>

***

## Riferimento degli endpoint

| Metodo   | Endpoint                                     | Descrizione                      |
| -------- | -------------------------------------------- | -------------------------------- |
| `POST`   | `/api/instances/{id}/labels`                 | Crea una nuova etichetta         |
| `GET`    | `/api/instances/{id}/labels`                 | Elenca tutte le etichette        |
| `PUT`    | `/api/instances/{id}/labels/{labelId}`       | Aggiorna un'etichetta            |
| `DELETE` | `/api/instances/{id}/labels/{labelId}`       | Elimina un'etichetta             |
| `GET`    | `/api/instances/{id}/labels/chats/{chatId}`  | Ottieni le etichette di una chat |
| `PUT`    | `/api/instances/{id}/labels/chats/{chatId}`  | Imposta le etichette su una chat |
| `GET`    | `/api/instances/{id}/labels/{labelId}/chats` | Ottieni le chat per etichetta    |

***

## Gestione degli errori

| Codice di stato | Descrizione                                                    |
| --------------- | -------------------------------------------------------------- |
| `400`           | Colore dell'etichetta non valido o campi obbligatori mancanti. |
| `404`           | Etichetta o chat non trovata.                                  |
| `409`           | Esiste gia un'etichetta con lo stesso nome.                    |
| `422`           | Formato dell'ID chat non valido.                               |