# Recibir mensajes

> Webhook por número para los mensajes entrantes y Workers para reaccionar a eventos

Fuente: https://developers.plazbot.com/whatsapp/recibir-mensajes/

## Webhook por número

Registra una URL y cada mensaje que recibe ese número llega a tu servidor por `POST`.

```ts SDK
await bot.message.registerWebhook({
number:     "51966446311", // tu número conectado
webhookUrl: "https://tu-app.com/api/whatsapp",
})
```

```bash CLI
plazbot whatsapp register-webhook \
--phone +51912345678 \
--url https://tu-app.com/api/whatsapp
```

También puedes registrarlo en el paso 4 de [`plazbot whatsapp setup`](https://developers.plazbot.com/whatsapp/setup). Para quitarlo: [`delete-webhook`](https://developers.plazbot.com/whatsapp/cli/delete-webhook).

### Qué llega a tu URL

```json POST → tu webhook
{
"id":             "msg_...",
"content":        "Hola, ¿tienen envío a Cusco?",
"contactId":      "cnt_...",
"recipientPhone": "51912345678",
"agentId":        "agt_...",
"agentName":      "Soporte",
"reference":      { "object": "whatsapp_business_account" }
}
```

| Campo | Descripción |
|-------|-------------|
| `id` | ID del mensaje en Plazbot |
| `content` | Texto del mensaje (o descripción del archivo) |
| `contactId` | ID del contacto en Plazbot |
| `recipientPhone` | Número de quien escribió, con código de país |
| `agentId`, `agentName` | Agente asignado al contacto, si hay |
| `reference` | Payload original que envió Meta |

### Ejemplo de handler

```ts app/api/whatsapp/route.ts
export async function POST(req: Request) {
const msg = await req.json()

console.log(msg.recipientPhone, "escribió:", msg.content)

return new Response("ok")
}
```

> **Tip:** Para probar sin servidor usa una URL de [webhook.site](https://webhook.site): escribe a tu número y verás el `POST` en tiempo real.

> **Info:** El webhook por número envía los **mensajes entrantes**. Los estados de entrega (enviado, entregado, leído) todavía no se envían a tu webhook.

## Eventos con Workers

Los Workers son funciones que Plazbot ejecuta por ti cuando ocurre un evento, sin montar servidor. Tienen acceso a WhatsApp, contactos y conversaciones desde `plz`.

```ts workers/bienvenida.ts
import { defineWorker } from "plazbot/workers"

export default defineWorker({
name:   "bienvenida",
events: ["contact.created"],
async handler(event, plz) {
  const { contact } = event.data
  if (!contact?.phoneNumber) return

  await plz.whatsapp.send({
    to:      contact.phoneNumber,
    message: "¡Bienvenido! ¿En qué te ayudamos?",
  })
},
})
```

```bash
plazbot workers deploy ./workers/bienvenida.ts
```

| Grupo | Eventos |
|-------|---------|
| `message.*` | `received`, `image.received`, `audio.received`, `document.received` |
| `contact.*` | `created`, `existing`, `deleted`, `blocked`, `from.ad` |
| `conversation.*` | `assigned`, `resolved`, `reopened` |

Más en [Workers](https://developers.plazbot.com/cli/workers/deploy).