The Live Chat Skill allows your raia AI agent to interact directly with users on your website. This guide covers every configuration option available in the Live Chat widget, from basic messaging to advanced theming, API controls, and proactive engagement.
01
General Chat Configuration
These settings define the core behavior and capabilities of the chat interface.
| Feature | Description | Values / Options |
|---|---|---|
| Default Page | The screen that opens when the widget is launched. | home, chat, voice-chat |
| Auto Open Mode | Controls if and when the widget opens automatically. | off, once_per_session, always |
| Auto Open Delay | Time in seconds before the widget auto-opens. | Number (default: 3) |
| View Mode | How the chat is displayed on the screen. | popup (floating), sidebar (anchored) |
| Popup Size | The dimensions of the chat window. | small, medium, big, full_height |
| Streaming Chat | Streams the AI's response in real-time as it generates. | Boolean (true / false) |
| File Uploads | Allows users to upload files in the chat interface. | Boolean (true / false) |
| Message Length Limit | Maximum character count for user messages. | Number (default: 3000) |
| Reasoning Details | Shows the AI's "thinking" process to the user. | Boolean (true / false) |
| Reasoning Label | Custom text displayed while the AI processes. | String (e.g., "Thinking...") |
| Citations Enabled | Shows source citations for retrieved information. | Boolean (true / false) |
| Use Current Page Text | Injects the text of the user's current webpage into the AI context. | Boolean (true / false) |
02
Welcome & Home Screen Content
The Home screen acts as a landing page before the user starts a chat.
| Feature | Description |
|---|---|
| Title Line 1 & 2 | The main greeting text on the Home screen. |
| Welcome Message | The first message the AI sends when a chat session starts. |
| Primary Button Title | Text for the main "Start Chat" button (e.g., "Ask a question"). |
| Primary Button Description | Subtitle text under the primary button (e.g., "We're here to help"). |
| Suggestions | Predefined quick-reply prompts (up to 4) users can click to start chatting. |
| Suggestions Open Mode | How suggestions appear around the launcher. (automatic, hover, none) |
| Links | Quick-access URLs displayed on the Home screen. |
| Link Target | How links open (_blank, _self, _parent, _top). |
| Disclaimer | Markdown-supported text shown at the bottom of the Home screen. |
| Chat Footer Content | Custom text displayed at the bottom of the active chat view. |
03
Theming & Design (UI Config)
The Live Chat widget supports extensive UI customization across Light, Dark, and System themes.
- Widget Template: Choose between default or hero layout styles.
- Content Vertical Alignment: Align Home screen content to the top or bottom.
Color Customization (per Light/Dark Theme)
| Element | Description |
|---|---|
| Background Color Type | solid or gradient |
| Background Color | Main background color of the chat window. |
| Message Background | Background color of the user's message bubbles. |
| Intro Text Color | Color of the greeting text. |
| Intro Text Font Size | small, medium, large |
| Button Background | Background color of quick-reply and action buttons. |
| Button Title/Subtitle Color | Text colors for the primary action buttons. |
| Link Title Color | Color of the external links on the Home screen. |
| Logo Background Color | Background color behind the avatar/logo. |
| Background Image URL | Optional background image for the Home screen. |
04
Launcher Button Configuration
The launcher is the button users click to open the chat widget.
| Feature | Description | Values / Options |
|---|---|---|
| Type | What the launcher displays. | icon_only, text_only, icon_and_text |
| Widget Button Text | The text displayed if text is enabled. | String (e.g., "Chat with us") |
| Border Radius | Shape of the launcher. | 0px (Square), 8px (Rounded), 100% (Circular) |
| Size | The physical size of the launcher in pixels. | String (e.g., 56px) |
| Color | Background color of the launcher. | HEX or RGB string |
| Text & Icon Color | Color of the icon/text inside the launcher. | HEX or RGB string |
| Launcher Theme | Visual style of the launcher. | default, solid, gradient, glassmorphism, custom |
| Attention Effect | Animation to draw the user's eye. | none, pulse |
| Launcher Teaser | Content shown next to the closed launcher. | none, suggestions, proactive |
Proactive Bubble
If Launcher Teaser is set to proactive, a small message bubble will pop out of the closed launcher to engage the user.
- Message: The text inside the bubble.
- Delay Seconds: How long to wait before showing the bubble.
05
Voice Chat Settings
If your agent supports voice, these settings control the audio experience.
| Feature | Description |
|---|---|
| Voice Chat Enabled | Allows users to click a microphone icon to talk to the AI. |
| Voice Chat Subtitles | Displays real-time text transcriptions during the voice call. |
06
Access Controls & User Information
Restrict who can chat and what information they must provide.
| Feature | Description |
|---|---|
| Required User Information | If true, users must fill out a form before chatting. |
| User Fields | Configurable form fields (text, email, phone_number, select). |
| Required Conversation Info | Requires users to provide context before a specific conversation starts. |
| Email Verification | Requires users to verify their email via OTP. |
| Phone Verification | Requires users to verify their phone number via OTP. |
| Security Key Required | If true, the widget will only load if a valid JWT/Security Key is passed. |
Availability Rules
- Limit Chat Hours: Set specific chatStartTime, chatEndTime, and daysOfWeek when the chat is online.
- Limit Unavailable Dates: Specify specific dates (holidays) when the chat is offline.
- Warning Messages: Custom text displayed when the chat is offline due to hours or dates.
07
Interactive Chat Buttons (In-Chat Actions)
You can configure custom buttons that appear inside the chat flow based on specific conditions.
| Feature | Description |
|---|---|
| Button Type | webhook, prompt, end_chat, new_chat, escalation, book_demo, open_url |
| Appearance Condition | When the button shows: after_every_response, regex_match, after_every_n_responses, after_n_seconds_since_last_request |
| Hide After Trigger | If true, the button disappears once clicked. |
| Appears Once Per Session | If true, the button will only be shown once per user session. |
| Button Style | default, custom, solid, outline, accent, danger, ghost, link |
| Shape & Size | Custom shape (square, rounded, circular) and size (xs to xl). |
08
Developer Controls (Iframe & API)
The Live Chat widget exposes an API for developers embedding the chat via script or iframe.
Developers can send commands to the widget using window.raiaChat or postMessage to:
- Open/Close the chat
- Send a message programmatically
- Set user data (SET_USER)
- Inject context (SET_CONTEXT)
- Update the theme dynamically (UPDATE_THEME)
- Set the unread message count
- Override configuration on the fly (PATCH_SKILL_CONFIG)
Tip
Always test configuration changes in SDK Studio (sdk.raia.run) before pushing them live. The preview updates in real time so you can verify theming, launcher behavior, and welcome messages instantly.