Programmable Chatbot

Overview

The Weav Chatbot Widget is a lightweight, embeddable chat interface that lets you add AI-powered customer support to any website.

It renders a customizable launcher button that opens a chat interface in an iframe, and it can be controlled through a simple JavaScript API.

Features

• Fully customizable appearance, including colors, icons, text, position, and theme
• Mobile responsive with optimized layouts
• Accessible, including ARIA labels and keyboard support with the Esc key
• Lightweight with minimal performance impact
• Secure iframe isolation
• JavaScript API for initialization, teardown, and event handling

Installation

Basic usage

1. Include the widget script near the end of your <body> tag.
2. Call window.WeavWidget.init() once the script has loaded.

<script src="https://app.weav.com/widget.js" defer></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    if (!window.WeavWidget) {
      console.error('Weav Chat Widget failed to load')
      return
    }

    window.WeavWidget.init({
      agentSlug: '{agent slug}',
    })
  })
</script>

The widget automatically injects its mount node and lazy-loads the iframe the first time it opens.

Quick start example

<!DOCTYPE html>
<html>
  <head>
    <title>My Website</title>
  </head>
  <body>
    <!-- Your page content -->

    <script src="https://app.weav.com/widget.js" defer></script>
    <script>
      document.addEventListener('DOMContentLoaded', () => {
        window.WeavWidget?.init({
          agentSlug: '{agent slug}',
          branding: {
            accent_color: '#007bff',
          },
        })
      })
    </script>
  </body>
</html>

JavaScript API

Once loaded, the script registers a single global object: window.WeavWidget.

Configuration options

Pass configuration through the object supplied to init().

agentSlug is required. All other properties are optional.

Top-level options

Branding options

Use the branding object to customize the launcher button.

Widget options

Use the widget object to customize behavior and appearance.

Widget modes

Button icons

Button positions

Examples

Minimal configuration

<script src="https://app.weav.com/widget.js" defer></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    window.WeavWidget?.init({ agentSlug: '{agent slug}' })
  })
</script>

Custom branding

<script src="https://app.weav.com/widget.js" defer></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    window.WeavWidget?.init({
      agentSlug: '{agent slug}',
      branding: {
        accent_color: '#8b5cf6',
        icon: '🤖',
        name: 'AI Assistant',
      },
    })
  })
</script>

Custom icon using an image URL

<script src="https://app.weav.com/widget.js" defer></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    window.WeavWidget?.init({
      agentSlug: '{agent slug}',
      branding: {
        accent_color: '#10b981',
        icon: 'https://example.com/logo.png',
      },
    })
  })
</script>

Left-aligned launcher button

<script src="https://app.weav.com/widget.js" defer></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    window.WeavWidget?.init({
      agentSlug: '{agent slug}',
      widget: {
        button_position: 'bottom-left',
      },
    })
  })
</script>

Dark mode widget

<script src="https://app.weav.com/widget.js" defer></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    window.WeavWidget?.init({
      agentSlug: '{agent slug}',
      widget: {
        mode: 'dark',
      },
    })
  })
</script>

Custom widget messages

<script src="https://app.weav.com/widget.js" defer></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    window.WeavWidget?.init({
      agentSlug: '{agent slug}',
      widget: {
        welcome_message: 'Welcome! How can we assist you?',
        message_placeholder: 'Ask a question...',
        footer_text: 'Powered by Weav',
      },
    })
  })
</script>

High z-index for complex sites

<script src="https://app.weav.com/widget.js" defer></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    window.WeavWidget?.init({
      agentSlug: '{agent slug}',
      launcherZIndex: 999999,
    })
  })
</script>

Identify logged-in users

Visitors start as anonymous by default. If your site or app has logged-in users, you can tell Weav who they are. Their conversations are then linked to the right customer in Weav, and your team can see who they're talking to without asking.

Your server signs a short-lived token for the logged-in user, and you pass that token to the widget. Weav checks the signature on its servers before it trusts the token.

// npm install jsonwebtoken
import jwt from 'jsonwebtoken'

const identityToken = jwt.sign(
  {
    user_id: String(user.id),
    email: user.email,
    name: user.name,
  },
  process.env.WEAV_WIDGET_IDENTITY_SECRET,
  { algorithm: 'HS256', expiresIn: '1h' },
)

// composer require firebase/php-jwt
use Firebase\JWT\JWT;

$identityToken = JWT::encode([
    'user_id' => (string) $user->id,
    'email' => $user->email,
    'name' => $user->name,
    'exp' => time() + 3600,
], getenv('WEAV_WIDGET_IDENTITY_SECRET'), 'HS256');

# pip install pyjwt
import os
import time
import jwt

identity_token = jwt.encode(
    {
        "user_id": str(user.id),
        "email": user.email,
        "name": user.name,
        "exp": int(time.time()) + 3600,
    },
    os.environ["WEAV_WIDGET_IDENTITY_SECRET"],
    algorithm="HS256",
)

<script src="https://app.weav.com/widget.js" defer></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    window.WeavWidget?.init({
      agentSlug: '{agent slug}',
      identityToken: '{token from your server}',
    })
  })
</script>

Token claims

What changes for identified users

When a visitor has a valid token:

• Their conversation is linked to a customer. The same user_id always maps to the same customer in your inbox. If no widget-identified customer has that user_id yet, Weav first looks for a customer with the same email and links to them. If none exists, it creates a new customer.
• They aren't asked for their email. The lead form is skipped. When the chat is handed to a human, the "leave your email" prompt is skipped too.
• Protected actions run without a verification code. If the token includes email, integration and custom actions that would normally email the user a one-time code run straight away, using that email. If the token has no email, the user still gets the usual verification code.

