# Reportes

> plazbot reports: los reportes del dashboard (mensajes, contactos, agentes, llamadas...) para un rango de fechas.

Fuente: https://developers.plazbot.com/cli/reports/

### Obtener un reporte

Devuelve los mismos datos que los reportes del dashboard de Plazbot para un rango de fechas: mensajes, contactos nuevos, desempeño de agentes, llamadas, encuestas y más. También funciona como `plazbot report`.

```bash
plazbot reports <type> [options]
```

### Parámetros

| Parámetro | Flag | Requerido | Descripción |
|-----------|------|-----------|-------------|
| Tipo | `<type>` | Sí | Reporte a obtener (ver tabla de tipos). |
| Desde | `--from <date>` | No | Fecha inicial `YYYY-MM-DD`. Por defecto, hace 7 días. |
| Hasta | `--to <date>` | No | Fecha final `YYYY-MM-DD`. Por defecto, hoy. |
| Teléfono | `-p, --phone <number>` | No | Solo un número de WhatsApp del workspace. Solo en los reportes que lo admiten. |
| Parámetro extra | `-q, --query <key=value>` | No | Parámetro adicional para la API (repetible), por ejemplo `-q pipelineId=pip_AbcDef123`. |
| Workspace | `-w, --workspace <id>` | No | Workspace a consultar. Por defecto, el activo. |
| Zona | `-z, --zone <zone>` | No | `LA` o `EU`. Por defecto, la zona activa. |
| JSON | `--json` | No | Imprime el reporte como JSON. |

### Tipos de reporte

| Tipo | Contenido | Admite `-p` |
|------|-----------|-------------|
| `contacts` | Contactos nuevos por canal | Sí |
| `messages` | Mensajes enviados y recibidos (totales, por canal, por hora y día) | Sí |
| `conversations` | Conversaciones | Sí |
| `whatsapp` | Contactos de WhatsApp | Sí |
| `meta-analytics` | Analítica de WhatsApp de Meta. Necesita `-p` | Sí |
| `agents` | Carga actual por agente. No usa fechas | No |
| `agent-tracking` | Asignaciones y resoluciones por agente | No |
| `agent-details` | Detalle por agente | Sí |
| `ai-agents` | Actividad de los agentes de IA | No |
| `opportunities` | Oportunidades. Filtra por pipeline con `-q pipelineId=...` | No |
| `surveys` | Respuestas de encuestas | No |
| `calls` | Llamadas | No |
| `contacts-by-day` | Contactos nuevos por día | No |
| `tags` | Contactos por etiqueta | No |
| `appointments` | Citas | No |

Rangos muy largos pueden ser rechazados por la API (por ejemplo, el de mensajes admite hasta 60 días). Si necesitas más, divide el rango en varias llamadas.

### Ejemplos

```bash
# Mensajes de los últimos 7 días
plazbot reports messages

# Contactos nuevos de septiembre para un número
plazbot reports contacts --from 2026-09-01 --to 2026-09-30 -p +51912345678

# Desempeño de agentes en JSON
plazbot reports agent-tracking --from 2026-10-01 --to 2026-10-07 --json

# Total de mensajes de la semana
plazbot reports messages --json | jq '.data.totals.totalMessages'
```

### Resultado

Los reportes tienen estructuras distintas, así que el CLI los imprime como JSON indentado bajo un título con el rango:

```text
Report: messages (2026-10-01 → 2026-10-07)
────────────────────────────────────────
{
  "workspaceId": "wok_AbcDef123",
  "data": {
    "totals": {
      "totalMessages": 12,
      "incomingMessages": 4,
      "outgoingMessages": 8,
      "messagesHumans": 4,
      "messagesAgentIA": 0,
      "totalTemplatesSent": 4
    },
    "messagesPerMonthPerChannel": [ ... ],
    "messagesCreatedByHourAndDay": [ ... ]
  }
}
```

### Salida JSON

Con `--json` se imprime el mismo objeto sin el título. Su forma depende del tipo de reporte: es la respuesta de `GET /api/report/<ruta>` de la API.

### Errores comunes

| Mensaje | Causa | Solución |
|---------|-------|----------|
| `Unknown report "..."` | El tipo no existe | Usa un tipo de la tabla |
| `Dates must be YYYY-MM-DD.` | Formato de fecha incorrecto | Ejemplo: `--from 2026-10-01 --to 2026-10-07` |
| `The ... report does not filter by phone.` | Pasaste `-p` a un reporte que no lo admite | Quita `-p` |
| `Invalid phone number "..."` | Número sin código de país | Usa el formato internacional, por ejemplo `+51912345678` |