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

# Label

> Buat dan kelola label WhatsApp Business untuk mengorganisir chat dan kontak Anda.

# Label

Label adalah fitur WhatsApp Business yang memungkinkan Anda mengkategorikan dan mengorganisir chat Anda. Melalui Wappfy API, Anda dapat membuat label kustom, menetapkannya ke chat, dan mengambil chat berdasarkan label.

<Note>
  Label hanya tersedia pada akun WhatsApp Business. Akun WhatsApp personal tidak mendukung label.
</Note>

Semua endpoint label terikat pada instance tertentu:

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

***

## Membuat Label

Buat label baru dengan nama dan warna.

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

**Respons:**

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

### Warna Label

WhatsApp Business mendukung set warna label tetap yang diidentifikasi dengan nomor:

| ID Warna | Warna            |
| -------- | ---------------- |
| `0`      | Abu-abu muda     |
| `1`      | Hijau            |
| `2`      | Biru             |
| `3`      | Kuning           |
| `4`      | Merah muda/Merah |

***

## Melihat Daftar Label

Ambil semua label untuk instance tersebut.

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

**Respons:**

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

***

## Memperbarui Label

Perbarui nama atau warna label yang sudah ada.

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

***

## Menghapus Label

Hapus label secara permanen. Ini menghapus label dari semua chat yang ditetapkan.

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

<Warning>
  Menghapus label menghapusnya dari semua chat terkait. Tindakan ini tidak dapat dibatalkan.
</Warning>

***

## Label Chat

### Mendapatkan Label untuk Chat

Ambil semua label yang ditetapkan ke chat tertentu.

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

**Respons:**

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

### Menetapkan Label pada Chat

Tetapkan satu atau beberapa label ke chat. Ini menggantikan label yang sudah ada pada chat tersebut.

<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>
  Untuk menghapus semua label dari chat, kirim array kosong: `{"label_ids": []}`.
</Tip>

### Mendapatkan Chat berdasarkan Label

Ambil semua chat yang memiliki label tertentu.

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

**Respons:**

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

***

## Kasus Penggunaan Umum

<AccordionGroup>
  <Accordion title="Menandai lead baru secara otomatis">
    Gunakan webhook untuk mendengarkan event `message.received`. Saat pesan datang dari kontak yang tidak dikenal, tetapkan label "New Lead" melalui API. Ini membantu tim Anda dengan cepat mengidentifikasi dan memprioritaskan percakapan baru.
  </Accordion>

  <Accordion title="Melacak status tiket dukungan">
    Buat label seperti "Open", "In Progress", dan "Resolved". Perbarui label saat tim Anda menyelesaikan permintaan dukungan. Gunakan endpoint "Mendapatkan Chat berdasarkan Label" untuk membangun antrian dukungan sederhana.
  </Accordion>

  <Accordion title="Mengelompokkan pelanggan untuk broadcast">
    Beri label pelanggan berdasarkan kategori (misalnya, "VIP", "Wholesale", "Retail"). Saat mengirim pesan broadcast, ambil semua chat untuk sebuah label dan kirim pesan secara berulang.
  </Accordion>
</AccordionGroup>

***

## Referensi Endpoint

| Method   | Endpoint                                     | Deskripsi                          |
| -------- | -------------------------------------------- | ---------------------------------- |
| `POST`   | `/api/instances/{id}/labels`                 | Membuat label baru                 |
| `GET`    | `/api/instances/{id}/labels`                 | Melihat daftar semua label         |
| `PUT`    | `/api/instances/{id}/labels/{labelId}`       | Memperbarui label                  |
| `DELETE` | `/api/instances/{id}/labels/{labelId}`       | Menghapus label                    |
| `GET`    | `/api/instances/{id}/labels/chats/{chatId}`  | Mendapatkan label untuk chat       |
| `PUT`    | `/api/instances/{id}/labels/chats/{chatId}`  | Menetapkan label pada chat         |
| `GET`    | `/api/instances/{id}/labels/{labelId}/chats` | Mendapatkan chat berdasarkan label |

***

## Penanganan Error

| Kode Status | Deskripsi                                           |
| ----------- | --------------------------------------------------- |
| `400`       | Warna label tidak valid atau field wajib tidak ada. |
| `404`       | Label atau chat tidak ditemukan.                    |
| `409`       | Label dengan nama yang sama sudah ada.              |
| `422`       | Format chat ID tidak valid.                         |