Skip to main content

Web channel developer guide

Instance methods​

The web channel exposes methods to control behavior and interact with the chat programmatically.

MoveoAI.init({
  integrationId: "YOUR-INTEGRATION-ID",
  version: "v2",
}).then((instance) => {
  // Use instance methods here
});

Window control​

openWindow()​

Opens the chat window if currently closed.

instance.openWindow();

closeWindow()​

Closes the chat window if currently open.

instance.closeWindow();

Messaging​

sendMessage()​

Programmatically send a message to the AI Agent.

instance.sendMessage({ text: "Hello, I need help" });

// Open window after sending
instance.sendMessage({ text: "Start conversation" });
instance.openWindow();

Behavior:

  • If conversation exists: sends immediately
  • No conversation: overrides welcome message
  • With visitor form: sends after form completion

User context​

updateContext()​

Update user information or session data dynamically.

instance.updateContext({
  user: {
    display_name: "John Doe",
    email: "john@example.com",
  },
  customer_id: "12345",
  account_type: "premium",
});

Session management​

destroy()​

End the conversation and hide the web channel completely.

// End session when user logs out
if (userLoggedOut) {
  instance.destroy();
}
After calling destroy(), you can reinitialize the web channel with MoveoAI.init().

Styling​

setCSSVariables()​

Dynamically update web channel appearance.

instance.setCSSVariables({
  "--moveo-background-color": "#1a1a1a",
  "--moveo-accent-color": "#00ff00",
  "--moveo-header-height": "70px",
});

Localization​

setLocale()​

Change the web channel language dynamically.

instance.setLocale("es"); // Switch to Spanish

Event listeners​

Subscribe to web channel events to track user interactions and session changes.

Session events​

onSessionCreated​

Fired when a new conversation starts.

instance.onSessionCreated(() => {
  console.log("New session started");
  // Track in analytics
  analytics.track("Chat Started");

  // Set initial context
  instance.updateContext({
    page_url: window.location.href,
    timestamp: new Date().toISOString(),
  });
});

onSessionReconnected​

Fired when reconnecting to existing session (with history enabled).

instance.onSessionReconnected(() => {
  console.log("Reconnected to existing session");
  // Update context with new page info
  instance.updateContext({
    returned_user: true,
    return_page: window.location.pathname,
  });
});

onSessionClosed​

Fired when the chat session terminates.

instance.onSessionClosed(() => {
  console.log("Session terminated");
  // Clean up or redirect
  if (shouldRedirect) {
    window.location.href = "/thank-you";
  }
});

Live chat events​

onConversationClosed​

Fired when live chat conversation is resolved/closed.

instance.onConversationClosed(() => {
  console.log("Live chat ended");
  // Show feedback form
  showCustomFeedbackModal();
});

onMemberLeave​

Fired when an agent leaves the conversation.

instance.onMemberLeave(() => {
  console.log("Agent left the conversation");
  // Notify user
  showNotification("Agent has disconnected");
});

Window events​

onWebchatOpened​

Fired when chat window opens.

instance.onWebchatOpened(() => {
  // Pause video when chat opens
  videoPlayer.pause();
  // Track engagement
  analytics.track("Chat Opened");
});

onWebchatClosed​

Fired when chat window closes.

instance.onWebchatClosed(() => {
  // Resume video when chat closes
  videoPlayer.play();
  // Save draft message if any
  saveDraftMessage();
});

Activity tracking​

onUserActivity​

Fired on any user activity in the chat.

let inactivityTimer;

instance.onUserActivity(() => {
  // Reset inactivity timer
  clearTimeout(inactivityTimer);
  inactivityTimer = setTimeout(() => {
    console.log("User inactive for 5 minutes");
  }, 300000);
});

Analytics events​

Track detailed user interactions with analytics events.

Setup​

instance.onAnalyticsEvent((eventData) => {
  const { event, properties, timestamp } = eventData;

  // Send to your analytics platform
  analytics.track(event, {
    ...properties,
    chat_session_id: properties.session_id,
    timestamp: timestamp,
  });
});

Available events​

Interaction events​

  • launcher_clicked - User clicks launcher
  • chat_expanded - Chat window opens
  • minimize_icon_clicked - Minimize button clicked
  • close_icon_clicked - Close button clicked
  • message_click - Message bubble clicked

Session events​

  • session_start - New session begins
  • session_end - Session ends
  • welcome_form_submitted - Pre-chat form completed

Engagement events​

  • rating_clicked - User selects rating
  • rating_submitted - Rating confirmed
  • download_conversation_clicked - Export chat

Popover events​

  • popover_inactivity_end_chat_clicked - End inactive chat
  • popover_inactivity_continue_clicked - Continue after inactivity
  • resolved_popover_continue_clicked - Continue resolved chat

Event data structure​

