Plazbot Help Center · Help Center

Los Workers son funciones TypeScript que extienden las capacidades de tu workspace en Plazbot. Permiten ejecutar logica personalizada que se integra con el Agente de IA, responde a eventos externos, o se ejecuta de forma programada.

Para que sirven

Conectar tu agente con APIs externas (inventario, CRM, pagos).
Procesar webhooks de servicios como Stripe, Shopify o MercadoPago.
Ejecutar tareas programadas (reportes, sincronizaciones, alertas).
Automatizar operaciones sobre contactos, conversaciones y variables.

Requisitos previos

Advertencia: Antes de usar workers, debes configurar los siguientes secrets obligatorios desde el tab Developers > Secrets en el dashboard. Sin estos secrets, ningun worker podra ejecutarse.
Secret
Descripcion
PLZ_API_KEY
Token de acceso a la API de Plazbot. Permite que los workers interactuen con contactos, conversaciones, templates y demas recursos del workspace.
PLZ_ZONE
Region del workspace (LA para Latinoamerica, EU para Europa). Determina a que servidor de API se conectan los workers.
Para configurarlos facilmente, haz click en el boton "Configurar Secrets de Plazbot" que aparece en el tab Secrets. Este genera el token automaticamente y detecta la zona de tu workspace.

Secret	Descripcion
`PLZ_API_KEY`	Token de acceso a la API de Plazbot. Permite que los workers interactuen con contactos, conversaciones, templates y demas recursos del workspace.
`PLZ_ZONE`	Region del workspace (`LA` para Latinoamerica, `EU` para Europa). Determina a que servidor de API se conectan los workers.

Estructura de un Worker

Cada worker es un archivo .ts que importa una funcion define* del SDK de Plazbot y exporta su configuracion junto con un handler.

typescript

01 
02  name: 'mi-herramienta',
03  reference: 'Descripcion de lo que hace esta herramienta',
04  agents: ['id_del_agente'],
05  parameters: [
06    { name: 'query', type: 'string', description: 'Parametro requerido' }
07  ],
08 
09  async run(payload, plz) {
10    // Logica del worker
11    return { resultado: 'ok' }
12  }
13})

Partes principales:

Parte	Descripcion
`import`	Importa la funcion define* correspondiente al tipo de worker.
`name`	Nombre unico del worker dentro del workspace.
`reference`	Descripcion del worker. En tools, el agente usa esta descripcion para decidir cuando invocarlo.
`run(payload, plz)`	Funcion handler que contiene la logica. Recibe el payload y el contexto `plz`.

Ciclo de vida

Escribir Crea un archivo .ts con la definicion del worker usando una de las funciones define*.
Desplegar Usa el CLI (plazbot workers deploy mi-worker.ts) o el editor del dashboard para subir el worker al workspace.
Ejecutar El worker se ejecuta automaticamente segun su tipo: el agente lo invoca (tool), un cron lo dispara (schedule/sync), un HTTP request lo activa (webhook), o se ejecuta bajo demanda (worker).

Integración con el Agente de IA

Los workers se integran con el Agente de IA a traves de las Acciones del Agente. Dentro de la configuracion de acciones, puedes usar el tipo action.worker para invocar un worker cuando el agente detecta una intencion.

Advertencia ⚠️: El tipo action.worker en las acciones del agente solo soporta workers de tipo worker (definidos con defineWorker). No puedes invocar directamente un tool, schedule o webhook desde una accion del agente.

Los workers de tipo tool (defineTool) se integran de forma diferente: se registran directamente como herramientas del agente mediante el campo agents, y el agente los invoca automaticamente durante la conversacion cuando lo considera necesario.

Campos comunes del define*

Todos los tipos de workers comparten estos campos de configuracion:

Campo	Tipo	Requerido	Descripcion
`name`	`string`	Si	Nombre unico del worker. Se usa como identificador en el workspace.
`reference`	`string`	No	Descripcion del proposito del worker.

Cada tipo agrega campos adicionales segun su funcion. Consulta la pagina de Tipos para ver los campos especificos.

Runtime

Los workers se ejecutan en un entorno aislado de Plazbot con acceso al contexto plz, que provee metodos para interactuar con la plataforma. El codigo TypeScript se compila a JavaScript antes del despliegue.

