Skip to main content
GET
/
conversations
/
v1
curl -X GET "https://api.whaapy.com/conversations/v1?status=active&limit=10" \
  -H "Authorization: Bearer wha_xxxxx"

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "phoneNumber": "+5215512345678",
      "contactName": "Juan Pérez",
      "profilePictureUrl": "https://...",
      "lastMessageAt": "2026-01-29T10:30:00Z",
      "lastMessagePreview": "Hola, ¿tienen disponibilidad?",
      "unreadCount": 2,
      "status": "active",
      "contact": {
        "id": "uuid",
        "name": "Juan Pérez",
        "email": "juan@ejemplo.com",
        "tags": ["cliente-nuevo"],
        "funnelStage": {
          "id": "uuid",
          "name": "Interesado",
          "color": "#3B82F6"
        }
      },
      "settings": {
        "aiEnabled": true,
        "aiPausedUntil": null
      },
      "assignedTo": {
        "agentId": "uuid",
        "agentName": "María García"
      },
      "createdAt": "2026-01-28T08:00:00Z"
    }
  ],
  "meta": {
    "total": 150,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

​
Parámetros de Query

​
status
string
default:"all"
Filtrar por estado: all, active, closed, archived
​
search
string
Buscar por nombre de contacto, teléfono o email
​
limit
number
default:"20"
Número de resultados (máximo 100)
​
offset
number
default:"0"
Offset para paginación
​
filters
string
Filtros avanzados en formato JSON (ver ejemplos abajo)

​
Filtros avanzados

El parámetro filters acepta un JSON URL-encoded con las siguientes opciones: 
{
  "statusFilter": "unread",        // unread, ai-paused, ai-active, needs-attention
  "stageId": "uuid",               // Etapa del funnel
  "tags": ["vip", "nuevo"],        // Tags del contacto (OR)
  "assignedTo": "me",              // "me", "none", o UUID de agente
  "updatedFilter": "today",        // today, week, month
  "inactiveDays": 7                // Días sin actividad
}
FiltroValoresDescripción
statusFilterunread, ai-paused, ai-active, needs-attentionEstado de la conversación
stageIdUUIDEtapa del funnel de ventas
tagsArray de stringsTags del contacto (match OR)
assignedTome, none, UUIDAsignación del agente
updatedFiltertoday, week, monthFiltro de tiempo
inactiveDays1-365Días de inactividad
curl -X GET "https://api.whaapy.com/conversations/v1?status=active&limit=10" \
  -H "Authorization: Bearer wha_xxxxx"

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "phoneNumber": "+5215512345678",
      "contactName": "Juan Pérez",
      "profilePictureUrl": "https://...",
      "lastMessageAt": "2026-01-29T10:30:00Z",
      "lastMessagePreview": "Hola, ¿tienen disponibilidad?",
      "unreadCount": 2,
      "status": "active",
      "contact": {
        "id": "uuid",
        "name": "Juan Pérez",
        "email": "juan@ejemplo.com",
        "tags": ["cliente-nuevo"],
        "funnelStage": {
          "id": "uuid",
          "name": "Interesado",
          "color": "#3B82F6"
        }
      },
      "settings": {
        "aiEnabled": true,
        "aiPausedUntil": null
      },
      "assignedTo": {
        "agentId": "uuid",
        "agentName": "María García"
      },
      "createdAt": "2026-01-28T08:00:00Z"
    }
  ],
  "meta": {
    "total": 150,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

​
Campos de respuesta

CampoTipoDescripción
idstringUUID de la conversación
phoneNumberstringNúmero de WhatsApp del contacto
contactNamestringNombre del contacto
lastMessageAtstringFecha del último mensaje (ISO 8601)
lastMessagePreviewstringPreview del último mensaje (truncado)
unreadCountnumberMensajes no leídos
statusstringEstado: active, closed, archived
contactobjectDatos del contacto asociado
settingsobjectConfiguración de IA para esta conversación
assignedToobjectAgente asignado (si aplica)
meta.totalnumberTotal de conversaciones que coinciden
meta.hasMorebooleanSi hay más páginas disponibles
Usa filters con assignedTo: "none" para encontrar conversaciones sin asignar que necesitan atención.

​
Errores comunes

{
  "error": "Missing API Key",
  "message": "Authorization header required. Format: \"Bearer wha_xxxxx\""
}

{
  "error": "Insufficient permissions",
  "message": "This API Key does not have the required scope: conversations:read"
}