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

01plazbot 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`)
Fase	`--stage <stageId>`	No	Solo los contactos de esa fase (IDs con `plazbot workspace show stages`)
Agente	`--agent <userId>`	No	Solo los contactos asignados a ese usuario, incluidos archivados y ocultos (IDs con `plazbot 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

01# Últimos 50 contactos
02plazbot contacts list
03 
04# Contactos de una vista guardada, todas las páginas, en JSON
05plazbot contacts list --view viw_AbcDef123 --all --json
06 
07# Contactos asignados a un agente
08plazbot contacts list --agent usr_AbcDef123
09 
10# Contactos de una fase en otro workspace
11plazbot contacts list --stage mos_AbcDef123 -w wok_AbcDef123

Resultado

text

01  Contacts (3)
02  ────────────────────────────────────────
03┌───────────────────────────┬─────────────┬─────────────┬──────────┬─────────────┬──────────────────┐
04│ ID                        │ Name        │ Phone       │ Channel  │ Agent       │ Last message     │
05├───────────────────────────┼─────────────┼─────────────┼──────────┼─────────────┼──────────────────┤
06│ con_AbcDef123             │ Ana Torres  │ 51912345678 │ whatsapp │ Luis Pérez  │ 2026-10-06 17:32 │
07├───────────────────────────┼─────────────┼─────────────┼──────────┼─────────────┼──────────────────┤
08│ con_GhiJkl456             │ Carlos Ruiz │ 51987654321 │ whatsapp │ Luis Pérez  │ 2026-10-06 15:43 │
09├───────────────────────────┼─────────────┼─────────────┼──────────┼─────────────┼──────────────────┤
10│ con_MnoPqr789             │ Usuario     │ 573001234567│ calls    │ —           │ 2026-09-29 17:01 │
11└───────────────────────────┴─────────────┴─────────────┴──────────┴─────────────┴──────────────────┘
12  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

01{
02  "data": [
03    {
04      "id": "con_AbcDef123",
05      "name": "Ana",
06      "lastname": "Torres",
07      "internalWhatsappNumber": "51912345678",
08      "email": "ana@empresa.com",
09      "platformId": 2,
10      "stageId": "mos_AbcDef123",
11      "assignedAgentId": "usr_AbcDef123",
12      "assignedAgentName": "Luis Pérez",
13      "tags": [{ "id": "mot_AbcDef123", "name": "VIP", "color": "#22c55e" }],
14      "isRead": true,
15      "isSolved": false,
16      "lastMessage": "Gracias",
17      "lastMessageDate": "2026-10-06T17:32:08.404Z"
18    }
19  ],
20  "nextCursor": "[{\"token\":\"...\"}]"
21}

Pasa nextCursor tal cual a --cursor para la siguiente página. Ver paginación.

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`

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