Web Widget

Seamlessly integrate Copilot into your website to provide visitors with conversational assistance, calls, and voice-to-text.

Embed Copilot on your website.

General

• Audio Transcription - Enables converting voice inputs into text directly within the widget.

• AI Web Call - Allows users to make calls directly from the web widget. Activating this feature consumes platform credits.

• Copilot Position - Adjust the Copilot's position on your website as needed.

  Enable voice-to-text, calls, and adjust your Copilot's position easily.

• Draggable - Enables users to drag and reposition the Copilot widget on the screen.

• Mobile Device Visibility - Ensures the widget is accessible and functional for users on mobile devices.

  Enable voice-to-text, calls, and adjust your Copilot's position easily.

• Logged In Users Only - When the Logged In Users Only toggle is enabled, the widget will only be visible to users who have signed in. This ensures that only authenticated users can access the widget.

  Enable Logged In User toggle

  • Set User - To activate this feature, use the setUser event to provide user details for authentication. If the details are not passed, the user will not be able to interact with the Copilot chatbot.

    window?.copilot?.users.set({
    hostId: "12312", // Mandatory
    email: "example@gmail.com",
    name: "Smith",
    additionalFields: {
        orgId: 123,
    },
    });
    
    // Either `email` or `name` (or both) must be provided along with `hostId` for user identification.

    Field	DataType	Description
    hostId	String	Unique identifier assigned to each user (mandatory).
    email	String	User’s email address. Optional but useful for identification and communication.
    name	String	User’s full name. Used to personalize interactions.
    phone	Integer	User’s phone number. Optional but useful for contact purposes.
    profilePicUrl	String	URL to the user’s profile picture. Optional but enhances user profiles visually.
    additionalFields	Object	Additional details like age, gender, or interests for improved chatbot responses.

  • Unset User - When a user logs out, use the unsetUser event to clear their session from the widget.

    window?.copilot?.users.unset();

• Resume Conversation - When enabled, the Copilot resumes the last conversation with the user. If disabled, it starts a new conversation each time the page is opened.

• Allowed Domains and Paths - Define specific domains and paths where the widget is allowed to function. This helps maintain security and ensures the widget is only accessible from approved locations.

Embed Code

To add the Copilot to your website, copy and paste the following code into your webpage:

Copy and paste this code to add the Copilot to your website

Integrate AI Actions

Explore more about AI Actions — including Workflows, Web Client Action, and MCP Server — in the AI Actions Guide.

---

React Copilot Widget

For the official React integration and advanced usage, see the React Copilot Widget Guide.

Mentions and User Tagging

Implement intelligent mention functionality that allows users to tag people, products, or any custom entities within message inputs. This feature supports custom data structures, grouping, search functionality, and styled display with avatars and metadata.

Setup

1. Register callback

Important: The callback name "get_mentions_data" is required for mentions functionality.

copilot(
  "init",
  {},
  function () {
    copilot.callbacks.add({
      name: "get_mentions_data",
      handler: () => [
        {
          type: "group",
          title: "Team",
          items: [
            {
              id: "alice",
              title: "Alice Johnson",
              directive: "Frontend Developer",
              icon: "https://example.com/alice.jpg",
            },
          ],
        },
        {
          id: "support",
          title: "Quick Support",
          directive: "Get help immediately",
        },
      ],
    });
  }
);

2. Data structure

Validation rules

• All IDs must be unique
• Titles max 50 characters
• Required fields: id, title, directive
• Single level grouping only

// Single item
{
  id: "unique_id",
  title: "Display Name",
  directive: "Additional context",
  icon?: "https://example.com/avatar.jpg"
}

// Group
{
  type: "group",
  title: "Group Name",
  items: [/* items */],
  searchPlaceholder?: "Custom search text"
}

Usage

How to use

1. Type @ in message input
2. Dropdown appears with options
3. Type to search or use arrow keys
4. Press Enter or click to select
5. Mention appears as styled chip

Type @ to open the mentions menu, search, and select.

Keyboard shortcuts

