SDK & Widget · Web

Website widget

Add Inboxi live chat to any website with one script tag, recognize signed-in users, and control the widget from JavaScript.

The widget loader injects a floating chat launcher into your page. The chat itself runs in an isolated iframe inside a Shadow DOM, so your site's CSS cannot break it and it cannot break your site. It loads lazily after your page is idle, so it does not slow down your first paint.

The widget designer shows a live preview of the widget on a desktop site.
1Switch the preview between Mobile and Desktop.
2Widget Status: turn the widget on or off on your site.
3AI Copilot: let an AI agent answer, and pick which agent.
4The launcher and label your visitors click.

Install the snippet

Paste this before the closing </body> tag on every page where the chat should appear. Replace YOUR_APP_ID with the App ID from Settings › Developer Hub › Credentials & Setup.

index.html

<script src="https://inboxi.app/widget-loader.js"
        data-app-id="YOUR_APP_ID"
        data-base-url="https://inboxi.app"
        defer></script>

Attribute	Required	Description
`data-app-id`	Yes	Your App ID. Can also be given as window.InboxiSettings.appId.
`data-base-url`	No	Inboxi server URL. Defaults to the origin the script was loaded from, so `https://inboxi.app` in practice.

The widget speaks the language of your page: if <html lang> starts with ar it opens in Arabic and right-to-left, otherwise in English. Without a lang attribute it falls back to the browser language. Loading the snippet twice on the same page is harmless; the second copy does nothing.

The widget designer also generates ready-made snippets for HTML, Next.js, React and WordPress under its Installation section.

Framework examples

// app/layout.jsx
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://inboxi.app/widget-loader.js"
          data-app-id="YOUR_APP_ID"
          data-base-url="https://inboxi.app"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Identify signed-in users

If the visitor is logged in to your site, pass who they are. The widget skips its "enter your name" step, your team sees the real name and email in the inbox, and the conversation is filed on the right contact. Define window.InboxiSettings before the loader script.

html

<script>
  window.InboxiSettings = {
    appId: 'YOUR_APP_ID',
    user: {
      id: 'user_456',              // your own user ID
      name: 'Mohamed Ali',         // required for identification
      email: 'mohamed@example.com',
      phone: '+201234567890'
    },
    customData: { plan: 'premium', city: 'Cairo' }
  };
</script>
<script src="https://inboxi.app/widget-loader.js" data-app-id="YOUR_APP_ID" defer></script>

Field	Type	Required	Description
`appId`	string	optional	Overrides data-app-id.
`baseUrl`	string	optional	Overrides data-base-url.
`user.id`	string	optional	Your user ID. Stored on the contact as the external user ID and echoed back in webhooks.
`user.name`	string	required	Display name. Without a name the user object is ignored and the widget asks the visitor.
`user.email`	string	optional	Email. Used to recognize the same person across devices and channels.
`user.phone`	string	optional	Phone in international format.
`customData`	object	optional	Any key/value data your team should see on the contact (plan, city, last order…).

Identity from the browser is trusted as given. Do not rely on it to expose private data in the chat; for that, let your AI agent look the customer up server-side with External data. Merge rules are explained in Widget identity & merge.

JavaScript API

Once the loader has run, window.InboxiWidget lets your page control the widget.

javascript

window.InboxiWidget.open();      // open the chat window
window.InboxiWidget.close();     // close it
window.InboxiWidget.isOpen();    // → true | false
window.InboxiWidget.destroy();   // remove the widget from the page

// Identify the visitor after page load, e.g. right after login
window.InboxiWidget.setUser({
  id: 'user_456',
  name: 'Mohamed Ali',
  email: 'mohamed@example.com',
  phone: '+201234567890'
});

Method	Description
`open()`	Opens the chat window (loads it first if needed). Use it for your own "Chat with us" buttons.
`close()`	Closes the chat window. The launcher stays.
`isOpen()`	Returns whether the chat window is currently open.
`destroy()`	Removes the launcher and chat from the page and sets window.InboxiWidget to null.
`setUser(user)`	Sends user details to the chat. Same shape as InboxiSettings.user; ignored without a name.

Your own button

<button onclick="window.InboxiWidget && window.InboxiWidget.open()">
  Talk to support
</button>

Embed as a full page

Want a dedicated /support page instead of a floating launcher? Embed the chat itself in an iframe. Give the container a height; the chat fills it.

support.html

<div style="height: 80vh; max-width: 600px; margin: 0 auto;">
  <iframe src="https://inboxi.app/widget.html#/widget-ui/YOUR_APP_ID"
          title="Support chat"
          style="width: 100%; height: 100%; border: none; border-radius: 16px;">
  </iframe>
</div>

Add ?hostLang=ar before the # (widget.html?hostLang=ar#/widget-ui/YOUR_APP_ID) to force Arabic. Do not load widget-loader.js on the same page, or visitors will see two chats.

Customize the look in the dashboard

Colors, texts and behavior are set in the dashboard, not in code, and apply to every page where the snippet is installed. Open Settings › Channels › Live Chat Widget.

Widget Settings with the mobile preview.
1Website or My Store: edit the widget for your website or for your Inboxi store.
2Identity: business name, logo and welcome message.
3Live preview, updated as you type.
4Launcher button and label as visitors will see them.

Section	What you set
Widget Status / AI Copilot	Turn the widget on, let the AI answer, choose the AI agent.
Identity	Business name, logo, welcome message.
Conversation Experience	Team intro, expected response time, office hours, email capture, conversation rating, team avatars.
Colors & Branding	Primary, header background and text, chat background, bot and user message colors.
Style & Position	Button layout and label, left or right position, corner shape.
Installation	Copy-ready snippets for HTML, Next.js, React and WordPress.

Saved changes are pushed to open widgets live; visitors do not need to reload. The same colors and welcome message are returned to mobile apps by /sdk/init.

Single-page apps

Load the snippet once, in your root layout. Route changes do not need to reload it.
On login, call window.InboxiWidget.setUser(…). On logout, call window.InboxiWidget.destroy() and load the script again so the next visitor starts a fresh, anonymous chat.
Guard calls with window.InboxiWidget && …: the object exists only after the loader has run.
To hide the widget on some routes (checkout, admin), call close() or destroy() on entering them.
Content-Security-Policy: allow https://inboxi.app in script-src, frame-src and connect-src.