Skip to main content
The Puppeteer widget is a floating bubble that sits in the corner of your website. When clicked, it expands into a full chat window where users can interact with your agent. Under the hood, the widget and the chat embed use the same chat interface — the only difference is presentation. The widget wraps it in a collapsible bubble, while the embed renders it inline in a container you control. Chat widget

​
Installation

Add this script tag before the closing </body> tag on every page where you want the widget to appear: 
<script async
  src="https://dashboard.puppeteerai.com/scripts/chat-loader.js"
  data-project-id="YOUR_PROJECT_ID"
  data-base-url="https://dashboard.puppeteerai.com">
</script>
That’s it. The widget will appear as a small bubble in the bottom-right corner of the page.

​
Configuration

Customize the widget’s appearance and behavior with data attributes on the script tag.

​
Position

AttributeDefaultDescription
data-widget-position"right"Side of the screen: "left" or "right".
data-bottom-offset"1rem"Distance from the bottom of the viewport.

​
Theming

AttributeDescription
data-header-bg-colorHeader background color (hex, e.g. #F6F7F9).
data-header-text-colorHeader text color.
data-header-bot-nameDisplay name shown in the header.
data-agent-imageURL for the bot’s avatar image.
data-bot-bubble-bg-colorBackground color of bot message bubbles.
data-bot-bubble-text-colorText color of bot message bubbles.
data-user-bubble-bg-colorBackground color of user message bubbles.
data-user-bubble-text-colorText color of user message bubbles.

​
Data

AttributeDescription
data-tokenPre-generated access token for the thread.
data-json-inputJSON string with initial data to send to the thread on creation.

​
Full example

<script async
  src="https://dashboard.puppeteerai.com/scripts/chat-loader.js"
  data-project-id="YOUR_PROJECT_ID"
  data-base-url="https://dashboard.puppeteerai.com"
  data-widget-position="right"
  data-bottom-offset="2rem"
  data-header-bg-color="#712F4A"
  data-header-text-color="#FFFFFF"
  data-header-bot-name="Care Assistant"
  data-bot-bubble-bg-color="#E5E7EB"
  data-bot-bubble-text-color="#000000"
  data-user-bubble-bg-color="#712F4A"
  data-user-bubble-text-color="#FFFFFF">
</script>

​
Opening a specific thread

By default, the widget creates a new thread for each session. To open an existing thread instead, generate a JWT token for that thread via the API and pass it using data-token: 
<script async
  src="https://dashboard.puppeteerai.com/scripts/chat-loader.js"
  data-project-id="YOUR_PROJECT_ID"
  data-base-url="https://dashboard.puppeteerai.com"
  data-token="eyJhbGciOiJIUzI1...">
</script>
See Authentication for how to generate a JWT token scoped to a thread.

​
JavaScript API

The widget exposes a global window.PuppeteerChat object that you can use to control it programmatically.

​
Open the widget

window.PuppeteerChat.open();

​
Send a message

window.PuppeteerChat.sendMessage("I'd like to schedule an appointment");
This sends the message as if the user typed it, triggering the agent’s response.

​
Dashboard setup

You can also configure the widget visually from the Puppeteer dashboard under your project’s Widget Setup page. Changes made there will apply automatically — no code changes needed.