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

# Create Widget Session

> Open the widgets for one restaurant: one URL per widget, for iframes

Guide: [Widget sessions](https://docs.minimo.it/embedded/widgets.md). Errors: [Errors and limits](https://docs.minimo.it/embedded/errors.md).


## OpenAPI

````yaml post /public/v1/widgets/sessions
openapi: 3.1.0
info:
  title: API Documentation
  description: Documentation for transactional and subscribe APIs
  version: 1.0.0
servers:
  - url: https://app.minimo.it
security:
  - bearerAuth: []
paths:
  /public/v1/widgets/sessions:
    servers:
      - url: https://api.minimo.it
    post:
      summary: Create widget session
      description: >-
        Call it from your backend for the restaurant that is looking at your
        app. Put the returned URLs in iframes.


        Every widget call is limited to this restaurant: its templates, guests,
        campaigns and sends. Set the allowed origins first with Update Widget
        Settings.
      operationId: createWidgetSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tenant:
                  type: string
                  description: >-
                    Your reference for the restaurant. 1 to 64 letters, digits,
                    `.` `_` `:` `-`. The same value as `tenant` on the send
                    endpoints.
                  example: restaurant_4812
                tenantName:
                  type: string
                  description: Name shown in the widgets.
                  example: Trattoria da Mario
                permissions:
                  type: array
                  items:
                    type: string
                    enum:
                      - templates
                      - campaigns
                      - contacts
                      - history
                      - stats
                      - brand
                      - whatsapp
                  description: >-
                    Widgets this session can open. Default: `templates`,
                    `campaigns`, `contacts`, `history`, `stats`. `brand` and
                    `whatsapp` are never in the default.
                locale:
                  type: string
                  enum:
                    - en
                    - it
                  default: en
                  description: Language of the widgets.
                variables:
                  type: object
                  description: >-
                    Merge values of this restaurant (for example
                    `RESTAURANT_NAME`, `LOGO_URL`), used in previews and in its
                    campaigns. At most 30 keys, values up to 500 characters.
                  example:
                    RESTAURANT_NAME: Trattoria da Mario
                from:
                  type: string
                  description: >-
                    Sender of the restaurant's campaigns: `"Name <address>"` or
                    an address under a verified domain of your workspace (`422`
                    otherwise). Default: your workspace sender.
                  example: Trattoria da Mario <news@yoursaas.example>
                replyTo:
                  type: string
                  maxLength: 320
                  description: >-
                    Where guests' replies go: `"Name <address>"` or an address.
                    Any mailbox. Default: the `RESTAURANT_EMAIL` variable when
                    it is a valid address.
                  example: Trattoria da Mario <owner@trattoriadamario.example>
                expiresInMinutes:
                  type: integer
                  minimum: 5
                  maximum: 720
                  default: 60
                  description: Session lifetime.
                poweredBy:
                  type: boolean
                  default: true
                  description: >-
                    Show the small Minimo line at the bottom of the widgets.
                    `false` = no Minimo text in the widgets.
                brand:
                  type: object
                  properties:
                    locked:
                      type: array
                      items:
                        type: string
                        enum:
                          - displayName
                          - legalName
                          - logoUrl
                          - brandColor
                          - address
                          - phone
                          - email
                          - website
                          - privacyUrl
                          - socials
                      example:
                        - legalName
                        - privacyUrl
                      description: >-
                        Brand fields your app keeps: the Brand widget shows them
                        read-only.
                  description: Options of the Brand widget.
              required:
                - tenant
            example:
              tenant: restaurant_4812
              tenantName: Trattoria da Mario
              locale: it
              permissions:
                - templates
                - campaigns
                - contacts
                - history
                - stats
              variables:
                RESTAURANT_NAME: Trattoria da Mario
                LOGO_URL: https://cdn.example.com/logo.png
              replyTo: Trattoria da Mario <owner@trattoriadamario.example>
      responses:
        '201':
          description: The session and one URL per widget
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/WidgetSession'
              example:
                data:
                  sessionId: 3f6c2a0e-8b1d-4c55-9a7e-2d4b6f1e9c10
                  token: mws_…
                  expiresAt: '2026-11-15T19:00:00.000Z'
                  tenant: restaurant_4812
                  urls:
                    templates: >-
                      https://api.minimo.it/public/v1/embed/widgets/templates#token=…
                    campaigns: >-
                      https://api.minimo.it/public/v1/embed/widgets/campaigns#token=…
                    history: >-
                      https://api.minimo.it/public/v1/embed/widgets/history#token=…
                    contacts: >-
                      https://api.minimo.it/public/v1/embed/widgets/contacts#token=…
                    brand: >-
                      https://api.minimo.it/public/v1/embed/widgets/brand#token=…
                    whatsapp: >-
                      https://api.minimo.it/public/v1/embed/widgets/whatsapp#token=…
                    stats: >-
                      https://api.minimo.it/public/v1/embed/widgets/stats#token=…
        '400':
          description: >-
            `EMBED_ORIGINS_NOT_CONFIGURED`: set the allowed origins first.
            `INVALID_PARAMETERS`: a field is not valid (also a wrong `tenant`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: >-
            `INVALID_TOKEN`: missing or wrong key, or a key without the
            **Widgets** permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: >-
            `SENDER_NOT_ALLOWED`, `INVALID_REPLY_TO` or another sender error.
            See [Errors and limits](/embedded/errors#sending).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - bearerAuth: []
      x-codeSamples:
        - label: cURL
          lang: bash
          source: |-
            curl --request POST \
              --url 'https://api.minimo.it/public/v1/widgets/sessions' \
              --header 'Authorization: Bearer YOUR_MINIMO_KEY' \
              --header 'Content-Type: application/json' \
              --data '{"tenant": "restaurant_4812", "tenantName": "Trattoria da Mario", "locale": "it"}'
        - lang: JavaScript
          source: >-
            const res = await
            fetch('https://api.minimo.it/public/v1/widgets/sessions', {
              method: 'POST',
              headers: {
                Authorization: 'Bearer YOUR_MINIMO_KEY',
                'Content-Type': 'application/json',
              },
              body: JSON.stringify({"tenant": "restaurant_4812", "tenantName": "Trattoria da Mario", "locale": "it"}),
            });

            const { data } = await res.json();

            console.log(data);
        - lang: Python
          source: |-
            import requests

            res = requests.post(
                'https://api.minimo.it/public/v1/widgets/sessions',
                headers={'Authorization': 'Bearer YOUR_MINIMO_KEY'},
                json={"tenant": "restaurant_4812", "tenantName": "Trattoria da Mario", "locale": "it"},
            )
            print(res.status_code, res.text)
components:
  schemas:
    WidgetSession:
      type: object
      properties:
        sessionId:
          type: string
          format: uuid
          description: Id of the session. Use it to revoke the session.
          example: 3f6c2a0e-8b1d-4c55-9a7e-2d4b6f1e9c10
        token:
          type: string
          description: >-
            Session token (starts with `mws_`). It is already inside every
            widget URL. Do not log it or send it anywhere else.
          example: mws_…
        expiresAt:
          type: string
          format: date-time
          description: When the session ends.
          example: '2026-11-15T19:00:00.000Z'
        tenant:
          type: string
          example: restaurant_4812
        urls:
          type: object
          properties:
            templates:
              type: string
              description: URL of the templates widget. Open it in an iframe.
            campaigns:
              type: string
              description: URL of the campaigns widget. Open it in an iframe.
            history:
              type: string
              description: URL of the history widget. Open it in an iframe.
            contacts:
              type: string
              description: URL of the contacts widget. Open it in an iframe.
            brand:
              type: string
              description: URL of the brand widget. Open it in an iframe.
            whatsapp:
              type: string
              description: URL of the whatsapp widget. Open it in an iframe.
            stats:
              type: string
              description: URL of the stats widget. Open it in an iframe.
          description: >-
            One URL per widget. A widget not in `permissions` answers `403
            WIDGET_PERMISSION_DENIED`.
      required:
        - sessionId
        - token
        - expiresAt
        - tenant
        - urls
    ApiError:
      type: object
      properties:
        status:
          type: string
          example: FAIL
        message:
          type: string
          description: The error code to test in your code.
          example: INVALID_PARAMETERS
        userMessage:
          type: string
          description: >-
            When present, a sentence that says what to fix. You can show or log
            it.
          example: Set the origins allowed to embed the widgets first.
      description: >-
        Every error has this shape. See [Errors and limits](/embedded/errors)
        for every code.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: mn-API_CLIENT_ID-API_KEY

````

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