Etiquetas

Una etiqueta es un nombre y un color que pones en una conversación para ordenar tu bandeja de entrada. Las etiquetas son por cuenta, invisibles para la persona con la que hablas, y viajan con cada chat que lees.

De quién son estas etiquetas

Son etiquetas de Sendveo, no etiquetas de WhatsApp Business, y la diferencia no es cosmética. El servicio de mensajería no publica ninguna API de etiquetas: nada para listar las del teléfono, nada para aplicar una, nada para avisarte cuando se añade otra. No existía ninguna versión de esta función que leyera tus etiquetas reales, así que Sendveo sirve el mismo contrato desde su propio lado. Una etiqueta de Sendveo no aparece en WhatsApp en el teléfono, y una etiqueta del teléfono no aparece aquí. Si algún día aparece una API de etiquetas, estos endpoints y el campo labels de un chat se quedan exactamente igual y solo cambia lo que hay detrás.

Gestionar etiquetas

Listar, crear, renombrar, recolorear y eliminar. chatCount está en la lista y en ningún otro sitio: en una conversación sería un recuento por etiqueta y por fila.

curl -X POST https://api.sendveo.com/v1/labels \
  -H "X-API-KEY: sv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Quote sent", "color": "teal" }'

{
  "label": { "id": "lbl_m8k3x7q2", "name": "Quote sent", "color": "teal", "chatCount": 0 }
}

Eliminar una etiqueta la quita de todas las conversaciones que la llevan, y la respuesta dice cuántas en chats. Una etiqueta que desaparece de la lista pero sigue mostrándose en cuarenta chats sería peor que cualquiera de los dos estados.

Poner una en una conversación

Envía { labelId } para una etiqueta que ya tienes, o { name } para crearla y aplicarla en una sola llamada. La forma por nombre es lo que necesita un campo de escribir para añadir: la alternativa es listar, luego crear y luego aplicar, tres idas y vueltas para hacer una sola cosa, con una carrera en medio en la que dos pestañas crean la misma etiqueta.

curl -X POST https://api.sendveo.com/v1/chats/chat_9Fp2/labels \
  -H "X-API-KEY: sv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Urgent" }'

Aplicar una etiqueta que la conversación ya lleva devuelve un 200, no un conflicto: pediste un estado y el estado se cumple. Quitar una que no lleva devuelve un 404. La asimetría es deliberada, porque quitar una etiqueta que la conversación nunca tuvo casi siempre significa que quien llama trabaja con una lista caducada.

Etiquetas en un chat

Cada chat y cada grupo lleva labels, siempre presente y [] cuando no tiene ninguna. A diferencia de members, las etiquetas viajan también en la lista, no solo en la lectura individual: son una unión local, así que una página de cincuenta conversaciones cuesta una consulta más en vez de cincuenta llamadas al servicio de mensajería, y filtrar una bandeja de entrada por etiqueta es justo lo que la gente hace con ellas.

{
  "id": "cht_m8k3x7q2a1b4",
  "chatId": "chat_9Fp2",
  "name": "Khadija Alaoui",
  "labels": [
    { "id": "lbl_m8k3x7q2", "name": "Quote sent", "color": "teal" },
    { "id": "lbl_m8k3wp41", "name": "Urgent", "color": "rose" }
  ]
}

Nombres, colores y límites

color es un nombre de una paleta fija, nunca CSS: slate, violet, blue, teal, green, amber, orange, rose. Cualquier otra cosa devuelve un 400 VALIDATION_FAILED que nombra toda la paleta. Un color libre sería una cadena facilitada por quien llama que acabaría en el atributo de estilo de un panel, y una lista donde cada fila tiene su tono elegido a mano es una lista que nadie puede repasar. Omite color y se deriva uno del nombre, de forma determinista, así que borrar una etiqueta y volver a crearla devuelve el mismo color.

Los nombres se normalizan y se recortan, así que Presupuesto y Presupuesto son una sola etiqueta, y son únicos por cuenta. Un duplicado devuelve un 409 cuyos details nombran la etiqueta con la que chocó, de modo que un script que importa categorías sabe cuáles de sus filas eran nuevas. Como máximo 40 caracteres por nombre, 50 etiquetas por cuenta y 20 etiquetas por conversación.

Ámbitos

Leer etiquetas requiere chats:read y todo lo que cambia una requiere chats:manage. No hay ningún ámbito nuevo, y es deliberado: una etiqueta se aplica a una conversación y es invisible fuera de tu cuenta, lo cual es estrictamente menos visible que archivarla o silenciarla, y una clave emitida antes de que existiera un ámbito no lo lleva. Reutilizar los ámbitos de chats significa que toda clave creada desde que llegaron los chats funciona con etiquetas de inmediato.