• @: Open mentions dropdown
• ↑/↓: Navigate options
• Enter: Select mention
• Escape: Close dropdown

Message Format

Mentions are stored in the backend in this format:

"Hello @<<user1>>, please review @<<prod1>>"

Display behavior:

• Renders as styled chips with avatars
• Uses primary button color for styling
• Falls back to initials if image fails

Troubleshooting

Common issues

• Required callback names:
  • Mentions: Must use "get_mentions_data"
  • Image preview: Must use "__agent_message_image_click"
• Verify callback returns valid data structure
• Ensure all items have unique IDs
• Check browser console for errors

Image Preview and Modal Display

Enhance user experience by enabling custom image preview functionality when users click on images within Copilot messages. This feature allows you to create custom modal overlays, lightbox effects, or any other image display behavior.

Setup

Register callback

Important: The callback name "__agent_message_image_click" is required for image preview functionality.

copilot(
  "init",
  {},
  function () {
    copilot.callbacks.add({
      name: "__agent_message_image_click",
      handler: showImageModal
    });
  }
);

Handler function

function showImageModal(imageData) {
  // imageData contains: src, alt, title
  console.log('Image clicked:', imageData);

  // Implement your modal logic here
  const modal = document.createElement('div');
  modal.innerHTML = `
    <div class="image-modal">
      <img src="${imageData.src}" alt="${imageData.alt || 'Image'}" />
    </div>
  `;
  document.body.appendChild(modal);
}

How it works

1. User clicks image in Copilot message
2. __agent_message_image_click callback triggers
3. Handler receives image data (src, alt, title)
4. Implement custom modal/preview logic

Custom image preview modal when clicking on images in Copilot messages.

Image data structure

{
  src: "https://example.com/image.jpg",
  alt: "Image description",
  title: "Image title"
}

Usage

Basic implementation

Create a modal overlay when image is clicked:

function showImageModal(imageData) {
  const overlay = document.createElement('div');
  overlay.style.cssText = `
    position: fixed;
    top: 0; left: 0;
    width: 100%; height: 100%;
    background: rgba(0, 0, 0, 0.8);
    display: flex;
    justify-content: center;
    align-items: center;
    z-index: 10000;
    cursor: pointer;
  `;

  const img = document.createElement('img');
  img.src = imageData.src;
  img.style.cssText = 'max-width: 90%; max-height: 90%;';

  overlay.addEventListener('click', () => {
    document.body.removeChild(overlay);
  });

  overlay.appendChild(img);
  document.body.appendChild(overlay);
}

Troubleshooting

Common issues

• Modal not appearing: Check callback registration
• Images not loading: Verify image URLs
• Z-index conflicts: Ensure sufficient z-index value
• Event conflicts: Prevent event bubbling

Instructions

Enhance your AI agent's capabilities by adding dynamic, interactive responses with callbacks and delays during tool execution. This feature allows you to create more engaging user experiences with real-time feedback and controlled execution flow.

Overview

Instructions enable you to:

• Execute custom JavaScript functions during tool execution
• Add controlled delays for better user experience
• Provide real-time progress updates
• Create multi-step interactive workflows

Implementation

1. Define your tool with instructions

copilot.tools.add([
  {
    name: "data_processor",
    description: "Process data with real-time progress updates",
    timeout: 15000,

    handler: () => {
      return {
        success: true,
        message: "Data processing initiated",

        _agent_instructions: [
          {
            type: "callback",
            options: {
              name: "show_processing_start",
              args: ["Starting data analysis..."]
            }
          },
          {
            type: "delay",
            options: {
              duration: 1000
            }
          },
          {
            type: "callback",
            options: {
              name: "update_progress",
              args: ["Processing step 1 of 3..."]
            }
          },
          {
            type: "delay",
            options: {
              duration: 2000
            }
          },
          {
            type: "callback",
            options: {
              name: "show_completion",
              args: ["Data processing completed successfully!"]
            }
          }
        ]
      };
    }
  }
]);

2. Register callback handlers

