On this page
Guides / Meteor inside

Meteor inside

For Tech Partners: the whole path for your merchant to connect their WhatsApp and work from their inbox without leaving your product, with a reference app.

Updated View .md

Meteor inside is what your merchant sees when you give them WhatsApp from your platform: they connect their number, and their chats show up in an inbox inside your page, with a Met that answers and your team or the merchant taking over the conversation when needed. The merchant never leaves your product and needs no Meteor user.

This page is the end-to-end path, in four steps, with the minimum code for each. Every step links to its full detail in WhatsApp for platforms, and the reference app puts them together in a single project you can run.

Before you start

StepWhat it doesWithScope
1Creates the merchant's accountmet.workspaces.create()workspaces:provision
2Connects their WhatsAppmet.workspaces.whatsappConnectSession() + connectWhatsapp()channels:connect
3Confirms the line by webhookmet.webhooks.subscriptions.create() + constructEvent()webhooks:manage (on your Met account)
4Mounts their embedded inboxmet.workspaces.inboxSession() + postMessageinbox:embed

1. Create the merchant's account

Your backend creates the account with the partner key. It is born on the Tech Partner plan, attributed to you and with no energy: top it up before its first message, or the Met does not answer.

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

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

const account = await met.workspaces.create(
  { business_name: 'Restaurante La Esquina', owner_email: 'owner@laesquina.co', owner_name: 'Carlos Ruiz', owner_phone: '+573001234567' },
  { idempotencyKey: `signup-${merchant.id}` }, // a retry returns the same account
);

Steps 2 and 4 only work on accounts attributed to you; on any other, 403 workspace_not_attributed. Quotas, top-ups and handover: Account provisioning.

2. Connect their WhatsApp with connectWhatsapp()

Your backend requests the connect session; your page opens it with connectWhatsapp(), from the SDK's browser subpath, inside the merchant's click. The key never goes to the browser.

// Backend: POST /api/whatsapp/session
const session = await met.workspaces.whatsappConnectSession(account.id, { return_origin: 'https://app.yourplatform.com' });
return { session_id: session.session_id, connect_url: session.connect_url }; // the connect_url works once: don't store it
// Page, at https://app.yourplatform.com
import { connectWhatsapp, MetWhatsappConnectError } from '@meteor.ia/sdk/browser';

button.onclick = async () => {
  try {
    const r = await connectWhatsapp(() => fetch('/api/whatsapp/session', { method: 'POST' }).then((res) => res.json()));
    show(`${r.phone_number} connected. Confirming…`); // a notice: the confirmation is the webhook
  } catch (e) {
    if (e instanceof MetWhatsappConnectError) showNotice(e.message); // e.code: popup_blocked, popup_closed…
  }
};

return_origin has to be the origin of the page that calls connectWhatsapp(), and that page can't send Cross-Origin-Opener-Policy: same-origin: in either case the notice doesn't arrive. By default it connects by coexistence: the merchant keeps using the WhatsApp Business app on their phone.

@meteor.ia/sdk/browser ships with SDK 0.18.0, which is not on npm yet. Until then, open the connect_url with window.open and listen for the meteor.whatsapp.connect postMessage, as the detail guide explains.

The link variant, the error codes and the postMessage without the SDK: Generate the link to connect WhatsApp.

3. Receive and verify the webhook

The browser's result may never arrive: the merchant closes the window too early. The truth is the webhook. Register your endpoint once on your own Met account, with a workspace key of that account:

const metMyAccount = new Met(process.env.MET_MY_ACCOUNT_KEY!);
const sub = await metMyAccount.webhooks.subscriptions.create({
  url: 'https://app.yourplatform.com/met/events',
  enabled_events: ['channel.line.connected', 'channel.line.failed'],
});
// sub.secret is shown ONLY once: store it

On your endpoint, verify the X-Met-Signature signature over the raw body, before parsing it:

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

