Dentro de cualquier worker (defineTool, defineWorker, defineWebhook, defineSchedule, defineSync) el contexto plz expone el modulo plz.contacts para trabajar con los contactos del workspace.
Listar contactos
01// Los 20 contactos con actividad mas reciente02const contacts = await plz.contacts.list();0304// Con limite, offset y filtros05const pendientes = await plz.contacts.list({06 filter: { isSolved: false },07 limit: 200,08});
Parametros de list
| Parametro | Tipo | Descripcion |
|---|---|---|
limit | number | Maximo de contactos a devolver. Default 20, tope 1000. |
offset | number | Cuantos contactos saltar antes de empezar a devolver. |
filter | object | Filtros opcionales (ver tabla). |
Filtros disponibles
| Filtro | Tipo | Coincide con... |
|---|---|---|
tags | string[] | Contactos que tienen todas las etiquetas (por id o por nombre). |
stage | string | El stageId del contacto. |
isSolved | boolean | Conversacion resuelta o pendiente. |
assignedAgentId | string | El agente asignado. |
search | string | Texto contenido en nombre, apellido, email o telefono. |
Los contactos vienen ordenados por ultima actividad (lastMessageDate descendente).
Recorrer todos los contactos (paginacion por cursor)
Para recorrer el universo completo del workspace usa listPage y repite con nextCursor hasta recibir null:
01import { defineSchedule } from 'plz/workers';0203export default defineSchedule({04 name: 'export-diario',05 reference: 'Recorre todos los contactos del workspace',06 cron: '0 6 * * *',07 async run(plz) {08 let cursor: string | null = null;09 let total = 0;1011 do {12 const page = await plz.contacts.listPage({ cursor, pageSize: 100 });1314 for (const contact of page.items) {15 // procesar cada contacto16 total++;17 }1819 cursor = page.nextCursor;20 } while (cursor);2122 plz.log.info(`Contactos recorridos: ${total}`);23 },24});
Parametros de listPage
| Parametro | Tipo | Descripcion |
|---|---|---|
pageSize | number | Tamano de pagina, entre 1 y 100. Default 20. |
cursor | string | null | El nextCursor de la pagina anterior. Omitir para la primera pagina. |
Respuesta
01{02 items: Contact[]; // los contactos de la pagina03 nextCursor: string | null; // pasar a la siguiente llamada; null = no hay mas04}
list vs listPage
| Usa... | Cuando... |
|---|---|
list | Necesitas un conjunto acotado (los ultimos N, los que cumplen un filtro). |
listPage | Necesitas recorrer o exportar todos los contactos del workspace. |
list con limit/offset itera paginas internamente por ti; para volumenes grandes listPage es mas eficiente y predecible.
Rate limits
Las llamadas de plz.contacts cuentan contra el limite de la API del workspace (120 req/min). Con pageSize: 100, recorrer 50.000 contactos son 500 llamadas — dentro del limite tarda unos 5 minutos.