# Números

> Números conectados, salud del número en Meta, nombre de usuario y enlace para conectar uno nuevo

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

### Introducción

El módulo **WhatsappNumbers** te da los números de WhatsApp conectados al workspace, su salud en Meta, su nombre de usuario y el enlace de registro de Meta para conectar uno nuevo. 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.numbers.list()
```

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

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

---

### Listar números

```ts
const numbers = await plazbot.numbers.list();

for (const n of numbers) {
console.log(n.phone, n.isActive ? "activo" : "inactivo");
}
```

| Campo | Descripción |
|-------|-------------|
| `id` | Id de la integración en Plazbot. |
| `phone` | Número en formato internacional. |
| `name` | Nombre del número. |
| `metaPhoneNumberId` | Phone number id de Meta. |
| `isActive` | Si el número está activo. |
| `isBusinessApp` | `true` si es la app WhatsApp Business conectada por QR (coexistencia). |

---

### Enlace para conectar un número

Devuelve el enlace de registro de Meta del workspace. Si no existe lo crea, y si venció lo regenera. Ábrelo en el navegador, o mándaselo a tu cliente, para conectar su número.

```ts
const link = await plazbot.numbers.getConnectLink();             // API de WhatsApp
const business = await plazbot.numbers.getConnectLink("whatsapp_business"); // app WhatsApp Business

console.log(link.url, link.expiresAt);

// Invalidar el enlace actual y crear otro
await plazbot.numbers.regenerateConnectLink("whatsapp");
```

---

### Salud del número

Lo mismo que el chequeo de salud de **Configuración** > **Integraciones**: calidad, límite de envío, si el número puede enviar, si llegan los mensajes entrantes y cada problema con su solución. Solo números conectados con la API de WhatsApp. Si el workspace tiene un solo número, no hace falta pasarlo.

```ts
const health = await plazbot.numbers.health("+51912345678");

if (health.level !== "GREEN") {
console.log(health.status, health.canSendMessage);
for (const issue of health.issues) console.log(issue.level, issue.description, issue.solution);
}
if (health.webhookSubscribed === false) console.log("Meta no está enviando los mensajes entrantes de este número");
```

| Campo | Descripción |
|-------|-------------|
| `level` | `GREEN`, `YELLOW` o `RED` (resumen de todo lo demás). |
| `canSendMessage` | `AVAILABLE`, `LIMITED` o `BLOCKED`. |
| `qualityRating` | Calidad del número según Meta: `GREEN`, `YELLOW`, `RED`. |
| `messagingLimit` | Conversaciones que puede iniciar por día (`TIER_250`, `TIER_1K`…). |
| `nameStatus` | Estado del nombre visible (`APPROVED`, `PENDING_REVIEW`…). |
| `numberStatus` | `CONNECTED`, `FLAGGED`, `RESTRICTED`, `BANNED`… |
| `webhookSubscribed` | `false` si la app no está suscrita al WABA (no llegan mensajes). `null` si no se pudo comprobar. |
| `issues` | Problemas de Meta: `{ entityType, level, code, description, solution }`. |
| `raw` | Respuesta completa del API. |

---

### Nombre de usuario (@usuario)

```ts
const { username, status } = await plazbot.numbers.getUsername();
const suggestions = await plazbot.numbers.getUsernameSuggestions();
await plazbot.numbers.claimUsername("mitienda");
```