curl -X GET "https://api.whaapy.com/conversations/v1?status=active&limit=10" \
-H "Authorization: Bearer wha_xxxxx"
const response = await fetch(
'https://api.whaapy.com/conversations/v1?status=active&limit=10',
{
headers: {
'Authorization': 'Bearer wha_xxxxx'
}
}
);
const data = await response.json();
import requests
response = requests.get(
'https://api.whaapy.com/conversations/v1',
params={'status': 'active', 'limit': 10},
headers={'Authorization': 'Bearer wha_xxxxx'}
)
data = response.json()
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.whaapy.com/conversations/v1?status=active&limit=10",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer wha_xxxxx"
],
]);
$response = curl_exec($curl);
$data = json_decode($response, true);
{
"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
}
}
Conversaciones
Listar Conversaciones
Obtén todas las conversaciones con filtros y paginación
GET
/
conversations
/
v1
curl -X GET "https://api.whaapy.com/conversations/v1?status=active&limit=10" \
-H "Authorization: Bearer wha_xxxxx"
const response = await fetch(
'https://api.whaapy.com/conversations/v1?status=active&limit=10',
{
headers: {
'Authorization': 'Bearer wha_xxxxx'
}
}
);
const data = await response.json();
import requests
response = requests.get(
'https://api.whaapy.com/conversations/v1',
params={'status': 'active', 'limit': 10},
headers={'Authorization': 'Bearer wha_xxxxx'}
)
data = response.json()
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.whaapy.com/conversations/v1?status=active&limit=10",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer wha_xxxxx"
],
]);
$response = curl_exec($curl);
$data = json_decode($response, true);
{
"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
string
default:"all"
Filtrar por estado:
all, active, closed, archivedstring
Buscar por nombre de contacto, teléfono o email
number
default:"20"
Número de resultados (máximo 100)
number
default:"0"
Offset para paginación
string
Filtros avanzados en formato JSON (ver ejemplos abajo)
Filtros avanzados
El parámetrofilters 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
}
| Filtro | Valores | Descripción |
|---|---|---|
statusFilter | unread, ai-paused, ai-active, needs-attention | Estado de la conversación |
stageId | UUID | Etapa del funnel de ventas |
tags | Array de strings | Tags del contacto (match OR) |
assignedTo | me, none, UUID | Asignación del agente |
updatedFilter | today, week, month | Filtro de tiempo |
inactiveDays | 1-365 | Días de inactividad |
curl -X GET "https://api.whaapy.com/conversations/v1?status=active&limit=10" \
-H "Authorization: Bearer wha_xxxxx"
const response = await fetch(
'https://api.whaapy.com/conversations/v1?status=active&limit=10',
{
headers: {
'Authorization': 'Bearer wha_xxxxx'
}
}
);
const data = await response.json();
import requests
response = requests.get(
'https://api.whaapy.com/conversations/v1',
params={'status': 'active', 'limit': 10},
headers={'Authorization': 'Bearer wha_xxxxx'}
)
data = response.json()
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.whaapy.com/conversations/v1?status=active&limit=10",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer wha_xxxxx"
],
]);
$response = curl_exec($curl);
$data = json_decode($response, true);
{
"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
| Campo | Tipo | Descripción |
|---|---|---|
id | string | UUID de la conversación |
phoneNumber | string | Número de WhatsApp del contacto |
contactName | string | Nombre del contacto |
lastMessageAt | string | Fecha del último mensaje (ISO 8601) |
lastMessagePreview | string | Preview del último mensaje (truncado) |
unreadCount | number | Mensajes no leídos |
status | string | Estado: active, closed, archived |
contact | object | Datos del contacto asociado |
settings | object | Configuración de IA para esta conversación |
assignedTo | object | Agente asignado (si aplica) |
meta.total | number | Total de conversaciones que coinciden |
meta.hasMore | boolean | Si 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"
}
Was this page helpful?