Contexto (plz)

El handler run de cada worker recibe dos parametros: payload y plz.

async run(payload, plz) {
  const { contactId, contact, agentId } = payload
  const fullContact = await plz.contacts.get(contactId)
}

payload

El objeto payload contiene los datos de contexto que se envian al worker cuando se ejecuta. Los campos disponibles dependen del tipo de worker y de como se invoca.

Campos del payload

Campo	Tipo	Disponible en	Descripcion
`contactId`	`string`	tool, worker	ID del contacto que disparo la ejecucion.
`agentId`	`string`	tool, worker	ID del agente IA asociado.
`workspaceId`	`string`	tool, worker	ID del workspace.
`workerName`	`string`	tool, worker	Nombre del worker ejecutado.
`contact`	`Contact`	worker	Datos del contacto (ver tabla abajo).
`sessionValues`	`Record<string, string>`	worker	Campos capturados por el LLM durante la conversacion.
(parametros custom)	`any`	tool	Campos extraidos por el LLM segun los `parameters` del tool.
(body del request)	`any`	webhook	Body del request HTTP recibido.

Los workers tipo schedule y sync no reciben payload — solo reciben plz como unico parametro.

Objeto contact en el payload

Cuando un worker se ejecuta desde una accion del agente, el payload.contact incluye estos campos:

Campo	Tipo	Descripcion
`name`	`string`	Nombre del contacto.
`lastname`	`string`	Apellido del contacto.
`email`	`string`	Correo electronico.
`phoneNumber`	`string \| null`	Numero de telefono del contacto.
`platformId`	`number`	Plataforma de origen (ver tabla).
`stageId`	`string \| null`	ID de la etapa actual.
`segmentationId`	`string \| null`	ID de la segmentacion.
`assignedAgentId`	`string \| null`	ID del agente humano asignado.
`assignedAgentName`	`string \| null`	Nombre del agente asignado.
`isSolved`	`boolean`	Si la conversacion esta resuelta.
`lastMessage`	`string`	Ultimo mensaje del contacto.
`tags`	`Array<{ id, name }>`	Etiquetas asignadas.
`variables`	`Array<{ code, val }>`	Variables custom del contacto.

Valores de platformId

Valor	Plataforma
`1`	Webchat
`2`	WhatsApp
`3`	Facebook Messenger
`4`	Instagram
`5`	Telegram
`7`	Playground (test del agente)

payload.contact es un resumen del contacto. Si necesitas campos adicionales como whatsappCellphone, documentNumber o creationDate, usa plz.contacts.get(payload.contactId) para obtener el contacto completo.

Ejemplo: usar datos del payload

async run(payload, plz) {
  const { contactId, contact } = payload

  // Datos rapidos del payload
  const nombre = contact?.name || 'Sin nombre'
  const telefono = contact?.phoneNumber || ''
  const ultimoMsg = contact?.lastMessage || ''

  // Si necesitas mas campos, consulta el contacto completo
  const full = await plz.contacts.get(contactId)
  const whatsapp = full.whatsappCellphone
  const documento = full.documentNumber
  const creado = full.creationDate
}

plz

El objeto plz es el SDK de Plazbot que se inyecta automaticamente en el runtime. No necesitas instalarlo ni importarlo.

plz y “plazbot” son el mismo SDK. Se usa la abreviatura plz para mantener el codigo conciso.

plz.contacts

Metodos para gestionar contactos del workspace.

Metodo	Parametros	Retorno	Descripcion
`get(id)`	`id: string`	`Contact`	Obtiene un contacto por ID.
`list(options?)`	`{ limit?: number }`	`Contact[]`	Lista contactos del workspace.
`search(query)`	`{ email?, phone?, name? }`	`Contact[]`	Busca contactos por email, telefono o nombre.
`create(data)`	`{ name, lastname?, email?, phoneNumber? }`	`Contact`	Crea un nuevo contacto.
`update(id, data)`	`id, { name?, lastname?, email?, phoneNumber? }`	`Contact`	Actualiza campos del sistema de un contacto.
`delete(id)`	`id: string`	`void`	Elimina un contacto.
`setVariable(id, code, value)`	`id, code: string, value: string`	`void`	Establece una variable custom del contacto.
`getVariable(id, code)`	`id, code: string`	`string \| null`	Obtiene el valor de una variable custom.
`addTag(id, tagName)`	`id, tagName: string`	`void`	Agrega una etiqueta al contacto.
`removeTag(id, tagName)`	`id, tagName: string`	`void`	Remueve una etiqueta del contacto.
`setStage(id, stage)`	`id, stage: string`	`void`	Asigna una etapa al contacto. Acepta nombre o ID.
`setSegmentation(id, segmentation)`	`id, segmentation: string`	`void`	Asigna una segmentacion al contacto. Acepta nombre o ID.
`assignAgent(id, agent)`	`id, agent: string`	`void`	Asigna un agente humano. Acepta email, nombre o ID.
`resolve(id)`	`id: string`	`void`	Marca la conversacion como resuelta.

