Crear etiqueta

POST

api

chat

tag

:instance

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

Descripción

Crea una etiqueta en la instancia. El id lo asigna la API (secuencial) y luego se propaga a WhatsApp vía app state, puede tardar 1 a 2 segundos en aparecer en el teléfono.

color es opcional (predeterminado 0) y acepta un entero entre 0 y 10, que corresponde a la paleta nativa de WhatsApp Business.

Ejemplos

Mínimo

Crea la etiqueta solo con name, sin color. El servidor asigna color: 0 por defecto y genera un id secuencial devuelto en la respuesta.

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

Con color

Crea la etiqueta “VIP” usando el tono 5 de la paleta de WhatsApp Business vía color: 5 (rango aceptado: 0 a 10), permitiendo diferenciar visualmente etiquetas en el teléfono.

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

Respuesta exitosa

El objeto tag lleva el id generado por WhatsApp (úsalo en tags-assign/tags-unassign), el name guardado, el color aplicado (0 cuando el cliente no lo envió o lo envió fuera del rango 0–10) y el type de la etiqueta. deleted se mantiene en false en las creaciones.

200 OK

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

Parámetros de ruta

string

requerido

Nombre de la instancia.

Cabeceras

Nombre	Requerido	Ejemplo	Descripción
`Content-Type`	sí	`application/json`	,
`token`	sí (o `Authorization`)	`a1b2c3d4-...`	TokenAccount o TokenInstance.

Cuerpo de la solicitud

string

requerido

Nombre de la etiqueta. No puede estar vacío después de TrimSpace.

int

predeterminado:"0"

Color de la etiqueta. Acepta enteros entre 0 y 10, cada índice mapea a un color de la paleta nativa de WhatsApp Business:

`color`	Hex	Color
`0`	`#ff9485`	Rojo coral
`1`	`#64c4ff`	Azul cielo
`2`	`#ffd429`	Amarillo dorado
`3`	`#dfaef0`	Lila claro
`4`	`#99b6c1`	Gris azulado
`5`	`#55ccb3`	Verde menta
`6`	`#ff9dff`	Rosa
`7`	`#d3a91d`	Mostaza
`8`	`#6d7cce`	Azul violeta
`9`	`#d7e752`	Verde lima
`10`	`#00d0e2`	Cian

Los valores anteriores reflejan la paleta actual de WhatsApp Business (puede cambiar en futuras versiones de la app, el índice es estable, el tono concreto lo define el cliente de WhatsApp). Los valores fuera del rango 0–10 se normalizan silenciosamente a 0.

Respuestas de error

HTTP	`error.message`	Cuándo ocurre
400	`Instance name is required`	`:instance` vacío.
400	`Invalid request body: <...>`	JSON malformado.
400	`Tag name is required`	`name` vacío.
401	`Invalid token`	,
404	`Instance not found`	,
503	`Instance is not connected to WhatsApp`	,

Error 400

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

Relacionados

Listar etiquetas

Confirma el id recién creado.

Asignar a un chat

Aplica la etiqueta tras crearla.

Introducción

Instancia

Eventos

Mensajes

Llamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidad

Descripción

Ejemplos

Mínimo

Con color

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Respuestas de error

Relacionados

Listar etiquetas

Asignar a un chat

​Descripción

​Ejemplos

​Mínimo

​Con color

​Respuesta exitosa

​Parámetros de ruta

​Cabeceras

​Cuerpo de la solicitud

​Respuestas de error

​Relacionados

Listar etiquetas

Asignar a un chat

Descripción

Ejemplos

Mínimo

Con color

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Respuestas de error

Relacionados