Etiquetas

Las etiquetas son una funcionalidad de WhatsApp Business que te permite categorizar y organizar tus chats. A traves de la API de Wappfy, puedes crear etiquetas personalizadas, asignarlas a chats y recuperar chats por etiqueta.

Las etiquetas solo estan disponibles en cuentas de WhatsApp Business. Las cuentas personales de WhatsApp no soportan etiquetas.

Todos los endpoints de etiquetas estan asociados a una instancia especifica:

/api/instances/{instanceId}/labels/...

Crear una etiqueta

Crea una nueva etiqueta con un nombre y un color.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/labels \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP Customer",
    "color": 1
  }'

const response = await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/labels",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "VIP Customer",
      color: 1,
    }),
  }
);

const label = await response.json();
console.log(label.data.id);

Respuesta:

{
  "data": {
    "id": "1",
    "name": "VIP Customer",
    "color": 1
  }
}

Colores de etiquetas

WhatsApp Business soporta un conjunto fijo de colores de etiquetas identificados por numero:

ID de color	Color
`0`	Gris claro
`1`	Verde
`2`	Azul
`3`	Amarillo
`4`	Rosa/Rojo

Listar etiquetas

Recupera todas las etiquetas de la instancia.

curl https://api.wappfy.io/api/instances/inst_abc123/labels \
  -H "X-Api-Key: YOUR_API_KEY"

const response = await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/labels",
  {
    headers: { "X-Api-Key": "YOUR_API_KEY" },
  }
);

const { data } = await response.json();
data.forEach((label) => {
  console.log(`${label.id}: ${label.name} (color: ${label.color})`);
});

Respuesta:

{
  "data": [
    { "id": "1", "name": "New Customer", "color": 0 },
    { "id": "2", "name": "VIP Customer", "color": 1 },
    { "id": "3", "name": "Pending Payment", "color": 3 },
    { "id": "4", "name": "Resolved", "color": 2 }
  ]
}

Actualizar una etiqueta

Actualiza el nombre o el color de una etiqueta existente.

curl -X PUT https://api.wappfy.io/api/instances/inst_abc123/labels/2 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Customer",
    "color": 2
  }'

Eliminar una etiqueta

Elimina permanentemente una etiqueta. Esto quita la etiqueta de todos los chats a los que estaba asignada.

curl -X DELETE https://api.wappfy.io/api/instances/inst_abc123/labels/2 \
  -H "X-Api-Key: YOUR_API_KEY"

Eliminar una etiqueta la quita de todos los chats asociados. Esta accion no se puede deshacer.

Etiquetas de chat

Obtener etiquetas de un chat

Recupera todas las etiquetas asignadas a un chat especifico.

curl https://api.wappfy.io/api/instances/inst_abc123/labels/chats/5511999998888@s.whatsapp.net \
  -H "X-Api-Key: YOUR_API_KEY"

Respuesta:

{
  "data": [
    { "id": "1", "name": "New Customer", "color": 0 },
    { "id": "3", "name": "Pending Payment", "color": 3 }
  ]
}

Asignar etiquetas a un chat

Asigna una o mas etiquetas a un chat. Esto reemplaza cualquier etiqueta existente en el chat.

curl -X PUT https://api.wappfy.io/api/instances/inst_abc123/labels/chats/5511999998888@s.whatsapp.net \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label_ids": ["1", "2"]
  }'

await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/labels/chats/5511999998888@s.whatsapp.net",
  {
    method: "PUT",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      label_ids: ["1", "2"],
    }),
  }
);

Para quitar todas las etiquetas de un chat, pasa un array vacio: {"label_ids": []}.

Obtener chats por etiqueta

Recupera todos los chats que tienen asignada una etiqueta especifica.

curl https://api.wappfy.io/api/instances/inst_abc123/labels/2/chats \
  -H "X-Api-Key: YOUR_API_KEY"

const response = await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/labels/2/chats",
  {
    headers: { "X-Api-Key": "YOUR_API_KEY" },
  }
);

const { data } = await response.json();
console.log(`${data.length} chats with the "VIP Customer" label`);

Respuesta:

{
  "data": [
    {
      "chat_id": "5511999998888@s.whatsapp.net",
      "name": "Maria Silva"
    },
    {
      "chat_id": "5511888887777@s.whatsapp.net",
      "name": "Carlos Oliveira"
    }
  ]
}

Casos de uso comunes

Etiquetar nuevos leads automaticamente

Usa un webhook para escuchar eventos message.received. Cuando un mensaje llega de un contacto desconocido, asigna la etiqueta “Nuevo Lead” a traves de la API. Esto ayuda a tu equipo a identificar y priorizar rapidamente las nuevas conversaciones.

Seguimiento del estado de tickets de soporte

Crea etiquetas como “Abierto”, “En progreso” y “Resuelto”. Actualiza la etiqueta a medida que tu equipo trabaja en las solicitudes de soporte. Usa el endpoint “Obtener chats por etiqueta” para construir una cola de soporte sencilla.

Segmentar clientes para envios masivos

Etiqueta a los clientes por categoria (por ejemplo, “VIP”, “Mayorista”, “Minorista”). Al enviar mensajes masivos, obtiene todos los chats de una etiqueta y envia mensajes en un bucle.

Referencia de endpoints

Metodo	Endpoint	Descripcion
`POST`	`/api/instances/{id}/labels`	Crear una nueva etiqueta
`GET`	`/api/instances/{id}/labels`	Listar todas las etiquetas
`PUT`	`/api/instances/{id}/labels/{labelId}`	Actualizar una etiqueta
`DELETE`	`/api/instances/{id}/labels/{labelId}`	Eliminar una etiqueta
`GET`	`/api/instances/{id}/labels/chats/{chatId}`	Obtener etiquetas de un chat
`PUT`	`/api/instances/{id}/labels/chats/{chatId}`	Asignar etiquetas a un chat
`GET`	`/api/instances/{id}/labels/{labelId}/chats`	Obtener chats por etiqueta

Manejo de errores

Codigo de estado	Descripcion
`400`	Color de etiqueta invalido o faltan campos obligatorios.
`404`	Etiqueta o chat no encontrado.
`409`	Ya existe una etiqueta con el mismo nombre.
`422`	Formato de chat ID invalido.

Primeros Pasos

Guías

Etiquetas

Etiquetas

Crear una etiqueta

Colores de etiquetas

Listar etiquetas

Actualizar una etiqueta

Eliminar una etiqueta

Etiquetas de chat

Obtener etiquetas de un chat

Asignar etiquetas a un chat

Obtener chats por etiqueta

Casos de uso comunes

Referencia de endpoints

Manejo de errores

​Etiquetas

​Crear una etiqueta

​Colores de etiquetas

​Listar etiquetas

​Actualizar una etiqueta

​Eliminar una etiqueta

​Etiquetas de chat

​Obtener etiquetas de un chat

​Asignar etiquetas a un chat

​Obtener chats por etiqueta

​Casos de uso comunes

​Referencia de endpoints

​Manejo de errores

Etiquetas

Crear una etiqueta

Colores de etiquetas

Listar etiquetas

Actualizar una etiqueta

Eliminar una etiqueta

Etiquetas de chat

Obtener etiquetas de un chat

Asignar etiquetas a un chat

Obtener chats por etiqueta

Casos de uso comunes

Referencia de endpoints

Manejo de errores