Tip: No necesitas instalar dependencias externas. El runtime provee automaticamente el SDK plz con acceso a contactos, WhatsApp, templates, key-value store y mas. Consulta la pagina de Contexto para ver todos los métodos disponibles.

Tipos de Workers

Existen 5 tipos de workers, cada uno diseñado para un caso de uso diferente. El tipo se define por la funcion define* que utilices.

Tabla comparativa

Tipo	Funcion	Trigger	Uso principal
Tool	`defineTool`	El agente IA lo invoca	Consultas a APIs durante conversaciones
Worker	`defineWorker`	Bajo demanda (API, acciones, otros workers)	Logica de negocio reutilizable
Sync	`defineSync`	Cron programado	Sincronizacion periodica de datos
Schedule	`defineSchedule`	Cron programado	Tareas automaticas recurrentes
Webhook	`defineWebhook`	HTTP request externo	Recibir eventos de servicios externos

Tool (`defineTool`)

Herramientas que el agente IA puede invocar durante una conversacion. Ideales para consultas a APIs externas, busquedas en base de datos, o cualquier operacion en tiempo real.

Campos de configuracion:

Campo	Tipo	Descripcion
`name`	`string`	Nombre unico del tool.
`reference`	`string`	Descripcion para que el agente entienda cuando usarlo.
`agents`	`string[]`	IDs de los agentes que pueden invocar este tool.
`parameters`	`array`	Parametros que el agente debe recopilar del usuario.

Signature del handler:

typescript

01async run(payload, plz) {
02  // payload contiene los parametros + contactId
03  // Retorna datos que el agente usara en su respuesta
04  return { ... }
05}

Cada parametro tiene:

Campo	Tipo	Descripcion
`name`	`string`	Nombre del parametro.
`type`	`string`	Tipo: `string`, `number`, `array`, `boolean`.
`description`	`string`	Descripcion para que el agente sepa que pedir al usuario.
`example`	`string`	Ejemplo de pregunta que el agente puede hacer.

Ejemplo:

typescript

01 
02  name: 'consultar-stock',
03  reference: 'Consulta disponibilidad de productos en inventario',
04  agents: ['agent_abc123'],
05  parameters: [
06    { name: 'producto', type: 'string', description: 'Nombre del producto' }
07  ],
08 
09  async run(payload, plz) {
10    const res = await fetch(`${plz.env.API_URL}/stock?q=${payload.producto}`)
11    return await res.json()
12  }
13})

Worker (`defineWorker`)

Funciones de proposito general invocadas bajo demanda. Se ejecutan desde automatizaciones, acciones del agente (action.worker), otros workers o la API.

Campos de configuracion:

Campo	Tipo	Descripcion
`name`	`string`	Nombre unico del worker.
`reference`	`string`	Descripcion del proposito.

Signature del handler:

typescript

01async run(payload, plz) {
02  // payload contiene los datos enviados al ejecutar
03  // payload.contactId y payload.contact disponibles si se invoca desde una accion
04  return { ... }
05}

Ejemplo:

typescript

01 
02  name: 'notificar-equipo',
03  reference: 'Envia notificacion al equipo por Slack',
04 
05  async run(payload, plz) {
06    const { contactId, mensaje } = payload
07 
08    plz.log.info('Enviando notificacion', { contactId })
09 
10    await fetch(plz.env.SLACK_WEBHOOK, {
11      method: 'POST',
12      headers: { 'Content-Type': 'application/json' },
13      body: JSON.stringify({ text: mensaje })
14    })
15 
16    return { success: true }
17  }
18})

Tip: Este es el unico tipo de worker que puede ser invocado desde las acciones del agente de IA usando action.worker.

Sync (`defineSync`)

Sincronizaciones programadas que mantienen datos actualizados entre la plataforma y sistemas externos. Se ejecutan en intervalos regulares via cron.

Campos de configuracion:

Campo	Tipo	Descripcion
`name`	`string`	Nombre unico del sync.
`reference`	`string`	Descripcion del proposito.
`cron`	`string`	Expresion cron que define la frecuencia.
`timezone`	`string`	Zona horaria para el cron (ej: `America/Mexico_City`).

Signature del handler:

typescript

01async run(plz) {
02  // No recibe payload - se ejecuta automaticamente
03  return { ... }
04}

Ejemplo:

