Criar etiqueta

POST

api

chat

tag

:instance

Criar etiqueta

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 ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: não

Descrição

Cria uma etiqueta na instância. O id é alocado pela API (sequencial) e depois propagado ao WhatsApp via app state, pode levar 1 a 2 segundos para aparecer no celular.

color é opcional (default 0) e aceita um inteiro entre 0 e 10, que corresponde à paleta nativa do WhatsApp Business.

Exemplos

Mínimo

Cria a etiqueta apenas com name, sem cor. O servidor atribui color: 0 por padrão e gera um id sequencial retornado na resposta.

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

Com cor

Cria a etiqueta “VIP” usando o tom 5 da paleta do WhatsApp Business via color: 5 (faixa aceita: 0 a 10), permitindo diferenciar etiquetas visualmente no celular.

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

Resposta de sucesso

O objeto tag traz o id gerado pelo WhatsApp (use-o em tags-atribuir/tags-desatribuir), o name salvo, a color aplicada (0 quando o cliente não enviou ou enviou fora da faixa 0–10) e o type da etiqueta. deleted permanece false em criações.

200 OK

{
  "success": true,
  "message": "Tag created successfully",
  "tag": {
    "id": "3",
    "name": "VIP",
    "color": 5,
    "type": "CUSTOM",
    "deleted": false
  }
}

Parâmetros de rota

string

obrigatório

Nome da instância.

Headers

Nome	Obrigatório	Exemplo	Descrição
`Content-Type`	sim	`application/json`	,
`token`	sim (ou `Authorization`)	`a1b2c3d4-...`	TokenAccount ou TokenInstance.

Request body

string

obrigatório

Nome da etiqueta. Não pode estar vazio após TrimSpace.

int

padrão:"0"

Cor da etiqueta. Aceita inteiros entre 0 e 10, cada índice mapeia para uma cor da paleta nativa do WhatsApp Business:

`color`	Hex	Cor
`0`	`#ff9485`	Vermelho coral
`1`	`#64c4ff`	Azul céu
`2`	`#ffd429`	Amarelo dourado
`3`	`#dfaef0`	Lilás claro
`4`	`#99b6c1`	Cinza azulado
`5`	`#55ccb3`	Verde menta
`6`	`#ff9dff`	Rosa pink
`7`	`#d3a91d`	Mostarda
`8`	`#6d7cce`	Azul violeta
`9`	`#d7e752`	Verde limão
`10`	`#00d0e2`	Ciano

Os valores acima refletem a paleta atual do WhatsApp Business (pode mudar em versões futuras do app, o índice é estável, o tom em si é definido pelo cliente WhatsApp). Valores fora da faixa 0–10 são silenciosamente normalizados para 0.

Respostas de erro

HTTP	`error.message`	Quando ocorre
400	`Instance name is required`	`:instance` vazio.
400	`Invalid request body: <...>`	JSON malformado.
400	`Tag name is required`	`name` vazio.
401	`Invalid token`	,
404	`Instance not found`	,
503	`Instance is not connected to WhatsApp`	,

Erro 400

{
  "success": false,
  "error": { "message": "Tag name is required" }
}

Relacionados

Listar etiquetas

Conferir o id recém-criado.

Atribuir a um chat

Aplicar a etiqueta após criar.

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Descrição

Exemplos

Mínimo

Com cor

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Respostas de erro

Relacionados

Listar etiquetas

Atribuir a um chat

​Descrição

​Exemplos

​Mínimo

​Com cor

​Resposta de sucesso

​Parâmetros de rota

​Headers

​Request body

​Respostas de erro

​Relacionados

Listar etiquetas

Atribuir a um chat

Descrição

Exemplos

Mínimo

Com cor

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Respostas de erro

Relacionados