# Create Token
Source: https://docs.puppeteerai.com/api-reference/auth/create-token

/api-reference/openapi.json post /threads/{thread_id}/token
Generate a JWT token for a specific thread. The JWT can be used to authenticate subsequent requests scoped to this thread, such as WebSocket connections and message retrieval.



# Authentication
Source: https://docs.puppeteerai.com/api-reference/authentication

How to authenticate with the Puppeteer API

## Overview

The Puppeteer API uses two authentication methods depending on the context:

* **API Keys** for server-to-server calls (organization-scoped)
* **JWT Tokens** for client-side and thread-scoped access

## API Key

Pass your API key in the `Authorization` header:

```bash theme={null}
curl https://api.puppeteerai.com/threads \
  -H "Authorization: YOUR_API_KEY"
```

API keys are scoped to an organization and grant access to all projects within it.

<Warning>
  Keep your API key secret. Never expose it in client-side code or public repositories.
</Warning>

## JWT Token

For client-facing integrations, generate a short-lived JWT token scoped to a specific thread:

```bash theme={null}
curl -X POST https://api.puppeteerai.com/threads/THREAD_ID/token \
  -H "Authorization: YOUR_API_KEY"
```

```json theme={null}
{
    "access_token": "eyJhbGciOiJIUzI1..."
}
```

Use the returned token in place of your API key for subsequent requests on that thread. JWT tokens are ideal for chat widgets and end-user-facing applications where you don't want to expose your API key.


# Get Call
Source: https://docs.puppeteerai.com/api-reference/calls/get-call

/api-reference/openapi.json get /calls/{call_id}
Get full details for a single call, including transcript, recording URL, and analysis.



# List Calls
Source: https://docs.puppeteerai.com/api-reference/calls/list-calls

/api-reference/openapi.json get /calls
List calls for the authenticated organization, newest first, using cursor-based pagination.



# Introduction
Source: https://docs.puppeteerai.com/api-reference/introduction

Overview of the Puppeteer API

## Base URL

```
https://api.puppeteerai.com
```

## Authentication

All requests require an `Authorization` header with your API key or a JWT token:

```
Authorization: YOUR_API_KEY
```

See the [Authentication guide](/api-reference/authentication) for details on generating JWT tokens scoped to specific threads.

## Available endpoints

The endpoints documented here are a curated subset of the full Puppeteer API, covering the most common integration use cases.

If you need access to additional functionality, reach out to our team.

<Card title="Support" icon="envelope" href="mailto:support@puppeteerai.com">
  Contact us for additional API access.
</Card>


# Chat
Source: https://docs.puppeteerai.com/api-reference/messages/chat

/api-reference/openapi.json post /chat
Send a user message to a thread and get back an AI response.



# Get Messages
Source: https://docs.puppeteerai.com/api-reference/messages/get-messages

/api-reference/openapi.json get /threads/{thread_id}/messages
Retrieve messages from a thread using cursor-based pagination.



# Search Messages
Source: https://docs.puppeteerai.com/api-reference/messages/search-messages

/api-reference/openapi.json get /threads/{thread_id}/messages/search
Search for messages within a thread that contain the given text query.



# Create Thread
Source: https://docs.puppeteerai.com/api-reference/threads/create-thread

/api-reference/openapi.json post /threads
Create a new thread.



# Get Thread
Source: https://docs.puppeteerai.com/api-reference/threads/get-thread

/api-reference/openapi.json get /threads/{thread_id}
Get thread details and usage statistics.



# Send Json Input
Source: https://docs.puppeteerai.com/api-reference/threads/send-json-input

/api-reference/openapi.json post /threads/{thread_id}/json-input
Send JSON input to a specific thread.



# Create Phone Call
Source: https://docs.puppeteerai.com/api-reference/voice/create-phone-call

/api-reference/openapi.json post /voice/phone-call
Find or create a thread for the given phone number and project, then initiate a phone call.



# Create Phone Call In Thread
Source: https://docs.puppeteerai.com/api-reference/voice/create-phone-call-in-thread

/api-reference/openapi.json post /voice/{thread_id}/phone-call
Create a phone call for the specified thread. The callee number is parsed and validated, and the call is initiated or scheduled based on the input.



# Create Web Call In Thread
Source: https://docs.puppeteerai.com/api-reference/voice/create-web-call-in-thread

