Guides / Web chat widget

Web chat widget

Read and change how your site's chat looks, the welcome message, the Met that answers and the domains it shows up on.

Updated October 22, 2026 View .md

The widget is the chat that shows up in the corner of your site. With GET and PATCH /workspaces/{workspaceId}/web-widget you read and change its appearance, the welcome message, the Met that answers and the domains where it can be shown.

Scopes channels:read (read) and channels:write (change). It does not consume Energy. The web chat is activated the first time from Channels → Web chat in the panel; until it is activated, both operations respond 404 with web_widget_not_found.

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

const met = new Met(process.env.MET_KEY!, { workspaceId: 42 });

const widget = await met.webWidget.retrieve();
console.log(widget.appearance.color, widget.welcome.title, widget.primary_met_id);

Changing the configuration

What you do not send does not change. Inside appearance and welcome it also goes field by field: you can change only the color without touching the rest.

await met.webWidget.update({
  appearance: { color: '#1F6FEB', theme: 'auto', position: 'left' },
  welcome: { title: '¡Hola! 👋', tagline: 'Escríbenos y te respondemos al instante.' },
  primary_met_id: 31,
  allowed_domains: ['mydomain.com', '*.mydomain.com'],
});

Field	Values
`appearance.color`	Hexadecimal `#RRGGBB`.
`appearance.avatar`	An emoji or the `https` URL of an image.
`appearance.position`	`right` or `left`.
`appearance.bubble_style`	`icon` (just the circle) or `expanded` (with `bubble_text` next to it).
`appearance.theme`	`light`, `dark` or `auto` (follows the visitor's system mode).
`welcome.title`, `welcome.tagline`	The chat's title and welcome message.
`primary_met_id`	The Met that answers, an `id` from `met.agents.list()`. `null` removes it.
`secondary_met_ids`	Backup Mets, up to 10. Replaces the whole list.
`allowed_domains`	From 1 to 50. Replaces the whole list. `*.mydomain.com` covers the subdomains.

A Met that is not from your workspace responds 404 with met_not_found; a misspelled domain, 400 with validation_error and param: 'allowed_domains'. Changes show up on your site the next time the page loads.

allowed_domains cannot be empty. An empty list does not close the widget: it leaves it open, and it would show up and answer on any site. That is why it responds 400 with allowed_domains_empty. For the widget not to appear on any site, deactivate it from Channels → Web chat in the panel. A wildcard that covers other people's sites is not accepted either: a public suffix such as *.com.co or *.co, or that of a platform that hands out subdomains, such as *.vercel.app, *.github.io, *.netlify.app or *.herokuapp.com. It responds 400 with allowed_domain_too_broad. Use your own domain (*.mydomain.com) or your exact subdomain (mydomain.vercel.app).

What stays in the panel

The installation code (the <script> with the widget's token), business hours, the pre-chat form and turning the widget on or off are handled from Channels → Web chat. The API response does not carry the snippet's token.

← PreviousChannel status Next →Meta forms (Lead Ads)