Vai al contenuto principale

​
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
  }'
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 coloreColore
0Grigio chiaro
1Verde
2Blu
3Giallo
4Rosa/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"
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/[email protected] \
  -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/[email protected] \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
Risposta: 
{
  "data": [
    {
      "chat_id": "[email protected]",
      "name": "Maria Silva"
    },
    {
      "chat_id": "[email protected]",
      "name": "Carlos Oliveira"
    }
  ]
}

​
Casi d’uso comuni

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

MetodoEndpointDescrizione
POST/api/instances/{id}/labelsCrea una nuova etichetta
GET/api/instances/{id}/labelsElenca 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}/chatsOttieni le chat per etichetta

​
Gestione degli errori

Codice di statoDescrizione
400Colore dell’etichetta non valido o campi obbligatori mancanti.
404Etichetta o chat non trovata.
409Esiste gia un’etichetta con lo stesso nome.
422Formato dell’ID chat non valido.