# Listar contactos

> plazbot contacts list: lista los contactos del workspace en el orden de la bandeja, con filtros por vista, fase o agente

Fuente: https://developers.plazbot.com/cli/contacts/list/

### Listar contactos

Lista los contactos del workspace en el mismo orden que la bandeja de chats: primero los que tuvieron actividad más reciente. Puedes aplicar los filtros de una vista guardada, o filtrar por fase o por agente asignado.

```bash
plazbot contacts list [opciones]
```

### Parámetros

| Parámetro | Flag | Requerido | Descripción |
|-----------|------|-----------|-------------|
| Vista | `--view <viewId>` | No | Aplica los filtros de una vista guardada (IDs con [`plazbot views list`](https://developers.plazbot.com/cli/views/list)) |
| Fase | `--stage <stageId>` | No | Solo los contactos de esa fase (IDs con [`plazbot workspace show stages`](https://developers.plazbot.com/cli/workspace)) |
| Agente | `--agent <userId>` | No | Solo los contactos asignados a ese usuario, incluidos archivados y ocultos (IDs con [`plazbot team list`](https://developers.plazbot.com/cli/team/list)) |
| Tamaño de página | `--page-size <n>` | No | Contactos por request a la API, máximo 100. Por defecto `50` |
| Límite | `--limit <n>` | No | Para al llegar a N contactos (páginas completas). Por defecto `50` |
| Cursor | `--cursor <token>` | No | Continúa desde el `nextCursor` de una llamada anterior |
| Todos | `--all` | No | Trae todas las páginas, hasta 5000 contactos |
| JSON | `--json` | No | Imprime `{ data, nextCursor }` en JSON |
| Workspace | `-w, --workspace <id>` | No | Otro de tus workspaces (por defecto, el activo) |
| Zona | `-z, --zone <zone>` | No | `LA` o `EU` |

Sin `--agent`, igual que la bandeja, no aparecen los contactos archivados ni los ocultos del chat.

### Ejemplos

```bash
# Últimos 50 contactos
plazbot contacts list

# Contactos de una vista guardada, todas las páginas, en JSON
plazbot contacts list --view viw_AbcDef123 --all --json

# Contactos asignados a un agente
plazbot contacts list --agent usr_AbcDef123

# Contactos de una fase en otro workspace
plazbot contacts list --stage mos_AbcDef123 -w wok_AbcDef123
```

### Resultado

```text
Contacts (3)
────────────────────────────────────────
┌───────────────────────────┬─────────────┬─────────────┬──────────┬─────────────┬──────────────────┐
│ ID                        │ Name        │ Phone       │ Channel  │ Agent       │ Last message     │
├───────────────────────────┼─────────────┼─────────────┼──────────┼─────────────┼──────────────────┤
│ con_AbcDef123             │ Ana Torres  │ 51912345678 │ whatsapp │ Luis Pérez  │ 2026-10-06 17:32 │
├───────────────────────────┼─────────────┼─────────────┼──────────┼─────────────┼──────────────────┤
│ con_GhiJkl456             │ Carlos Ruiz │ 51987654321 │ whatsapp │ Luis Pérez  │ 2026-10-06 15:43 │
├───────────────────────────┼─────────────┼─────────────┼──────────┼─────────────┼──────────────────┤
│ con_MnoPqr789             │ Usuario     │ 573001234567│ calls    │ —           │ 2026-09-29 17:01 │
└───────────────────────────┴─────────────┴─────────────┴──────────┴─────────────┴──────────────────┘
More results available: add --all, or use --json and pass its nextCursor to --cursor.
```

| Columna | Descripción |
|---------|-------------|
| Channel | `whatsapp`, `webchat`, `facebook`, `instagram`, `telegram`, `portal`, `code`, `calls`, `facebook-leads`, `tickos` o `tiktok` |
| Last message | Fecha del último mensaje, en UTC |

### Salida JSON

Cada elemento es el contacto completo, con todos sus campos (etiquetas, variables, fase, seguimiento...):

```json
{
"data": [
  {
    "id": "con_AbcDef123",
    "name": "Ana",
    "lastname": "Torres",
    "internalWhatsappNumber": "51912345678",
    "email": "ana@empresa.com",
    "platformId": 2,
    "stageId": "mos_AbcDef123",
    "assignedAgentId": "usr_AbcDef123",
    "assignedAgentName": "Luis Pérez",
    "tags": [{ "id": "mot_AbcDef123", "name": "VIP", "color": "#22c55e" }],
    "isRead": true,
    "isSolved": false,
    "lastMessage": "Gracias",
    "lastMessageDate": "2026-10-06T17:32:08.404Z"
  }
],
"nextCursor": "[{\"token\":\"...\"}]"
}
```

Pasa `nextCursor` tal cual a `--cursor` para la siguiente página. Ver [paginación](https://developers.plazbot.com/cli/ia/scripting).

### Errores comunes

| Mensaje | Causa | Solución |
|---------|-------|----------|
| `No contacts found` | No hay contactos con esos filtros | Revisa la vista, la fase o el agente |
| `Invalid --limit "..."` | `--limit` no es un número positivo | Usa un entero, o `--all` |
| `You are not signed in.` | Sin sesión | Ejecuta [`plazbot login`](https://developers.plazbot.com/cli/login) |

Con sesiones de variables de entorno, define `PLAZBOT_USER_ID` para que funcionen las vistas filtradas por "usuario actual".