/api-reference/openapi.json post /voice/{thread_id}/web-call
Create a new web voice call for a thread. Queues the call for setup; once ready, the access token will be delivered to the client via WebSocket.



# End Phone Call
Source: https://docs.puppeteerai.com/api-reference/voice/end-phone-call

/api-reference/openapi.json delete /voice/{thread_id}/phone-call
End an active phone call for a thread.



# WebSocket
Source: https://docs.puppeteerai.com/api-reference/websocket

Real-time streaming communication with your agent

The WebSocket endpoint enables real-time, streaming communication with a Puppeteer agent. It supports sending messages and receiving streamed AI responses token by token.

## Connection

```
wss://api.puppeteerai.com/ws/{thread_id}
```

### Query parameters

| Parameter | Required | Description                                                        |
| --------- | -------- | ------------------------------------------------------------------ |
| `token`   | Yes      | JWT token associated with the thread.                              |
| `project` | No       | Project name. If provided, the agent is initialized on connection. |
| `version` | No       | Config version ID. Use to pin a specific config version.           |

### Example

```
wss://api.puppeteerai.com/ws/abc123?token=eyJhbGci...&project=my-project
```

## Sending messages

Send a JSON message to the WebSocket to interact with the agent:

```json theme={null}
{
  "type": "message",
  "data": {
    "message": "Hello!",
    "start_new_conversation": false,
    "puppeteer_config_name": "my-project"
  }
}
```

| Field                         | Required | Description                                                    |
| ----------------------------- | -------- | -------------------------------------------------------------- |
| `type`                        | Yes      | Must be `"message"`.                                           |
| `data.message`                | Yes      | The user's message.                                            |
| `data.start_new_conversation` | Yes      | If `true`, ends the current conversation and starts a new one. |
| `data.puppeteer_config_name`  | Yes      | The project name.                                              |

## Receiving messages

The server sends JSON messages over the WebSocket. Each message has a `type` field indicating what it is.

### Stream start

Signals the beginning of a new AI message.

```json theme={null}
{
  "type": "stream",
  "data": {
    "type": "start"
  }
}
```

### Tool running

Sent when a pre-response tool is being executed. The message can be displayed as a loading indicator.

```json theme={null}
{
  "type": "stream",
  "data": {
    "type": "tool_running",
    "message": "Fetching user data"
  }
}
```

| Field          | Description                                          |
| -------------- | ---------------------------------------------------- |
| `data.message` | A user-facing description of what the tool is doing. |

### Stream chunk

A token (word or partial word) of the AI's response, delivered as it's generated.

```json theme={null}
{
  "type": "stream",
  "data": {
    "type": "chunk",
    "token": "Hello",
    "index": 0
  }
}
```

| Field        | Description                                              |
| ------------ | -------------------------------------------------------- |
| `data.token` | A piece of the generated response.                       |
| `data.index` | The position of this token in the stream (zero-indexed). |

### Stream end

Signals the end of an AI message and includes the complete response.

```json theme={null}
{
  "type": "stream",
  "data": {
    "type": "end",
    "message": {
      "message": "Hello! How can I help you today?",
      "extras": {
        "conversation_id": "1893",
        "user_message_id": "132546d5-57fa-4f7e-a324-1d698081d2de",
        "reply_message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  }
}
```

| Field                                  | Description                                          |
| -------------------------------------- | ---------------------------------------------------- |
| `data.message.message`                 | The complete AI response.                            |
| `data.message.extras.conversation_id`  | ID of the conversation.                              |
| `data.message.extras.user_message_id`  | ID of the user message that triggered this response. |
| `data.message.extras.reply_message_id` | ID of the AI reply message.                          |

<Note>An agent may send multiple messages in a single response. Each message follows the full start → chunks → end sequence. An `end_response` event (see below) signals that all messages for the response are complete.</Note>

### End response

Sent after all messages for a response are complete. Includes response-level metadata.

```json theme={null}
{
  "type": "stream",
  "data": {
    "type": "end_response",
    "extras": {}
  }
}
```

### Error

Sent if an error occurs during processing.

```json theme={null}
{
  "type": "error",
  "data": {
    "message": "Error description",
    "code": "WEBSOCKET_ERROR"
  }
}
```

## Ping / Pong

Send a ping to check if the connection is still alive. The server responds with a pong.

**Client sends:**

```json theme={null}
{
  "type": "ping"
}
```

**Server responds:**

```json theme={null}
{
  "type": "pong"
}
```

