Skip to main content

Web Widget

RunLLM offers a chat widget that you can deploy out of the box on any website or documentation site. There are two modes of deployment:

  1. If you can add custom HTML or Javascript to your site, please follow the instructions for deploying with custom JS or HTML.
  2. If you're using a specific documentation framework (Docusaurus, MkDocs, GitBook, or Sphinx), please follow the relevant instructions for each of those frameworks.
Please contact us after installing the widget

To prevent abuse, RunLLM uses reCAPTCHA to validate requests from your site. When you install the widget, you will get an error message indicating that requests are being rejected. Please reach out to the RunLLM team to ensure that requests from your domain can be allowed.

Deployment Options​

Custom JS or HTML​

If you have the option to add custom Javascript, we recommend using a Javascript event listener for readability. You can use the following template:

document.addEventListener("DOMContentLoaded", function () {
  var script = document.createElement("script");
  script.type = "module";
  script.id = "runllm-widget-script"

  script.src = "https://widget.runllm.com";

  script.setAttribute("version", "stable");
  script.setAttribute("runllm-keyboard-shortcut", "Mod+j");
  script.setAttribute("runllm-name", "<ASSISTANT_NAME>");
  script.setAttribute("runllm-position", "BOTTOM_RIGHT | BOTTOM_LEFT | TOP_LEFT | TOP_RIGHT");
  script.setAttribute("runllm-assistant-id", "<ASSISTANT_ID>");

  script.async = true;
  document.head.appendChild(script);
});

Alternately, you can also add a custom HTML script tag to configure the widget:

<script
  type="text/javascript"
  id="runllm-widget-script"
  src="https://widget.runllm.com"
  version="stable"
  runllm-keyboard-shortcut="Mod+j"
  runllm-name="<ASSISTANT_NAME>"
  runllm-position="BOTTOM_RIGHT | BOTTOM_LEFT | TOP_LEFT | TOP_RIGHT"
  runllm-assistant-id="<ASSISTANT_ID>"
  async
></script>

Docusaurus​

To add RunLLM to Docusarus, add the following snippet to your docusaurus.config.js:

 scripts: [
    {
      id: "runllm-widget-script",
      type: "module",
      src: "https://widget.runllm.com",
      "runllm-name": "<ASSISTANT_NAME>",
      "runllm-assistant-id": "<ASSISTANT_ID>",
      "runllm-position": "BOTTOM_RIGHT | BOTTOM_LEFT | TOP_RIGHT | TOP_LEFT",
      "runllm-keyboard-shortcut": "Mod+j",
      "runllm-preset": "docusaurus",
      async: true,
    },
  ],

MkDocs​

To add RunLLM to MkDocs:

  1. Copy the Javascript snippet under custom JS into a file called runllm-widget.js under docs/js.
  2. Open your mkdocs.yml config.
  3. Under the extra_javascript section, add the following snippet: 
    extra_javascript:
        - "js/runllm-widget.js"

GitBook​

To add RunLLM to your GitBook site:

  1. Go to the RunLLM GitBook app and install it on your site.
  2. Use the GitBook configuration form to enter your assistant name & ID and any other configuration parameters.
GitBook's caching can interfere with new changes

We've found that GitBook's caching occasionally causes the RunLLM integration not to shoow up on first installation. The more reliable way to make GitBook's cache refresh is by changing some content on the site itself.

Sphinx​

To add RunLLM to Sphinx:

  1. Copy the Javascript snippet under custom JS into a file called runllm-widget.js under docs/js.
  2. Navigate to the source/conf.py config.
  3. Check if a varaible called html_js_files already exists. If it does, append "custom.js" to the list. If no such variable exists, add it under your html_theme variable: 
    html_theme = "sphinx_book_theme"
    html_js_files = ["custom.js"]
Need a custom framework?

If you're using a documentation framework that's not listed here that doesn't support custom JS or HTML, please reach out! We'd be happy to help out.

Configuration​

You can customize many aspects of the appearance and behavior of the RunLLM Widget using the following parameters.

