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.
`sendMedia(options)`	`{ to, url, caption?, filename? }`	Envia un archivo multimedia (imagen, video, documento, audio).
`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 imagen con caption
await plz.whatsapp.sendMedia({
  to: '+5215512345678',
  url: 'https://example.com/factura.pdf',
  caption: 'Aqui tienes tu factura del mes',
  filename: 'factura-junio.pdf'
})

// Enviar audio (sin caption)
await plz.whatsapp.sendMedia({
  to: '+5215512345678',
  url: 'https://example.com/audio.mp3'
})

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

sendMedia detecta automaticamente el tipo de archivo por la extension de la URL. El campo caption es opcional y no aplica para archivos de audio (limitacion de WhatsApp). Formatos soportados: imagenes (jpg, png, webp), video (mp4), documentos (pdf, xlsx, docx, csv, txt), audio (mp3, ogg, aac).

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. Para llamar a la API interna de Plazbot, usa plz.api en su lugar (incluye autenticacion automatica).

plz.api

Cliente HTTP autenticado para llamar a los endpoints internos de la API de Plazbot. A diferencia de plz.fetch, plz.api incluye automaticamente el token de autenticacion y el workspaceId en cada peticion.

Metodo	Parametros	Retorno	Descripcion
`get(path)`	`path: string`	`any`	Peticion GET al endpoint especificado.
`post(path, body?)`	`path: string, body?: object`	`any`	Peticion POST con body JSON opcional.
`put(path, body?)`	`path: string, body?: object`	`any`	Peticion PUT con body JSON opcional.
`delete(path, body?)`	`path: string, body?: object`	`any`	Peticion DELETE con body JSON opcional.

El path debe comenzar con /api/ seguido del endpoint. Por ejemplo: /api/contact/bulk-mark-read. Ejemplo:

// Marcar todas las conversaciones como leidas
await plz.api.post('/api/contact/bulk-mark-read', {
  workspaceId: payload.workspaceId
})

// Obtener datos de un contacto via API REST
const contact = await plz.api.get(`/api/contact/${payload.contactId}`)

// Actualizar un recurso
await plz.api.put('/api/workspace/settings', {
  workspaceId: payload.workspaceId,
  key: 'valor'
})

plz.api esta pensado para acceder a endpoints de Plazbot que no tienen un metodo dedicado en el SDK. Para APIs externas usa plz.fetch o fetch directamente.

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

plz.api

​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

​plz.api

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

plz.api