Chat Widget

The chat widget runs in your visitors' browsers and routes their messages into the inbox you've connected to the widget. Pick the install path that matches your stack — every option ends up in the same place.

Prerequisites

• A chat widget created in Settings → Channels → Chat Widget.
• An inbox the widget routes conversations into (set on the widget's General tab).
• Your widget's channel id — find it in Settings → Channels → your widget → Setup. Every snippet on this page uses <channelId> as a placeholder.

1. Install the widget

Open your widget in Settings → Channels → Setup and copy the snippet that matches your stack. The Setup tab generates the exact same snippets shown here, with your real channel id pre-filled.

<script
  src="https://app.auxx.ai/scripts/chat-widget.js"
  data-channel-id="<channelId>"
  async defer></script>

npm install @auxx/chat

import Auxx from '@auxx/chat'

Auxx.boot({ channelId: '<channelId>' })

import Auxx from '@auxx/chat'

// On app start / login
Auxx.boot({ channelId: '<channelId>', userJwt })

// On user data change (no reboot)
Auxx.update({ plan: 'pro' })

// On logout
Auxx.shutdown()

npm install @auxx/chat

import { AuxxChat } from '@auxx/chat/react'

export function AppRoot() {
  return (
    <>
      {/* … your app … */}
      <AuxxChat channelId="<channelId>" userJwt={token} />
    </>
  )
}

npm install @auxx/chat

<!-- components/AuxxChat.vue -->
<script setup lang="ts">
import { onMounted, onUnmounted, watch } from 'vue'
import Auxx from '@auxx/chat'

const props = defineProps<{
  channelId: string
  userJwt?: string
  attributes?: Record<string, unknown>
}>()

onMounted(() => {
  Auxx.boot({
    channelId: props.channelId,
    userJwt: props.userJwt,
    attributes: props.attributes,
  })
})
onUnmounted(() => {
  Auxx.shutdown()
})
watch(
  () => props.attributes,
  (next) => next && Auxx.update(next),
  { deep: true }
)
</script>

<template></template>

<!-- App.vue -->
<script setup lang="ts">
import AuxxChat from './components/AuxxChat.vue'
</script>

<template>
  <!-- … your app … -->
  <AuxxChat channel-id="<channelId>" :user-jwt="token" />
</template>

npm install @auxx/chat

// auxx-chat.component.ts
import { Component, Input, OnDestroy, OnInit } from '@angular/core'
import Auxx from '@auxx/chat'

@Component({ selector: 'auxx-chat', template: '' })
export class AuxxChatComponent implements OnInit, OnDestroy {
  @Input() channelId!: string
  @Input() userJwt?: string

  ngOnInit() {
    Auxx.boot({ channelId: this.channelId, userJwt: this.userJwt })
  }
  ngOnDestroy() {
    Auxx.shutdown()
  }
}

<!-- app.component.html -->
<!-- … your app … -->
<auxx-chat channelId="<channelId>" [userJwt]="token"></auxx-chat>

2. Configure allowed domains (optional)

By default the widget loads on any site you embed it on. To restrict that:

1. Open the widget's Identity tab.
2. Add each domain that should be allowed to embed the widget — bare hostnames only, no protocol (example.com, not https://example.com).
3. Subdomains of an allowed domain pass automatically — adding example.com also allows app.example.com.

Leave the list empty to allow the widget to load anywhere.

3. Identify the visitor (optional)

If you know who's on the page — typically after a user signs in — pass their info to the widget so the conversation attaches to a known visitor instead of an anonymous one.

Pass identity at boot

When using the npm package, React, Vue, or Angular install paths, pass an identity payload directly to Auxx.boot:

import Auxx from '@auxx/chat'

Auxx.boot({
  channelId: '<channelId>',
  attributes: {
    name: 'Jane Doe',
    email: '[email protected]',
    externalId: 'cus_123',
  },
})

Queue-style identify

If your visitor data is rendered into the page server-side (e.g. a Rails or Django template), push commands onto a window.AuxxChat array before the script tag. The widget drains the queue once it boots — works with any install path, but it's most natural with the Basic JS snippet.

<script>
  window.AuxxChat = window.AuxxChat || [];
  window.AuxxChat.push(['identify', {
    name: 'Jane Doe',
    email: '[email protected]',
    externalId: 'cus_123'
  }]);
</script>
<script
  src="https://app.auxx.ai/scripts/chat-widget.js"
  data-channel-id="<channelId>"
  async defer></script>

Or call identify directly after the bundle has loaded:

window.AuxxChat.identify({
  email: '[email protected]',
  externalId: 'cus_123',
})

Payload reference

All three fields are optional, but at least one must be non-empty for the call to register. Empty strings are dropped, and the most recent payload is persisted to sessionStorage so calling identify on every page load is safe.

4. Verify identity with a JWT (recommended)

Anyone can call identify from the browser, so the email or external id you pass is only as trustworthy as the visitor's tab. For sensitive surfaces (account info, billing, support history), sign a short-lived JWT on your server with one of your widget's signing keys and pass it as userJwt.

1. Open the widget's Identity tab.
2. Click Create signing key and copy the secret — it's only shown once.
3. Sign a JWT for the current visitor on your server using that secret.
4. Pass the token to Auxx.boot({ channelId, userJwt }).
5. Once your server reliably signs every visitor, click Enforce to reject anonymous traffic.

The Identity tab walks through this end-to-end with the exact code snippets to paste on your server.

5. Verify the install

Open a page that includes the snippet — you should see the launcher in the configured corner. If it doesn't appear:

• Check Identity → Allowed Domains — if you've restricted domains, the current page's hostname must be in the list (or be a subdomain of one).
• Open the browser console and look for Content Security Policy errors blocking the script src.
• Confirm the snippet is actually in the rendered HTML (some CMS templates strip script tags).

You can also use the Open preview button at the top of widget settings to load a live preview in a popup — useful for smoke-testing settings without touching your live site.

Troubleshooting

• Launcher doesn't appear — check the allowed-domain list, browser console errors, and that the snippet is in the rendered HTML.
• identify doesn't take effect — confirm at least one field is non-empty and that the command string is exactly 'identify'.
• Identity enforcement rejects requests — the JWT may be expired or signed with a revoked key. Mint a new signing key, sign with the new secret, then revoke the old key once the rollout is complete.
• AI auto-reply isn't firing — verify an agent is selected in General → AI Auto-Reply and that auto-reply behaviour is enabled in the Behavior tab.