typescript

01 
02  name: 'sync-crm-contacts',
03  reference: 'Sincroniza contactos modificados en el CRM',
04  cron: '*/30 * * * *',
05  timezone: 'America/Lima',
06 
07  async run(plz) {
08    const contacts = await plz.contacts.list({ limit: 100 })
09    // ... logica de sincronizacion
10    return { synced: 15 }
11  }
12})

Schedule (`defineSchedule`)

Tareas programadas que se ejecutan automaticamente en horarios definidos. Utiles para reportes, limpiezas, notificaciones periodicas y mas.

Campos de configuracion:

Campo	Tipo	Descripcion
`name`	`string`	Nombre unico del schedule.
`reference`	`string`	Descripcion del proposito.
`cron`	`string`	Expresion cron que define cuando se ejecuta.
`timezone`	`string`	Zona horaria para el cron.

Signature del handler:

typescript

01async run(plz) {
02  // No recibe payload - se ejecuta automaticamente
03  return { ... }
04}

Nota: La diferencia entre defineSync y defineSchedule es conceptual: sync se usa para sincronizar datos entre sistemas, schedule para tareas autonomas. Tecnicamente funcionan igual.

Ejemplo:

typescript

01 
02  name: 'reporte-diario',
03  reference: 'Envia resumen diario de chats pendientes',
04  cron: '0 22 * * 1-5',
05  timezone: 'America/Mexico_City',
06 
07  async run(plz) {
08    const contacts = await plz.contacts.list({ limit: 200 })
09    const pending = contacts.filter(c => !c.isSolved)
10    // ... enviar reporte
11    return { pending: pending.length }
12  }
13})

Webhook (`defineWebhook`)

Endpoints HTTP que reciben eventos de servicios externos en tiempo real. Al desplegarse, se genera una URL unica que puedes configurar en el servicio externo.

Campos de configuracion:

Campo	Tipo	Descripcion
`name`	`string`	Nombre unico del webhook.
`reference`	`string`	Descripcion del proposito.
`method`	`string`	Metodo HTTP aceptado: `POST`, `GET`, `PUT`.

Signature del handler:

typescript

01async run(payload, plz) {
02  // payload contiene el body del request HTTP
03  return { ... }
04}

Ejemplo:

typescript

01 
02  name: 'webhook-pagos',
03  reference: 'Recibe eventos de pago de Stripe',
04  method: 'POST',
05 
06  async run(payload, plz) {
07    if (payload.type !== 'checkout.session.completed') {
08      return { ignored: true }
09    }
10 
11    const email = payload.data.object.customer_details.email
12    const matches = await plz.contacts.search({ email })
13 
14    if (matches.length > 0) {
15      await plz.contacts.addTag(matches[0].id, 'cliente-pagado')
16    }
17 
18    return { success: true }
19  }
20})

Tip: Al desplegar un webhook, el sistema genera automaticamente una URL. Puedes verla en el dashboard o con plazbot workers list. Usa esa URL para configurar el webhook en el servicio externo (Stripe, Shopify, etc).

Expresiones Cron

Los workers de tipo sync y schedule usan expresiones cron para definir su frecuencia de ejecucion.

Expresion	Significado
`/5 * * *`	Cada 5 minutos
`/30 * * *`	Cada 30 minutos
`0 * * * *`	Cada hora en punto
`0 9 * * *`	Todos los dias a las 9:00
`0 22 * * 1-5`	Lunes a viernes a las 22:00
`0 0 * * 0`	Domingos a medianoche
`0 /6 * *`	Cada 6 horas

El campo timezone determina en que zona horaria se evalua la expresion cron. Valores comunes:

America/Mexico_City
America/Lima
America/Bogota
America/Santiago
America/Argentina/Buenos_Aires

Ejemplos de Workers

A continuacion se presentan ejemplos reales de workers para cada tipo principal. Estos mismos ejemplos estan disponibles en el tab "Ejemplos" del modulo Developers en el dashboard.

Tool: Consultar inventario

El agente IA consulta productos disponibles en stock desde un ERP o base de datos externa.

typescript

