# Contexto (plz) de Workers > Referencia completa del SDK plz disponible en el runtime de Workers Source: https://docs.plazbot.com/kb/agentes-contexto El handler `run` de cada worker recibe dos parametros: `payload` y `plz`. ```typescript 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` 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. > **Nota:** 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) > **Tip:** `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 ```typescript 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. > **Tip:** `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. > **Tip:** Los metodos `setStage`, `setSegmentation`, `addTag` y `assignAgent` aceptan **nombre o ID** indistintamente. El runtime resuelve automaticamente el ID interno. **Ejemplo:** ```typescript // 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:** ```typescript // 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] }) ``` > **Nota:** `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:** ```typescript // 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:** ```typescript // 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:** ```typescript // 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:** ```typescript plz.log.info('Worker iniciado', { contactId }) plz.log.warn('Campo faltante', { field: 'email' }) plz.log.error('API respondio con error', { status: 500, body: responseText }) ``` > **Tip:** 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`). ```typescript // 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. ```typescript 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() ``` > **Nota:** 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:** ```typescript // 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' }) ``` > **Nota:** `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.