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

# Etykiety

> Tworzenie i zarzadzanie etykietami WhatsApp Business do organizacji czatow i kontaktow.

# Etykiety

Etykiety to funkcja WhatsApp Business, ktora pozwala kategoryzowac i organizowac czaty. Za pomoca Wappfy API mozesz tworzyc niestandardowe etykiety, przypisywac je do czatow i pobierac czaty wedlug etykiet.

<Note>
  Etykiety sa dostepne tylko na kontach WhatsApp Business. Osobiste konta WhatsApp nie obsluguja etykiet.
</Note>

Wszystkie endpointy etykiet sa przypisane do konkretnej instancji:

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

***

## Tworzenie etykiety

Utworz nowa etykiete z nazwa i kolorem.

<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>

**Odpowiedz:**

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

### Kolory etykiet

WhatsApp Business obsluguje ustalony zestaw kolorow etykiet identyfikowanych numerem:

| ID koloru | Kolor           |
| --------- | --------------- |
| `0`       | Jasnoszary      |
| `1`       | Zielony         |
| `2`       | Niebieski       |
| `3`       | Zolty           |
| `4`       | Rozowy/Czerwony |

***

## Lista etykiet

Pobierz wszystkie etykiety dla instancji.

<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>

**Odpowiedz:**

```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 }
  ]
}
```

***

## Aktualizacja etykiety

Zaktualizuj nazwe lub kolor istniejacej etykiety.

```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
  }'
```

***

## Usuwanie etykiety

Trwale usun etykiete. Spowoduje to usuniecie etykiety ze wszystkich czatow, do ktorych byla przypisana.

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

<Warning>
  Usuniecie etykiety powoduje jej usuniecie ze wszystkich powiazanych czatow. Tej operacji nie mozna cofnac.
</Warning>

***

## Etykiety czatow

### Pobieranie etykiet czatu

Pobierz wszystkie etykiety przypisane do konkretnego czatu.

```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"
```

**Odpowiedz:**

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

### Ustawianie etykiet na czacie

Przypisz jedna lub wiecej etykiet do czatu. Zastepuje to wszystkie istniejace etykiety na czacie.

<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>
  Aby usunac wszystkie etykiety z czatu, przekaz pusta tablice: `{"label_ids": []}`.
</Tip>

### Pobieranie czatow wedlug etykiety

Pobierz wszystkie czaty, ktore maja przypisana konkretna etykiete.

<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>

**Odpowiedz:**

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

***

## Typowe przypadki uzycia

<AccordionGroup>
  <Accordion title="Automatyczne tagowanie nowych leadow">
    Uzyj webhooka do nasluchiwania zdarzen `message.received`. Gdy wiadomosc pochodzi od nieznanego kontaktu, przypisz etykiete "Nowy lead" przez API. Pomaga to Twojemu zespolowi szybko identyfikowac i priorytetyzowac nowe rozmowy.
  </Accordion>

  <Accordion title="Sledzenie statusu zgloszen wsparcia">
    Utworz etykiety takie jak "Otwarte", "W trakcie" i "Rozwiazane". Aktualizuj etykiete w miare pracy zespolu nad zgloszeniami wsparcia. Uzyj endpointu "Pobieranie czatow wedlug etykiety", aby zbudowac prosta kolejke wsparcia.
  </Accordion>

  <Accordion title="Segmentacja klientow do masowych wiadomosci">
    Oznacz klientow wedlug kategorii (np. "VIP", "Hurt", "Detal"). Przy wysylaniu masowych wiadomosci pobierz wszystkie czaty dla etykiety i wysylaj wiadomosci w petli.
  </Accordion>
</AccordionGroup>

***

## Informacje o endpointach

| Metoda   | Endpoint                                     | Opis                          |
| -------- | -------------------------------------------- | ----------------------------- |
| `POST`   | `/api/instances/{id}/labels`                 | Utworz nowa etykiete          |
| `GET`    | `/api/instances/{id}/labels`                 | Lista wszystkich etykiet      |
| `PUT`    | `/api/instances/{id}/labels/{labelId}`       | Zaktualizuj etykiete          |
| `DELETE` | `/api/instances/{id}/labels/{labelId}`       | Usun etykiete                 |
| `GET`    | `/api/instances/{id}/labels/chats/{chatId}`  | Pobierz etykiety czatu        |
| `PUT`    | `/api/instances/{id}/labels/chats/{chatId}`  | Ustaw etykiety na czacie      |
| `GET`    | `/api/instances/{id}/labels/{labelId}/chats` | Pobierz czaty wedlug etykiety |

***

## Obsluga bledow

| Kod statusu | Opis                                                  |
| ----------- | ----------------------------------------------------- |
| `400`       | Nieprawidlowy kolor etykiety lub brak wymaganych pol. |
| `404`       | Etykieta lub czat nie znaleziony.                     |
| `409`       | Etykieta o tej samej nazwie juz istnieje.             |
| `422`       | Nieprawidlowy format identyfikatora czatu.            |