Web Chat Widget

The Obelisk web chat widget allows you to embed conversational scribes directly into your website. Add a single line of code to your site and your scribe will be ready to interact with visitors.

Quick start: Visit your scribe's "Web Chat Widget" page to generate embed codes with a visual interface. ()

How the Widget Works

When you embed the widget on your site, it creates a chat interface that visitors can use to interact with your scribe. The widget runs in an isolated environment to prevent conflicts with your site's styling or functionality.

Creates a chat button or attaches to an existing element on your page
Loads the chat interface when first opened
Maintains conversation history even when the chat is closed and reopened

Conversation Sessions

Each visitor gets their own conversation session that persists across page visits. When someone opens the chat, they can continue where they left off.

How Sessions Work

First Visit: When a visitor opens the chat, a new session begins and their conversation history starts.
Returning: If they return within 3 minutes, they continue their existing conversation.
New Conversation: After 3 minutes of inactivity, a fresh conversation automatically starts on their next visit.

Note: Session management is fully automatic. Visitors don't need to do anything to resume or start fresh — the widget handles it all seamlessly.

JavaScript API

Control the widget programmatically using the window.ObeliskChat object.

Control the Widget

// Open the chat window
window.ObeliskChat.open();

// Close the chat window
window.ObeliskChat.close();

// Toggle the chat window
window.ObeliskChat.toggle();

// Minimize/maximize the chat
window.ObeliskChat.minimize();

Example: Trigger from a custom button

Open the chat from any element on your page:

document.getElementById('help-button').addEventListener('click', function() {
  window.ObeliskChat.open();
});

Manage Sessions

// Get the current session ID
const sessionId = window.ObeliskChat.getSessionId();

// Clear the session and start fresh
window.ObeliskChat.clearSession();

Example: Reset on user logout

Clear the chat session when users log out to ensure a clean slate:

function handleLogout() {
  // Your logout logic...
  
  // Clear chat session
  if (window.ObeliskChat) {
    window.ObeliskChat.clearSession();
  }
}

Example: Context switches

Start fresh conversations when users switch between different contexts:

function switchToProject(projectId) {
  // Switch project context...
  
  // Start fresh chat
  if (window.ObeliskChat) {
    window.ObeliskChat.clearSession();
    window.ObeliskChat.close();
  }
}

Configuration Options

Customize the widget's appearance and behavior when generating the embed code:

Trigger Mode

Floating button: Creates a chat button in the corner of the page
Element trigger: Opens chat when clicking an existing element on your page

Position

Choose between lower right or lower left corner (for floating button)

Header Title

Custom title text displayed at the top of the chat window

Security & Privacy

Public Access

When you embed a scribe, anyone who visits your website can interact with it. They can access any data the scribe has been given access to through tomes and abilities.

Before embedding: Review the scribe's tomes and abilities. Only embed scribes designed for public interaction with appropriate data access restrictions.

Session Privacy

Each visitor gets their own private conversation session. Sessions are completely isolated from other users. If a visitor clears their browser data, they'll start with a fresh session on their next visit.

Troubleshooting

Widget doesn't appear

Check browser console for errors
Verify embed code was copied completely
If using element trigger, confirm the element ID matches

Sessions don't persist

Browser privacy settings or incognito mode may prevent session storage. Check console for storage-related errors.

Content Security Policy blocks iframe

Add obelisk.li to your CSP's frame-src directive to allow iframe embedding.

Z-index conflicts

Target #obelisk-chat-button and #obelisk-chat-container with custom CSS to adjust z-index if needed.

Best Practices

Design for public access: Create dedicated scribes for your website. Only give them access to data appropriate for public interaction.
Set clear expectations: Use the scribe's personality and "On Session Start" ability to greet visitors and explain what it can help with.
Design for interruptions: Visitors may leave and return. Design conversations that work well even if they start fresh after a timeout.
Test across browsers: Test on Chrome, Firefox, and Safari to ensure consistent behavior.
Monitor performance: Review session histories to identify where visitors get stuck or confused, then improve the scribe.
Provide fallback support: Include a link to human support for cases where the scribe can't help.

Need more help? Contact Support