# Meteor adentro

**Meteor adentro** es lo que ve tu comercio cuando le das WhatsApp desde tu plataforma: conecta su número, y sus chats aparecen en una bandeja dentro de tu página, con un Met que responde y tu equipo o el comercio tomando la conversación cuando hace falta. **El comercio no sale de tu producto ni necesita usuario en Meteor.**

Esta página es el recorrido de punta a punta, en cuatro pasos, con el código mínimo de cada uno. Cada paso enlaza a su detalle completo en [WhatsApp para plataformas](whatsapp-para-plataformas.html), y la app de referencia los junta en un solo proyecto que puedes correr.

## Antes de empezar

- **Una API key de partner viva** de un Tech Partner aprobado. Los pasos 1, 2 y 4 solo funcionan con ella: una key de workspace no tiene esos permisos, y una key de prueba (`met_test_`) tampoco, porque conectan números reales.
- **Tus orígenes registrados.** El origen https desde el que tu página abre la conexión y la bandeja tiene que estar en la lista de tu partner; si no, la API responde `403 origin_not_allowed`. Pídeselo a tu contacto en Meteor.
- **Tu partner vinculado a una cuenta Met tuya**, para recibir en un solo endpoint los avisos de las líneas de todos tus comercios (paso 3).

| Paso | Qué hace | Con qué | Scope |
|---|---|---|---|
| 1 | Crea la cuenta del comercio | `met.workspaces.create()` | `workspaces:provision` |
| 2 | Conecta su WhatsApp | `met.workspaces.whatsappConnectSession()` + `connectWhatsapp()` | `channels:connect` |
| 3 | Confirma la línea por webhook | `met.webhooks.subscriptions.create()` + `constructEvent()` | `webhooks:manage` (en tu cuenta Met) |
| 4 | Monta su bandeja incrustada | `met.workspaces.inboxSession()` + `postMessage` | `inbox:embed` |

## 1. Crea la cuenta del comercio

Tu backend crea la cuenta con la key de partner. Nace con el plan Tech Partner, atribuida a ti y **sin energía**: cárgale saldo antes de su primer mensaje, o el Met no responde.

```ts
import Met from '@meteor.ia/sdk';

const met = new Met(process.env.MET_PARTNER_KEY!);

const cuenta = await met.workspaces.create(
  { business_name: 'Restaurante La Esquina', owner_email: 'dueno@laesquina.co', owner_name: 'Carlos Ruiz', owner_phone: '+573001234567' },
  { idempotencyKey: `alta-${comercio.id}` }, // un reintento devuelve la misma cuenta
);
```

Los pasos 2 y 4 solo funcionan sobre cuentas atribuidas a ti; sobre otra, `403 workspace_not_attributed`. Cupos, recargas y traspaso: [Aprovisionamiento de cuentas](aprovisionamiento.html).

## 2. Conecta su WhatsApp con `connectWhatsapp()`

Tu backend pide la sesión de conexión; tu página la abre con `connectWhatsapp()`, del subpath de navegador del SDK, **en el clic** del comercio. La key nunca va al navegador.

```ts
// Backend: POST /api/whatsapp/sesion
const sesion = await met.workspaces.whatsappConnectSession(cuenta.id, { return_origin: 'https://app.tuplataforma.com' });
return { session_id: sesion.session_id, connect_url: sesion.connect_url }; // el connect_url sirve una vez: no lo guardes
```

```ts
// Página, en https://app.tuplataforma.com
import { connectWhatsapp, MetWhatsappConnectError } from '@meteor.ia/sdk/browser';

boton.onclick = async () => {
  try {
    const r = await connectWhatsapp(() => fetch('/api/whatsapp/sesion', { method: 'POST' }).then((res) => res.json()));
    mostrar(`${r.phone_number} conectado. Confirmando…`); // un aviso: la confirmación es el webhook
  } catch (e) {
    if (e instanceof MetWhatsappConnectError) mostrarAviso(e.message); // e.code: popup_blocked, popup_closed…
  }
};
```

`return_origin` tiene que ser el origen de la página que llama a `connectWhatsapp()`, y esa página no puede enviar `Cross-Origin-Opener-Policy: same-origin`: en los dos casos no llega el aviso. Por defecto se conecta por coexistencia: el comercio sigue usando la app WhatsApp Business en su celular.

