Create label

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

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({name: '<string>', color: 123})
};

fetch('https://api.example.com/api/chat/tag/:instance', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/api/chat/tag/:instance"

payload = {
    "name": "<string>",
    "color": 123
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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

await fetch(`https://ryzeapi.cloud/api/chat/tag/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ name: "Premium" })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/chat/tag/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={"name": "Premium"}
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{"name":"Premium"}`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/chat/tag/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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

await fetch(`https://ryzeapi.cloud/api/chat/tag/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ name: "VIP", color: 5 })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/chat/tag/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={"name": "VIP", "color": 5}
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{"name":"VIP","color":5}`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/chat/tag/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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

string

required

Instance name.

Headers

Name	Required	Example	Description
`Content-Type`	yes	`application/json`	,
`token`	yes (or `Authorization`)	`a1b2c3d4-...`	TokenAccount or TokenInstance.

Request body

string

required

Label name. Cannot be empty after TrimSpace.

int

default:"0"

Label color. Accepts integers between 0 and 10, each index maps to a color from the native WhatsApp Business palette:

`color`	Hex	Color
`0`	`#ff9485`	Coral red
`1`	`#64c4ff`	Sky blue
`2`	`#ffd429`	Golden yellow
`3`	`#dfaef0`	Light lilac
`4`	`#99b6c1`	Bluish gray
`5`	`#55ccb3`	Mint green
`6`	`#ff9dff`	Pink
`7`	`#d3a91d`	Mustard
`8`	`#6d7cce`	Violet blue
`9`	`#d7e752`	Lime green
`10`	`#00d0e2`	Cyan

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

HTTP	`error.message`	When it happens
400	`Instance name is required`	Empty `:instance`.
400	`Invalid request body: <...>`	Malformed JSON.
400	`Tag name is required`	Empty `name`.
401	`Invalid token`	,
404	`Instance not found`	,
503	`Instance 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.

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

Description

Examples

Minimum

With color

Success response

Path parameters

Headers

Request body

Error responses

List labels

Assign to a chat

​Description

​Examples

​Minimum

​With color

​Success response

​Path parameters

​Headers

​Request body

​Error responses

​Related

List labels

Assign to a chat

Description

Examples

Minimum

With color

Success response

Path parameters

Headers

Request body

Error responses

Related