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.

Le etichette sono disponibili solo sugli account WhatsApp Business. Gli account WhatsApp personali non supportano le etichette.

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.

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

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

Risposta:

{
  "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.

curl https://api.wappfy.io/api/instances/inst_abc123/labels \
  -H "X-Api-Key: YOUR_API_KEY"

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})`);
});

Risposta:

{
  "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.

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.

curl -X DELETE https://api.wappfy.io/api/instances/inst_abc123/labels/2 \
  -H "X-Api-Key: YOUR_API_KEY"

L’eliminazione di un’etichetta la rimuove da tutte le chat associate. Questa azione non puo essere annullata.

Etichette delle chat

Ottenere le etichette di una chat

Recupera tutte le etichette assegnate a una chat specifica.

curl https://api.wappfy.io/api/instances/inst_abc123/labels/chats/5511999998888@s.whatsapp.net \
  -H "X-Api-Key: YOUR_API_KEY"

Risposta:

{
  "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.

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"]
  }'

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"],
    }),
  }
);

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

Ottenere le chat per etichetta

Recupera tutte le chat che hanno una specifica etichetta assegnata.

curl https://api.wappfy.io/api/instances/inst_abc123/labels/2/chats \
  -H "X-Api-Key: YOUR_API_KEY"

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`);

Risposta:

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

Casi d’uso comuni

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.

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.

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.

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.

Per Iniziare

Guide

Etichette

Etichette

Creare un’etichetta

Colori delle etichette

Elencare le etichette

Aggiornare un’etichetta

Eliminare un’etichetta

Etichette delle chat

Ottenere le etichette di una chat

Impostare le etichette su una chat

Ottenere le chat per etichetta

Casi d’uso comuni

Riferimento degli endpoint

Gestione degli errori

​Etichette

​Creare un’etichetta

​Colori delle etichette

​Elencare le etichette

​Aggiornare un’etichetta

​Eliminare un’etichetta

​Etichette delle chat

​Ottenere le etichette di una chat

​Impostare le etichette su una chat

​Ottenere le chat per etichetta

​Casi d’uso comuni

​Riferimento degli endpoint

​Gestione degli errori

Etichette

Creare un’etichetta

Colori delle etichette

Elencare le etichette

Aggiornare un’etichetta

Eliminare un’etichetta

Etichette delle chat

Ottenere le etichette di una chat

Impostare le etichette su una chat

Ottenere le chat per etichetta

Casi d’uso comuni

Riferimento degli endpoint

Gestione degli errori