🏷️ Labels

You can work with WhatsApp Labels available in WhatsApp Business using the API!

Features#

Here’s the list of features that are available by 🏭 Engines:

Label color#

You’ll see two color-related fields in the body and response:

• color: 1 - internal color number, 0-19 values.
• colorHex: #64c4ff - is the latest known hex color for the label

⚠️ It’s possible that color - colorHex map will be changed, so consider using color value instead when creating or updating labels.

Here’s the current color map (color - colorHex - preview):

• 0 - #ff9485 -
• 1 - #64c4ff -
• 2 - #ffd429 -
• 3 - #dfaef0 -
• 4 - #99b6c1 -
• 5 - #55ccb3 -
• 6 - #ff9dff -
• 7 - #d3a91d -
• 8 - #6d7cce -
• 9 - #d7e752 -
• 10 - #00d0e2 -
• 11 - #ffc5c7 -
• 12 - #93ceac -
• 13 - #f74848 -
• 14 - #00a0f2 -
• 15 - #83e422 -
• 16 - #ffaf04 -
• 17 - #b5ebff -
• 18 - #9ba6ff -
• 19 - #9368cf -

Label type and lists#

WhatsApp keeps its chat lists (Unread, Favourites, Groups and others) in the same place as labels, so the API returns them next to your labels.

Two fields tell them apart (ListType enum in the proto):

• type - WhatsApp list type:
  • 5 - CUSTOM - a label you created
  • 4 - PREDEFINED - a label created from a WhatsApp template (New customer, New order, …)
  • 16 - LEAD - the leads list
  • missing or 0 - NONE - a label created before WhatsApp added lists
  • 1 - UNREAD, 2 - GROUPS, 3 - FAVORITES and others - built-in lists.
• isActive - false for lists the user turned off

👉 Built-in lists can be read and renamed, but you can not add chats to them via API.

WPP doesn’t return type and isActive.

API#

Get labels#

You can get a list of labels for the session using the endpoint:

GET /api/{session}/labels

[
  {
    "id": "1",
    "name": "New Client",
    "color": 1,
    "colorHex": "#64c4ff",
    "type": 5,
    "isActive": true
  },
  ...
]

Create label#

POST /api/{session}/labels

Using color

{
  "name": "New Client",
  "color": 1
}

Using colorHex

{
  "name": "New Client",
  "colorHex" : "#64c4ff"
}

Update label#

PUT /api/{session}/labels/{labelId}

Using color

{
  "name": "New Client",
  "color": 1
}

Using colorHex

{
  "name": "New Client",
  "colorHex" : "#64c4ff"
}

Delete label#

DELETE /api/{session}/labels/{labelId}

Get chats by label id#

You can get a list of chats by label id using the endpoint:

GET /api/{session}/labels/{labelId}/chats

ℹ️ The response format currently depends on the 🏭 Engine you’re using, similar to how it works with 💬 Chats

Get labels by chat id#

You can get a list of labels by chat id using the endpoint:

GET /api/{session}/labels/chats/{chatId}/

[
  {
    "id": "1",
    "name": "New Client",
    "color": 1,
    "colorHex": "#64c4ff",
    "type": 5,
    "isActive": true
  },
  ...
]

Update labels to chat#

PUT /api/{session}/labels/chats/{chatId}/

Upsert label:

👉 You need to provide the full list of labels you want to set to the chat. All other labels will be removed.

{
  "labels": [
    {
      "id": "1"
    }
  ]
}

Remove labels:

{
  "labels": []
}

Events#

Read more about 🔄 Events.

label.upsert#

{
  "event": "label.upsert",
  "session": "default",
  "payload": {
    "id": "10",
    "name": "Label Name",
    "color": 14,
    "colorHex": "#00a0f2"
  },
  "engine": "NOWEB",
  ...
}

label.deleted#

{
  "event": "label.deleted",
  "session": "default",
  "payload": {
    "id": "10",
    "name": "",
    "color": 14,
    "colorHex": "#00a0f2"
  },
  "engine": "NOWEB",
  ...
}

label.chat.added#

{
  "event": "label.chat.added",
  "session": "default",
  "payload": {
    "labelId": "6",
    "chatId": "11111111111@c.us",
    "label": null  // Note: This can be null right after scanning QR code
  },
  "engine": "NOWEB",
  ...
}

label.chat.deleted#

{
  "event": "label.chat.deleted",
  "session": "default",
  "payload": {
    "labelId": "6",
    "chatId": "11111111111@c.us",
    "label": null
  },
  "engine": "NOWEB",
  ...
}