Installation Guide

Add Instro Web Assist to almost any website

Generate your widget in the dashboard, then install it with the `instro-web-assist` npm package for modern app projects or copy your Instro snippet into the stack that matches your website.

Go to dashboard Back to Web Assist

Universal snippet

Copy the exact code from your dashboard

Copy the snippet generated in your Instro dashboard. In the example below, your user ID is the value inside z7k9q1m, so z7k9q1m="16bnjxd" means your user ID is 16bnjxd.

<script
  src="YOUR_INSTRO_WIDGET_URL/MudDt5Fdr.js"
  z7k9q1m="YOUR_INSTRO_USER_ID"
  defer
><\/script>

Use that ID in npm and framework installs, or keep the whole snippet intact for CMS and plain HTML installs.

Rules

Choose one install path

npm for app projects

Use `npm install instro-web-assist` when your site is built with React, Next.js, or another JavaScript bundler.

Snippet for simple sites

Use the dashboard snippet for plain HTML, CMS platforms, ecommerce templates, and no-build websites.

Platforms

npm HTML React Next.js Vue Nuxt WordPress Wix Shopify PHP

npm

npm package

App entry or root component

For modern JavaScript apps, install the official Instro Web Assist SDK from npm and initialise it once near the root of your app.

How to install

1Install the package with `npm install instro-web-assist`.
2Import `InstroWebAssist` in your app entry, root component, or a small client-only widget module.
3Call `InstroWebAssist.init()` once with the user ID from your Instro dashboard.

Example

npm install instro-web-assist

import InstroWebAssist from "instro-web-assist";

InstroWebAssist.init({
  userId: "YOUR_INSTRO_USER_ID",
});

Use the npm package when your site is built with a JavaScript bundler. Use the dashboard snippet for no-build sites, CMS platforms, and simple template installs.

HTML

HTML website

`index.html` or footer include

For plain HTML or simple server-rendered pages, paste the Instro snippet just before the closing body tag.

How to install

1Open the HTML file or shared footer template used by your site.
2Paste your Instro dashboard snippet just before `</body>`.
3Save, upload, and refresh a live page to verify the widget loads.

Example

HTML

<!-- Paste your Instro dashboard snippet just before </body> -->
<script
  src="YOUR_INSTRO_WIDGET_URL/MudDt5Fdr.js"
  data-user-id="YOUR_INSTRO_USER_ID"
  defer
><\/script>
</body>

Using `defer` keeps the script from blocking the initial HTML parse in standard websites.

React

React site

`App.tsx` or a root layout component

For React apps, use the React component from the `instro-web-assist` npm package and mount it once at the root.

How to install

1Install the SDK with `npm install instro-web-assist`.
2Import `InstroWebAssist` from `instro-web-assist/react`.
3Render that component once near the bottom of your root app component.

Example

TSX

npm install instro-web-assist

import { InstroWebAssist } from "instro-web-assist/react";

export default function App() {
  return (
    <>
      {/* your app */}
      <InstroWebAssist userId="YOUR_INSTRO_USER_ID" />
    </>
  );
}

You can still use the dashboard script snippet if you prefer a script-tag install.

Next.js

Next.js site

`app/layout.tsx` or `pages/_app.tsx`

For Next.js, install the npm package and render the React component from a small client component.

How to install

1Install the SDK with `npm install instro-web-assist`.
2Create a client component that imports `InstroWebAssist` from `instro-web-assist/react`.
3Render that component once from your root layout so it appears across the site.

Example

TSX

npm install instro-web-assist

"use client";

import { InstroWebAssist } from "instro-web-assist/react";

export default function WebAssistWidget() {
  return <InstroWebAssist userId={process.env.NEXT_PUBLIC_INSTRO_USER_ID} />;
}

Keep the user ID in a public environment variable only if it is intended to be available in browser code.

Vue

Vue site

`App.vue` or a global layout component

For Vue, load the widget after mount so the DOM exists and the script only runs on the client.

How to install

1Add the script in `onMounted()` inside `App.vue` or your global layout.
2Guard against duplicates with a fixed script id.
3Clean it up in `onUnmounted()` if that root component can be replaced.

Example

Vue

<script setup>
import { onMounted, onUnmounted } from "vue";

let scriptEl;

onMounted(() => {
  const existing = document.getElementById("instro-web-assist");
  if (existing) return;

  scriptEl = document.createElement("script");
  scriptEl.id = "instro-web-assist";
  scriptEl.src = "YOUR_INSTRO_WIDGET_URL/MudDt5Fdr.js";
  scriptEl.defer = true;
  scriptEl.setAttribute("data-user-id", "YOUR_INSTRO_USER_ID");
  document.body.appendChild(scriptEl);
});

