# Web chat widget

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

```ts
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.

```ts
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.