Los metodos setStage, setSegmentation, addTag y assignAgent aceptan nombre o ID indistintamente. El runtime resuelve automaticamente el ID interno.

Ejemplo:

// Puedes usar nombre directamente — no necesitas buscar el ID
await plz.contacts.setStage(contactId, 'Nuevo')
await plz.contacts.addTag(contactId, 'cliente-vip')
await plz.contacts.setSegmentation(contactId, 'Premium')
await plz.contacts.assignAgent(contactId, 'kristian@plazbot.com')

// Buscar contacto y actualizar datos
const matches = await plz.contacts.search({ email: 'user@email.com' })
if (matches.length > 0) {
  await plz.contacts.update(matches[0].id, { name: 'Juan' })
  await plz.contacts.setVariable(matches[0].id, 'ctc_plan', 'premium')
}

plz.whatsapp

Metodos para enviar mensajes por WhatsApp.

Metodo	Parametros	Descripcion
`send(options)`	`{ to: string, message: string }`	Envia un mensaje de texto libre.
`sendTemplate(options)`	`{ to, templateName, language, parameters }`	Envia una plantilla aprobada.
`getHistory(contactId)`	`contactId: string`	Obtiene historial de mensajes.

Ejemplo:

// Enviar mensaje directo
await plz.whatsapp.send({
  to: '+5215512345678',
  message: 'Tu pedido ha sido enviado'
})

// Enviar plantilla con parametros
await plz.whatsapp.sendTemplate({
  to: contact.phoneNumber,
  templateName: 'confirmacion_pedido',
  language: 'es',
  parameters: [contact.name, orderNumber]
})

plz.agents

Metodos para interactuar con los agentes de IA.

Metodo	Parametros	Descripcion
`get(id)`	`id: string`	Obtiene configuracion de un agente.
`list()`	-	Lista agentes del workspace.
`chat(options)`	`{ agentId, message, contactId? }`	Envia un mensaje al agente y obtiene respuesta.

Ejemplo:

// Consultar un agente desde otro worker
const response = await plz.agents.chat({
  agentId: 'agent_abc123',
  message: 'Clasifica este mensaje: ' + payload.text,
  contactId: payload.contactId
})

plz.conversations

Metodos para gestionar conversaciones.

Metodo	Parametros	Descripcion
`get(contactId)`	`contactId: string`	Obtiene datos de la conversacion.
`getMessages(contactId, options?)`	`contactId, { limit? }`	Obtiene mensajes de la conversacion.
`addNote(contactId, note)`	`contactId, note: string`	Agrega una nota interna.
`resolve(contactId)`	`contactId: string`	Marca como resuelta.
`reopen(contactId)`	`contactId: string`	Reabre la conversacion.

plz.templates

Metodos para gestionar plantillas de WhatsApp.

Metodo	Parametros	Descripcion
`list()`	-	Lista todas las plantillas.
`getActive()`	-	Obtiene solo las plantillas activas/aprobadas.

plz.workspace

Metodos para obtener informacion del workspace. Los datos del workspace se cachean internamente, asi que puedes llamar multiples metodos sin generar llamadas repetidas a la API.

Listar configuraciones

Metodo	Retorno	Descripcion
`get()`	`Workspace`	Obtiene datos completos del workspace.
`getVariables()`	`Variable[]`	Lista las variables custom definidas.
`getTags()`	`Tag[]`	Lista las etiquetas activas.
`getStages()`	`Stage[]`	Lista las etapas configuradas.
`getSegmentations()`	`Segmentation[]`	Lista las segmentaciones configuradas.
`getMembers()`	`Member[]`	Lista los miembros del equipo.

Buscar por nombre o ID

Estos metodos buscan un elemento especifico por su nombre o ID y retornan el objeto completo, o null si no existe.