01 
02  name: 'consultar-inventario',
03  reference: 'Busca productos disponibles en stock por nombre o SKU',
04  agents: ['id_agent_1'],
05  parameters: [
06    { name: 'query', type: 'string', description: 'Nombre o SKU del producto', example: 'Que producto estas buscando?' }
07  ],
08 
09  async run(payload, plz) {
10    const apiUrl = plz.env.INVENTORY_API_URL
11    const apiKey = plz.env.INVENTORY_API_KEY
12 
13    const res = await fetch(`${apiUrl}/products/search?q=${payload.query}`, {
14      headers: { 'Authorization': `Bearer ${apiKey}` }
15    })
16 
17    const products = await res.json()
18 
19    return products.map(p => ({
20      nombre: p.name,
21      precio: `$${p.price}`,
22      stock: p.stock > 0 ? `${p.stock} disponibles` : 'Agotado',
23      sku: p.sku
24    }))
25  }
26})

Como funciona:

El agente detecta que el usuario pregunta por un producto.
Recopila el parametro query del usuario.
Ejecuta el tool, que consulta la API de inventario.
El agente responde con la informacion de los productos encontrados.

Secrets necesarios: INVENTORY_API_URL, INVENTORY_API_KEY

Worker: Notificar a Slack

Notifica a Slack cuando un contacto solicita atencion humana. Demuestra el uso de plz.log para registrar cada paso.

typescript

01 
02  name: 'notificar-slack',
03  reference: 'Notifica a Slack cuando un contacto solicita atencion humana',
04 
05  async run(payload, plz) {
06    const { contactId, contact } = payload
07 
08    plz.log.info('Worker iniciado', { contactId })
09 
10    // Validar configuracion
11    const webhookUrl = plz.env.SLACK_WEBHOOK_URL
12    if (!webhookUrl) {
13      plz.log.error('SLACK_WEBHOOK_URL no configurado en secrets')
14      return { success: false, error: 'Webhook no configurado' }
15    }
16 
17    // Obtener datos del contacto si no vienen en el payload
18    let contactName = contact?.name || 'Sin nombre'
19    let contactPhone = contact?.phoneNumber || ''
20 
21    if (!contact && contactId) {
22      plz.log.info('Consultando datos del contacto...')
23      const contactData = await plz.contacts.get(contactId)
24      contactName = contactData.name || 'Sin nombre'
25      contactPhone = contactData.phoneNumber || ''
26    }
27 
28    plz.log.info('Contacto identificado', { contactName, contactPhone })
29 
30    // Enviar notificacion a Slack
31    const message = `*Nuevo lead solicita atencion humana*\n- Nombre: ${contactName}\n- Telefono: ${contactPhone}\n- Ultimo mensaje: ${contact?.lastMessage || 'N/A'}`
32 
33    const response = await fetch(webhookUrl, {
34      method: 'POST',
35      headers: { 'Content-Type': 'application/json' },
36      body: JSON.stringify({ text: message })
37    })
38 
39    if (!response.ok) {
40      plz.log.error('Error enviando a Slack', await response.text())
41      return { success: false }
42    }
43 
44    plz.log.info('Notificacion enviada a Slack exitosamente')
45 
46    return { success: true, contactName }
47  }
48})

Como funciona:

Se invoca desde una accion del agente (action.worker) cuando el usuario pide hablar con un humano.
Usa plz.log.info y plz.log.error para registrar cada paso (visibles en el tab Logs).
Obtiene datos del contacto y envia un mensaje a Slack con la informacion.

Secrets necesarios: SLACK_WEBHOOK_URL

Webhook: Pagos de Stripe

Recibe notificaciones de pagos exitosos de Stripe y actualiza el contacto automaticamente.

typescript

01 
02  name: 'webhook-stripe-payments',
03  reference: 'Recibe eventos de pago de Stripe y actualiza contactos',
04  method: 'POST',
05 
06  async run(payload, plz) {
07    const event = payload
08 
09    if (event.type !== 'checkout.session.completed') {
10      return { ignored: true, reason: `Evento ${event.type} ignorado` }
11    }
12 
13    const session = event.data.object
14    const email = session.customer_details.email
15 
16    // Buscar contacto por email y actualizar
17    const matches = await plz.contacts.search({ email })
18 
19    if (matches.length > 0) {
20      const contactId = matches[0].id
21 
22      // Actualizar variables custom del contacto
23      await plz.contacts.setVariable(contactId, 'ctc_ultimo_pago', `$${session.amount_total / 100}`)
24      await plz.contacts.setVariable(contactId, 'ctc_fecha_pago', new Date().toISOString())
25      await plz.contacts.setVariable(contactId, 'ctc_stripe_customer', session.customer)
26 
27      // Agregar tag
28      await plz.contacts.addTag(contactId, 'cliente-pagado')
29    }
30 
31    return {
32      success: true,
33      email,
34      amount: session.amount_total / 100,
35      currency: session.currency
36    }
37  }
38})

