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

​
Description

Assigns an existing label to a chat. If the label is already present on the chat, the operation is treated as success (idempotent). The change is propagated to WhatsApp via app state.

​
Example

curl -X POST "https://ryzeapi.cloud/api/chat/assignTag/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "tagId":  "2"
  }'

​
Success response

The response confirms the assignment by echoing the applied tag_id. chat_jid is not included when the handler delegates only to the service (omitempty fields); rely on success/message for the operation result.
200 OK
{
  "success": true,
  "message": "Tag assigned successfully",
  "tag_id": "2"
}

​
Path parameters

​
instance
string
required
Instance name.

​
Headers

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

​
Request body

​
number
string
required
Phone number (5511999999999), private JID (...@s.whatsapp.net or ...@lid), group JID (...@g.us), or newsletter.
​
tagId
string
required
ID of the label to assign.

​
Error responses

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

Unassign label

Remove the label from the chat.

Contacts by label

List every chat that has the label.