En esta sección
Guías / Meteor adentro

Meteor adentro

Para Tech Partners: el recorrido completo para que tu comercio conecte su WhatsApp y atienda en su bandeja sin salir de tu producto, con una app de referencia.

Actualizada el Ver .md

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, y la app de referencia los junta en un solo proyecto que puedes correr.

Antes de empezar

PasoQué haceCon quéScope
1Crea la cuenta del comerciomet.workspaces.create()workspaces:provision
2Conecta su WhatsAppmet.workspaces.whatsappConnectSession() + connectWhatsapp()channels:connect
3Confirma la línea por webhookmet.webhooks.subscriptions.create() + constructEvent()webhooks:manage (en tu cuenta Met)
4Monta su bandeja incrustadamet.workspaces.inboxSession() + postMessageinbox: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.

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.

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.

// 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
// 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.

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:

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:

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; la firma y los reintentos: Webhooks.

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:

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.
<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:

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ónEn vivo, por postMessage
Tematheme: light, dark o systemset_theme
Color de marcabrand_color en #RRGGBBset_theme
Idiomalanguage: es o enset_language
Estilo de burbujas y botonesstyle (lista cerrada, sin CSS libre)init
Ocultar seccioneshide: 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 y 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é llamasQué responde con una key met_test_
Tu negocio de partner: GET /partner/clients, /partner/leads y /partner/commissions en api.partners.meteor.com.co200 si tu key trae los scopes partner:*:read. Sin cuentas atribuidas, las listas llegan vacías
Pasos 1, 2 y 4403 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 3Se 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 ti403 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

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