Customization and Reference

Component `<m8ty-chat>`

Kind	Name	Description
Attribute	`share`	Share ID (required)
Attribute	`locale`	`de` or `en`; default: page language
Attribute	`theme`	`light`, `dark` or `auto` (default)
Attribute	`api-base`	Override of the Ragty chat API URL; only needed for special proxy setups
Property	`getTicket`	Delegated shares: `(nonce: string) => Promise<{ ticket: string }>`
Property	`version`	Component version (read-only)
Method	`reset()`	Starts a new, empty conversation
Event	`m8ty-ready`	Session established; `detail.version`
Event	`m8ty-error`	`detail.code`: `unavailable`, `rate_limited` or `failed`
Event	`m8ty-session-expired`	The session could not be renewed (e.g. `getTicket` failed)

Events bubble and cross the shadow boundary. They never contain tokens, chat content or user identifiers.

Type declarations: https://rag.example.com/embed-assets/v1/m8ty-chat.d.ts.

Theming

Set CSS custom properties on the element:

m8ty-chat {
  --m8ty-color-primary: #0b5fff;
  --m8ty-color-on-primary: #ffffff;
  --m8ty-color-background: #ffffff;
  --m8ty-color-surface: #f3f5f8;
  --m8ty-color-header: #ffffff;
  --m8ty-color-text: #1b1f24;
  --m8ty-color-muted: #5f6b7a;
  --m8ty-color-border: #d9dee5;
  --m8ty-color-input: #ffffff;
  --m8ty-color-code: rgba(0, 0, 0, .06);
  --m8ty-font-family: "Inter", sans-serif;
  --m8ty-font-size: 14px;
  --m8ty-radius: 10px;
}

Style individual parts with ::part():

m8ty-chat::part(header) { display: none; }
m8ty-chat::part(message-user) { border-radius: 4px; }

Parts: container, header, history, messages, message, message-user, message-assistant, sources, input-row, input, send.

Behavior

Answers stream in; numbered markers [1] refer to the cited sources listed below the answer (document name, page, link for web sources).
The history button lists the user's previous chats; they can be reopened and deleted by the user.
Maximum question length and daily quota are configured on the share; the component shows a localized message when they are reached.

iframe

https://rag.example.com/embed/{shareId}?locale=de&theme=auto

Kind	Name	Description
Query parameter	`locale`	`de` or `en`; default: browser language
Query parameter	`theme`	`light`, `dark` or `auto` (default)
Attribute	`referrerpolicy="strict-origin"`	Required: lets the iframe determine your page origin
Attribute	`allow="clipboard-write"`	Optional: allows the chat to write to the clipboard
Function	`connectIframe(iframe, { getTicket })`	Delegated shares: answers the iframe's ticket requests; returns a function that disconnects it. Exported by `m8ty-chat.js` and available as `window.M8tyEmbed.connectIframe`

The iframe requests a ticket on start and whenever the session must be renewed. It repeats the request with backoff until your page acknowledges it and gives up after 15 seconds; connectIframe calls getTicket only once per request, even if it was repeated. See iframe. Theming via CSS is not possible inside the iframe; use theme or the web component.

HTTP endpoints you call

Only one endpoint is called by your code, and only for delegated shares.

`POST /api/v1/embed/tickets` (server to server)


Caller	Your backend only
Headers	`Authorization: Bearer <gateway key>`, `X-End-User-Assertion: <JWT>`, `Content-Type: application/json`
Body	`{"share_id": "shr_…", "origin": "https://…", "nonce": "…"}`
Success	`200 {"ticket": "…", "expires_in": 60}` — single use, bound to share, origin, nonce and user

Status	`detail`	Meaning	What to do
`401`	`unauthorized`	Missing headers, unknown/revoked/expired gateway key, or invalid assertion (`iss`, `aud`, `exp`, signature, `kid`)	Check key and assertion format (How the User Is Passed)
`403`	`forbidden`	Origin not allowed for the share, assertion issuer differs from the share's issuer, or user erased/blocked	Use an allowed origin; check issuer; contact the administrator
`404`	`unavailable`/`not_found`	Share unknown, disabled, expired, not delegated, not bound to this gateway key, or delegation disabled on the platform	Check the share with the administrator
`422`	`invalid_origin`/ validation	Malformed origin, share ID or nonce	Fix the request
`429`	`rate_limited`	Too many tickets for this gateway key	Retry later; do not request tickets in a loop
`503`	`temporarily_unavailable`	Ragty state backend unavailable	Retry with backoff

HTTP endpoints called by the component

For reference and for firewall/proxy rules — you do not call them yourself.

Method	Path	Purpose
`GET`	`/embed/v1/shares/{id}/config`	Name, greeting and limits of the share
`POST`	`/embed/v1/shares/{id}/visitor`	Public: resume or create the anonymous visitor
`POST`	`/embed/v1/shares/{id}/session`	Delegated: redeem the ticket
`GET`, `POST`	`/embed/v1/shares/{id}/conversations`	List / create own chats
`GET`, `DELETE`	`/embed/v1/shares/{id}/conversations/{cid}`	Read / delete own chat
`POST`	`/embed/v1/shares/{id}/conversations/{cid}/messages`	Ask a question (Server-Sent Events)
`GET`	`/embed-assets/v1/m8ty-chat.js`	Component script
`GET`	`/embed/{shareId}`	iframe page

All chat requests carry X-M8TY-Embed: 1, an Authorization: M8TY-PoP <token> header and an M8TY-PoP proof signed by the browser's non-exportable device key. Responses: 401 unauthorized, 404 unavailable, 429 rate_limited (with Retry-After), 503 temporarily_unavailable.

If you run a reverse proxy or WAF in front of your own site, nothing has to be configured for these calls — they go directly from the browser to the Ragty URL. Make sure response buffering is disabled for Server-Sent Events if you proxy the Ragty URL itself.

12 November 2026