Required Parameters

  • id: This must be runllm-widget for our script to locate itself in the page.
  • runllm-assistant-id: ID of assistant to use. This value is provided by RunLLM. If you are unsure which value to use here, please contact us.
  • runllm-position: Specifies where on the page to position the widget. Possible values for this parameter are: TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT

Optional Parameters

  • Positioning:
    • runllm-position-x: The X-positioning of the widget placement to override the default value. The anchor is decided by runllm-position parameter. For example, in BOTTOM_RIGHT mode, the positioning is calculated with respect to the lower-right corner. This parameter accepts any valid CSS value, for example px, percentage, vw for you to specify a fixed position, or a relative positioning based on the viewport.
    • runllm-position-y: Similar to X-positioning to override the default positioning of the widget.
  • runllm-name: Sets the name of the assistant. i.e., Chat with "RunLLM Assistant"
  • runllm-keyboard-shortcut: Sets the keyboard shortcut for activating the widget. Default: None
  • runllm-preset: Configures the widget to use preset styling configuration. Currently supported presets are mkdocs and docusaurus. Please use the one corresponding to your documentation site.
  • runllm-theme-color: A hex color code for your brand color; the widget will automatically use this as the main color.
  • runllm-brand-logo: A URL pointing to your product logo.
  • runllm-support-email: If specified, RunLLM will gives users the option to continue a conversation with your support team by starting an email thread. The current conversation's context will be included.
  • runllm-floating-button-text: When set, replaces the 'Ask AI' text in the floating button with your own customized value.
  • runllm-join-community-text: When set, replaces the 'Join our Community' text in the modal button with your own customized value.
  • runllm-community-url: URL used for users to join your community. If a URL is provided, a banner will be shown allowing users to click and join your community. If no URL is provided, there will be no banner shown.
  • runllm-community-type: The platform on which you community is hosted — supported values are slack, discord, and discourse.
  • runllm-per-user-usage-limit: The number of questions that should be allowed from a particular user on the chat widget.
  • runllm-usage-limit-effective-days: The time period after which the usage limit resets.
  • runllm-usage-limit-message: The message to be displayed when the usage limit is exceeded.
  • runllm-assistant-routing-config: Advanced routing config to control widget behavior within your site. The config should be a serialized dict of string to integer mapping, where the keys are URL prefixes, and values are assistant IDs. When the page URL matches a prefix in the dictionary, it will be routed to the specified assistant ID. Otherwise, we will fall back to runllm-assistant-id. We also support hiding the widget by using "" for the assistant ID. Please refer to the following two examples:
    • In the first example, we hide the widget for all URLs under mysite/marketing 
      <script
          src="https://widget.runllm.com"
          runllm-assistant-id="1"
          runllm-assistant-rounting-config="{\"https://www.mysite/marketing\": \"\"}"
      />
    • In the second example, we hide the widget by default. The widget is shown and routed to assistant 1 for pages under mysite/docs. It's shown and routed to assistant ID 2 for pages under mysite/advanced: 
      <script
          src="https://widget.runllm.com"
          runllm-assistant-id=""
          runllm-assistant-rounting-config="{\"https://www.mysite/docs\": 1, \"https://www.mysite/advanced\": 2}"
      />
  • runllm-disclaimer: A custom disclaimer to be shown to users on the chat widget. You can either use a string or a custom HTML component. For example, runllm-disclaimer='A disclaimer with <a href="" target="_blank">link</a>'.
  • runllm-hide-trigger-button: If set to "true", hides the trigger button on the chat widget. This is useful if you want to use your own component to control the widget's behavior.
  • runllm-algolia-api-key: API key for your Algolia account.
  • runllm-algolia-application-id: Application ID for your Algolia account.
  • runllm-algolia-index-name: Index name for your Algolia account.
  • runllm-algolia-filters: Filters to be applied to the Algolia search.

Javascript API​

RunLLM offers a Javascript API to control the chat widget's behavior from external components. We support the following methods:

  • window.runllm.open(): Opens the chat widget modal.
  • window.runllm.close(): Closes the chat widget modal.
  • window.runllm.sendMessage(message: string): Opens the chat widget model, and sends a message to the widget on behalf of the user.