# Quickstart

> De cero a tu primer mensaje de WhatsApp enviado desde la API, paso a paso

Fuente: https://developers.plazbot.com/whatsapp/quickstart/

Esta guía sigue el orden recomendado. Cada paso indica **qué hacer** y **qué vas a ver**. Tiempo total: unos 10 minutos (la mayor parte es el registro del número en Meta).

## Antes de empezar

- Una cuenta de Plazbot. Si no tienes, créala gratis en [appla.plazbot.com](https://appla.plazbot.com/register) (América) o [appeu.plazbot.com](https://appeu.plazbot.com/register) (Europa).
- Node.js 18.17 o superior.
- Tu celular con WhatsApp a mano (para la prueba).
- Para conectar un número nuevo: una cuenta de Facebook con acceso al Business Manager de tu empresa.

## 1. Instala el CLI

```bash
npm i -g plazbot-cli
plazbot --version
```

**Qué vas a ver:** la versión instalada (`0.4.0` o superior).

## 2. Inicia sesión

```bash
plazbot login
```

1. Elige dónde creaste tu cuenta: **América** o **Europa**.
2. Se abre tu navegador en la pantalla **Autorizar CLI**. Si no tenías sesión en Plazbot, primero inicias sesión y vuelves solo.
3. Confirma que el código que ves en el navegador es el mismo de tu terminal, elige el **workspace** y presiona **Autorizar**.

**Qué vas a ver en la terminal:**

```text
Tu código de verificación: KXPD-7M4Q

Abrimos tu navegador. Si no se abrió, entra a:
https://appla.plazbot.com/cli/authorize?code=KXPD-7M4Q&r=...

✔ Sesión iniciada en Mi Empresa (LA)
Cuenta: tu@empresa.com
```

No copiaste ninguna API key: el CLI la recibió y la guardó en `~/.plazbot/config.json`. Más detalles en [Iniciar sesión](https://developers.plazbot.com/whatsapp/login).

## 3. Conecta tu número y prueba tu primer mensaje

```bash
plazbot whatsapp setup
```

El asistente tiene 4 pasos:

**[1/4] Tu cuenta.** Confirma la sesión activa.

**[2/4] Tu número de WhatsApp.** Elige un número ya conectado o **Connect a new number**:

- **WhatsApp API**: un número nuevo o dedicado. Ideal para enviar a escala.
- **WhatsApp Business**: tu app actual del celular, en coexistencia. Se vincula escaneando un QR.

Si conectas uno nuevo, se abre el registro de Meta en tu navegador. El CLI espera y te avisa cuando el número queda conectado y activo.

**[3/4] Prueba de ida y vuelta.**

1. Escribe tu celular con código de país (por ejemplo `+51987654321`).
2. **Desde ese celular envía "hello"** por WhatsApp al número conectado. El CLI te da un atajo `wa.me`.
3. El CLI detecta tu mensaje y pregunta si te responde desde la API. Acepta.

**[4/4] Webhook (opcional).** Escribe la URL que recibirá los mensajes entrantes, o presiona Enter para omitirlo.

**Qué vas a ver:**

```text
[3/4] Round-trip test
? Which phone will you write from? (international format, e.g. +51912345678) +51987654321

From that phone, send "hello" on WhatsApp to +51912345678
Shortcut: https://wa.me/51912345678?text=hello
Your message creates the contact and opens the 24h window in which WhatsApp allows free-form replies.

✔ Message received: "hello"
? Reply to you from the API? Yes
✔ Message sent. Check your WhatsApp.
```

En tu celular llega una respuesta que empieza con "It works!" y termina con "This message was sent by your code through the Plazbot API."

> **Tip:** ¿Por qué hay que escribir "hello" primero? WhatsApp solo permite enviar texto libre a alguien que te escribió en las últimas 24 horas. Tu mensaje abre esa ventana y crea el contacto. Para escribirle primero a un cliente nuevo se usan plantillas aprobadas. Ver [Conceptos clave](https://developers.plazbot.com/whatsapp/conceptos).

Detalle de cada paso y posibles errores en [Asistente de configuración](https://developers.plazbot.com/whatsapp/setup).

## 4. Usa la API en tu app

Al final el asistente imprime el código con tus datos. Para tu servidor necesitas una **API key propia** (la del CLI es de tu computadora): créala en el panel, **Configuración → Developer**, y guárdala en una variable de entorno.

```bash
npm i plazbot
```

```ts send.ts
import { Plazbot } from "plazbot"

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

await bot.message.onWhatsappMessage({
to:      "51912345678",
message: "Hola desde mi app",
})
```

Más tipos de mensaje en [Enviar mensajes](https://developers.plazbot.com/whatsapp/enviar-mensajes).

## 5. Recibe las respuestas

Si registraste un webhook en el paso 3, cada mensaje que llegue a tu número se envía por `POST` a tu URL. El formato del JSON y un ejemplo de handler están en [Recibir mensajes](https://developers.plazbot.com/whatsapp/recibir-mensajes).

---

## Resumen

| Paso | Comando | Resultado |
|------|---------|-----------|
| 1 | `npm i -g plazbot-cli` | CLI instalado |
| 2 | `plazbot login` | Sesión iniciada sin copiar credenciales |
| 3 | `plazbot whatsapp setup` | Número conectado, primer mensaje ida y vuelta, webhook |
| 4 | `npm i plazbot` | Envíos desde tu app con tu API key |
| 5 | Webhook | Mensajes entrantes en tu servidor |