Embed Widget

Quick start

Add the following script tag to any page where you want the chat widget to appear:

<script src="https://your-thotis-domain.com/api/embed/YOUR_AGENT_KEY/widget"></script>

This injects a floating chat bubble in the bottom-right corner. Clicking it opens a 420x640px chat window.

If identity verification is enabled, add signed user attributes directly on the script tag:

<script
  src="https://your-thotis-domain.com/api/embed/YOUR_AGENT_KEY/widget"
  data-user-id="user_123"
  data-user-hash="SERVER_GENERATED_HMAC"
></script>

Configuration

For more control, use the JavaScript SDK directly:

<script>
  window.ThotisChat = window.ThotisChat || {};
  ThotisChat.init({
    agentKey: 'YOUR_AGENT_KEY',
    apiUrl: 'https://your-thotis-domain.com',
    theme: 'light',         // 'light' or 'dark'
    position: 'bottom-right', // 'bottom-right' or 'bottom-left'
    opener: 'Hello! How can I help you today?',
    userId: 'optional-user-id',
    userHash: 'optional-server-generated-hmac',
  });
</script>

Domain allowlisting

For security, you must configure allowed origins in your agent settings. Only requests from allowlisted domains will be accepted by the embed API.

Set the RAG_EMBED_ALLOWED_ORIGINS environment variable as a comma-separated list of origins:

RAG_EMBED_ALLOWED_ORIGINS=https://example.com,https://app.example.com

Rate limiting

The embed endpoint enforces rate limits to prevent abuse:

• 30 requests per minute per IP address
• Per-agent limits configurable in agent settings
• Per-session message limits configurable

Identity verification (HMAC)

For authenticated users, you can enable HMAC identity verification to prevent spoofing:

1. Enable identity verification in the agent's settings.
2. Generate a user hash server-side using the agent's secret key.
3. Pass the userId and userHash in the widget configuration.

This ensures that the userId in embed conversations is verified and trustworthy.

Streaming

The embed widget supports real-time streaming via Server-Sent Events (SSE). Responses appear token by token as they are generated, providing a natural conversational experience.

Session persistence

Sessions are stored in the browser's localStorage using the key thotis_chat_session_{agentKey}. Returning visitors resume their previous conversation automatically.