Prerequisites and Onboarding

Before you write any code, the Ragty administrator of your organization creates a share for your application. Send them the information below and you will receive everything you need for the integration.

1. What you send to the Ragty administrator

Information	Example	Notes
Which chat (dialog) to publish	"Product FAQ"	The administrator selects the knowledge base behind it
Access mode	Public or Delegated	See What you get
Integration type(s)	Web component, iframe or both	Both can be enabled on one share
Origins of your pages	`https://www.example.com`, `https://portal.example.com`	Exact `scheme://host[:port]`, one per environment. No paths, no wildcards. Every page on another origin is rejected.
History retention	30 days	Chats are deleted automatically after this period without activity
Expected traffic	2,000 questions per day	Used for the daily quota of the share

For delegated shares additionally:

Information	Example	Notes
Identity provider issuer (`iss`)	`https://idp.example.com/realms/customers`	Must match the `iss` claim exactly
JWKS URL	`https://idp.example.com/realms/customers/protocol/openid-connect/certs`	HTTPS; must be reachable from the Ragty server
Audience (`aud`)	`ragty-chat`	The audience your IdP puts into the end-user assertion
Signing algorithm	RS256	Asymmetric only

2. What you receive

Item	Example	Where you use it
Ragty base URL	`https://rag.example.com`	Script URL, iframe URL, ticket endpoint
Share ID	`shr_Wq3x…` (28 characters)	`share` attribute / iframe path — not a secret
Integration guide	Copy-ready snippets	Shown in Ragty under Chat shares → `</>`
Delegated only: gateway key	`ragty-…`	Your backend only. Treat it like a database password.
Delegated only: issuer ID	`customer-portal`	Informational; Ragty binds the share to it

3. Environments

Request one share per environment (development, test, production), each with only the origins of that environment. Shares are cheap; mixing environments in one share weakens the origin check and mixes chat histories.

For local development the administrator can allow http://localhost:<port> on a non-production Ragty installation. Production installations accept https origins only.

4. Technical requirements on your side

Modern browsers (current Chrome, Edge, Firefox, Safari). The component uses Custom Elements, Shadow DOM, WebCrypto (ECDSA P-256) and Fetch streams.
Your pages are served over HTTPS (WebCrypto and secure cookies require it).
If your pages send a Content Security Policy, you can extend it (see Content Security Policy).
Delegated only: a backend that knows the signed-in user and can obtain a short-lived signed JWT for that user from your identity provider.

12 November 2026