Saltar al contenido principal

​
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
  }'
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 colorColor
0Gris claro
1Verde
2Azul
3Amarillo
4Rosa/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"
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/[email protected] \
  -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/[email protected] \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
Respuesta: 
{
  "data": [
    {
      "chat_id": "[email protected]",
      "name": "Maria Silva"
    },
    {
      "chat_id": "[email protected]",
      "name": "Carlos Oliveira"
    }
  ]
}

​
Casos de uso comunes

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.
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.
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

MetodoEndpointDescripcion
POST/api/instances/{id}/labelsCrear una nueva etiqueta
GET/api/instances/{id}/labelsListar 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}/chatsObtener chats por etiqueta

​
Manejo de errores

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