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

# Labels

> Erstellen und verwalten Sie WhatsApp-Business-Labels, um Ihre Chats und Kontakte zu organisieren.

# Labels

Labels sind eine WhatsApp-Business-Funktion, mit der Sie Ihre Chats kategorisieren und organisieren koennen. Ueber die Wappfy API koennen Sie benutzerdefinierte Labels erstellen, sie Chats zuweisen und Chats nach Label abrufen.

<Note>
  Labels sind nur auf WhatsApp-Business-Konten verfuegbar. Persoenliche WhatsApp-Konten unterstuetzen keine Labels.
</Note>

Alle Label-Endpunkte beziehen sich auf eine bestimmte Instanz:

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

***

## Label erstellen

Erstellen Sie ein neues Label mit einem Namen und einer Farbe.

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

**Antwort:**

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

### Label-Farben

WhatsApp Business unterstuetzt einen festen Satz von Label-Farben, die durch Nummern identifiziert werden:

| Farb-ID | Farbe    |
| ------- | -------- |
| `0`     | Hellgrau |
| `1`     | Gruen    |
| `2`     | Blau     |
| `3`     | Gelb     |
| `4`     | Pink/Rot |

***

## Labels auflisten

Rufen Sie alle Labels der Instanz ab.

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

**Antwort:**

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

***

## Label aktualisieren

Aktualisieren Sie den Namen oder die Farbe eines bestehenden Labels.

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

***

## Label loeschen

Loeschen Sie ein Label permanent. Dadurch wird das Label von allen Chats entfernt, denen es zugewiesen war.

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

<Warning>
  Das Loeschen eines Labels entfernt es von allen zugehoerigen Chats. Diese Aktion kann nicht rueckgaengig gemacht werden.
</Warning>

***

## Chat-Labels

### Labels eines Chats abrufen

Rufen Sie alle Labels ab, die einem bestimmten Chat zugewiesen sind.

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

**Antwort:**

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

### Labels einem Chat zuweisen

Weisen Sie einem Chat ein oder mehrere Labels zu. Dies ersetzt alle bestehenden Labels des Chats.

<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>
  Um alle Labels von einem Chat zu entfernen, uebergeben Sie ein leeres Array: `{"label_ids": []}`.
</Tip>

### Chats nach Label abrufen

Rufen Sie alle Chats ab, denen ein bestimmtes Label zugewiesen ist.

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

**Antwort:**

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

***

## Haeufige Anwendungsfaelle

<AccordionGroup>
  <Accordion title="Neue Leads automatisch taggen">
    Verwenden Sie einen Webhook, um auf `message.received`-Ereignisse zu lauschen. Wenn eine Nachricht von einem unbekannten Kontakt kommt, weisen Sie ueber die API das Label "Neuer Lead" zu. So kann Ihr Team neue Konversationen schnell identifizieren und priorisieren.
  </Accordion>

  <Accordion title="Support-Ticket-Status verfolgen">
    Erstellen Sie Labels wie "Offen", "In Bearbeitung" und "Geloest". Aktualisieren Sie das Label, waehrend Ihr Team Support-Anfragen bearbeitet. Nutzen Sie den Endpunkt "Chats nach Label abrufen", um eine einfache Support-Warteschlange aufzubauen.
  </Accordion>

  <Accordion title="Kunden fuer Broadcasts segmentieren">
    Labeln Sie Kunden nach Kategorie (z.B. "VIP", "Grosshandel", "Einzelhandel"). Beim Versenden von Broadcast-Nachrichten rufen Sie alle Chats fuer ein Label ab und senden Nachrichten in einer Schleife.
  </Accordion>
</AccordionGroup>

***

## Endpunkt-Referenz

| Methode  | Endpunkt                                     | Beschreibung               |
| -------- | -------------------------------------------- | -------------------------- |
| `POST`   | `/api/instances/{id}/labels`                 | Neues Label erstellen      |
| `GET`    | `/api/instances/{id}/labels`                 | Alle Labels auflisten      |
| `PUT`    | `/api/instances/{id}/labels/{labelId}`       | Label aktualisieren        |
| `DELETE` | `/api/instances/{id}/labels/{labelId}`       | Label loeschen             |
| `GET`    | `/api/instances/{id}/labels/chats/{chatId}`  | Labels eines Chats abrufen |
| `PUT`    | `/api/instances/{id}/labels/chats/{chatId}`  | Labels einem Chat zuweisen |
| `GET`    | `/api/instances/{id}/labels/{labelId}/chats` | Chats nach Label abrufen   |

***

## Fehlerbehandlung

| Statuscode | Beschreibung                                        |
| ---------- | --------------------------------------------------- |
| `400`      | Ungueltige Label-Farbe oder fehlende Pflichtfelder. |
| `404`      | Label oder Chat nicht gefunden.                     |
| `409`      | Ein Label mit demselben Namen existiert bereits.    |
| `422`      | Ungueltiges Chat-ID-Format.                         |