> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plazbot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contexto (plz)

> Referencia completa del SDK plz disponible en el runtime de Workers

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

```typescript theme={null}
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.                              |

<Note>
  Los workers tipo `schedule` y `sync` no reciben `payload` — solo reciben `plz` como unico parametro.
</Note>

### 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.
</Tip>

### Ejemplo: usar datos del payload

```typescript theme={null}
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.
</Tip>

***

## 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.
</Tip>

**Ejemplo:**

```typescript theme={null}
// 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:**

```typescript theme={null}
// 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:**

```typescript theme={null}
// 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 theme={null}
// 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 theme={null}
// 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 theme={null}
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.
</Tip>

***

## 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 theme={null}
// 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 theme={null}
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()
```

<Note>
  Puedes usar `fetch` directamente (global) o `plz.fetch` — ambos son equivalentes en el runtime de workers.
</Note>