whatsapp.cloud_api: operational·bsp: meta_business_partner·regions: la / eu·sdk: v2.1.4·cli: v0.2.22

// WHATSAPP CLOUD API · OFICIAL DE META

Whatsapp for Developers

Conecta tu número, envía mensajes y plantillas, y recibe cada evento por webhook en tiempo real. API oficial de Meta — Plazbot es Meta Business Partner, sin intermediarios extra. Mismo API en SDK, CLI y REST.

├── plantillas aprobadas directo desde Meta

├── 7 tipos de mensaje · 12 eventos webhook

└── primer mensaje en 3 pasos — quickstart abajo ↓

empezar en 3 pasos docs

~/send.ts·typescript

01import { Plazbot } from "plazbot"
02 
03const bot = new Plazbot({
04  apiKey: process.env.PLAZBOT_KEY!,
05  workspaceId: "ws_...",
06  zone: "LA" // LA | EU
07})
08 
09// envía una plantilla aprobada con variables
10await bot.message.onConversation({
11  to: "5491123456789",
12  template: "welcome",
13  variablesBody: [{ variable: "1", value: "Ana" }]
14})

✓ message.queued · id: msg_018f... · status: accepted

// QUICKSTART · 3 PASOS · DEL INSTALL AL PRIMER MESSAGEID

Tu primer mensaje en 3 pasos.

Tres pasos copia-pega para mandar tu primera plantilla a un número real. Requiere PLAZBOT_KEY y PLAZBOT_WORKSPACE_ID (los obtienes en el panel).

step [01/03]

instala el SDK

Un solo paquete. Sin dependencias externas extra.

~/terminal·bash

01$ npm install plazbot
02# o si prefieres CLI global para ops:
03$ npm install -g plazbot

step [02/03]

inicializa el cliente

Lleva apiKey, workspaceId y zona (LA / EU). El host se resuelve solo.

~/lib/plazbot.ts·typescript

01import { Plazbot } from "plazbot"
02 
03export const bot = new Plazbot({
04  apiKey:      process.env.PLAZBOT_KEY!,
05  workspaceId: process.env.PLAZBOT_WORKSPACE_ID!,
06  zone:        "LA", // "LA" | "EU"
07})

step [03/03]

manda tu primer mensaje

Plantilla aprobada con variables. La respuesta trae messageId para tracking.

~/scripts/welcome.ts·typescript

01import { bot } from "@/lib/plazbot"
02 
03const res = await bot.message.onConversation({
04  to:            "51912345678",
05  template:      "welcome",
06  variablesBody: [{ variable: "1", value: "Ana" }],
07})
08 
09console.log(res.messageId) // → "msg_018f..."

$ next: ver tipos de mensaje · registrar webhook · leer docs completas

// MESSAGE TYPES · 3 SURFACES · MISMA OP

Envía texto, plantillas y archivos.

La misma operación expresada en SDK TypeScript, CLI Bash y REST HTTP. Body y parámetros idénticos — elige la superficie según el contexto (app vs ops vs cualquier stack).

onWhatsappMessage()

Texto libre. Solo funciona si el cliente te escribió en las últimas 24 horas (regla de WhatsApp, no de Plazbot).

onConversation()

Plantilla aprobada por Meta. Sirve para iniciar la conversación o reabrir la ventana de 24 horas.

[01]

texto plano

mensaje libre — ventana de 24h abierta

~/send-text.ts·ts

await bot.message.onWhatsappMessage({
  to: "51912345678",
  message: "Hola Ana, gracias por escribir.",
})

[02]

plantilla con variables

HSM aprobada — abre ventana / inicia conversación

~/send-template.ts·ts

await bot.message.onConversation({
  to: "51912345678",
  template: "welcome",
  variablesBody:   [{ variable: "1", value: "Ana" }],
  variablesHeader: [{ variable: "1", value: "Q3 2025" }],
})

[03]

plantilla con archivo

imagen, documento o video como header media

~/send-template-file.ts·ts

await bot.message.onConversation({
  to: "51912345678",
  template: "factura_mensual",
  variablesBody: [{ variable: "1", value: "Ana" }],
  file: {
    fileUrl:  "https://cdn.tu-app.com/facturas/u/123.pdf",
    fileName: "factura.pdf",
  },
})

$ base.url = https://api.plazbot.com | https://apieu.plazbot.com · auth: Bearer + x-workspace-id

// WEBHOOKS · 12 EVENTOS EN TIEMPO REAL · POST JSON

Escucha cada evento en tiempo real.

