Campañas | Plazbot Devs

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

Plazbot (recomendado)·ts

01import { Plazbot } from 'plazbot';
02 
03const plazbot = new Plazbot({
04  workspaceId: "YOUR_WORKSPACE_ID",
05  apiKey: "YOUR_API_KEY",
06  zone: "LA"
07});
08 
09// Usar: plazbot.campaign.createCampaign()

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}}…).

01const { id } = await plazbot.campaign.createCampaign({
02  name: "Recordatorio noviembre",
03  templateId: "tem_...",
04  recipients: [
05    { phone: "+51912345678", name: "Ana", variables: ["lunes 9:00"] },
06    { phone: "+51998765432", name: "Luis", variables: ["martes 10:30"] }
07  ]
08});

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

01import { readFile } from "node:fs/promises";
02 
03await plazbot.campaign.createCampaign({
04  name: "Promo noviembre",
05  templateId: "tem_...",
06  csv: { data: await readFile("./destinatarios.csv"), filename: "destinatarios.csv" },
07  scheduledAt: "2026-11-02T09:00:00-05:00"
08});

Seguir y cancelar

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

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.

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.