> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minimo.it/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget sessions

> Give each restaurant its own email area inside your app: settings, sessions, permissions and embedding

The widgets give each restaurant its own email area **inside your app**, without a Minimo account. Your backend
creates a session for one restaurant; your page shows the widgets in iframes.

## Example

```bash theme={null}
# Your backend, when the restaurant opens the page
curl -X POST https://api.minimo.it/public/v1/widgets/sessions \
  -H "Authorization: Bearer YOUR_MINIMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tenant": "restaurant_4812", "tenantName": "Trattoria da Mario", "locale": "it" }'
```

```html theme={null}
<!-- Your page, with the URL your backend got back -->
<div id="minimo-templates"></div>
<script src="https://api.minimo.it/public/v1/embed/widgets/widgets.js"></script>
<script>
  Minimo.mountWidget({ url: session.urls.templates, container: '#minimo-templates' });
</script>
```

The widgets:

| Widget | Permission | In the default | Page |
| - | - | - | - |
| Automatic messages (with the email editor and the on/off switches) | `templates` | yes | [Automatic messages widget](https://docs.minimo.it/embedded/widget-automatic-messages.md) |
| Campaigns | `campaigns` (+ `contacts` to pick and add recipients) | yes | [Campaigns widget](https://docs.minimo.it/embedded/widget-campaigns.md) |
| Contacts | `contacts` | yes | [Contacts widget](https://docs.minimo.it/embedded/widget-contacts.md) |
| Send history | `history` | yes | [Send history widget](https://docs.minimo.it/embedded/widget-history.md) |
| Statistics | `stats` | yes | [Statistics widget](https://docs.minimo.it/embedded/widget-statistics.md) |
| Brand | `brand` | no, ask for it | [Brand widget](https://docs.minimo.it/embedded/widget-brand.md) |
| WhatsApp (coming soon) | `whatsapp` | no, ask for it | [WhatsApp widget](https://docs.minimo.it/embedded/widget-whatsapp.md) |

Your API key never reaches the browser. Every widget call is limited to the restaurant of the session: a restaurant
never sees another restaurant's templates, guests or sends.

> [!NOTE]
>
> The widgets are in English and Italian, with a neutral look and a small "Email by Minimo" line (hide it with
> `poweredBy: false` for a white-label look).

## Before you start

* An API key with the **Widgets** permission (`widgets`), kept on your server. See [API keys and permissions](https://docs.minimo.it/embedded/overview.md#api-keys-and-permissions).
* The **origins** of the pages that embed the widgets and the **templates** your tenants see, set once. Set them before your first send, booking event or contact with `tenant`: until then Minimo does not keep restaurants apart (see [Contacts and the API](https://docs.minimo.it/embedded/overview.md#guests-and-the-contacts-api)).

```bash theme={null}
curl -X PUT https://api.minimo.it/public/v1/widgets/settings \
  -H "Authorization: Bearer YOUR_MINIMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allowedOrigins": ["https://app.yoursaas.example"],
    "masterTemplateIds": ["TRF4MS9", "RMD2HRS", "RVW3DAY"]
  }'
```

```json theme={null}
{
  "data": {
    "allowedOrigins": ["https://app.yoursaas.example"],
    "masterTemplateIds": [1201, 1202, 1203],
    "masterTemplateUids": ["TRF4MS9", "RMD2HRS", "RVW3DAY"]
  }
}
```

| Field | Notes |
| - | - |
| `allowedOrigins` | Pages allowed to embed the widgets (`frame-ancestors`) and to receive their events. One list shared with [embedded domain connect](https://docs.minimo.it/embedded/domain-connect.md): `PUT /public/v1/domains/embed-settings` writes the same list. Exact `scheme://host[:port]`, `https` only (`http` for `localhost`), no wildcards, at most 20. Anything else answers `400` with a `userMessage`. |
| `masterTemplateIds` | The templates every tenant sees, at most 50. Use the uid (for example `"TRF4MS9"`, from the UID column of **Templates** or `GET /public/v1/templates/email`) or the numeric id. You can mix them. The answer lists both: `masterTemplateIds` (numeric) and `masterTemplateUids`. Your **transactional** templates are the tenants' automatic messages. Your **campaign** templates are the starters of their broadcasts. An id that is not an email template of your workspace answers `400` with a `userMessage` naming it. A utility template that reads like a promotion (review request, offer, newsletter) is refused with `422 MASTER_LOOKS_PROMOTIONAL`: set its category to marketing. |

Each field replaces its list; omit a field to keep it. `GET` on the same path reads the settings.

## 1. Create a session (your backend)

```bash theme={null}
curl -X POST https://api.minimo.it/public/v1/widgets/sessions \
  -H "Authorization: Bearer YOUR_MINIMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant": "restaurant_4812",
    "tenantName": "Trattoria da Mario",
    "locale": "it",
    "variables": { "RESTAURANT_NAME": "Trattoria da Mario", "LOGO_URL": "https://cdn.example.com/mario/logo.png" },
    "from": "Trattoria da Mario <news@trattoriadamario.yoursaas.example>"
  }'
```

| Field | Required | Notes |
| - | - | - |
| `tenant` | yes | Your reference for the customer, the same value you pass as `tenant` when you send. 1-64 chars: letters, digits, `.` `_` `:` `-`. |
| `tenantName` | no | Shown in the widgets. |
| `permissions` | no | Any of `templates`, `campaigns`, `contacts`, `history`, `stats`, `brand`, `whatsapp`. Default: `templates`, `campaigns`, `contacts`, `history`, `stats`. A list you pass is taken as is (nothing is added to it). `brand` and `whatsapp` are never in the default: ask for them explicitly. |
| `locale` | no | `en` (default) or `it`. Any other value (`es`, `de`…) gives `400 INVALID_PARAMETERS`. See [Language and look](https://docs.minimo.it/embedded/overview.md#language-and-look). |
| `variables` | no | The tenant's merge values (`{RESTAURANT_NAME}`…), used in previews and in their broadcasts. Up to 30 keys, values up to 500 characters. |
| `from` | no | Sender of the tenant's broadcasts. Must be under a verified domain of your workspace (a subdomain works too), otherwise `422`. |
| `expiresInMinutes` | no | 5 to 720, default 60. |
| `poweredBy` | no | Default `true`: a small "Email by Minimo" line at the bottom of the widget pages, like the domain popup. `false` = white label: the pages carry no Minimo name. The emails your tenants send never carry a Minimo badge either way. |
| `brand.locked` | no | Brand fields you keep for yourself, read-only in the [Brand widget](https://docs.minimo.it/embedded/widget-brand.md): any of `displayName`, `legalName`, `logoUrl`, `brandColor`, `address`, `phone`, `email`, `website`, `privacyUrl`, `socials`. |

Response (`201`):

```json theme={null}
{
  "data": {
    "sessionId": "00000000-0000-4000-8000-000000000001",
    "token": "mws_…",
    "expiresAt": "2026-11-08T19:45:33.457Z",
    "tenant": "restaurant_4812",
    "urls": {
      "templates": "https://api.minimo.it/public/v1/embed/widgets/templates?s=…#mws_…",
      "campaigns": "https://api.minimo.it/public/v1/embed/widgets/campaigns?s=…#mws_…",
      "history": "https://api.minimo.it/public/v1/embed/widgets/history?s=…#mws_…",
      "contacts": "https://api.minimo.it/public/v1/embed/widgets/contacts?s=…#mws_…",
      "brand": "https://api.minimo.it/public/v1/embed/widgets/brand?s=…#mws_…",
      "whatsapp": "https://api.minimo.it/public/v1/embed/widgets/whatsapp?s=…#mws_…",
      "stats": "https://api.minimo.it/public/v1/embed/widgets/stats?s=…#mws_…"
    }
  }
}
```

Mint a session when your customer opens the page and pass only the `urls` to the browser. The token travels in the URL fragment, which never reaches a server log.

* Every URL is returned. A widget whose permission is not in the session loads, but its calls are refused (`403`) and it shows an error: mount only the widgets you asked for.
* Every session also refreshes the [tenant profile](https://docs.minimo.it/embedded/widget-brand.md#tenant-profile) from `tenantName`, `locale` and the brand variables, except the fields the restaurant changed itself.
* Revoke a session early with `DELETE /public/v1/widgets/sessions/{sessionId}` (`204`; `404` once it is gone). A revoked or expired session shows "Session expired: reload the page."
* If the call fails: `400 INVALID_PARAMETERS` (a field is wrong, or no allowed origin is set yet: the `userMessage`
  says which), `422 SENDER_NOT_ALLOWED` (`from` is not under a verified domain of your workspace), `429` (more than
  600 sessions in an hour). Reference: [Create Widget Session](https://docs.minimo.it/api-reference/embedded/widgets/create-session.md).

## 2. Embed the widgets (your frontend)

```html theme={null}
<div id="minimo-templates"></div>
<script src="https://api.minimo.it/public/v1/embed/widgets/widgets.js"></script>
<script>
  Minimo.mountWidget({
    url: session.urls.templates,
    container: '#minimo-templates',
    minHeight: 760,
    onEvent: function (event) {
      console.log(event.widget, event.type, event.data);
    },
  });
</script>
```

| Option | Notes |
| - | - |
| `url` | Required. One of the session `urls`. |
| `container` | Required. A CSS selector or an element. |
| `minHeight` | Minimum height in pixels, default 480. |
| `autoHeight` | Default `true`: the iframe follows the height of its content. |
| `title` | Title of the iframe for screen readers, default "Email". |
| `onEvent` | Called with `{ widget, type, data }` for every event of this iframe. |

`mountWidget` returns `{ iframe, destroy() }`. A plain `<iframe src="…">` works too.

## Events

Your page gets an event for what happens inside a widget (`template.saved`, `campaign.sent`, …). The full list:
[Widget events](https://docs.minimo.it/embedded/widget-events.md).

## What a tenant can and cannot do

* **Automatic messages**: personalize a copy of each master (texts, colors, images, subject), reset it to the standard, switch each automatic send on or off. Merge variables stay as they are. The footer with the unsubscribe link and the sender identity cannot be removed.
* **Campaigns**: create from a starter, edit, send now, only to their own contacts who gave marketing consent. A sent campaign cannot be edited or sent again.
* **Contacts**: manage their own guests in the [Contacts widget](https://docs.minimo.it/embedded/widget-contacts.md), or add them from the campaign widget. Every guest belongs to exactly one tenant: the same address in your workspace or at another tenant is another contact, never read or changed from here.
* **Brand**: set its own logo, color, contacts and legal details, except the fields you lock.
* **WhatsApp** (coming soon): each tenant will connect its own number and see its state. It uses the tenant's own WhatsApp Business account and its own card on Meta. Today the [WhatsApp widget](https://docs.minimo.it/embedded/widget-whatsapp.md) only explains how it works, and its button is off. A number already connected to Minimo will be refused, never moved.
* Your workspace's sending rules apply to every tenant (consent, daily limits for new tenants, clean lists, and the optional review of the first campaigns), see [Protections and sending limits](https://docs.minimo.it/embedded/protections.md). The usage counts on your workspace.

## Security

* The API key stays on your server; the session token is stored hashed (SHA-256) and expires.
* Every widget request is pinned to the session's workspace **and tenant**; another tenant's ids answer `404`.
* The editor opens through a single-use link bound to one template.
* `frame-ancestors` and `postMessage` targets are your allowed origins only.

## If something fails

A revoked or expired session shows "Session expired: reload the page": create a new session. A widget that is not
in the session's `permissions` answers `403 WIDGET_PERMISSION_DENIED`. Every code:
[Errors and limits](https://docs.minimo.it/embedded/errors.md).

## Next step

[Widget events](https://docs.minimo.it/embedded/widget-events.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.