> **`@meteor.ia/sdk/browser` llega con la 0.18.0 del SDK**, que todavía no está en npm. Mientras tanto, abre el `connect_url` con `window.open` y escucha el `postMessage` `meteor.whatsapp.connect`, como explica la guía de detalle.

La variante por enlace, los códigos de error y el `postMessage` sin SDK: [Genera el enlace para conectar WhatsApp](whatsapp-para-plataformas.html#2-genera-el-enlace-para-conectar-whatsapp).

## 3. Recibe y verifica el webhook

El resultado del navegador puede no llegar: el comercio cierra la ventana antes de tiempo. La verdad es el webhook. Registra **una vez** tu endpoint en tu propia cuenta Met, con una key de workspace de esa cuenta:

```ts
const metMiCuenta = new Met(process.env.MET_MI_CUENTA_KEY!);
const sub = await metMiCuenta.webhooks.subscriptions.create({
  url: 'https://app.tuplataforma.com/met/eventos',
  enabled_events: ['channel.line.connected', 'channel.line.failed'],
});
// sub.secret se muestra UNA sola vez: guárdalo
```

En tu endpoint, verifica la firma `X-Met-Signature` sobre el cuerpo **crudo**, antes de parsearlo:

```ts
import { constructEvent, MetSignatureVerificationError } from '@meteor.ia/sdk';

// `crudo`: el cuerpo tal cual llegó, como texto o Buffer
try {
  const evento = constructEvent(crudo, String(req.headers['x-met-signature'] ?? ''), process.env.MET_WEBHOOK_SECRET!);
  if (evento.type === 'channel.line.connected') {
    const { workspace_id, connect_session_id, line_id, phone_number } = evento.data;
    // connect_session_id es el session_id del paso 2; guarda el line_id para el paso 4
  }
  res.status(200).end();
} catch (e) {
  if (e instanceof MetSignatureVerificationError) res.status(400).end();
  else throw e;
}
```

`channel.line.failed` trae `error_code`, nunca el mensaje crudo de Meta. Un reintento de entrega trae el mismo `id` de evento: úsalo para no procesarlo dos veces. El cuerpo completo de los eventos: [Entérate de cada línea por webhook](whatsapp-para-plataformas.html#3-enterate-de-cada-linea-por-webhook); la firma y los reintentos: [Webhooks](webhooks.html).

## 4. Monta su bandeja incrustada

Tu backend pide una sesión de bandeja **cada vez** que la vas a mostrar, y tu página pone el `inbox_url` en un iframe servido desde `parent_origin`:

```ts
const bandeja = await met.workspaces.inboxSession(cuenta.id, {
  parent_origin: 'https://app.tuplataforma.com', // origen exacto, registrado
  line_id: lineId,                                 // el del webhook; sin él, todos los chats de la cuenta
  language: 'es',
  theme: 'system',
  brand_color: '#0F7B6C',
  hide: ['search'],
});
// bandeja.inbox_url → al src del iframe. Sirve una vez y vale 10 minutos sin abrir.
```

```html
<iframe id="bandeja" src="INBOX_URL" title="Bandeja de WhatsApp" style="width:100%;height:640px;border:0"></iframe>
```

Ahí el comercio lee y responde, toma un chat (el Met se calla), lo devuelve y pausa la IA. Está hecha con las mismas piezas del Chat de Met: cuando Met mejora su bandeja, la tuya mejora con ella. Tu página es solo el anfitrión, y le habla por `postMessage` con el prefijo `meteor.inbox:` y el `nonce` que la bandeja anuncia en su primer mensaje:

```ts
const ORIGEN = new URL(bandeja.inbox_url).origin;
const marco = document.getElementById('bandeja') as HTMLIFrameElement;
let nonce: string | null = null;
const enviar = (event: string, payload = {}) =>
  nonce && marco.contentWindow!.postMessage('meteor.inbox:' + JSON.stringify({ version: 1, nonce, event, payload }), ORIGEN);

window.addEventListener('message', (e) => {
  if (e.origin !== ORIGEN || e.source !== marco.contentWindow) return;
  if (typeof e.data !== 'string' || !e.data.startsWith('meteor.inbox:')) return;
  let m;
  try { m = JSON.parse(e.data.slice('meteor.inbox:'.length)); } catch { return; }
  if (m.version !== 1) return;
  nonce ??= m.nonce;
  if (m.nonce !== nonce) return;
  if (m.event === 'ready') enviar('init', { theme: 'dark', brand_color: '#0F7B6C' });
  if (m.event === 'session.expired') pedirOtraSesion(); // nunca reuses la URL
});
```

**Lo que personalizas:**

| Qué | Al crear la sesión | En vivo, por `postMessage` |
|---|---|---|
| Tema | `theme`: `light`, `dark` o `system` | `set_theme` |
| Color de marca | `brand_color` en `#RRGGBB` | `set_theme` |
| Idioma | `language`: `es` o `en` | `set_language` |
| Estilo de burbujas y botones | `style` (lista cerrada, sin CSS libre) | `init` |
| Ocultar secciones | `hide`: `search`, `ai_controls`, `attachments`, `new_chat`, `sort` | — se fija al crear la sesión |

Para cerrarla antes de que venza, revócala con `met.workspaces.revokeInboxSession(cuenta.id, bandeja.session_id)`. El anfitrión completo con la reconexión, el panel del cliente con tus acciones y relaciones, y cada variable de estilo: [Abre la bandeja dentro de tu producto](whatsapp-para-plataformas.html#4-abre-la-bandeja-dentro-de-tu-producto) y [Personaliza la bandeja](whatsapp-para-plataformas.html#5-personaliza-la-bandeja).

## La app de referencia

La app de referencia (la carpeta `examples/meteor-adentro/` del SDK de TypeScript, que llega con la 0.18.0) hace los cuatro pasos en un solo proyecto: un servidor Node sin más dependencias que el SDK (`servidor.ts`), un script que registra el webhook una vez (`registrar-webhook.ts`) y una página sin bundler que usa `connectWhatsapp()` y monta la bandeja con su anfitrión. Las credenciales van por variables de entorno (`MET_PARTNER_KEY`, `MET_WEBHOOK_SECRET`, `APP_ORIGIN`, y `MET_MI_CUENTA_KEY` para registrar), con un `DEMO_TOKEN` opcional que protege sus rutas `/api`, y su README dice cómo correrla. Guarda el estado en memoria: es una referencia, no un producto.

## Prueba antes con una key de prueba

Mientras no tengas la key viva, una key de partner de prueba (`met_test_`) sirve para comprobar que tu backend se autentica y que maneja bien cada error del recorrido. No toca números ni chats reales.

| Qué llamas | Qué responde con una key `met_test_` |
|---|---|
| Tu negocio de partner: `GET /partner/clients`, `/partner/leads` y `/partner/commissions` en `api.partners.meteor.com.co` | `200` si tu key trae los scopes `partner:*:read`. Sin cuentas atribuidas, las listas llegan vacías |
| Pasos 1, 2 y 4 | `403 missing_scope` si tu key de prueba no trae el scope del paso; `403 test_mode_restricted` si lo trae. Crean cuentas, conectan números y responden chats reales: con una key de prueba no corren nunca |
| Paso 3 | Se registra en tu propia cuenta Met, con una key de workspace de esa cuenta, no con la de partner |
| Cualquier otra ruta sobre una cuenta que no está atribuida a ti | `403 workspace_not_attributed` |

Si tu código ya distingue esos tres `403` y te muestra el `message`, el cambio a la key viva es solo la variable de entorno, con una key viva que traiga los scopes de los pasos de la tabla.

## Qué no incluye todavía

- **El chat con un Met.** Lo que se incrusta hoy es la bandeja de WhatsApp. La conversación con un Met no se puede poner en tu página.
- **Números nuevos por API.** La API no crea ni compra números de WhatsApp. El comercio conecta un número que ya tiene, en el registro de Meta del paso 2, sea por coexistencia o como número dedicado.

> **La bandeja está en piloto.** Funciona de punta a punta. Escríbenos antes de llevarla a todos tus comercios.