{
  "timestamp": "2025-01-20T10:30:45.123Z",
  "event": "launcher_clicked",
  "properties": {
    "session_id": "uuid-here",
    "page_url": "https://example.com/products",
    "user_id": "user-123" // If authenticated
  }
}

Advanced integration patterns​

Custom launcher​

Hide default launcher and use custom button:

MoveoAI.init({
  integrationId: "YOUR-INTEGRATION-ID",
  version: "v2",
  launcher: { show: false }, // Hide default launcher
}).then((instance) => {
  // Custom button opens chat
  document.getElementById("custom-chat-btn").addEventListener("click", () => {
    instance.openWindow();
  });
});

Contextual messaging​

Send different messages based on page:

const pageMessages = {
  "/products": "Looking for product information?",
  "/pricing": "Need help choosing a plan?",
  "/support": "How can we assist you today?",
};

instance.sendMessage({
  text: pageMessages[window.location.pathname] || "Hello!",
});

User authentication flow​

// After user logs in
async function onUserLogin(user) {
  // Get fresh JWT from server
  const token = await fetchUserToken(user.id);

  // Destroy old session
  if (window.chatInstance) {
    window.chatInstance.destroy();
  }

  // Initialize authenticated session
  window.chatInstance = await MoveoAI.init({
    integrationId: "YOUR-INTEGRATION-ID",
    identityToken: token,
    version: "v2",
  });

  // Set user context
  window.chatInstance.updateContext({
    user: {
      display_name: user.name,
      email: user.email,
    },
  });
}

Analytics integration​

// Google Analytics 4
instance.onAnalyticsEvent((eventData) => {
  gtag("event", eventData.event, {
    chat_session_id: eventData.properties.session_id,
    engagement_time_msec: 100,
  });
});

// Segment
instance.onAnalyticsEvent((eventData) => {
  analytics.track(eventData.event, eventData.properties);
});

// Mixpanel
instance.onAnalyticsEvent((eventData) => {
  mixpanel.track(eventData.event, eventData.properties);
});

Error handling​

MoveoAI.init({
  integrationId: "YOUR-INTEGRATION-ID",
  version: "v2",
})
  .then((instance) => {
    window.chatInstance = instance;
  })
  .catch((error) => {
    console.error("Chat initialization failed:", error);

    // Show fallback contact options
    document.getElementById("fallback-contact").style.display = "block";

    // Report to monitoring
    errorReporting.log(error);
  });

Multi-language support​

// Detect user language preference
const userLang =
  localStorage.getItem("language") || navigator.language.substring(0, 2);

// Initialize with user's language
MoveoAI.init({
  integrationId: "YOUR-INTEGRATION-ID",
  language: userLang,
  version: "v2",
}).then((instance) => {
  // Allow language switching
  document.getElementById("lang-selector").addEventListener("change", (e) => {
    instance.setLocale(e.target.value);
    localStorage.setItem("language", e.target.value);
  });
});

Testing and debugging​

Development mode​

const isDev = window.location.hostname === "localhost";

MoveoAI.init({
  integrationId: isDev ? "DEV-INTEGRATION-ID" : "PROD-INTEGRATION-ID",
  version: "v2",
}).then((instance) => {
  if (isDev) {
    // Expose instance for debugging
    window.debugChat = instance;

    // Log all events
    instance.onAnalyticsEvent(console.log);
  }
});

Event monitoring​

// Monitor all chat events
const events = [
  "onSessionCreated",
  "onSessionReconnected",
  "onSessionClosed",
  "onWebchatOpened",
  "onWebchatClosed",
];

events.forEach((eventName) => {
  instance[eventName](() => {
    console.log(`Event fired: ${eventName}`, new Date());
  });
});

Performance optimization​

Lazy loading​

// Load chat only when needed
function loadChat() {
  const script = document.createElement("script");
  script.src = "https://web.moveo.ai/web-client.min.js";
  script.onload = () => {
    MoveoAI.init({
      integrationId: "YOUR-INTEGRATION-ID",
      version: "v2",
    });
  };
  document.body.appendChild(script);
}

// Load on user interaction
document
  .getElementById("chat-trigger")
  .addEventListener("click", loadChat, { once: true });

Resource cleanup​

// Clean up on page unload
window.addEventListener("beforeunload", () => {
  if (window.chatInstance) {
    // Save conversation state if needed
    localStorage.setItem(
      "chatState",
      JSON.stringify({
        timestamp: Date.now(),
        page: window.location.href,
      })
    );
  }
});

Security considerations​

  1. Never expose sensitive data in client-side code
  2. Validate tokens server-side before passing to web channel
  3. Use HTTPS for all communications
  4. Implement rate limiting for API calls
  5. Sanitize user input before passing to context
  6. Monitor for abuse using analytics events

Next steps​

Last updated on