## Example interaction

**Client sends:**

```json theme={null}
{
  "type": "message",
  "data": {
    "message": "Hello there!",
    "start_new_conversation": true,
    "puppeteer_config_name": "my-project"
  }
}
```

**Server responds with a streamed reply:**

```json theme={null}
{"type": "stream", "data": {"type": "start"}}
```

```json theme={null}
{"type": "stream", "data": {"type": "chunk", "token": "Hi", "index": 0}}
```

```json theme={null}
{"type": "stream", "data": {"type": "chunk", "token": "!", "index": 1}}
```

```json theme={null}
{"type": "stream", "data": {"type": "chunk", "token": " How", "index": 2}}
```

```json theme={null}
{"type": "stream", "data": {"type": "chunk", "token": " can", "index": 3}}
```

```json theme={null}
{"type": "stream", "data": {"type": "chunk", "token": " I", "index": 4}}
```

```json theme={null}
{"type": "stream", "data": {"type": "chunk", "token": " help", "index": 5}}
```

```json theme={null}
{"type": "stream", "data": {"type": "chunk", "token": "?", "index": 6}}
```

```json theme={null}
{
  "type": "stream",
  "data": {
    "type": "end",
    "message": {
      "message": "Hi! How can I help?",
      "extras": {
        "conversation_id": "1893",
        "user_message_id": "132546d5-57fa-4f7e-a324-1d698081d2de",
        "reply_message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  }
}
```

```json theme={null}
{"type": "stream", "data": {"type": "end_response", "extras": {}}}
```


# Channels
Source: https://docs.puppeteerai.com/channels

Ways to surface your Puppeteer agent to patients

You can surface your Puppeteer agent to your patients in several ways, depending on the desired experience and level of customization.

## Web UI

Three web-based options, each with a different level of customization:

* [**Chat Widget**](/widget) — A floating bubble that expands into a chat window. Install with a single script tag.
* [**Chat Embed**](/chat-embed) — The same chat interface, embedded inline via an iframe.
* [**Rich Dashboard**](/dashboard) — A fully hosted, branded experience with text chat, voice calls, phone calls, form collection, and white-labeling.

## API

Build your own UI or integrate Puppeteer into existing systems using the REST API and WebSocket endpoints.

The endpoints documented in the [API Reference](/api-reference) are a subset of what's available. Contact our team if you need access to additional functionality.

## Phone Call

Agents can make and receive phone calls. This works for both inbound use cases (e.g., an AI receptionist) and outbound ones (e.g., appointment reminders).

## SMS

Two-way text messaging through standard SMS, maintaining conversational context across messages.

<img alt="SMS conversation" />

## WhatsApp

Same functionality as SMS, delivered through WhatsApp.

<img alt="WhatsApp conversation" />


# Chat Embed
Source: https://docs.puppeteerai.com/chat-embed

Embed the full chat interface into your website via an iFrame

