Reference Docs¶
Learn how to customize the Open Chat Studio widget to match your brand and improve user experience.
Button Customization¶
The widget button can be customized using the following properties:
<open-chat-studio-widget
button-text="Chat with us"
button-shape="round"
icon-url="https://your-domain.com/custom-chat-icon.svg">
</open-chat-studio-widget>
Button Text
- When button-text is provided, the button displays both icon and text
- When button-text is empty or not provided, only an icon is shown
Button Shape
- round - Circular button
- square - Rectangular button with rounded corners
Icon URL
If no icon-url is provided, the default Open Chat Studio logo is used.
Button position¶
Customize the button position using CSS variables or a CSS class attached to the widget element:
- See CSS Styling for more customization options.
User Identification¶
Control how users are identified across chat sessions to enable personalized experiences and session continuity.
Overview¶
The chat widget uses user identification to:
- Maintain chat history across page reloads and different visits
- Separate conversations for different users on shared devices
- Personalize interactions with user names and context
- Enable analytics and user tracking in your chat system
Basic Implementation¶
Anonymous Users (Default)
Identified Users<open-chat-studio-widget
chatbot-id="your-chatbot-id"
user-id="user_12345"
user-name="Sarah Johnson">
</open-chat-studio-widget>
Auto-Generated User IDs¶
When no user-id is provided, the widget automatically creates a unique identifier:
- Example: ocs:1703123456789_a7x9k2m8f
Persistence Behavior:
- Same browser/device: ID persists across sessions
- Different browser/device: Gets new auto-generated ID
- Incognito mode: New ID that's cleared when session ends
Dynamic User Management¶
Update user identification when authentication state changes:
function updateChatUser(user) {
const widget = document.querySelector('open-chat-studio-widget');
if (user) {
widget.userId = user.id;
widget.userName = user.name;
}
}
Welcome Messages¶
Enhance user experience by displaying personalized greeting messages when the chat opens. These messages appear as bot messages at the beginning of the conversation. Welcome messages are perfect for:
- Greeting users and introducing your bot's capabilities
- Providing context about what kind of help is available
- Creating a warm, engaging first impression
Pass welcome messages as a JSON array string. Each message appears as a separate message bubble.
<open-chat-studio-widget
welcome-messages="['Hi! Welcome to our support chat.', 'How can I assist you today?']"
>
</open-chat-studio-widget>
Starter Questions¶
Accelerate user engagement with pre-defined clickable questions that address common queries. These starter questions help users quickly find what they're looking for without having to type which improves the user experience. Starter questions are ideal for:
- Highlighting your most frequently asked questions
- Guiding users toward key features or information
- Improving accessibility for users who prefer clicking to typing
These questions appear as blue-outlined buttons aligned to the right (similar to user messages), making it clear that they are user actions. When clicked, they automatically send that question as a user message, initiating the conversation flow. The starter questions disappear after the user clicks one or starts typing their own message.
<open-chat-studio-widget
starter-questions="[
'I need technical support',
'Tell me about pricing',
'Schedule a demo',
'Contact sales team'
]">
</open-chat-studio-widget>
File Attachments¶
Enable users to send files along with their messages. This feature is perfect for support scenarios where users need to share screenshots, documents, or other files.
Supported File Types¶
Documents:¶
- Text files: .txt
- PDF documents: .pdf
- Microsoft Word: .doc, .docx
- Microsoft Excel: .xls, .xlsx
- Spreadsheets: .csv
Images:¶
- Common formats: .jpg, .jpeg, .png, .gif, .bmp, .webp
- Vector graphics: .svg
Media:¶
- Video files: .mp4, .mov, .avi
- Audio files: .mp3, .wav
File Size Limits¶
- Maximum file size: 50MB per individual file
- Maximum total size: 50MB for all files combined in a single message
- Multiple files: Users can attach multiple files as long as the total doesn't exceed 50MB
User Experience¶
- Users click the paperclip icon next to the send button to select files
- Selected files appear in a preview area above the input field
- Files show name, size, and upload status
- Users can remove files before sending by clicking the X button
- Error messages appear for unsupported file types or files exceeding size limits
- Files are uploaded when the message is sent
See CSS Styling for customization options
New Chat Confirmation¶
When users have an active conversation and click the "new chat" button, a confirmation dialog appears to prevent accidental loss of conversation history. You can customize the message displayed in this confirmation dialog:
<open-chat-studio-widget
new-chat-confirmation-message="Are you sure you want to start a new conversation?">
</open-chat-studio-widget>
Default behavior:
- Shows confirmation dialog with the message: "Starting a new chat will clear your current conversation. Continue?"
- Users can either "Cancel" to keep their current chat or "Continue" to start fresh
- The dialog only appears when there's an existing conversation with messages
Customization options:
- Customize the confirmation message text to match your brand voice
- Style the dialog appearance using CSS variables (see CSS Styling)
Typing Indicator¶
Customize the message displayed while the assistant is preparing a response. This helps set user expectations and can match your brand's personality.
The typing indicator appears with animated dots and a progress bar to provide visual feedback during response generation.
Styling:
- Text color is controlled by
--loading-text-color
- Font size uses
--chat-window-font-size-sm
- See CSS Styling for customization options
Persistent Sessions¶
By default, the widget will save the chat messages in the browser local storage. This allows users to continue sessions after reloading the page or navigating to a new page. In addition to automatic session expiration, the user can also use the 'new chat' button to start a new session.
To disable this feature, set the persistent-session="false"
attribute on the widget element.
Note
The session persistence is associated with the chatbot-id
. If the chatbot-id
changes, any previous session data will be ignored.
The session data is set to expire after 24 hours. This is also configurable by using the persistent-session-expire
attribute. The value is interpreted as "the number of minutes since the last message before the session expires". Setting this attribute to 0
will disable the expiration entirely.
Note
Session persistence works in conjunction with User Identification. Different users will have separate persistent sessions.
Properties Reference¶
Core Configuration¶
Property | Type | Required | Default | Description | Example |
---|---|---|---|---|---|
chatbot-id |
string |
REQUIRED | - | Your chatbot ID from Open Chat Studio | "183312ac-cbe5-4c91-9e7b-d9df96b088e4" |
api-base-url |
string |
Optional | "https://chatbots.dimagi.com" |
API base URL for your Open Chat Studio instance | "https://your-domain.com" |
Button & UI Customization¶
Property | Type | Required | Default | Validation | Description | Example |
---|---|---|---|---|---|---|
button-text |
string |
Optional | undefined |
Max 50 chars | Button display text. If empty, shows icon only | "Need Help?" |
button-shape |
string |
Optional | "square" |
"round" | "square" |
Button shape style | "round" for circular button |
icon-url |
string |
Optional | OCS default logo | Valid URL | Custom icon for the chat button | "https://yoursite.com/chat-icon.svg" |
visible |
boolean |
Optional | false |
true | false |
Show widget immediately on page load | "true" to auto-open |
position |
string |
Optional | "right" |
"left" | "center" | "right" |
Initial widget position on screen | "left" for left side placement |
header-text |
string |
Optional | undefined |
Max 100 chars | Text displayed in chat window header | "Customer Support" |
User Management¶
Property | Type | Required | Default | Validation | Description | Example |
---|---|---|---|---|---|---|
user-id |
string |
Optional | Auto-generated | Alphanumeric + underscore/dash | Unique user identifier for session continuity Auto-format: ocs:1703123456789_a7x9k2m8f |
"user_12345" or "customer@email.com" |
user-name |
string |
Optional | undefined |
Max 200 chars | Display name sent to chat API for personalization | "John Smith" or "Customer #12345" |
Chat Behavior & Sessions¶
Property | Type | Required | Default | Validation | Description | Example |
---|---|---|---|---|---|---|
persistent-session |
boolean |
Optional | true |
true | false |
Save chat history in browser localStorage | "false" to disable session saving |
persistent-session-expire |
number |
Optional | 1440 (24 hours) |
0-43200 (30 days) | Minutes before session expires | 720 for 12 hours, 0 for never expire |
allow-full-screen |
boolean |
Optional | true |
true | false |
Enable fullscreen mode button | "false" to hide fullscreen option |
allow-attachments |
boolean |
Optional | false |
true | false |
Enable file upload functionality Limits: 50MB per file, 50MB total per message |
"true" to enable file uploads |
Messages & Content¶
Property | Type | Required | Default | Validation | Description | Example |
---|---|---|---|---|---|---|
welcome-messages |
string |
Optional | undefined |
Valid JSON array Max: 5 messages, 500 chars each |
Welcome messages shown when chat opens Format: '["Message 1", "Message 2"]' |
'["Welcome!", "How can I help?"]' |
starter-questions |
string |
Optional | undefined |
Valid JSON array Max: 6 questions, 100 chars each |
Clickable question buttons to start conversation Format: '["Question 1", "Question 2"]' |
'["Check my order", "Technical support"]' |
typing-indicator-text |
string |
Optional | "Preparing response" |
Max 50 chars | Text shown while bot is typing | "AI is thinking..." |
new-chat-confirmation-message |
string |
Optional | "Starting a new chat will clear your current conversation. Continue?" |
Max 200 chars | Confirmation dialog text for new chat button | "Start over? Your current chat will be lost." |