Metodo	Parametros	Retorno	Descripcion
`getTag(idOrName)`	`string`	`Tag \| null`	Busca una etiqueta por nombre o ID.
`getStage(idOrName)`	`string`	`Stage \| null`	Busca una etapa por nombre o ID.
`getSegmentation(idOrName)`	`string`	`Segmentation \| null`	Busca una segmentacion por nombre o ID.

Ejemplo:

// Resolver el stageId del contacto a su nombre
const stage = await plz.workspace.getStage(contact.stageId)
plz.log.info(`Etapa actual: ${stage?.name}`) // "Nuevo", "En proceso", etc.

// Resolver el segmentationId
const seg = await plz.workspace.getSegmentation(contact.segmentationId)
plz.log.info(`Segmentacion: ${seg?.name}`) // "Premium", "Free", etc.

// Listar todas las etapas disponibles
const stages = await plz.workspace.getStages()
stages.forEach(s => plz.log.info(`${s.id} → ${s.name}`))

plz.kv

Key-Value Store para persistir datos entre ejecuciones.

Metodo	Parametros	Descripcion
`get(key)`	`key: string`	Obtiene un valor por clave.
`set(key, value)`	`key: string, value: any`	Guarda un valor.
`delete(key)`	`key: string`	Elimina un valor.
`list(prefix?)`	`prefix?: string`	Lista claves (con filtro de prefijo opcional).

Ejemplo:

// Guardar estado entre ejecuciones
const lastSync = await plz.kv.get('last-sync-date')
// ... logica de sincronizacion
await plz.kv.set('last-sync-date', new Date().toISOString())

plz.log

Metodos para registrar logs durante la ejecucion. Los logs se guardan en la tabla worker_logs y son visibles en el tab “Logs” del dashboard.

Metodo	Parametros	Descripcion
`info(message, data?)`	`message: string, data?: any`	Registra informacion general.
`warn(message, data?)`	`message: string, data?: any`	Registra advertencias.
`error(message, data?)`	`message: string, data?: any`	Registra errores.

Ejemplo:

plz.log.info('Worker iniciado', { contactId })
plz.log.warn('Campo faltante', { field: 'email' })
plz.log.error('API respondio con error', { status: 500, body: responseText })

Los logs se muestran en tiempo real en el tab “Logs” del worker en el dashboard. Usa plz.log.info para depurar paso a paso y plz.log.error para registrar fallos.

plz.env

Acceso a los secrets encriptados del workspace. Los secrets se configuran desde el dashboard (tab Secrets) o via CLI (plazbot workers secret set).

// Acceso directo por nombre del secret
const apiKey = plz.env.STRIPE_API_KEY
const webhookUrl = plz.env.SLACK_WEBHOOK_URL

Los secrets se almacenan encriptados (AES-256) y se desencriptan en runtime. El key debe estar en formato UPPER_SNAKE_CASE.

plz.fetch

HTTP client disponible para hacer peticiones a APIs externas. Funciona igual que el fetch estandar del browser.

const res = await fetch('https://api.example.com/data', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${plz.env.API_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ key: 'value' })
})

const data = await res.json()

Puedes usar fetch directamente (global) o plz.fetch — ambos son equivalentes en el runtime de workers.

Introducción

Primeros Pasos

Contactos

Agente de IA

Marketing

Partners Marca Blanca

Legal

payload

Campos del payload

Objeto contact en el payload

Valores de platformId

Ejemplo: usar datos del payload

plz

plz.contacts

plz.whatsapp

plz.agents

plz.conversations

plz.templates

plz.workspace

Listar configuraciones

Buscar por nombre o ID

plz.kv

plz.log

plz.env

plz.fetch

Introducción

Primeros Pasos

Contactos

Agente de IA

Marketing

Partners Marca Blanca

Legal

Documentation Index

​payload

​Campos del payload

​Objeto contact en el payload

​Valores de platformId

​Ejemplo: usar datos del payload

​plz

​plz.contacts

​plz.whatsapp

​plz.agents

​plz.conversations

​plz.templates

​plz.workspace

​Listar configuraciones

​Buscar por nombre o ID

​plz.kv

​plz.log

​plz.env

​plz.fetch

payload

Campos del payload

Objeto contact en el payload

Valores de platformId

Ejemplo: usar datos del payload

plz

plz.contacts

plz.whatsapp

plz.agents

plz.conversations

plz.templates

plz.workspace

Listar configuraciones

Buscar por nombre o ID

plz.kv

plz.log

plz.env

plz.fetch