Skip to main content

Manual Installation with Javascript

This guide provides step-by-step instructions on how to install the XAPP Chat Widget on your website using a JavaScript snippet. The key part of this process is placing the snippet right before the closing </body> tag in your website's HTML.

Prerequisites​

Before you begin, ensure you have the following:

  • Access to your website's HTML code.
  • Your unique key for the XAPP Chat Widget.

Installation Steps​

  1. Locate Your Unique Key

    Each XAPP widget (Chat, Search, Form/Scheduler) requires a unique key. This key should have been provided to you by XAPP. It will be used in the JavaScript snippet to uniquely identify your widget.

  2. Insert the JavaScript Snippets

    Insert the following JavaScript snippets into the HTML of your website. It is crucial to place the snippets just before the closing </body> tag for optimal performance.

    Chat Snippet

    <script
      id="xapp-js"
      src="https://widget.xapp.ai/xapp-chat-widget.js?key=YOUR_CHAT_KEY"
    ></script>

    Note! Please replace "YOUR_CHAT_KEY" with your actual widget key.

    Form / Scheduler Snippet

    <script
      id="xapp-form-js"
      src="https://form.xapp.ai/xapp-form-widget.js?key=YOUR_FORM_KEY"
    ></script>

    Note! Please replace "YOUR_FORM_KEY" with your actual widget key.

    Search Snippet

    <script
      id="xapp-search-js"
      src="https://search.xapp.ai/xapp-search-bar.js?key=YOUR_SEARCH_KEY"
    ></script>

    Note! Please replace "YOUR_SEARCH_KEY" with your actual widget key.

    important

    For the search bar, you will also need to setup a button on your website to trigger the search bar pop over, please see these instructions.

  3. Save and Upload Changes

    After inserting the snippets with your unique key, save the changes to your HTML file. If your website is hosted on a server, upload the modified file to your server.

  4. Verify Installation

    Once uploaded, visit your website to ensure all installed widgets are visible and functioning correctly. If you encounter any issues, double-check the key and the placement of the snippet in your HTML file.

Embedded Chat on Any HTML Page​

Instead of the floating button, the chat can sit inside your page layout — for example on a "Talk to us" page. Add these to that page, replacing the floating chat snippet:

<div id="xapp-widget" style="height: 600px; max-width: 420px;"></div>

<script>
  window.xaConfig = {
    mode: "docked",
    // The action bar is a floating page element; hide it inside an embedded chat.
    actionBar: { enabled: false },
  };
</script>
<script
  id="xapp-js"
  src="https://widget.xapp.ai/xapp-chat-widget.js?key=YOUR_CHAT_KEY"
></script>

Note! Please replace "YOUR_CHAT_KEY" with your actual widget key.

  • The chat renders inside the element with id="xapp-widget" and fills it, so set the height on that element itself — a height on a parent element is not enough.
  • window.xaConfig must be set before the widget script. Your Studio settings still apply; the values here only override the mode and the action bar.

Follow the Visitor as They Scroll​

Add popOut and the embedded chat moves into a floating window while its place on the page is scrolled out of view, then returns when the visitor scrolls back to it. It is the same chat that moves, so the conversation carries on. On a phone it offers the chat button or action bar instead of covering the screen.

<script>
  window.xaConfig = {
    mode: "docked",
    actionBar: { enabled: false },
    popOut: { enabled: true },
  };
</script>

Needs the widget script to be serving @xapp/chat-widget 1.104.0 or later. See the chat widget channel reference for after, minWidth and mobile.

important

The script renders the chat once, when the page loads. This suits server-rendered and multi-page sites (static HTML, WordPress templates, PHP, Rails, Django and similar), where each page is a full page load. In a single-page app whose routes mount and unmount the chat, use the component guide for your framework instead: React / Next.js, Vue, Angular or Svelte.

Troubleshooting​

  • Widget Not Appearing: Ensure the snippet is placed correctly in your HTML and that the key is accurate.
  • Functionality Issues: Check for any JavaScript errors in your browser's console that might be related to the widget.

For further assistance, contact XAPP support.