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.
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
- 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.
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/browserllega con la 0.18.0 del SDK, que todavía no está en npm. Mientras tanto, abre elconnect_urlconwindow.openy escucha elpostMessagemeteor.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ó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 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é 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.