# Campañas

> Envía una plantilla aprobada a muchos contactos, al instante o programada

Fuente: https://developers.plazbot.com/sdk/campaign/

### Introducción

El módulo **Campaign** crea campañas de WhatsApp desde tu código: una plantilla aprobada que se envía a una lista de números, al instante o en una fecha. Es lo mismo que **Marketing** > **Campañas** en Plazbot: el envío corre en los servidores de Plazbot, así que tu código no tiene que quedarse esperando. Disponible desde la versión **2.4.0**.

### Inicialización

```ts Plazbot (recomendado)
import { Plazbot } from 'plazbot';

const plazbot = new Plazbot({
workspaceId: "YOUR_WORKSPACE_ID",
apiKey: "YOUR_API_KEY",
zone: "LA"
});

// Usar: plazbot.campaign.createCampaign()
```

```ts Campaign individual
import { Campaign } from 'plazbot';

const campaign = new Campaign({
workspaceId: "YOUR_WORKSPACE_ID",
apiKey: "YOUR_API_KEY",
zone: "LA"
});
```

---

### Crear una campaña

Pasa los destinatarios en `recipients` y el SDK arma el archivo que espera Plazbot. Las `variables` son los valores del cuerpo de la plantilla, en orden (`{{1}}`, `{{2}}`…).

```ts
const { id } = await plazbot.campaign.createCampaign({
name: "Recordatorio noviembre",
templateId: "tem_...",
recipients: [
  { phone: "+51912345678", name: "Ana", variables: ["lunes 9:00"] },
  { phone: "+51998765432", name: "Luis", variables: ["martes 10:30"] }
]
});
```

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `name` | `string` | Nombre de la campaña. |
| `templateId` | `string` | Id de una plantilla aprobada (`tem_...`). |
| `recipients` | `CampaignRecipient[]` | `{ phone, name?, variables?, headerVariable? }`. Usa `recipients` o `csv`. |
| `csv` | `FileInput` | Tu propio CSV con columnas `name`, `phone`, `body_var1`, `body_var2`… y `header_var1`. Máximo 2 MB. |
| `scheduledAt` | `Date \| string` | Fecha de envío. Si la omites, sale de inmediato. |
| `showInChat` | `boolean` | Mostrar los mensajes en el chat de cada contacto. Por defecto `true`. |
| `startAiAgent` | `boolean` | Si el contacto responde, lo atiende el agente IA del número. Por defecto `true`. |
| `tagIds` | `string[]` | Etiquetas que se agregan a cada destinatario. |

#### Programada y con tu propio CSV

```ts
import { readFile } from "node:fs/promises";

await plazbot.campaign.createCampaign({
name: "Promo noviembre",
templateId: "tem_...",
csv: { data: await readFile("./destinatarios.csv"), filename: "destinatarios.csv" },
scheduledAt: "2026-11-02T09:00:00-05:00"
});
```

---

### Seguir y cancelar

```ts
const page = await plazbot.campaign.getCampaigns({ search: "noviembre" }); // { items, nextCursor }
const records = await plazbot.campaign.getCampaignRecords(id);          // estado y error por destinatario
await plazbot.campaign.cancelCampaign(id);                              // los ya enviados no se recuperan
```

> **Importante:** Las plantillas salen aunque el contacto no haya escrito en las últimas 24 horas, y Meta cobra cada mensaje según la categoría de la plantilla. Revisa los precios en [WhatsApp Pricing](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing).

### Errores

Los métodos lanzan `PlazbotApiError` (con `code` y `message`) cuando la API rechaza la campaña, por ejemplo si la plantilla no está aprobada o el CSV no tiene la columna `phone`.