Labels

A label is a name and a colour you put on a conversation to sort your inbox. Labels are per account, invisible to the person you are talking to, and they ride on every chat you read back.

Whose labels these are

These are Sendveo labels, not WhatsApp Business labels, and the difference is not cosmetic. The messaging service publishes no label API of any kind: nothing to list the labels on the phone, nothing to apply one, nothing to be told when one is added. There was no version of this feature that reads your real labels, so Sendveo serves the same contract from its own side. A Sendveo label does not appear in WhatsApp on the phone, and a label on the phone does not appear here. If a label API ever appears, these endpoints and the labels field on a chat stay exactly as they are and only what is behind them changes.

Manage labels

List, create, rename, recolour and delete. chatCount is on the list and nowhere else: on a conversation it would be a count per label per row.

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

Deleting a label takes it off every conversation carrying it, and the response says how many in chats. A label gone from the list but still shown on forty chats would be worse than either state.

Put one on a conversation

Send { labelId } for a label you already have, or { name } to create it and apply it in one call. The name form is what a type-to-add box wants: the alternative is list, then create, then apply, which is three round trips to do one thing with a race in the middle where two tabs both create the same label.

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

Applying a label the conversation already carries is a 200, not a conflict: you asked for a state and the state holds. Removing one it does not carry is a 404. The asymmetry is deliberate, because removing a label a conversation never had is almost always a caller working from a stale list.

Labels on a chat

Every chat and every group carries labels, always present and [] for one with none. Unlike members, labels ride on the list as well as the single read: they are a local join, so a page of fifty conversations costs one extra query rather than fifty upstream calls, and filtering an inbox by label is exactly what people do with them.

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

Names, colours and limits

color is a name from a fixed palette, never CSS: slate, violet, blue, teal, green, amber, orange, rose. Anything else is 400 VALIDATION_FAILED naming the whole palette. A free-form colour would be a caller-supplied string going into a dashboard’s style attribute, and a list where every row is a hand-picked shade is a list nobody can scan. Omit color and one is derived from the name, deterministically, so deleting a label and recreating it gives the same colour back.

Names are collapsed and trimmed, so Quote and Quote are one label, and they are unique per account. A duplicate is 409 whose details name the label it collided with, so a script importing categories learns which of its rows were new. At most 40 characters per name, 50 labels per account, and 20 labels per conversation.

Scopes

Reading labels needs chats:read and everything that changes one needs chats:manage. There is deliberately no new scope: a label is applied to a conversation and is invisible outside your account, which is strictly less visible than archiving or muting one, and a new scope is not carried by any key issued before it existed. Reusing the chat scopes means every key minted since chats arrived works with labels immediately.