onUnmounted(() => {
  scriptEl?.remove();
});
<\/script>

<template>
  <RouterView />
</template>

Vue's `onMounted()` hook is intended for DOM-related side effects and does not run during SSR.

Nuxt

Nuxt site

`app.vue`

For Nuxt, register the external script with `useHead()` and place it at the end of the body so it loads globally.

How to install

1Open `app.vue` so the widget loads across every route.
2Add the script through `useHead()` with `tagPosition: 'bodyClose'`.
3Keep the `data-user-id` on the script element and publish the site.

Example

Vue

<script setup lang="ts">
useHead({
  script: [
    {
      key: "instro-web-assist",
      src: "YOUR_INSTRO_WIDGET_URL/MudDt5Fdr.js",
      defer: true,
      tagPosition: "bodyClose",
      "data-user-id": "YOUR_INSTRO_USER_ID",
    },
  ],
});
<\/script>

<template>
  <NuxtPage />
</template>

Nuxt's head management supports body-close scripts directly. If you prefer package-based setup, use the npm guide above.

WordPress

WordPress site

Custom HTML block or theme footer

For WordPress, the quickest path is a Custom HTML block on the page you want. For a site-wide install, place the snippet in your footer template or code injection area.

How to install

1In the block editor, add a Custom HTML block where you want the widget to be available.
2Paste your Instro dashboard snippet into that block and update the page.
3If you want it site-wide, add the same snippet to your footer template or site-wide code injection area instead.

Example

HTML

<!-- Custom HTML block or footer.php -->
<script
  src="YOUR_INSTRO_WIDGET_URL/MudDt5Fdr.js"
  data-user-id="YOUR_INSTRO_USER_ID"
  defer
><\/script>

On WordPress.com, script tags require hosting-enabled plans. On WordPress.org or self-hosted installs, the user adding the block may need permission to use unfiltered HTML.

Wix

Wix site

Site dashboard custom code settings

For Wix, add the Instro snippet through the platform's Custom Code settings so it loads globally without editing raw template files.

How to install

1Publish the site and make sure it has a connected domain, because Wix requires that before site-wide custom code can run.
2Open your site's dashboard, go to Settings, then Custom Code in Development & integrations.
3Click Add Custom Code, paste your Instro snippet, apply it to All pages, and place it at Body - end.
4Choose to load it once per visit unless you have a specific reason to reload it on every page open, then apply and test the live site.

Example

HTML

<!-- Wix dashboard > Settings > Custom Code -->
<script
  src="YOUR_INSTRO_WIDGET_URL/MudDt5Fdr.js"
  data-user-id="YOUR_INSTRO_USER_ID"
  defer
><\/script>

Wix's recommended placement options are Head, Body - start, or Body - end. For a chat widget, Body - end is the safest default.

Shopify

Shopify store

`layout/theme.liquid`

For Shopify, edit the theme code and place the widget in `theme.liquid` before the closing body tag so it loads across the storefront.

How to install

1From Shopify admin, go to Online Store, Themes, then Edit code.
2Open `layout/theme.liquid` in your active theme.
3Paste the Instro snippet just before `</body>`, save, and preview the storefront.

Example

Liquid / HTML

{%- comment -%} Paste before </body> in layout/theme.liquid {%- endcomment -%}
<script
  src="YOUR_INSTRO_WIDGET_URL/MudDt5Fdr.js"
  data-user-id="YOUR_INSTRO_USER_ID"
  defer
><\/script>
</body>

Duplicate your theme before editing code so you have a rollback point if you need one.

PHP

PHP website

`footer.php` or a shared layout include

For PHP sites, add the widget to the shared footer or layout partial so every page inherits it automatically.

How to install

1Open the shared footer include used by your PHP templates.
2Paste the Instro snippet just before the closing `</body>` tag.
3Deploy the updated file and test a live page.

Example

PHP / HTML

<!-- footer.php or a shared PHP layout partial -->
<?php /* Paste your Instro widget just before </body> */ ?>
<script
  src="YOUR_INSTRO_WIDGET_URL/MudDt5Fdr.js"
  data-user-id="YOUR_INSTRO_USER_ID"
  defer
><\/script>
</body>

If your PHP site uses multiple layout files, install the widget in the one shared by every page so it only loads once.

Troubleshooting

Widget does not appear

Check that the script is present in the final page HTML, that it only appears once, and that you published the change to the live site instead of only saving locally.

Console shows script or CSP errors

If your site uses a Content Security Policy, allow the Instro script origin in `script-src` and the API origin used by your widget in `connect-src`.

It loads twice

This usually means the snippet was added both in a global layout and on an individual page. Keep only one installation path.

Framework route changes behave oddly

Move the install to the root app layout so the script stays attached once instead of reloading on every page transition.