Chat Widgets

Embed AI-powered chat widgets on your website to provide instant customer support, lead generation, or interactive assistance powered by your AI configuration.

Overview

Chat widgets allow you to deploy your AI configuration directly on any website. Visitors can interact with the AI assistant without leaving your site, and you can track all conversations in your ConfigureMyAI dashboard.

Conversation Starters

Pre-defined prompts to guide users

Actions

Execute API calls from conversations

Secure

Token-based authentication

Basic Installation

Adding a chat widget to your website requires just one line of code. Copy the script tag from your widget's settings page and paste it before the closing </body> tag. 

<script src="https://configuremyai.com/widgets/YOUR_TOKEN/loader.js" async></script>

Async Loading

The async attribute ensures the widget loads without blocking your page content.

Passing User Context

To personalize the chat experience and pass context to your action endpoints, add data attributes to the script tag: 

<script 
  src="https://configuremyai.com/widgets/YOUR_TOKEN/loader.js"
  data-user-id="SET_USER_ID"
  data-object-id="SET_OBJECT_ID"
  async
></script>

Available Attributes

Attribute Description Passed To Actions As
data-user-id Your application's user identifier user_id
data-object-id Context object (order, ticket, product, etc.) object_id

JavaScript API

After the widget loads, you can control it programmatically using the window.AIWidget object.

Methods

AIWidget.open()

Opens the chat widget.

window.AIWidget.open();
AIWidget.close()

Closes the chat widget.

window.AIWidget.close();
AIWidget.toggle()

Toggles the widget open/closed state.

window.AIWidget.toggle();
AIWidget.setUserId(userId)

Updates the user ID after the widget has loaded. Useful after login.

window.AIWidget.setUserId('user_123');
AIWidget.setObjectId(objectId)

Updates the object context dynamically. Useful on page navigation.

window.AIWidget.setObjectId('order_456');
AIWidget.sendMessage(message)

Sends a message to the chat programmatically.

window.AIWidget.sendMessage('I need help with my order');

Conversation Starters

Conversation starters are clickable prompts displayed to users when they open the widget. They help guide users toward common questions or actions.

Configuration Options

Label

The text displayed on the button

Question

The actual message sent to the AI when clicked

Context Answer

Hidden context sent to the AI (not shown to user)

Active

Toggle to show/hide the starter

Pro Tip

Use the Context Answer field to provide the AI with information about how to handle the question, without revealing this context to the user. This helps create more focused, helpful responses.

Widget Actions

Actions allow the AI to interact with your backend systems. When enabled, the AI can collect information from users and execute API calls to your endpoints.

Action Types

Create Object

POST data to your API endpoint to create records

Visit URL

Redirect users to a specific page or URL

Web Search

Allow AI to search for information

Action Request Format

When an action is triggered, your endpoint receives a POST request with the following format: 

{
  "user_id": "user_123",
  "object_id": "order_456",
  "session_id": "widget_session_abc",
  "action_name": "create_support_ticket",
  "parameters": {
    "subject": "Help with my order",
    "description": "I haven't received my package",
    "priority": "high"
  }
}

Expected Response

Your endpoint should return a JSON response indicating success or failure:

Success Response

{
  "success": true,
  "message": "Ticket created",
  "data": {
    "ticket_id": "TKT-1234"
  }
}

Error Response

{
  "success": false,
  "error": "Invalid user"
}

Request Headers

The following headers are included with every action request:

Header Value
Content-Type application/json
Authorization Bearer {your_api_token}
X-Widget-Token {widget_token}

Security Considerations

API Token Authentication

Configure an API token in your widget settings. This token is sent as a Bearer token in the Authorization header for all action requests. Validate this token on your backend to ensure requests are coming from your widget.

User Verification

The user_id passed via data attributes should be verified on your backend. Don't trust user_id for authentication - use it only for context. Your backend should validate the session or use additional authentication mechanisms.

Action Confirmation

Enable "Require Confirmation" in your widget settings to prompt users before executing actions. This adds a confirmation modal that users must accept before the action is performed.

CORS Configuration

The widget handles CORS automatically. If you're calling your own endpoints from actions, ensure your backend allows requests from the ConfigureMyAI domain or configure appropriate CORS headers.

Customization

Customize the appearance of your widget to match your brand:

Option Description
Primary Color Background color for the widget header and button
Text Color Text color for the header and icons
Position Widget placement: bottom-right, bottom-left, top-right, top-left
Button Icon Custom image for the widget launcher button
Chat Avatar Avatar image displayed in the chat header and messages
Welcome Message Initial message shown when widget opens
Placeholder Text Placeholder text in the message input field

Troubleshooting

Widget Not Appearing

  • Check that the widget is set to "Active"
  • Verify the script tag is placed before </body>
  • Check browser console for JavaScript errors
  • Ensure your domain allows the widget script

Actions Not Executing

  • Verify "Enable Actions" is turned on
  • Check that your endpoint URL is correct
  • Ensure your API token matches what your backend expects
  • Check your backend logs for error messages

User Context Not Being Passed

  • Ensure data attributes are on the script tag (not a wrapper element)
  • Check that values are being rendered (view page source)
  • Try updating context dynamically with the JavaScript API