Chat Embed

The chat embed lets you place the full Puppeteer chat experience directly inside your website. Unlike the widget, which floats as a bubble, the embed fills a container you define — ideal for dedicating a section of a page to the agent. Under the hood, both the embed and the widget use the same chat interface and support the same theming options. The difference is purely in presentation — the widget adds a collapsible bubble, while the embed renders inline.

Basic setup

Add an iframe pointing to the /widget route:

<iframe
  src="https://dashboard.puppeteerai.com/widget?projectId=YOUR_PROJECT_ID"
  style="width: 100%; height: 600px; border: none;">
</iframe>

Theming

Pass color and branding options as URL parameters:

Parameter	Description
`projectId`	Your project ID (required).
`accessToken`	Pre-generated access token for the thread.
`headerBgColor`	Header background color (hex-encoded, e.g. `%23712F4A`).
`headerTextColor`	Header text color.
`headerBotName`	Display name shown in the header.
`agentImage`	URL for the bot’s avatar image.
`botBubbleBgColor`	Background color of bot message bubbles.
`botBubbleTextColor`	Text color of bot message bubbles.
`userBubbleBgColor`	Background color of user message bubbles.
`userBubbleTextColor`	Text color of user message bubbles.
`jsonInput`	JSON string with initial data for the thread.

Hex color values must be URL-encoded — replace # with %23. For example, #712F4A becomes %23712F4A.

Full example

<iframe
  src="https://dashboard.puppeteerai.com/widget?projectId=YOUR_PROJECT_ID&headerBgColor=%23712F4A&headerTextColor=%23FFFFFF&headerBotName=Care%20Assistant&botBubbleBgColor=%23E5E7EB&userBubbleBgColor=%23712F4A&userBubbleTextColor=%23FFFFFF"
  style="width: 100%; height: 600px; border: none; border-radius: 12px;">
</iframe>

Opening a specific thread

By default, the embed creates a new thread. To open an existing thread, generate a JWT token for that thread and pass it as the accessToken parameter:

<iframe
  src="https://dashboard.puppeteerai.com/widget?projectId=YOUR_PROJECT_ID&accessToken=eyJhbGciOiJIUzI1..."
  style="width: 100%; height: 600px; border: none;">
</iframe>

See Authentication for how to generate a JWT token scoped to a thread.

Interaction modes

The embed supports three interaction modes depending on your project configuration:

Text — Standard chat interface.
Web Call — Browser-based voice call.
Phone Call — Triggers a phone call to the user.

The available modes are determined by your project settings in the Puppeteer dashboard.

Getting Started

Web UI

Basic setup

Theming

Full example

Opening a specific thread

Interaction modes

​Basic setup

​Theming

​Full example

​Opening a specific thread

​Interaction modes

Basic setup

Theming

Full example

Opening a specific thread

Interaction modes