// Progress indicator callback
copilot.callbacks.add({
  name: "show_processing_start",
  handler: (message) => {
    console.log("Processing started:", message);
    // Update UI to show loading state
    updateProgressUI("start", message);
  }
});

// Progress update callback
copilot.callbacks.add({
  name: "update_progress",
  handler: (message) => {
    console.log("Progress update:", message);
    // Update progress bar or status
    updateProgressUI("update", message);
  }
});

// Completion callback
copilot.callbacks.add({
  name: "show_completion",
  handler: (message) => {
    console.log("Processing completed:", message);
    // Show success state
    updateProgressUI("complete", message);
  }
});

Instruction Types

Callback Instructions

Execute custom JavaScript functions during tool execution to update UI, show progress, or perform side effects.

{
  type: "callback",
  options: {
    name: "your_callback_function",
    args: ["parameter1", "parameter2"]
  }
}

Parameters:

• name: The callback function name (must match registered handler)
• args: Array of arguments passed to the callback function

Delay Instructions

Pause execution for a specified duration to create natural conversation flow or simulate processing time.

Parameters:

• duration: Time to wait in milliseconds

{
  type: "delay",
  options: {
    duration: 2000 // milliseconds
  }
}

Quick Reply Instructions

Automatically send a predefined message as a quick reply option during tool execution.

{
  type: "quick_reply",
  options: {
    value: "Show Details of move-on-restart-oversize-men-s-tshirt-7868711"
  }
}

Navigate Instructions

Redirect users to a specific URL during tool execution.

{
  type: "navigate",
  options: {
    value: "https://fynd.hostx5.de/product/move-on-restart-oversize-men-s-tshirt-7868711"
  }
}

Parameters:

• value: The URL to navigate to

Best Practices

1. User Experience

• Use delays sparingly to avoid frustrating users
• Provide meaningful progress updates
• Keep callback execution time minimal

2. Error Handling

copilot.callbacks.add({
  name: "handle_error",
  handler: (errorMessage) => {
    console.error("Tool execution error:", errorMessage);
    showErrorMessage(errorMessage);
  }
});

3. Performance

• Limit the number of instructions per tool
• Use appropriate timeout values
• Clean up resources in callback handlers

Common Use Cases

Progress Indicators

// Show step-by-step progress
{
  type: "callback",
  options: {
    name: "update_progress_bar",
    args: ["Step 1/5: Initializing..."]
  }
}

User Feedback

// Provide real-time status updates
{
  type: "callback",
  options: {
    name: "show_notification",
    args: ["Data validation completed"]
  }
}

Sequential Operations

// Chain multiple operations with delays
[
  { type: "callback", options: { name: "start_operation", args: [] } },
  { type: "delay", options: { duration: 1000 } },
  { type: "callback", options: { name: "complete_operation", args: [] } }
]

Interactive Workflows

// Create multi-step processes
[
  { type: "callback", options: { name: "show_step_1", args: [] } },
  { type: "delay", options: { duration: 500 } },
  { type: "callback", options: { name: "show_step_2", args: [] } },
  { type: "delay", options: { duration: 500 } },
  { type: "callback", options: { name: "show_final_result", args: [] } }
]

Troubleshooting

Common Issues and Solutions

Callbacks not executing:

• Verify callback names match exactly between tool definition and registration
• Check browser console for JavaScript errors
• Ensure callback handlers are registered before tool execution

Timeout errors:

• Increase the tool's timeout value
• Reduce the number of instructions or delay durations
• Optimize callback handler performance

UI not updating:

• Ensure callback handlers properly update DOM elements
• Check for CSS conflicts or z-index issues
• Verify event listeners are properly attached

Memory leaks:

• Clean up event listeners in callback handlers
• Avoid creating circular references
• Use proper cleanup functions for long-running operations

Debug Mode

Enable debug logging to troubleshoot instruction execution:

// Enable debug mode
copilot.debug = true;

// Check instruction execution in console
copilot.callbacks.add({
  name: "debug_callback",
  handler: (message) => {
    console.log("Debug callback executed:", message);
  }
});