// `raw`: the body exactly as it arrived, as text or a Buffer
try {
  const event = constructEvent(raw, String(req.headers['x-met-signature'] ?? ''), process.env.MET_WEBHOOK_SECRET!);
  if (event.type === 'channel.line.connected') {
    const { workspace_id, connect_session_id, line_id, phone_number } = event.data;
    // connect_session_id is the session_id from step 2; keep the line_id for step 4
  }
  res.status(200).end();
} catch (e) {
  if (e instanceof MetSignatureVerificationError) res.status(400).end();
  else throw e;
}

channel.line.failed carries error_code, never Meta's raw message. A delivery retry carries the same event id: use it so you don't process it twice. The full body of the events: Learn about each line by webhook; signatures and retries: Webhooks.

4. Mount their embedded inbox

Your backend requests an inbox session every time you are about to show it, and your page puts the inbox_url in an iframe served from parent_origin:

const inbox = await met.workspaces.inboxSession(account.id, {
  parent_origin: 'https://app.yourplatform.com', // exact origin, registered
  line_id: lineId,                                  // the one from the webhook; without it, every chat on the account
  language: 'en',
  theme: 'system',
  brand_color: '#0F7B6C',
  hide: ['search'],
});
// inbox.inbox_url → into the iframe's src. It works once and lasts 10 minutes unopened.
<iframe id="inbox" src="INBOX_URL" title="WhatsApp inbox" style="width:100%;height:640px;border:0"></iframe>

There the merchant reads and replies, takes a chat (the Met goes quiet), hands it back and pauses the AI. It is built from the same pieces as Met's Chat: when Met improves its inbox, yours improves with it. Your page is only the host, and talks to it by postMessage with the meteor.inbox: prefix and the nonce the inbox announces in its first message:

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

window.addEventListener('message', (e) => {
  if (e.origin !== ORIGIN || e.source !== frame.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') send('init', { theme: 'dark', brand_color: '#0F7B6C' });
  if (m.event === 'session.expired') requestAnotherSession(); // never reuse the URL
});

What you customize:

WhatWhen creating the sessionLive, by postMessage
Themetheme: light, dark or systemset_theme
Brand colorbrand_color as #RRGGBBset_theme
Languagelanguage: es or enset_language
Bubble and button stylestyle (closed list, no free CSS)init
Hide sectionshide: search, ai_controls, attachments, new_chat, sort— fixed when the session is created

To close it before it expires, revoke it with met.workspaces.revokeInboxSession(account.id, inbox.session_id). The full host with reconnection, the customer panel with your actions and relations, and every style variable: Open the inbox inside your product and Customize the inbox.

The reference app

The reference app (the examples/meteor-adentro/ folder of the TypeScript SDK, which ships with 0.18.0) does the four steps in a single project: a Node server with no dependencies beyond the SDK (servidor.ts), a script that registers the webhook once (registrar-webhook.ts) and a page with no bundler that uses connectWhatsapp() and mounts the inbox with its host. Credentials go in environment variables (MET_PARTNER_KEY, MET_WEBHOOK_SECRET, APP_ORIGIN, and MET_MI_CUENTA_KEY to register), with an optional DEMO_TOKEN that protects its /api routes, and its README explains how to run it. It keeps state in memory: it is a reference, not a product.

Try it first with a test key

Until you have your live key, a partner test key (met_test_) lets you check that your backend authenticates and handles every error along the path. It doesn't touch real numbers or chats.

What you callWhat a met_test_ key gets
Your partner business: GET /partner/clients, /partner/leads and /partner/commissions on api.partners.meteor.com.co200 if your key carries the partner:*:read scopes. With no attributed accounts, the lists come back empty
Steps 1, 2 and 4403 missing_scope if your test key doesn't carry the step's scope; 403 test_mode_restricted if it does. They create accounts, connect numbers and answer real chats: they never run with a test key
Step 3It's registered in your own Met account, with a workspace key of that account, not with the partner key
Any other route on an account that isn't attributed to you403 workspace_not_attributed

If your code already tells those three 403s apart and shows you the message, switching to the live key is just the environment variable, with a live key that carries the scopes of the steps in the table.

What it doesn't include yet

The inbox is in pilot. It works end to end. Write to us before rolling it out to all your merchants.