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 módulo plz.contacts para trabajar con los contactos del workspace.

Listar contactos

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

Parámetros de list

ParámetroTipoDescripción
limitnumberMáximo de contactos a devolver. Default 20, tope 1000.
offsetnumberCuántos 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.
isSolvedbooleanConversación resuelta o pendiente.
assignedAgentIdstringEl agente asignado.
searchstringTexto contenido en nombre, email o teléfono.

Los contactos vienen ordenados por última actividad (lastMessageDate descendente).

Recorrer todos los contactos (paginación por cursor)

Para recorrer el universo completo del workspace usa listPage y repite con nextCursor hasta recibir null:

ts
01import { defineSchedule } from 'plazbot/workers';
02 
03export default defineSchedule({
04 name: 'export-diario',
05 reference: 'Recorre todos los contactos del workspace',
06 cron: '0 6 * * *',
07 async handler(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});

Parámetros de listPage

ParámetroTipoDescripción
pageSizenumberTamaño de página, entre 1 y 100. Default 20.
cursorstring | nullEl nextCursor de la página anterior. Omitir para la primera página.

Respuesta

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

list vs listPage

Usa...Cuando...
listNecesitas un conjunto acotado (los últimos N, los que cumplen un filtro).
listPageNecesitas recorrer o exportar todos los contactos del workspace.

list con limit/offset itera páginas internamente por ti; para volumenes grandes listPage es más eficiente y predecible.

Rate limits

Las llamadas de plz.contacts cuentan contra el límite de la API del workspace (120 req/min). Con pageSize: 100, recorrer 50.000 contactos son 500 llamadas ; dentro del límite tarda unos 5 minutos.

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