Producto
CLI

Runtime: Contactos

Listar, paginar y filtrar contactos desde un worker con plz.contacts

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

ts
01// Los 20 contactos con actividad mas reciente
02const contacts = await plz.contacts.list();
03 
04// Con limite, offset y filtros
05const pendientes = await plz.contacts.list({
06 filter: { isSolved: false },
07 limit: 200,
08});

Parametros de list

ParametroTipoDescripcion
limitnumberMaximo de contactos a devolver. Default 20, tope 1000.
offsetnumberCuantos contactos saltar antes de empezar a devolver.
filterobjectFiltros opcionales (ver tabla).

Filtros disponibles

FiltroTipoCoincide con...
tagsstring[]Contactos que tienen todas las etiquetas (por id o por nombre).
stagestringEl stageId del contacto.
isSolvedbooleanConversacion resuelta o pendiente.
assignedAgentIdstringEl agente asignado.
searchstringTexto 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:

ts
01import { defineSchedule } from 'plz/workers';
02 
03export 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;
10 
11 do {
12 const page = await plz.contacts.listPage({ cursor, pageSize: 100 });
13 
14 for (const contact of page.items) {
15 // procesar cada contacto
16 total++;
17 }
18 
19 cursor = page.nextCursor;
20 } while (cursor);
21 
22 plz.log.info(`Contactos recorridos: ${total}`);
23 },
24});

Parametros de listPage

ParametroTipoDescripcion
pageSizenumberTamano de pagina, entre 1 y 100. Default 20.
cursorstring | nullEl nextCursor de la pagina anterior. Omitir para la primera pagina.

Respuesta

ts
01{
02 items: Contact[]; // los contactos de la pagina
03 nextCursor: string | null; // pasar a la siguiente llamada; null = no hay mas
04}

list vs listPage

Usa...Cuando...
listNecesitas un conjunto acotado (los ultimos N, los que cumplen un filtro).
listPageNecesitas 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.

¿Quieres probar la API en vivo? Abre el Playground.