Registra una URL y Plazbot te envía un POST con JSON por cada evento de tu número: mensajes, contactos y conversaciones. Dos pasos, nada más.

[01] registra tu endpoint

Una sola llamada. Desde ese momento, cada evento del número llega a tu URL.

~/register.ts·typescript

await bot.message.registerWebhook({
  number: "51912345678",
  url:    "https://tu-app.com/wa-events",
})

[02] recibe cada evento como JSON

12 eventos en 3 familias. Todos llegan con la misma estructura: type indica qué pasó y data trae el contacto, el mensaje o la conversación.

message.*

Mensajes entrantes por tipo de contenido

4 eventos

[01]message.receivedtexto
[02]message.image.receivedimagen
[03]message.audio.receivedaudio
[04]message.document.receiveddocumento

contact.*

Ciclo de vida del contacto

5 eventos

[01]contact.creatednuevo contacto creado
[02]contact.existingcontacto ya conocido interactuó
[03]contact.deletedcontacto eliminado
[04]contact.blockedcontacto bloqueado
[05]contact.from.adclick-to-WhatsApp desde anuncio

conversation.*

Estado de la conversación

3 eventos

[01]conversation.assignedasignada a agente / miembro
[02]conversation.resolvedmarcada como resuelta
[03]conversation.reopenedreabierta

POST tu-app.com/wa-events·json

01{
02  "type":        "message.image.received",
03  "workspaceId": "ws_018f...",
04  "timestamp":   "2025-05-24T13:42:01.812Z",
05  "data": {
06    "contact": {
07      "id":          "cnt_018f...",
08      "name":        "Ana Quispe",
09      "phoneNumber": "51912345678",
10      "tags":        ["lead", "ventas"]
11    },
12    "message": {
13      "id":          "msg_018f...",
14      "contentUrl":  "https://media.plazbot.com/.../img.jpg",
15      "contentType": "image",
16      "platform":    "whatsapp",
17      "direction":   "incoming",
18      "timestamp":   "2025-05-24T13:42:01.700Z"
19    }
20  }
21}

ejemplo real · type: "message.image.received"

└── ¿usas TypeScript? el SDK incluye los tipos del payload (PlazbotEvent) — autocompletado sin escribir interfaces a mano.

// CAPABILITIES · 10 ÍTEMS · SDK · CLI · REST

Todo lo que puedes hacer.

Las 10 operaciones de WhatsApp disponibles desde código, agrupadas por objetivo. Haz clic en cualquiera para ver el snippet real del SDK o del CLI — sin invenciones.

conecta tu número· 2 operaciones

envía mensajes· 4 operaciones

consulta tus datos· 3 operaciones

escucha eventos· 1 operación

$ capabilities.total = 10 · verificadas contra plazbot-sdk@2.1.4 + plazbot-cli@0.2.22

// REGIONS · 2 ZONAS · ZONE-AWARE

Dos regiones, un mismo código.

El SDK resuelve el host según la zona del workspace. Elige la región correcta y el cliente apunta automáticamente al host operativo de esa zona.

zone: LA

Latinoamérica

operational

baseUrl

https://api.plazbot.com

Cobertura para América Latina, Caribe y Estados Unidos

├── BSP Meta operando 24/7 con plantillas locales
├── Soporte en español y portugués
└── Optimizado para tráfico desde MX · CO · PE · CL · AR · BR

~/client.ts·typescript

const bot = new Plazbot({
  apiKey:      process.env.PLAZBOT_KEY!,
  workspaceId: "ws_...",
  zone:        "LA",
})

zone: EU

Europa

operational

baseUrl

https://apieu.plazbot.com

Cobertura para Europa con residencia de datos en la región

├── Procesamiento y almacenamiento dentro de la UE
├── Compatible con requisitos de GDPR / soberanía de datos
└── Optimizado para tráfico desde ES · PT · IT · FR · DE

~/client.ts·typescript

const bot = new Plazbot({
  apiKey:      process.env.PLAZBOT_KEY!,
  workspaceId: "ws_...",
  zone:        "EU",
})

└── on-premise / cluster dedicado: new Plazbot({ apiKey, workspaceId, customUrl: "https://api.tu-cluster.com" })

// READY ? · 3 PASOS · 10 CAPABILITIES · 12 WEBHOOKS

Empieza a construir con WhatsApp.

Crea tu workspace gratis, conecta un número y manda tu primera plantilla en minutos. Si necesitas volumen, BSP dedicado u on-premise, hablamos.

hablar con ventas

├── developers.plazbot.com
├── github.com/plazbot
├── /developers
└── status

~/developers/whatsapp · end-of-file · press [↑] to scroll