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

# Etiquettes

> Creez et gerez les etiquettes WhatsApp Business pour organiser vos conversations et contacts.

# Etiquettes

Les etiquettes sont une fonctionnalite WhatsApp Business qui vous permet de categoriser et d'organiser vos conversations. Via l'API Wappfy, vous pouvez creer des etiquettes personnalisees, les attribuer a des conversations et recuperer les conversations par etiquette.

<Note>
  Les etiquettes ne sont disponibles que sur les comptes WhatsApp Business. Les comptes WhatsApp personnels ne prennent pas en charge les etiquettes.
</Note>

Tous les endpoints d'etiquettes sont limites a une instance specifique :

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

***

## Creer une etiquette

Creez une nouvelle etiquette avec un nom et une couleur.

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

**Reponse :**

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

### Couleurs des etiquettes

WhatsApp Business prend en charge un ensemble fixe de couleurs d'etiquettes identifiees par numero :

| ID couleur | Couleur    |
| ---------- | ---------- |
| `0`        | Gris clair |
| `1`        | Vert       |
| `2`        | Bleu       |
| `3`        | Jaune      |
| `4`        | Rose/Rouge |

***

## Lister les etiquettes

Recuperez toutes les etiquettes de l'instance.

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

**Reponse :**

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

***

## Mettre a jour une etiquette

Mettez a jour le nom ou la couleur d'une etiquette existante.

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

***

## Supprimer une etiquette

Supprimez definitivement une etiquette. Cela retire l'etiquette de toutes les conversations auxquelles elle etait attribuee.

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

<Warning>
  La suppression d'une etiquette la retire de toutes les conversations associees. Cette action est irreversible.
</Warning>

***

## Etiquettes de conversation

### Obtenir les etiquettes d'une conversation

Recuperez toutes les etiquettes attribuees a une conversation specifique.

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

**Reponse :**

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

### Definir les etiquettes d'une conversation

Attribuez une ou plusieurs etiquettes a une conversation. Cela remplace toutes les etiquettes existantes sur la conversation.

<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>
  Pour retirer toutes les etiquettes d'une conversation, transmettez un tableau vide : `{"label_ids": []}`.
</Tip>

### Obtenir les conversations par etiquette

Recuperez toutes les conversations auxquelles une etiquette specifique est attribuee.

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

**Reponse :**

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

***

## Cas d'utilisation courants

<AccordionGroup>
  <Accordion title="Etiquetage automatique des nouveaux prospects">
    Utilisez un webhook pour ecouter les evenements `message.received`. Lorsqu'un message provient d'un contact inconnu, attribuez l'etiquette "Nouveau prospect" via l'API. Cela aide votre equipe a identifier et prioriser rapidement les nouvelles conversations.
  </Accordion>

  <Accordion title="Suivi du statut des tickets de support">
    Creez des etiquettes comme "Ouvert", "En cours" et "Resolu". Mettez a jour l'etiquette au fur et a mesure que votre equipe traite les demandes de support. Utilisez l'endpoint "Obtenir les conversations par etiquette" pour construire une file d'attente de support simple.
  </Accordion>

  <Accordion title="Segmentation des clients pour les diffusions">
    Etiquetez les clients par categorie (par ex., "VIP", "Grossiste", "Detail"). Lors de l'envoi de messages en masse, recuperez toutes les conversations d'une etiquette et envoyez les messages en boucle.
  </Accordion>
</AccordionGroup>

***

## Reference des endpoints

| Methode  | Endpoint                                     | Description                               |
| -------- | -------------------------------------------- | ----------------------------------------- |
| `POST`   | `/api/instances/{id}/labels`                 | Creer une nouvelle etiquette              |
| `GET`    | `/api/instances/{id}/labels`                 | Lister toutes les etiquettes              |
| `PUT`    | `/api/instances/{id}/labels/{labelId}`       | Mettre a jour une etiquette               |
| `DELETE` | `/api/instances/{id}/labels/{labelId}`       | Supprimer une etiquette                   |
| `GET`    | `/api/instances/{id}/labels/chats/{chatId}`  | Obtenir les etiquettes d'une conversation |
| `PUT`    | `/api/instances/{id}/labels/chats/{chatId}`  | Definir les etiquettes d'une conversation |
| `GET`    | `/api/instances/{id}/labels/{labelId}/chats` | Obtenir les conversations par etiquette   |

***

## Gestion des erreurs

| Code de statut | Description                                                    |
| -------------- | -------------------------------------------------------------- |
| `400`          | Couleur d'etiquette invalide ou champs obligatoires manquants. |
| `404`          | Etiquette ou conversation non trouvee.                         |
| `409`          | Une etiquette avec le meme nom existe deja.                    |
| `422`          | Format d'identifiant de conversation invalide.                 |