The chat embed lets you place the full Puppeteer chat experience directly inside your website. Unlike the [widget](/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.

<img alt="Embedded chat" />

## Basic setup

Add an iframe pointing to the `/widget` route:

```html theme={null}
<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.            |

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

### Full example

```html theme={null}
<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:

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

See [Authentication](/api-reference/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.


# Rich Dashboard
Source: https://docs.puppeteerai.com/dashboard

A branded, hosted experience for your agent

The Puppeteer dashboard is a fully hosted, branded page where users can interact with your agent. It supports voice calls, phone calls, and text chat — all in a polished interface with your own branding.

<Frame>
  <img alt="Dashboard" />
</Frame>

<Frame>
  <img alt="Dashboard conversation" />
</Frame>

<Frame>
  <img alt="Dashboard view" />
</Frame>

## Features

* **Multiple interaction modes** — text chat, browser-based voice calls, and phone calls.
* **Custom branding** — your logo, colors, and copy.
* **Form collection** — collect patient information (name, phone number, email) before starting a conversation.
* **White-label ready** — fully branded to your organization, with no Puppeteer branding visible to end users.
* **No authentication required** — users access the page via a direct URL, no login needed.

## Interaction modes

Each dashboard can be configured with one or more interaction modes:

| Mode      | Description                                           |
| --------- | ----------------------------------------------------- |
| **Text**  | Standard text chat interface.                         |
| **Voice** | Browser-based voice call using the device microphone. |
| **Phone** | Triggers a phone call to the user's number.           |

## Standalone

Your dashboard is accessible at a unique URL:

```
https://dashboard.puppeteerai.com/demos/YOUR_SLUG
```

This is a full-page experience that works on desktop and mobile. Users can interact with your agent immediately.

## Embedded

You can also embed the dashboard into your own website:

<img alt="Embedded dashboard" />

```html theme={null}
<iframe
  src="https://dashboard.puppeteerai.com/demos/YOUR_SLUG"
  style="width: 100%; height: 700px; border: none;">
</iframe>
```

## Setup

Dashboards are set up and configured by the Puppeteer team. Contact us to get yours created with your branding, interaction modes, and form fields.

<Card title="Support" icon="envelope" href="mailto:support@puppeteerai.com">
  Reach out to get your dashboard set up.
</Card>


# Puppeteer AI
Source: https://docs.puppeteerai.com/index

Build AI-powered conversational agents for healthcare

## Welcome

Puppeteer AI is a platform for building and deploying conversational AI agents for healthcare. This documentation covers integration options and the API.

<Columns>
  <Card icon="rocket" href="/quickstart" title="Getting Started">
    Integration options and how to become a client.
  </Card>

  <Card icon="tower-broadcast" href="/channels" title="Channels">
    Phone, SMS, WhatsApp, web UI, and API.
  </Card>

  <Card icon="terminal" href="/api-reference" title="API Reference">
    Explore available endpoints with an interactive playground.
  </Card>

  <Card icon="key" href="/api-reference/authentication" title="Authentication">
    API keys and JWT tokens.
  </Card>
</Columns>


# Getting Started
Source: https://docs.puppeteerai.com/quickstart

Get started with Puppeteer AI

## What is Puppeteer?

Puppeteer AI is a platform for building and deploying conversational AI agents for healthcare. Agents can interact with patients via phone calls, SMS, WhatsApp, and web-based chat interfaces.

## Become a client

Puppeteer is not self-service. If you're not yet a client, visit our website or contact sales to get started.

<Columns>
  <Card title="Website" icon="globe" href="https://puppeteerai.com">
    puppeteerai.com
  </Card>

  <Card title="Contact Sales" icon="envelope" href="mailto:hello@puppeteerai.com">
    [hello@puppeteerai.com](mailto:hello@puppeteerai.com)
  </Card>
</Columns>

## Next steps

Once you're onboarded, you can integrate your Puppeteer agent through a variety of channels depending on your use case.

<Card title="Channels" icon="tower-broadcast" href="/channels">
  Explore integration options — phone, SMS, WhatsApp, web UI, and API.
</Card>


# Chat Widget
Source: https://docs.puppeteerai.com/widget

Add a floating chat bubble to your website

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](/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.

<img alt="Chat widget" />

## Installation

Add this script tag before the closing `</body>` tag on every page where you want the widget to appear:

```html theme={null}
<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

| Attribute              | Default   | Description                                |
| ---------------------- | --------- | ------------------------------------------ |
| `data-widget-position` | `"right"` | Side of the screen: `"left"` or `"right"`. |
| `data-bottom-offset`   | `"1rem"`  | Distance from the bottom of the viewport.  |

### Theming

| Attribute                     | Description                                    |
| ----------------------------- | ---------------------------------------------- |
| `data-header-bg-color`        | Header background color (hex, e.g. `#F6F7F9`). |
| `data-header-text-color`      | Header text color.                             |
| `data-header-bot-name`        | Display name shown in the header.              |
| `data-agent-image`            | URL for the bot's avatar image.                |
| `data-bot-bubble-bg-color`    | Background color of bot message bubbles.       |
| `data-bot-bubble-text-color`  | Text color of bot message bubbles.             |
| `data-user-bubble-bg-color`   | Background color of user message bubbles.      |
| `data-user-bubble-text-color` | Text color of user message bubbles.            |

### Data

| Attribute                  | Description                                                                                    |
| -------------------------- | ---------------------------------------------------------------------------------------------- |
| `data-token`               | Pre-generated access token for the thread.                                                     |
| `data-json-input`          | JSON string with initial data to send to the thread on creation.                               |
| `data-show-audio-waveform` | When "true", shows an animated audio waveform during web calls instead of the live transcript. |

### Full example

```html theme={null}
<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`:

```html theme={null}
<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](/api-reference/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

```javascript theme={null}
window.PuppeteerChat.open();
```

### Send a message

```javascript theme={null}
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.