Étiquettes

Une étiquette est un nom et une couleur que vous posez sur une conversation pour classer votre boîte de réception. Les étiquettes sont propres à un compte, invisibles pour votre interlocuteur, et elles voyagent avec chaque chat que vous relisez.

À qui appartiennent ces étiquettes

Ce sont des étiquettes Sendveo, pas des étiquettes WhatsApp Business, et la différence n'est pas cosmétique. Le service de messagerie ne publie aucune API d'étiquettes : rien pour lister celles du téléphone, rien pour en appliquer une, rien pour être averti quand une est ajoutée. Aucune version de cette fonctionnalité ne pouvait lire vos vraies étiquettes, alors Sendveo assure le même contrat depuis son propre côté. Une étiquette Sendveo n'apparaît pas dans WhatsApp sur le téléphone, et une étiquette du téléphone n'apparaît pas ici. Si une API d'étiquettes voit le jour, ces endpoints et le champ labels d'un chat resteront exactement tels quels ; seul ce qui se trouve derrière changera.

Gérer les étiquettes

Lister, créer, renommer, recolorer et supprimer. chatCount figure sur la liste et nulle part ailleurs : sur une conversation, ce serait un compteur par étiquette et par ligne.

curl -X POST https://api.sendveo.com/v1/labels \
  -H "X-API-KEY: sv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Quote sent", "color": "teal" }'

{
  "label": { "id": "lbl_m8k3x7q2", "name": "Quote sent", "color": "teal", "chatCount": 0 }
}

Supprimer une étiquette la retire de toutes les conversations qui la portent, et la réponse indique combien dans chats. Une étiquette disparue de la liste mais toujours affichée sur quarante chats serait pire que l'un ou l'autre état.

En poser une sur une conversation

Envoyez { labelId } pour une étiquette que vous avez déjà, ou { name } pour la créer et l'appliquer en un seul appel. La forme par nom est celle qu'attend un champ où l'on tape pour ajouter : sinon il faut lister, puis créer, puis appliquer, soit trois allers-retours pour une seule action, avec au milieu une course où deux onglets créent la même étiquette.

curl -X POST https://api.sendveo.com/v1/chats/chat_9Fp2/labels \
  -H "X-API-KEY: sv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Urgent" }'

Appliquer une étiquette que la conversation porte déjà donne un 200, pas un conflit : vous avez demandé un état, et cet état est vrai. En retirer une qu'elle ne porte pas donne un 404. L'asymétrie est volontaire : retirer une étiquette qu'une conversation n'a jamais eue trahit presque toujours un appelant qui travaille sur une liste périmée.

Les étiquettes sur un chat

Chaque chat et chaque groupe porte labels, toujours présent et [] quand il n'y en a aucune. Contrairement à members, les étiquettes voyagent aussi sur la liste, pas seulement sur la lecture unitaire : c'est une jointure locale, donc une page de cinquante conversations coûte une requête de plus au lieu de cinquante appels en amont, et filtrer une boîte de réception par étiquette est précisément ce qu'on en fait.

{
  "id": "cht_m8k3x7q2a1b4",
  "chatId": "chat_9Fp2",
  "name": "Khadija Alaoui",
  "labels": [
    { "id": "lbl_m8k3x7q2", "name": "Quote sent", "color": "teal" },
    { "id": "lbl_m8k3wp41", "name": "Urgent", "color": "rose" }
  ]
}

Noms, couleurs et limites

color est un nom tiré d'une palette fixe, jamais du CSS : slate, violet, blue, teal, green, amber, orange, rose. Toute autre valeur donne un 400 VALIDATION_FAILED qui nomme la palette entière. Une couleur libre serait une chaîne fournie par l'appelant qui finirait dans l'attribut de style d'un tableau de bord, et une liste où chaque ligne a sa nuance choisie à la main est une liste que personne ne peut parcourir. Omettez color et une couleur est dérivée du nom, de façon déterministe : supprimer une étiquette puis la recréer redonne la même couleur.

Les noms sont normalisés et détourés, si bien que Devis et Devis ne font qu'une seule étiquette, et ils sont uniques par compte. Un doublon donne un 409 dont les details nomment l'étiquette heurtée, ce qui permet à un script qui importe des catégories de savoir lesquelles de ses lignes étaient nouvelles. Au maximum 40 caractères par nom, 50 étiquettes par compte et 20 étiquettes par conversation.

Portées

Lire les étiquettes demande chats:read, et tout ce qui en modifie une demande chats:manage. Il n'y a volontairement aucune nouvelle portée : une étiquette s'applique à une conversation et reste invisible hors de votre compte, ce qui est strictement moins visible qu'archiver ou mettre en sourdine, et aucune clé émise avant l'existence d'une portée ne la porte. Réutiliser les portées des chats fait que toute clé créée depuis l'arrivée des chats fonctionne immédiatement avec les étiquettes.