Skip to main content
POST
/
api
/
chat
/
tag
/
:instance
Create label
curl --request POST \
  --url https://api.example.com/api/chat/tag/:instance \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "color": 123
}
'
Auth: TokenAccount or TokenInstance • Rate-limit: Global (100/min) • Idempotent: no

​
Description

Creates a label on the instance. The id is allocated by the API (sequential) and then propagated to WhatsApp via app state, it may take 1 to 2 seconds to appear on the phone.
color is optional (default 0) and accepts an integer between 0 and 10, which corresponds to the native WhatsApp Business palette.

​
Examples

​
Minimum

Creates the label with name only, without color. The server assigns color: 0 by default and generates a sequential id returned in the response. 
curl -X POST "https://ryzeapi.cloud/api/chat/tag/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{"name":"Premium"}'

​
With color

Creates the “VIP” label using shade 5 of the WhatsApp Business palette via color: 5 (accepted range: 0 to 10), enabling visual differentiation between labels on the phone. 
curl -X POST "https://ryzeapi.cloud/api/chat/tag/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{"name":"VIP","color":5}'

​
Success response

The tag object carries the id generated by WhatsApp (use it in tags-assign/tags-unassign), the saved name, the applied color (0 when the client did not send it or sent it outside the 0–10 range), and the label type. deleted stays false on creations.
200 OK
{
  "success": true,
  "message": "Tag created successfully",
  "tag": {
    "id": "3",
    "name": "VIP",
    "color": 5,
    "type": "CUSTOM",
    "deleted": false
  }
}

​
Path parameters

​
instance
string
required
Instance name.

​
Headers

NameRequiredExampleDescription
Content-Typeyesapplication/json,
tokenyes (or Authorization)a1b2c3d4-...TokenAccount or TokenInstance.

​
Request body

​
name
string
required
Label name. Cannot be empty after TrimSpace.
​
color
int
default:"0"
Label color. Accepts integers between 0 and 10, each index maps to a color from the native WhatsApp Business palette:
colorHexColor
0#ff9485Coral red
1#64c4ffSky blue
2#ffd429Golden yellow
3#dfaef0Light lilac
4#99b6c1Bluish gray
5#55ccb3Mint green
6#ff9dffPink
7#d3a91dMustard
8#6d7cceViolet blue
9#d7e752Lime green
10#00d0e2Cyan
The values above reflect the current WhatsApp Business palette (it may change in future versions of the app, the index is stable, the actual shade is defined by the WhatsApp client). Values outside the 0–10 range are silently normalized to 0.

​
Error responses

HTTPerror.messageWhen it happens
400Instance name is requiredEmpty :instance.
400Invalid request body: <...>Malformed JSON.
400Tag name is requiredEmpty name.
401Invalid token,
404Instance not found,
503Instance is not connected to WhatsApp,
Error 400
{
  "success": false,
  "error": { "message": "Tag name is required" }
}

List labels

Confirm the newly created id.

Assign to a chat

Apply the label after creating it.