ChatKit Frontend Bootstrap

Embed and initialize OpenAI's ChatKit widget in Rails views.

When to Use

• Embedding ChatKit as a custom <openai-chatkit> element
• Configuring ChatKit options (API URL, attachments, theme)
• Theme synchronization with app-wide dark/light mode
• Building both embedded and standalone ChatKit pages

Quick Start

1. Add Bootstrap Partial to Head

<% content_for :head do %>
  <%= render "shared/chatkit_bootstrap" %>
<% end %>

2. Create Container with Data Attributes

<div class="chatkit-shell__frame"
     data-chatkit-api-url-value="<%= chatkit_url %>?agent_id=<%= @agent.id %>"
     data-chatkit-domain-key-value="<%= @chatkit_settings[:domain_key] %>"
     data-chatkit-upload-url-value="<%= chatkit_upload_url(agent_id: @agent.id) %>"
     data-chatkit-upload-max-size-value="<%= ChatkitConfig.upload_max_bytes %>"
     data-chatkit-upload-accept-value="<%= ChatkitConfig.allowed_mime_types.join(',') %>">
</div>

3. Add Required CSS

.chatkit-shell__frame {
  min-height: 520px;
  height: 100%;
  flex: 1 1 auto;
  display: flex;
}

.chatkit-shell__frame > openai-chatkit {
  flex: 1 1 auto;
  width: 100%;
  height: 100%;
}

Key Patterns

Data Attribute Configuration

The bootstrap JavaScript reads options from container data attributes:

Theme Sync

ChatKit automatically syncs with document.documentElement.dataset.theme:

const observer = new MutationObserver((mutations) => {
  if (mutations.some((m) => m.attributeName === "data-theme")) {
    syncTheme()
  }
})
observer.observe(document.documentElement, { attributes: true, attributeFilter: ["data-theme"] })

Turbo Integration

Works with Turbo by listening to both events:

document.addEventListener("turbo:load", applyOptions)
document.addEventListener("DOMContentLoaded", applyOptions)

Reference Files

For detailed implementation patterns, see:

• embedding.md - View integration patterns
• initialization.md - JavaScript setup and options
• theming.md - Theme synchronization
• configuration.md - ChatkitConfig and environment
• styling.md - CSS patterns

File Locations

Two Modes

Self-Hosted Mode (Default)

ChatKit connects to your Rails backend. No external dependencies.

# Environment (optional - uses defaults)
CHATKIT_API_URL="/chatkit"

Hosted Mode (OpenAI Infrastructure)

ChatKit connects to OpenAI servers, requires client secret.

# Environment (required)
CHATKIT_CLIENT_SECRET="sk-..."
CHATKIT_PK="your-domain-key"

Example Controller Setup

def chatkit
  @chatkit_settings = {
    api_url: "#{chatkit_url}?agent_id=#{@agent.id}",
    domain_key: ChatkitConfig.domain_key,
    upload_url: chatkit_upload_url(agent_id: @agent.id),
    upload_max_bytes: ChatkitConfig.upload_max_bytes,
    allowed_mime_types: ChatkitConfig.allowed_mime_types,
    header_title: @agent.name,
    initial_thread: params[:thread_id]
  }

  if ChatkitConfig.hosted?
    @chatkit_settings[:client_secret_path] = chatkit_client_secret_path
  end
end