Conversation history and switching users

• Same user returns: their previous conversation resumes.
• User logs out, or a different user logs in on the same browser: a new conversation starts, so nobody sees someone else's chat history.
• Anonymous visitor logs in: a new, identified conversation starts. Their anonymous chat isn't merged into their account.
• Single-page apps: when the logged-in user changes without a page reload, call window.WeavWidget.destroy(), then call init() again with the new token, or with no token after logout.

window.WeavWidget.destroy()
window.WeavWidget.init({
  agentSlug: '{agent slug}',
  identityToken: newToken,
})

Keep tokens fresh on long-lived pages

Tokens are short-lived, but some pages stay open for hours, like dashboards or single-page apps. To keep visitors identified on those pages, fetch a fresh token from your server before the current one expires, then pass it to setIdentityToken().

// Your server endpoint returns { token } for the logged-in user, or { token: null }
async function refreshWeavToken() {
  const response = await fetch('/weav/identity-token', { credentials: 'same-origin' })
  if (!response.ok) return

  const { token } = await response.json()
  window.WeavWidget.setIdentityToken(token)
}

// Tokens last 1 hour, so refresh every 55 minutes
setInterval(refreshWeavToken, 55 * 60 * 1000)

• No interruption: the open chat keeps going and isn't reloaded. The widget uses the new token the next time the chat window loads, for example when the visitor starts a new conversation.
• Same signing as before: sign the refreshed token on your server, just like the first one. Never sign tokens in the browser.
• Logged out on the server: if the user's session has ended, return null and call setIdentityToken(null). The visitor's next conversation will be anonymous.

Security notes

Programmatic control

• Use window.WeavWidget.open() to open the widget without user interaction
• Use window.WeavWidget.close() to close it programmatically
• Use window.WeavWidget.destroy() to remove the widget entirely
• Use window.WeavWidget.init(newOptions) at any time to re-initialize the widget with updated configuration\

Queued open() and close() calls made immediately after init() run as soon as the React tree is ready, so you do not need to wait for a callback.

Events

Use on() and off() to react to widget lifecycle events.

<script>
  document.addEventListener('DOMContentLoaded', () => {
    const widget = window.WeavWidget
    if (!widget) return

    widget.init({ agentSlug: '{agent slug}' })

    const unsubscribeOpened = widget.on('opened', () => {
      console.log('Chat widget opened')
    })

    const unsubscribeClosed = widget.on('closed', () => {
      console.log('Chat widget closed')
    })

    // Later
    // unsubscribeOpened()
    // unsubscribeClosed()
  })
</script>

Listeners run inside a guard so thrown errors are logged without breaking other listeners.

Custom mount point

Provide mountElement if you want to render the widget inside your own container.

<div id="weav-mount"></div>

<script>
  document.addEventListener('DOMContentLoaded', () => {
    const mount = document.getElementById('weav-mount')

    window.WeavWidget?.init({
      agentSlug: '{agent slug}',
      mountElement: mount,
    })
  })
</script>

The widget clears the provided element before rendering. Calling destroy() leaves the element in place so you can reuse it for future mounts.

Triggering the widget from custom elements

You can open the widget and optionally send a pre-filled message from any element on your page.

This is useful when you want buttons, links, or other UI elements to start a specific conversation.

Open and send a message by element ID

<button id="my-id">Ask about getting started</button>

<script src="https://app.weav.com/widget.js" defer></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    window.WeavWidget?.init({ agentSlug: '{agent slug}' })

    document.getElementById('my-id')?.addEventListener('click', () => {
      WeavWidget.open()
      WeavWidget.sendMessage('How do I get started?')
    })
  })
</script>

Open and send a message by class name

<button class="my-class">Ask about getting started</button>

<script src="https://app.weav.com/widget.js" defer></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    window.WeavWidget?.init({ agentSlug: '{agent slug}' })

    document.querySelector('.my-class')?.addEventListener('click', () => {
      WeavWidget.open()
      WeavWidget.sendMessage('How do I get started?')
    })
  })
</script>

Multiple trigger buttons

You can attach different messages to different elements.

<button class="weav-trigger" data-message="How do I get started?">Getting Started</button>
<button class="weav-trigger" data-message="How do I reset my password?">Reset Password</button>
<button class="weav-trigger" data-message="What pricing plans are available?">Pricing</button>

<script src="https://app.weav.com/widget.js" defer></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    window.WeavWidget?.init({ agentSlug: '{agent slug}' })

    document.querySelectorAll('.weav-trigger').forEach((button) => {
      button.addEventListener('click', () => {
        const message = button.getAttribute('data-message')

        WeavWidget.open()

        if (message) {
          WeavWidget.sendMessage(message)
        }
      })
    })
  })
</script>

Advanced usage

Programmatic control only

The launcher button is visible by default.

To hide it and control the widget entirely through JavaScript, set launcherHidden: true and use open() and close().

<button id="contact-support">Contact support</button>

<script>
  document.addEventListener('DOMContentLoaded', () => {
    const widget = window.WeavWidget
    if (!widget) return

    widget.init({
      agentSlug: '{agent slug}',
      launcherHidden: true,
    })

    document.getElementById('contact-support')?.addEventListener('click', () => {
      widget.open()
    })
  })
</script>

When launcherHidden is true, the launcher button is completely hidden and the widget can only be opened with window.WeavWidget.open().

This is useful when you want to integrate the widget into your own custom UI.

Re-initializing with new options

window.WeavWidget.destroy()

window.WeavWidget.init({
  agentSlug: '{agent slug}',
  branding: {
    accent_color: '#22d3ee',
  },
})

Re-initializing ensures updated configuration values are applied cleanly.