Como funciona:

Stripe envia un POST a la URL del webhook cada vez que ocurre un evento.
El worker filtra solo eventos checkout.session.completed.
Busca el contacto por email y actualiza sus variables custom con los datos del pago.
Agrega el tag cliente-pagado para segmentacion.

Configuracion en Stripe:

Despliega el webhook con plazbot workers deploy webhook-stripe.ts.
Copia la URL generada (visible con plazbot workers list).
Configura esa URL en Stripe Dashboard > Webhooks > Add endpoint.

Schedule: Reporte nocturno

Envia un resumen diario de conversaciones pendientes al equipo por Slack, de lunes a viernes a las 10pm.

typescript

01 
02  name: 'reporte-nocturno',
03  reference: 'Envia resumen diario de chats pendientes por Slack',
04  cron: '0 22 * * 1-5',
05  timezone: 'America/Mexico_City',
06 
07  async run(plz) {
08    // Obtener contactos y filtrar los no resueltos
09    const allContacts = await plz.contacts.list({ limit: 200 })
10    const pendingChats = allContacts.filter(c => !c.isSolved)
11 
12    const summary = {
13      total: pendingChats.length,
14      byAgent: {}
15    }
16 
17    for (const chat of pendingChats) {
18      const agent = chat.assignedAgentName || 'Sin asignar'
19      summary.byAgent[agent] = (summary.byAgent[agent] || 0) + 1
20    }
21 
22    const agentLines = Object.entries(summary.byAgent)
23      .map(([agent, count]) => `  - ${agent}: ${count} chats`)
24      .join('\n')
25 
26    await fetch(plz.env.SLACK_WEBHOOK, {
27      method: 'POST',
28      headers: { 'Content-Type': 'application/json' },
29      body: JSON.stringify({
30        text: `*Reporte nocturno*\n\nChats pendientes: *${summary.total}*\n\nPor agente:\n${agentLines}`
31      })
32    })
33 
34    return { sent: true, pending: summary.total }
35  }
36})

Como funciona:

Se ejecuta automaticamente de lunes a viernes a las 22:00 (hora Mexico).
Lista todos los contactos y filtra los no resueltos.
Agrupa los chats pendientes por agente asignado.
Envia un resumen formateado a Slack.

Secrets necesarios: SLACK_WEBHOOK

Cron explicado: 0 22 * * 1-5 = minuto 0, hora 22, cualquier dia del mes, cualquier mes, lunes(1) a viernes(5).

Gestión de Workers

Para que sirven

Requisitos previos

Estructura de un Worker

Ciclo de vida

Integración con el Agente de IA

Campos comunes del define*

Runtime

Tipos de Workers

Tabla comparativa

Tool (`defineTool`)

Worker (`defineWorker`)

Sync (`defineSync`)

Schedule (`defineSchedule`)

Webhook (`defineWebhook`)

Expresiones Cron

Ejemplos de Workers

Tool: Consultar inventario

Worker: Notificar a Slack

Webhook: Pagos de Stripe

Schedule: Reporte nocturno

Was this article helpful?

Related articles

Gestión de Workers

Para que sirven

Requisitos previos

Estructura de un Worker

Ciclo de vida

Integración con el Agente de IA

Campos comunes del define*

Runtime

Tipos de Workers

Tabla comparativa

Tool (defineTool)

Worker (defineWorker)

Sync (defineSync)

Schedule (defineSchedule)

Webhook (defineWebhook)

Expresiones Cron

Ejemplos de Workers

Tool: Consultar inventario

Worker: Notificar a Slack

Webhook: Pagos de Stripe

Schedule: Reporte nocturno

Was this article helpful?

Related articles

Tool (`defineTool`)

Worker (`defineWorker`)

Sync (`defineSync`)

Schedule (`defineSchedule`)

Webhook (`defineWebhook`)