# Delete chatbot icon
Source: https://chatbase.co/docs/api-reference/assets/delete-chatbot-icon

/openapi.yaml delete /delete-chatbot-icon
Deletes the chatbot's icon image



# Delete chatbot profile picture
Source: https://chatbase.co/docs/api-reference/assets/delete-chatbot-profile-picture

/openapi.yaml delete /delete-chatbot-profile-picture
Deletes the chatbot's profile picture



# Upload chatbot icon
Source: https://chatbase.co/docs/api-reference/assets/upload-chatbot-icon

/openapi.yaml post /upload-chatbot-icon
Uploads an icon image for the chatbot



# Upload chatbot profile picture
Source: https://chatbase.co/docs/api-reference/assets/upload-chatbot-profile-picture

/openapi.yaml post /upload-chatbot-profile-picture
Uploads a profile picture for the chatbot



# Chat with a chatbot
Source: https://chatbase.co/docs/api-reference/chat/chat-with-a-chatbot

/openapi.yaml post /chat
Send a message to a chatbot and receive a response. Supports streaming responses.
Can continue existing conversations by providing a conversationId.


<Note>
  **Looking for API v2?** The new Chatbase API v2 features structured error codes, cursor-based pagination, and SSE streaming. Note that API v2 is available starting from the Standard Plan. [Check out the API v2 Reference →](/docs/api-v2/overview)
</Note>


# Create a new chatbot
Source: https://chatbase.co/docs/api-reference/chatbots/create-a-new-chatbot

/openapi.yaml post /create-chatbot
Creates a new chatbot with training data from text



# Delete a chatbot
Source: https://chatbase.co/docs/api-reference/chatbots/delete-a-chatbot

/openapi.yaml delete /delete-chatbot
Permanently deletes a chatbot and all associated data



# Get all chatbots
Source: https://chatbase.co/docs/api-reference/chatbots/get-all-chatbots

/openapi.yaml get /get-chatbots
Retrieves all chatbots for the authenticated account



# Update a chatbot
Source: https://chatbase.co/docs/api-reference/chatbots/update-a-chatbot

/openapi.yaml post /update-chatbot-data
Updates and retrains a chatbot with new content



# Update chatbot settings
Source: https://chatbase.co/docs/api-reference/chatbots/update-chatbot-settings

/openapi.yaml post /update-chatbot-settings
Updates various chatbot configuration settings



# Create contacts for a chatbot
Source: https://chatbase.co/docs/api-reference/contacts/create-contacts-for-a-chatbot

/openapi.yaml post /chatbots/{chatbotId}/contacts
Creates one or more contacts for a specific chatbot (max 1000 per request)



# Create custom attribute
Source: https://chatbase.co/docs/api-reference/contacts/create-custom-attribute

/openapi.yaml post /chatbots/{chatbotId}/custom-attributes
Creates a new custom attribute for contacts



# Delete a contact
Source: https://chatbase.co/docs/api-reference/contacts/delete-a-contact

/openapi.yaml delete /chatbots/{chatbotId}/contacts/{contactId}
Permanently deletes a contact



# Get a specific contact
Source: https://chatbase.co/docs/api-reference/contacts/get-a-specific-contact

/openapi.yaml get /chatbots/{chatbotId}/contacts/{contactId}
Retrieves a single contact by ID



# Get contacts for a chatbot
Source: https://chatbase.co/docs/api-reference/contacts/get-contacts-for-a-chatbot

/openapi.yaml get /chatbots/{chatbotId}/contacts
Retrieves paginated list of contacts for a specific chatbot



# Get custom attributes schema
Source: https://chatbase.co/docs/api-reference/contacts/get-custom-attributes-schema

/openapi.yaml get /chatbots/{chatbotId}/custom-attributes
Retrieves the custom attributes schema for contacts



# Update a contact
Source: https://chatbase.co/docs/api-reference/contacts/update-a-contact

/openapi.yaml patch /chatbots/{chatbotId}/contacts/{contactId}
Updates an existing contact's information



# Update custom attribute
Source: https://chatbase.co/docs/api-reference/contacts/update-custom-attribute

/openapi.yaml put /chatbots/{chatbotId}/custom-attributes/{name}
Updates an existing custom attribute



# Get conversations for a chatbot
Source: https://chatbase.co/docs/api-reference/conversations/get-conversations-for-a-chatbot

/openapi.yaml get /get-conversations
Retrieves conversation history for a specific chatbot

<Note>
  **Looking for API v2?** The new Chatbase API v2 features structured error codes, cursor-based pagination, and SSE streaming. [Check out the API v2 Reference →](/docs/api-v2/overview)
</Note>


# Get leads for a chatbot
Source: https://chatbase.co/docs/api-reference/leads/get-leads-for-a-chatbot

/openapi.yaml get /get-leads
Retrieves collected leads/customers for a specific chatbot



# Chat with an agent
Source: https://chatbase.co/docs/api-v2/agents/chat-with-an-agent

/api-v2-openapi.json post /agents/{agentId}/chat
Send a message to an agent and receive a response. Supports streaming responses when `stream: true` is set in the request body.



# Retry a message
Source: https://chatbase.co/docs/api-v2/agents/retry-a-message

/api-v2-openapi.json post /agents/{agentId}/conversations/{conversationId}/retry
Retry generating an assistant response for a given message. Truncates the conversation at the target message, then re-sends the preceding user message through the chat service.



# Submit a tool result
Source: https://chatbase.co/docs/api-v2/agents/submit-a-tool-result

/api-v2-openapi.json post /agents/{agentId}/conversations/{conversationId}/tool-result
Submit the result of a client-side tool call. Use the toolCallId from the tool-call part in the chat response to identify the tool call.



# Authentication
Source: https://chatbase.co/docs/api-v2/authentication

How to authenticate with the Chatbase API v2 using Bearer tokens, and understand rate limiting.

## Bearer Token Authentication

All API v2 endpoints (except the health check) require a Bearer token in the `Authorization` header:

```
Authorization: Bearer <api-key>
```

### Getting an API Key

1. Go to the [Chatbase Dashboard](https://www.chatbase.co/dashboard)
2. Navigate to **Workspace Settings** → **API Keys**
3. Click **Create API Key**
4. Copy and securely store the generated key

<Warning>
  API keys grant full access to your workspace. Never expose them in client-side code, public repositories, or browser network requests.
</Warning>

<Note>
  API v2 requires a Chatbase Standard Plan or above. Requests from accounts on unsupported plans will be rejected.
</Note>

### Example Request

```bash theme={null}
curl -X POST 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"message": "Hello!"}'
```

## Rate Limiting

The API enforces a rate limit of **100 requests per 10-second sliding window**, scoped per API key and IP address.

### Rate Limit Headers

Every response includes rate limit headers so you can track your usage:

| Header                  | Description                                                       |
| ----------------------- | ----------------------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum number of requests allowed in the window (100).           |
| `X-RateLimit-Remaining` | Number of requests remaining in the current window.               |
| `X-RateLimit-Reset`     | Unix timestamp in milliseconds when the current window resets.    |
| `Retry-After`           | Seconds to wait before retrying. Only present on `429` responses. |

### Handling Rate Limits

When you exceed the rate limit, the API returns a `429` status code:

```json theme={null}
{
  "error": {
    "code": "RATE_LIMIT_TOO_MANY_REQUESTS",
    "message": "Too many requests, please try again later"
  }
}
```

Use the `Retry-After` header to determine how long to wait before retrying:

```javascript theme={null}
async function fetchWithRetry(url, options) {
  const response = await fetch(url, options);

  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get("Retry-After"), 10);
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
    return fetchWithRetry(url, options);
  }

  return response;
}
```

## Request ID

Every response includes an `x-request-id` header containing a unique identifier for the request. When contacting support about an error, always include this value to help with debugging.

```
x-request-id: req_a1b2c3d4e5f6
```


# Client Actions
Source: https://chatbase.co/docs/api-v2/client-actions

Handle client-side actions invoked by your AI agent through the Chatbase API v2.

## What Are Client Actions?

Client actions allow your AI agent to request that your application perform an action on the client side. When an agent determines it needs external information or wants to trigger an operation, it responds with a `finishReason` of `"tool-calls"` and includes `tool-call` parts describing what it needs.

Your application executes the action, submits the result back to the API, and then continues the conversation.

<Note>
  Client actions correspond to the **Custom Actions** configured on your agent in the Chatbase dashboard. The `toolName` in the API response is the name of the configured action.
</Note>

## Flow

```mermaid theme={null}
sequenceDiagram
    participant App as Your App
    participant API as Chatbase API
    participant Agent as AI Agent

    App->>API: POST /chat (message)
    API->>Agent: Process message
    Agent-->>API: Response with tool-call parts
    API-->>App: finishReason: "tool-calls"
    App->>App: Execute action client-side
    App->>API: POST /tool-result (toolCallId, output)
    API-->>App: { success: true }
    App->>API: POST /chat (continue conversation)
    API->>Agent: Process with tool result
    Agent-->>API: Final response
    API-->>App: finishReason: "stop"
```

<Steps>
  <Step title="Send a chat message">
    Send a message to the chat endpoint as usual.
  </Step>

  <Step title="Receive a client action request">
    The response has `finishReason: "tool-calls"` and `tool-call` parts containing `toolCallId`, `toolName`, and `input`.
  </Step>

  <Step title="Execute the action client-side">
    Use `toolName` and `input` to determine what to do and execute the action in your application.
  </Step>

  <Step title="Submit the result">
    Send the result to `POST /agents/{agentId}/conversations/{conversationId}/tool-result` with the `toolCallId` and `output`.
  </Step>

  <Step title="Continue the conversation">
    Call the chat endpoint again with the `conversationId`. You can omit `message` to let the agent continue based on the tool result alone, or include a new message.
  </Step>
</Steps>

## Message Parts

Responses can include three types of parts in the `parts` array:

<CardGroup>
  <Card title="text" icon="font">
    Text content generated by the agent.

    Fields: `type`, `text`
  </Card>

  <Card title="tool-call" icon="bolt">
    A client action the agent wants your app to execute.

    Fields: `type`, `toolCallId`, `toolName`, `input`
  </Card>

  <Card title="tool-result" icon="check">
    The result of a previously executed client action (visible in conversation history).

    Fields: `type`, `toolCallId`, `toolName`, `output`
  </Card>
</CardGroup>

## Detecting a Client Action

Check the `finishReason` in the response metadata. When it is `"tool-calls"`, the `parts` array will contain one or more `tool-call` entries:

```json theme={null}
{
  "data": {
    "id": "msg_abc123",
    "role": "assistant",
    "parts": [
      { "type": "text", "text": "Let me look up that order for you." },
      {
        "type": "tool-call",
        "toolCallId": "call_abc123",
        "toolName": "lookupOrder",
        "input": { "orderId": "ORD-123" }
      }
    ],
    "metadata": {
      "userMessageId": "msg_xyz789",
      "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "userId": "user_abc123",
      "finishReason": "tool-calls",
      "usage": { "credits": 2 }
    }
  }
}
```

## Submitting the Result

After executing the action, submit the result using the tool-result endpoint:

```
POST /api/v2/agents/{agentId}/conversations/{conversationId}/tool-result
```

### Request Body

<ParamField type="string">
  The `toolCallId` from the `tool-call` part in the chat response.
</ParamField>

<ParamField type="any">
  The result of executing the action.
</ParamField>

### Response

```json theme={null}
{
  "data": {
    "success": true
  }
}
```

## Continuing the Conversation

After submitting the tool result, continue the conversation by calling the chat endpoint again. You can either:

* **Omit `message`** to let the agent continue based on the tool result alone.
* **Include a `message`** to provide additional context or a follow-up question.

You must include the `conversationId` to continue the same conversation.

```bash theme={null}
curl -X POST 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  }'
```

## Streaming Client Actions

When streaming is enabled, client action input arrives incrementally through these events:

<Steps>
  <Step title="tool-input-start">
    Signals the start of a client action. Includes `toolCallId` and `toolName`.
  </Step>

  <Step title="tool-input-delta">
    Incremental chunks of the action input stream in.
  </Step>

  <Step title="tool-input-available">
    The complete input is ready. You can read the full `input` object directly from this event without concatenating the preceding deltas.
  </Step>
</Steps>

The stream's `message-metadata` event will have `finishReason: "tool-calls"`. See [Streaming](/docs/api-v2/streaming) for full event type reference.

## Code Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  // Step 1: Send a message
  const chatResponse = await fetch(
    "https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        message: "What's the status of order ORD-123?",
        stream: false,
      }),
    }
  );

  const { data } = await chatResponse.json();
  const { conversationId, finishReason } = data.metadata;

  // Step 2: Check if a client action was invoked
  if (finishReason === "tool-calls") {
    for (const part of data.parts) {
      if (part.type === "tool-call") {
        // Step 3: Execute the action
        const result = await executeAction(part.toolName, part.input);

        // Step 4: Submit the result
        await fetch(
          `https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/conversations/${conversationId}/tool-result`,
          {
            method: "POST",
            headers: {
              Authorization: "Bearer YOUR_API_KEY",
              "Content-Type": "application/json",
            },
            body: JSON.stringify({
              toolCallId: part.toolCallId,
              output: result,
            }),
          }
        );
      }
    }

    // Step 5: Continue the conversation
    const continueResponse = await fetch(
      "https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat",
      {
        method: "POST",
        headers: {
          Authorization: "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          conversationId,
          stream: false,
        }),
      }
    );

    const continued = await continueResponse.json();
    console.log(continued.data.parts);
  }

  // Your action handler
  async function executeAction(toolName, input) {
    switch (toolName) {
      case "lookupOrder":
        // Call your order service
        return { status: "shipped", eta: "2026-04-03" };
      default:
        return { error: "Unknown action" };
    }
  }
  ```

  ```python Python theme={null}
  import requests

  API_KEY = "YOUR_API_KEY"
  AGENT_ID = "YOUR_AGENT_ID"
  BASE_URL = "https://www.chatbase.co/api/v2"
  HEADERS = {
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json",
  }

  # Step 1: Send a message
  chat_response = requests.post(
      f"{BASE_URL}/agents/{AGENT_ID}/chat",
      headers=HEADERS,
      json={
          "message": "What's the status of order ORD-123?",
          "stream": False,
      },
  ).json()

  data = chat_response["data"]
  conversation_id = data["metadata"]["conversationId"]
  finish_reason = data["metadata"]["finishReason"]

  # Step 2: Check if a client action was invoked
  if finish_reason == "tool-calls":
      for part in data["parts"]:
          if part["type"] == "tool-call":
              # Step 3: Execute the action
              result = execute_action(part["toolName"], part["input"])

              # Step 4: Submit the result
              requests.post(
                  f"{BASE_URL}/agents/{AGENT_ID}/conversations/{conversation_id}/tool-result",
                  headers=HEADERS,
                  json={
                      "toolCallId": part["toolCallId"],
                      "output": result,
                  },
              )

      # Step 5: Continue the conversation
      continued = requests.post(
          f"{BASE_URL}/agents/{AGENT_ID}/chat",
          headers=HEADERS,
          json={
              "conversationId": conversation_id,
              "stream": False,
          },
      ).json()

      for part in continued["data"]["parts"]:
          if part["type"] == "text":
              print(part["text"])


  def execute_action(tool_name, tool_input):
      if tool_name == "lookupOrder":
          return {"status": "shipped", "eta": "2026-04-03"}
      return {"error": "Unknown action"}
  ```

  ```bash curl theme={null}
  # Step 1: Send a message
  curl -X POST 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "message": "What is the status of order ORD-123?",
      "stream": false
    }'

  # Step 2: Submit the tool result (use toolCallId from the response)
  curl -X POST 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/conversations/CONVERSATION_ID/tool-result' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "toolCallId": "call_abc123",
      "output": { "status": "shipped", "eta": "2026-04-03" }
    }'

  # Step 3: Continue the conversation
  curl -X POST 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "conversationId": "CONVERSATION_ID"
    }'
  ```
</CodeGroup>

## Error Handling

| Code                           | Status | Description                                                                                               |
| ------------------------------ | ------ | --------------------------------------------------------------------------------------------------------- |
| `RESOURCE_TOOL_CALL_NOT_FOUND` | 404    | No pending client action matches the provided `toolCallId`. It may have expired or already been resolved. |
| `VALIDATION_INVALID_BODY`      | 400    | The request body failed schema validation. Check the `details` field for specifics.                       |


# Export conversations
Source: https://chatbase.co/docs/api-v2/conversations/export-conversations

/api-v2-openapi.json get /agents/{agentId}/conversations/export
Export all conversations with full message history for an agent. Includes conversations from all sources. Tool results are sanitized to remove internal data. Supports cursor-based pagination.



# Get a conversation
Source: https://chatbase.co/docs/api-v2/conversations/get-a-conversation

/api-v2-openapi.json get /agents/{agentId}/conversations/{conversationId}
Get conversation metadata and its most recent messages. The pagination cursor can be used with the list messages endpoint to fetch older messages.



# List conversation messages
Source: https://chatbase.co/docs/api-v2/conversations/list-conversation-messages

/api-v2-openapi.json get /agents/{agentId}/conversations/{conversationId}/messages
List all messages in a conversation with cursor-based pagination. Messages are returned in chronological order within each page, paginating backward from newest. The cursor from the get-conversation endpoint works here.



# List conversations
Source: https://chatbase.co/docs/api-v2/conversations/list-conversations

/api-v2-openapi.json get /agents/{agentId}/conversations
List conversations for an agent, ordered by createdAt date. Supports cursor-based pagination.



# List conversations for a user
Source: https://chatbase.co/docs/api-v2/conversations/list-conversations-for-a-user

/api-v2-openapi.json get /agents/{agentId}/users/{userId}/conversations
List conversations for a specific user under an agent, ordered by last activity. Supports cursor-based pagination.



# Update message feedback
Source: https://chatbase.co/docs/api-v2/conversations/update-message-feedback

/api-v2-openapi.json patch /agents/{agentId}/conversations/{conversationId}/messages/{messageId}/feedback
Set or clear feedback on an assistant message. Use "positive" or "negative" to set feedback, or null to remove existing feedback.



# Error Handling
Source: https://chatbase.co/docs/api-v2/error-handling

Structured error codes and troubleshooting guide for the Chatbase API v2.

## Error Response Format

All errors follow a consistent envelope format:

```json theme={null}
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": {}
  }
}
```

| Field     | Type     | Description                                                                     |
| --------- | -------- | ------------------------------------------------------------------------------- |
| `code`    | `string` | Machine-readable error code. Use this for programmatic handling.                |
| `message` | `string` | Human-readable description of the error.                                        |
| `details` | `object` | Optional. Field-level validation errors (present on `VALIDATION_INVALID_BODY`). |

## Error Codes

<table>
  <thead>
    <tr>
      <th>Code</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr><td><code>VALIDATION\_INVALID\_BODY</code></td><td>The request body failed schema validation. Check the <code>details</code> field for specific field errors.</td></tr>
    <tr><td><code>VALIDATION\_INVALID\_JSON</code></td><td>The request body is not valid JSON.</td></tr>
    <tr><td><code>CHAT\_RETRY\_NO\_USER\_MESSAGE</code></td><td>The retry target message has no preceding user message to re-send.</td></tr>
    <tr><td><code>AUTH\_MISSING\_API\_KEY</code></td><td>No <code>Authorization</code> header was provided.</td></tr>
    <tr><td><code>AUTH\_INVALID\_API\_KEY</code></td><td>The API key is not valid.</td></tr>
    <tr><td><code>AUTH\_EXPIRED\_API\_KEY</code></td><td>The API key has expired. Generate a new one from the dashboard.</td></tr>
    <tr><td><code>CHAT\_CREDITS\_EXHAUSTED</code></td><td>The workspace's message credit balance is zero. Upgrade the plan or wait for credits to reset.</td></tr>
    <tr><td><code>CHAT\_AGENT\_CREDITS\_EXHAUSTED</code></td><td>The specific agent's credit allocation has been used up.</td></tr>
    <tr><td><code>SUBSCRIPTION\_API\_RESTRICTED\_PLAN</code></td><td>Your current plan does not include API access. A Standard Plan or above is required.</td></tr>
    <tr><td><code>AUTH\_INSUFFICIENT\_PERMISSIONS</code></td><td>The API key does not have the required permissions for this operation.</td></tr>
    <tr><td><code>CHAT\_MODEL\_NOT\_ALLOWED</code></td><td>The agent is configured to use a model that is not available on the current plan.</td></tr>
    <tr><td><code>CHAT\_CONVERSATION\_MISMATCH</code></td><td>The conversation does not belong to the specified agent.</td></tr>
    <tr><td><code>CHAT\_CONVERSATION\_NOT\_ONGOING</code></td><td>The conversation has ended or been taken over and cannot receive new messages.</td></tr>
    <tr><td><code>RESOURCE\_NOT\_FOUND</code></td><td>The requested resource does not exist.</td></tr>
    <tr><td><code>RESOURCE\_TOOL\_CALL\_NOT\_FOUND</code></td><td>No pending client action matches the provided <code>toolCallId</code>. It may have expired or already been resolved.</td></tr>
    <tr><td><code>RESOURCE\_MESSAGE\_NOT\_FOUND</code></td><td>The specified message was not found in the conversation.</td></tr>
    <tr><td><code>RESOURCE\_MESSAGE\_NOT\_ASSISTANT</code></td><td>Only assistant messages support feedback and metadata updates.</td></tr>
    <tr><td><code>CHAT\_RETRY\_MESSAGE\_NOT\_FOUND</code></td><td>The message ID provided for retry was not found in the conversation.</td></tr>
    <tr><td><code>RATE\_LIMIT\_TOO\_MANY\_REQUESTS</code></td><td>Rate limit exceeded. Check the <code>Retry-After</code> header for how long to wait. See <a href="/api-v2/authentication#rate-limiting">Authentication</a> for details.</td></tr>
    <tr><td><code>INTERNAL\_SERVER\_ERROR</code></td><td>An unexpected error occurred. If this persists, contact support with the <code>x-request-id</code> header value.</td></tr>
    <tr><td><code>CHAT\_STREAMING\_ERROR</code></td><td>An error occurred during stream generation. The stream may have been partially delivered.</td></tr>
  </tbody>
</table>

**Example with field-level details (`VALIDATION_INVALID_BODY`):**

```json theme={null}
{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request",
    "details": {
      "message": "Required"
    }
  }
}
```

## Handling Errors

```javascript theme={null}
const response = await fetch(
  "https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message: "Hello" }),
  }
);

if (!response.ok) {
  const { error } = await response.json();
  const requestId = response.headers.get("x-request-id");

  switch (error.code) {
    case "RATE_LIMIT_TOO_MANY_REQUESTS":
      const retryAfter = response.headers.get("Retry-After");
      // Wait and retry
      break;
    case "CHAT_CREDITS_EXHAUSTED":
      // Notify user about credit limit
      break;
    case "VALIDATION_INVALID_BODY":
      // Fix request based on error.details
      console.log("Validation errors:", error.details);
      break;
    default:
      console.error(`[${error.code}] ${error.message} (request: ${requestId})`);
  }
}
```


# Health check
Source: https://chatbase.co/docs/api-v2/health/health-check

/api-v2-openapi.json get /health
Returns the API health status. No authentication required.



# API v2 Overview
Source: https://chatbase.co/docs/api-v2/overview

Introduction to the Chatbase API v2 — a structured, modern REST API for chatting with agents and managing conversations.

<Info>
  **Standard Plan required.** The Chatbase API v2 is available starting from the Standard Plan. [View pricing →](https://www.chatbase.co/pricing)
</Info>

<Warning>
  Most conversation endpoints apply exclusively to conversations created programmatically via the Chatbase API. Conversations generated through the widget or external integrations cannot be accessed using these endpoints. The exception is the [Export conversations](/docs/api-v2/conversations/export-conversations) endpoint, which returns conversations from **all sources**.
</Warning>

## What is the Chatbase API v2?

The Chatbase API v2 is a redesigned REST API that provides a clean, consistent interface for interacting with your AI agents. It features structured error codes, cursor-based pagination, streaming support via Server-Sent Events, and a predictable response format.

**Base URL:**

```
https://www.chatbase.co/api/v2
```

## Quick Start

<Steps>
  <Step title="Get your API key">
    1. Go to the [Chatbase Dashboard](https://www.chatbase.co/dashboard)
    2. Navigate to **Workspace Settings** → **API Keys**
    3. Click **Create API Key** and copy the generated key

    <Warning>Store your API key securely. Never expose it in client-side code.</Warning>
  </Step>

  <Step title="Get your Agent ID">
    1. Select your AI Agent in the dashboard
    2. Go to **Settings** → **General**
    3. Copy the **Agent ID**
  </Step>

  <Step title="Send your first message">
    ```bash theme={null}
    curl -X POST 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat' \
      -H 'Authorization: Bearer YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
        "message": "Hello! How can you help me?"
      }'
    ```

    **Response:**

    ```json theme={null}
    {
      "data": {
        "id": "msg_abc123",
        "role": "assistant",
        "parts": [
          { "type": "text", "text": "Hello! I'm here to help. What can I assist you with today?" }
        ],
        "metadata": {
          "userMessageId": "msg_xyz789",
          "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
          "userId": null,
          "finishReason": "stop",
          "usage": { "credits": 2 }
        }
      }
    }
    ```
  </Step>
</Steps>

## Endpoints

| Method  | Endpoint                                                                                |
| ------- | --------------------------------------------------------------------------------------- |
| `GET`   | `/api/v2/health`                                                                        |
| `POST`  | `/api/v2/agents/{agentId}/chat`                                                         |
| `POST`  | `/api/v2/agents/{agentId}/conversations/{conversationId}/retry`                         |
| `GET`   | `/api/v2/agents/{agentId}/conversations`                                                |
| `GET`   | `/api/v2/agents/{agentId}/conversations/export`                                         |
| `GET`   | `/api/v2/agents/{agentId}/conversations/{conversationId}`                               |
| `GET`   | `/api/v2/agents/{agentId}/conversations/{conversationId}/messages`                      |
| `GET`   | `/api/v2/agents/{agentId}/users/{userId}/conversations`                                 |
| `POST`  | `/api/v2/agents/{agentId}/conversations/{conversationId}/tool-result`                   |
| `PATCH` | `/api/v2/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/feedback` |

## Response Headers

Every response includes these headers:

| Header                  | Description                                                      |
| ----------------------- | ---------------------------------------------------------------- |
| `x-request-id`          | Unique request identifier. Include this when contacting support. |
| `X-RateLimit-Limit`     | Maximum requests allowed in the current window.                  |
| `X-RateLimit-Remaining` | Requests remaining in the current window.                        |
| `X-RateLimit-Reset`     | Unix timestamp (ms) when the rate limit window resets.           |

## Next Steps

<CardGroup>
  <Card title="Authentication" icon="key" href="/api-v2/authentication">
    API keys, Bearer tokens, and rate limiting
  </Card>

  <Card title="Streaming" icon="wave-pulse" href="/api-v2/streaming">
    Real-time SSE streaming responses
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/api-v2/error-handling">
    Structured error codes and troubleshooting
  </Card>

  <Card title="Pagination" icon="arrow-right" href="/api-v2/pagination">
    Cursor-based pagination for list endpoints
  </Card>
</CardGroup>


# Pagination
Source: https://chatbase.co/docs/api-v2/pagination

How cursor-based pagination works in the Chatbase API v2.

## How It Works

The API v2 uses **cursor-based pagination** for all list endpoints. Cursors are opaque, base64-encoded strings — treat them as opaque tokens and do not attempt to decode or construct them.

### Query Parameters

| Parameter | Type      | Default | Description                                                               |
| --------- | --------- | ------- | ------------------------------------------------------------------------- |
| `cursor`  | `string`  | —       | Opaque cursor from a previous response. Omit to start from the beginning. |
| `limit`   | `integer` | `20`    | Number of items per page. Range: 1–100.                                   |

### Response Shape

All paginated responses follow this structure:

```json theme={null}
{
  "data": [...],
  "pagination": {
    "cursor": "eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMC4wMDBaIiwiaWQiOiJhYmMxMjMifQ==",
    "hasMore": true,
    "total": 142
  }
}
```

| Field                | Type             | Description                                                              |
| -------------------- | ---------------- | ------------------------------------------------------------------------ |
| `data`               | `array`          | The page of results.                                                     |
| `pagination.cursor`  | `string \| null` | Cursor to pass for the next page. `null` when there are no more results. |
| `pagination.hasMore` | `boolean`        | `true` if more results are available beyond this page.                   |
| `pagination.total`   | `integer`        | Total number of items matching the query.                                |

## Paginating Through All Results

Pass the `cursor` from each response into the next request to iterate through all pages:

<CodeGroup>
  ```javascript Node.js theme={null}
  async function fetchAllConversations(agentId, apiKey) {
    const conversations = [];
    let cursor = undefined;

    do {
      const params = new URLSearchParams({ limit: "100" });
      if (cursor) params.set("cursor", cursor);

      const response = await fetch(
        `https://www.chatbase.co/api/v2/agents/${agentId}/conversations?${params}`,
        {
          headers: { Authorization: `Bearer ${apiKey}` },
        }
      );

      const { data, pagination } = await response.json();
      conversations.push(...data);
      cursor = pagination.cursor;
    } while (cursor);

    return conversations;
  }
  ```

  ```python Python theme={null}
  import requests

  def fetch_all_conversations(agent_id: str, api_key: str):
      conversations = []
      cursor = None

      while True:
          params = {"limit": 100}
          if cursor:
              params["cursor"] = cursor

          response = requests.get(
              f"https://www.chatbase.co/api/v2/agents/{agent_id}/conversations",
              headers={"Authorization": f"Bearer {api_key}"},
              params=params,
          )
          body = response.json()
          conversations.extend(body["data"])

          cursor = body["pagination"]["cursor"]
          if not cursor:
              break

      return conversations
  ```
</CodeGroup>

## Export Pagination

The export endpoint (`GET /api/v2/agents/{agentId}/conversations/export`) paginates through **all conversations** (from every source) with full message history included. Each page returns up to `limit` conversations with their complete messages already embedded — no separate call to a messages endpoint is needed.

<Tip>
  Because each exported conversation includes all of its messages, pages can be significantly larger than other paginated responses. Use a smaller `limit` if you want to keep response sizes manageable.
</Tip>

## Message Pagination

The messages endpoint (`GET /api/v2/agents/{agentId}/conversations/{conversationId}/messages`) paginates **backward from the newest messages**. Within each page, messages are returned in chronological order.

This means:

* The first page contains the most recent messages
* Passing the `cursor` fetches the next older page
* Each page's messages are ordered oldest → newest

<Tip>
  The cursor returned by the [Get a conversation](/docs/api-v2/conversations/get-a-conversation) endpoint is compatible with the messages endpoint, so you can use it to fetch older messages beyond what the conversation response includes.
</Tip>


# Streaming
Source: https://chatbase.co/docs/api-v2/streaming

How to use Server-Sent Events (SSE) streaming with the Chatbase API v2 for real-time responses.

## Enabling Streaming

To receive a streaming response, set `stream: true` in the request body of the chat or retry endpoints:

```bash theme={null}
curl -X POST 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Explain quantum computing",
    "stream": true,
    "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "userId": "user_abc123"
  }'
```

## Request Body

<ParamField type="string">
  The user message to send to the agent. Omit to continue the conversation after submitting a client action result.
</ParamField>

<ParamField type="boolean">
  Stream the response as SSE. Defaults to `true`.
</ParamField>

<ParamField type="string">
  Continue an existing conversation. Omit to create a new one.
</ParamField>

<ParamField type="string">
  Associate a user with a new conversation. Max 128 chars, `[a-zA-Z0-9._-]` only. Ignored when `conversationId` is provided.
</ParamField>

<Note>
  Once set, a conversation's `userId` is immutable — it cannot be changed or removed. See [User Conversations](/docs/api-v2/user-conversations) for details on managing per-user conversation history.
</Note>

The response uses `Content-Type: text/event-stream` and follows the **AI SDK UIMessage Stream** protocol. Events are newline-delimited JSON, where each line is a JSON object with a `type` field.

## Event Types

<Tabs>
  <Tab title="Text Events" icon="font">
    ### `message-start`

    Emitted once at the beginning of a new message. Contains the message ID.

    ```json theme={null}
    { "type": "message-start", "messageId": "msg_abc123" }
    ```

    ### `text-start`

    Emitted at the beginning of a text block.

    ```json theme={null}
    { "type": "text-start", "id": "text_001" }
    ```

    ### `text-delta`

    Emitted for each chunk of generated text. Concatenate all deltas to build the full response.

    ```json theme={null}
    { "type": "text-delta", "id": "text_001", "delta": "Quantum computing is" }
    ```

    ### `text-end`

    Emitted when a text block is complete.

    ```json theme={null}
    { "type": "text-end", "id": "text_001" }
    ```
  </Tab>

  <Tab title="Client Action Events" icon="bolt">
    These events are emitted when the agent invokes a [client action](/docs/api-v2/client-actions). The `toolName` corresponds to the name of the configured action.

    ### `tool-input-start`

    Emitted at the start of a client action input.

    ```json theme={null}
    { "type": "tool-input-start", "toolCallId": "call_abc123", "toolName": "lookupOrder" }
    ```

    ### `tool-input-delta`

    Emitted for each chunk of the action input as it streams.

    ```json theme={null}
    { "type": "tool-input-delta", "toolCallId": "call_abc123", "inputTextDelta": "{\"order" }
    ```

    ### `tool-input-available`

    Emitted when the complete action input is ready.

    <Tip>You can read the full `input` object directly from this event without concatenating the preceding deltas.</Tip>

    ```json theme={null}
    { "type": "tool-input-available", "toolCallId": "call_abc123", "toolName": "lookupOrder", "input": { "orderId": "ORD-123" } }
    ```

    ### `tool-output-available`

    Emitted when a tool execution result is available.

    <Tip>The full `output` can be read directly from this event.</Tip>

    ```json theme={null}
    { "type": "tool-output-available", "toolCallId": "call_abc123", "output": { "status": "shipped", "eta": "2026-04-03" } }
    ```

    <Info>
      For the full client action flow — including how to submit results and continue the conversation — see [Client Actions](/docs/api-v2/client-actions).
    </Info>
  </Tab>

  <Tab title="Step & Completion Events" icon="flag-checkered">
    ### `start-step`

    Emitted at the start of a processing step.

    ```json theme={null}
    { "type": "start-step" }
    ```

    ### `finish-step`

    Emitted at the end of a processing step.

    ```json theme={null}
    { "type": "finish-step" }
    ```

    ### `finish`

    Emitted once when generation is complete.

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

    ### `error`

    Emitted if an error occurs during generation. The stream may have been partially delivered.

    ```json theme={null}
    { "type": "error", "errorText": "An error occurred during generation" }
    ```
  </Tab>
</Tabs>

## Metadata

The `finish` event is accompanied by a `message-metadata` event containing Chatbase-specific metadata:

```json theme={null}
{
  "type": "message-metadata",
  "messageId": "msg_abc123",
  "userMessageId": "msg_xyz789",
  "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "userId": "user_abc123",
  "finishReason": "stop",
  "usage": { "credits": 2 }
}
```

<ResponseField name="messageId" type="string">
  Unique ID of the assistant message.
</ResponseField>

<ResponseField name="userMessageId" type="string">
  The ID of the user message that triggered this response. For continuation responses, this is the last user message in the conversation.
</ResponseField>

<ResponseField name="conversationId" type="string">
  The conversation ID. Use this for follow-up messages.
</ResponseField>

<ResponseField name="userId" type="string | null">
  The user ID associated with this conversation, or `null` if none.
</ResponseField>

<ResponseField name="finishReason" type="string">
  Why the model stopped generating:

  * `"stop"` — normal completion
  * `"error"` — an error occurred
  * `"tool-calls"` — the agent invoked a client action — submit the result and continue
</ResponseField>

<ResponseField name="usage" type="object">
  <Expandable title="properties">
    <ResponseField name="credits" type="number">
      Credits consumed by this request.
    </ResponseField>
  </Expandable>
</ResponseField>

The stream terminates with `data: [DONE]`.

## Code Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        message: "Explain quantum computing",
        stream: true,
        // conversationId: "a1b2c3d4-...", // omit to start a new conversation
        // userId: "user_abc123",          // associate a user with the conversation
      }),
    }
  );

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let conversationId;
  let userId;

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const lines = decoder.decode(value, { stream: true }).split("\n");
    for (const line of lines) {
      if (!line.trim()) continue;
      const event = JSON.parse(line);

      switch (event.type) {
        case "message-start":
          console.log("Message ID:", event.messageId);
          break;
        case "text-delta":
          process.stdout.write(event.delta);
          break;
        case "tool-input-available":
          console.log("\nClient action requested:", event.toolName, event.input);
          // Handle client action — see Client Actions guide
          break;
        case "message-metadata":
          conversationId = event.conversationId;
          userId = event.userId;
          console.log("\nFinish reason:", event.finishReason);
          console.log("Credits used:", event.usage.credits);
          break;
        case "error":
          console.error("Stream error:", event.errorText);
          break;
      }
    }
  }
  ```

  ```python Python theme={null}
  import requests
  import json

  response = requests.post(
      "https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "message": "Explain quantum computing",
          "stream": True,
          # "conversationId": "a1b2c3d4-...",  # omit to start a new conversation
          # "userId": "user_abc123",            # associate a user with the conversation
      },
      stream=True,
  )

  conversation_id = None
  user_id = None

  for line in response.iter_lines():
      if not line:
          continue
      event = json.loads(line)

      if event["type"] == "message-start":
          print(f"Message ID: {event['messageId']}")
      elif event["type"] == "text-delta":
          print(event["delta"], end="", flush=True)
      elif event["type"] == "tool-input-available":
          print(f"\nClient action requested: {event['toolName']}", event["input"])
          # Handle client action — see Client Actions guide
      elif event["type"] == "message-metadata":
          conversation_id = event["conversationId"]
          user_id = event["userId"]
          print(f"\nFinish reason: {event['finishReason']}")
          print(f"Credits used: {event['usage']['credits']}")
      elif event["type"] == "error":
          print(f"Stream error: {event['errorText']}")
  ```

  ```bash curl theme={null}
  curl -N -X POST 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "message": "Explain quantum computing",
      "stream": true,
      "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "userId": "user_abc123"
    }'
  ```
</CodeGroup>

## Non-Streaming Mode

When `stream` is set to `false`, the API returns a standard JSON response with the complete message:

<Tabs>
  <Tab title="Text Response">
    ```json theme={null}
    {
      "data": {
        "id": "msg_abc123",
        "role": "assistant",
        "parts": [
          { "type": "text", "text": "Quantum computing is a type of computation..." }
        ],
        "metadata": {
          "userMessageId": "msg_xyz789",
          "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
          "userId": "user_abc123",
          "finishReason": "stop",
          "usage": { "credits": 2 }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Client Action Response">
    When a client action is invoked, the response includes `tool-call` parts and `finishReason: "tool-calls"`:

    ```json theme={null}
    {
      "data": {
        "id": "msg_abc123",
        "role": "assistant",
        "parts": [
          { "type": "text", "text": "Let me look up that order for you." },
          { "type": "tool-call", "toolCallId": "call_abc123", "toolName": "lookupOrder", "input": { "orderId": "ORD-123" } }
        ],
        "metadata": {
          "userMessageId": "msg_xyz789",
          "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
          "userId": "user_abc123",
          "finishReason": "tool-calls",
          "usage": { "credits": 2 }
        }
      }
    }
    ```

    See [Client Actions](/docs/api-v2/client-actions) for how to submit the result and continue the conversation.
  </Tab>
</Tabs>


# User Conversations
Source: https://chatbase.co/docs/api-v2/user-conversations

Associate users with conversations, manage per-user history, and export full conversation data across all sources.

## Overview

Tag conversations with a `userId` to track per-user chat history. Once a conversation is associated with a user, you can list all of that user's conversations and continue any of them by passing the `conversationId`.

## Setting a User ID

Pass `userId` when creating a new conversation. The ID must follow these constraints:

| Constraint         | Value                                                          |
| ------------------ | -------------------------------------------------------------- |
| Max length         | 128 characters                                                 |
| Allowed characters | `a-z`, `A-Z`, `0-9`, `.`, `_`, `-`                             |
| When applied       | Only on conversation creation (no `conversationId` in request) |
| Mutability         | Immutable — cannot be changed or removed after creation        |

<Warning>
  A conversation's `userId` is set once at creation and cannot be changed. If you send `userId` with a `conversationId`, the `userId` field is ignored.
</Warning>

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        message: "Hello!",
        stream: true,
        userId: "user_abc123",
      }),
    }
  );
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "message": "Hello!",
          "stream": True,
          "userId": "user_abc123",
      },
      stream=True,
  )
  ```
</CodeGroup>

The response metadata includes the `userId`:

```json theme={null}
{
  "type": "finish",
  "finishReason": "stop",
  "metadata": {
    "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "userId": "user_abc123",
    "usage": { "credits": 2 }
  }
}
```

## Continuing a Conversation

To send follow-up messages in the same conversation, pass the `conversationId` from a previous response:

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        message: "Tell me more about that.",
        stream: true,
        conversationId: "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      }),
    }
  );
  ```

  ```python Python theme={null}
  response = requests.post(
      "https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "message": "Tell me more about that.",
          "stream": True,
          "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      },
      stream=True,
  )
  ```
</CodeGroup>

<Tip>
  The `conversationId` is returned in the streaming `finish` event's `metadata` or in the non-streaming response's `metadata` object. See [Streaming](/docs/api-v2/streaming) for details.
</Tip>

<Note>
  If the conversation has ended (e.g. after a human takeover), the API returns a `CHAT_CONVERSATION_NOT_ONGOING` error. Start a new conversation instead.
</Note>

## Listing a User's Conversations

Retrieve all conversations for a specific user with `GET /api/v2/agents/{agentId}/users/{userId}/conversations`.

### Path Parameters

| Parameter | Type     | Description                            |
| --------- | -------- | -------------------------------------- |
| `agentId` | `string` | The agent ID.                          |
| `userId`  | `string` | The user ID to list conversations for. |

### Query Parameters

| Parameter | Type      | Default | Description                                                               |
| --------- | --------- | ------- | ------------------------------------------------------------------------- |
| `cursor`  | `string`  | —       | Opaque cursor from a previous response. Omit to start from the beginning. |
| `limit`   | `integer` | `20`    | Number of items per page. Range: 1–100.                                   |

### Response

```json theme={null}
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "title": "Quantum computing basics",
      "createdAt": 1770681600,
      "updatedAt": 1770681900,
      "userId": "user_abc123",
      "status": "ongoing"
    },
    {
      "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "title": "Pricing questions",
      "createdAt": 1770595200,
      "updatedAt": 1770595500,
      "userId": "user_abc123",
      "status": "ended"
    }
  ],
  "pagination": {
    "cursor": "eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMC4wMDBaIiwiaWQiOiJhYmMxMjMifQ==",
    "hasMore": true,
    "total": 42
  }
}
```

### Response Fields

| Field       | Type             | Description                                               |
| ----------- | ---------------- | --------------------------------------------------------- |
| `id`        | `string`         | Conversation ID.                                          |
| `title`     | `string \| null` | Conversation title.                                       |
| `createdAt` | `number`         | Unix epoch timestamp (seconds).                           |
| `updatedAt` | `number`         | Unix epoch timestamp (seconds) of last activity.          |
| `userId`    | `string \| null` | The user ID associated with this conversation.            |
| `status`    | `string`         | Conversation status: `ongoing`, `ended`, or `taken_over`. |

### Pagination Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  async function fetchUserConversations(agentId, userId, apiKey) {
    const conversations = [];
    let cursor = undefined;

    do {
      const params = new URLSearchParams({ limit: "100" });
      if (cursor) params.set("cursor", cursor);

      const response = await fetch(
        `https://www.chatbase.co/api/v2/agents/${agentId}/users/${userId}/conversations?${params}`,
        {
          headers: { Authorization: `Bearer ${apiKey}` },
        }
      );

      const { data, pagination } = await response.json();
      conversations.push(...data);
      cursor = pagination.cursor;
    } while (cursor);

    return conversations;
  }
  ```

  ```python Python theme={null}
  import requests

  def fetch_user_conversations(agent_id: str, user_id: str, api_key: str):
      conversations = []
      cursor = None

      while True:
          params = {"limit": 100}
          if cursor:
              params["cursor"] = cursor

          response = requests.get(
              f"https://www.chatbase.co/api/v2/agents/{agent_id}/users/{user_id}/conversations",
              headers={"Authorization": f"Bearer {api_key}"},
              params=params,
          )
          body = response.json()
          conversations.extend(body["data"])

          cursor = body["pagination"]["cursor"]
          if not cursor:
              break

      return conversations
  ```
</CodeGroup>

## Full Example

<Steps>
  <Step title="Start a conversation with a user ID">
    Send the first message with a `userId` to associate the conversation:

    ```bash theme={null}
    curl -N -X POST 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat' \
      -H 'Authorization: Bearer YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
        "message": "What is quantum computing?",
        "stream": true,
        "userId": "user_abc123"
      }'
    ```

    Save the `conversationId` from the `finish` event.
  </Step>

  <Step title="Send a follow-up message">
    Continue the conversation by passing the `conversationId`:

    ```bash theme={null}
    curl -N -X POST 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat' \
      -H 'Authorization: Bearer YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
        "message": "How does it differ from classical computing?",
        "stream": true,
        "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
      }'
    ```
  </Step>

  <Step title="List the user's conversations">
    Retrieve all conversations for the user:

    ```bash theme={null}
    curl 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/users/user_abc123/conversations?limit=20' \
      -H 'Authorization: Bearer YOUR_API_KEY'
    ```
  </Step>
</Steps>

## Exporting All Conversations

The [Export conversations](/docs/api-v2/conversations/export-conversations) endpoint returns **all conversations with full message history**, regardless of source. This is different from the list endpoints above, which only return API-created conversations.

### Key differences from list endpoints

|                     | List conversations           | Export conversations                         |
| ------------------- | ---------------------------- | -------------------------------------------- |
| **Sources**         | API-only                     | All (Widget, WhatsApp, Messenger, API, etc.) |
| **Messages**        | Not included (metadata only) | Full message history included                |
| **Tool results**    | Not included (metadata only) | Sanitized — internal data stripped           |
| **Tool call input** | Not included (metadata only) | Omitted (not useful for export consumers)    |

### Conversation sources

Exported conversations include a `source` field indicating where the conversation originated:

`API`, `WhatsApp`, `Messenger`, `Instagram`, `Slack`, `Salesforce`, `Zendesk`, `Zendesk Messaging`, `Widget or Iframe`, `Iframe`, `Email`, `Agent page`, `Phone`, `Android SDK`, `iOS SDK`, `Chatbase site`, `Playground`, and others.

### Message format

Each conversation includes a `messages` array. Messages contain `parts`, which can be:

| Part type     | Fields                                     | Description                                                    |
| ------------- | ------------------------------------------ | -------------------------------------------------------------- |
| `text`        | `type`, `text`                             | Text content from the user or assistant                        |
| `tool-call`   | `type`, `toolCallId`, `toolName`           | A tool invocation by the agent (`input` is omitted in exports) |
| `tool-result` | `type`, `toolCallId`, `toolName`, `output` | The sanitized result of a tool invocation                      |

### Tool result output shape

All tool results in the export follow a unified shape, so you can handle them with a single `switch` on `status`:

| Status    | Shape                                 | Description                                                                        |
| --------- | ------------------------------------- | ---------------------------------------------------------------------------------- |
| `success` | `{ status: "success", data?: <T> }`   | Tool completed successfully. `data` is present when there is a meaningful payload. |
| `error`   | `{ status: "error", error?: string }` | Tool encountered an error.                                                         |
| `pending` | `{ status: "pending" }`               | Tool execution is still in progress.                                               |
| `ignored` | `{ status: "ignored" }`               | Tool was skipped by the user.                                                      |

### Example response

```json theme={null}
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "title": "Order status inquiry",
      "createdAt": 1770681600,
      "updatedAt": 1770681900,
      "userId": "user_abc123",
      "source": "WhatsApp",
      "status": "ended",
      "messages": [
        {
          "id": "msg_001",
          "role": "user",
          "parts": [
            { "type": "text", "text": "What's the status of my order?" }
          ],
          "createdAt": 1770681600
        },
        {
          "id": "msg_002",
          "role": "assistant",
          "parts": [
            { "type": "text", "text": "Let me look that up for you." },
            {
              "type": "tool-call",
              "toolCallId": "call_abc123",
              "toolName": "lookupOrder"
            },
            {
              "type": "tool-result",
              "toolCallId": "call_abc123",
              "toolName": "lookupOrder",
              "output": { 
                "status": "success", 
                "data": { "orderId": "ORD-123", "shipped": true }
              }
            },
            { "type": "text", "text": "Your order ORD-123 has been shipped!" }
          ],
          "createdAt": 1770681605,
          "feedback": "positive",
          "metadata": { "score": 0.95 }
        }
      ]
    }
  ],
  "pagination": {
    "cursor": "eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMC4wMDBaIiwiaWQiOiJhYmMxMjMifQ==",
    "hasMore": true,
    "total": 1250
  }
}
```

### Paginating through all exports

<CodeGroup>
  ```javascript Node.js theme={null}
  async function exportAllConversations(agentId, apiKey) {
    const conversations = [];
    let cursor = undefined;

    do {
      const params = new URLSearchParams({ limit: "100" });
      if (cursor) params.set("cursor", cursor);

      const response = await fetch(
        `https://www.chatbase.co/api/v2/agents/${agentId}/conversations/export?${params}`,
        {
          headers: { Authorization: `Bearer ${apiKey}` },
        }
      );

      const { data, pagination } = await response.json();
      conversations.push(...data);
      cursor = pagination.cursor;
    } while (cursor);

    return conversations;
  }
  ```

  ```python Python theme={null}
  import requests

  def export_all_conversations(agent_id: str, api_key: str):
      conversations = []
      cursor = None

      while True:
          params = {"limit": 100}
          if cursor:
              params["cursor"] = cursor

          response = requests.get(
              f"https://www.chatbase.co/api/v2/agents/{agent_id}/conversations/export",
              headers={"Authorization": f"Bearer {api_key}"},
              params=params,
          )
          body = response.json()
          conversations.extend(body["data"])

          cursor = body["pagination"]["cursor"]
          if not cursor:
              break

      return conversations
  ```
</CodeGroup>

<Tip>
  The export endpoint can return large amounts of data. Use a smaller `limit` (e.g., 20) if you're processing messages as they arrive rather than collecting everything in memory.
</Tip>

## Related

<CardGroup>
  <Card title="Streaming" icon="bolt" href="/api-v2/streaming">
    Learn about streaming responses and event types.
  </Card>

  <Card title="Pagination" icon="arrow-right" href="/api-v2/pagination">
    How cursor-based pagination works across all list endpoints.
  </Card>

  <Card title="Export Conversations" icon="download" href="/api-v2/conversations/export-conversations">
    Full API reference for the export endpoint.
  </Card>

  <Card title="Client Actions" icon="bolt" href="/api-v2/client-actions">
    How tool calls and tool results work in conversations.
  </Card>
</CardGroup>


# REST API Integration
Source: https://chatbase.co/docs/developer-guides/api-integration

Complete guide to integrating Chatbase AI Agents using our REST API for custom integrations and applications.

<Note>
  **Looking for API v2?** The new Chatbase API v2 features structured error codes, cursor-based pagination, and SSE streaming. Note that API v2 is available starting from the Standard Plan. [Check out the API v2 Reference →](/docs/api-v2/overview)
</Note>

## Overview

The Chatbase REST API enables you to integrate AI-powered conversations into any application or workflow. Build custom chat experiences, automate customer interactions, and manage your AI agents programmatically.

<CardGroup>
  <Card title="Send Messages" icon="message-dots">
    Chat with your AI agents and handle real-time streaming responses
  </Card>

  <Card title="Manage Agents" icon="robot">
    Create, configure, and update AI agents with custom training data
  </Card>

  <Card title="Access Data" icon="database">
    Retrieve conversations, leads, and analytics from your AI interactions
  </Card>
</CardGroup>

## Quick Start

<Steps>
  <Step title="Get Your API Key">
    <Frame>
      <img alt="Creating API key in Chatbase dashboard" />
    </Frame>

    1. Visit your [Chatbase Dashboard](https://www.chatbase.co/dashboard)
    2. Navigate to **Workspace Settings** → **API Keys**
    3. Click **Create API Key** and copy the generated key

    <Warning>
      Store your API key securely and never expose it in client-side code.
    </Warning>
  </Step>

  <Step title="Get Your Agent ID">
    <Frame>
      <img alt="Finding Agent ID in Chatbase settings" />
    </Frame>

    1. Select your AI Agent in the dashboard
    2. Go to **Settings** → **General**
    3. Copy the **Chatbot ID** (UUID format)
  </Step>

  <Step title="Send Your First Message">
    Test your integration with a simple chat request:

    ```bash theme={null}
    curl -X POST 'https://www.chatbase.co/api/v1/chat' \
      -H 'Authorization: Bearer YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
        "messages": [{"content": "Hello! How can you help me?", "role": "user"}],
        "chatbotId": "your-chatbot-id-here"
      }'
    ```

    **Expected Response:**

    ```json theme={null}
    {
      "text": "Hello! I'm here to help answer your questions and assist with any information you need. What can I help you with today?"
    }
    ```
  </Step>
</Steps>

### Chat API Streaming

The [chat API](/docs/api-reference/chat) supports real-time streaming responses for better user experience.

<CodeGroup>
  ```javascript Node.js theme={null}
  // streamer.js

  const axios = require('axios')
  const {Readable} = require('stream')

  const apiKey = '<Your-Secret-Key>'
  const chatId = '<Your Chatbot ID>'
  const apiUrl = 'https://www.chatbase.co/api/v1/chat'

  const messages = [{content: '<Your query here>', role: 'user'}]

  const authorizationHeader = `Bearer ${apiKey}`

  async function readChatbotReply() {
    try {
      const response = await axios.post(
        apiUrl,
        {
          messages,
          chatId,
          stream: true,
          temperature: 0,
        },
        {
          headers: {
            Authorization: authorizationHeader,
            'Content-Type': 'application/json',
          },
          responseType: 'stream',
        }
      )

      const readable = new Readable({
        read() {},
      })

      response.data.on('data', (chunk) => {
        readable.push(chunk)
      })

      response.data.on('end', () => {
        readable.push(null)
      })

      const decoder = new TextDecoder()
      let done = false

      readable.on('data', (chunk) => {
        const chunkValue = decoder.decode(chunk)

        // Process the chunkValue as desired
        // Here we just output it as in comes in without \n
        process.stdout.write(chunkValue)
      })

      readable.on('end', () => {
        done = true
      })
    } catch (error) {
      console.log('Error:', error.message)
    }
  }

  readChatbotReply()
  ```

  ```python Python theme={null}
  ## streamer.py

  import requests

  api_url = 'https://www.chatbase.co/api/v1/chat'
  api_key = '<Your-Secret-Key>'
  chat_id = '<Your Chatbot ID>'

  messages = [
      { 'content': '<Your query here>', 'role': 'user' }
  ]

  authorization_header = f'Bearer {api_key}'

  def read_chatbot_reply():
      try:
          headers = {
              'Authorization': authorization_header,
              'Content-Type': 'application/json'
          }

          data = {
              'messages': messages,
              'chatId': chat_id,
              'stream': True,
              'temperature': 0
          }

          response = requests.post(api_url, json=data, headers=headers, stream=True)
          response.raise_for_status()

          decoder = response.iter_content(chunk_size=None)
          for chunk in decoder:
              chunk_value = chunk.decode('utf-8')
              print(chunk_value, end='', flush=True)

      except requests.exceptions.RequestException as error:
          print('Error:', error)

  read_chatbot_reply()
  ```
</CodeGroup>

## Performance Best Practices

<Tip>
  **Optimization Strategies:**

  * Use streaming for chat responses to improve perceived performance
  * Cache agent responses when appropriate
  * Batch multiple operations when possible
  * Monitor and optimize conversation context length
</Tip>

## 🚀 Try It Live!

Ready to see the magic in action? Dive straight into our interactive playground where you can test every API endpoint, experiment with real responses, and build your integration in real-time.

<CardGroup>
  <Card title="🎮 Launch Interactive Playground" icon="play" href="/api-reference">
    Test APIs instantly • No setup required • Real-time responses • Copy working code snippets
  </Card>
</CardGroup>

### Key API Endpoints

<CardGroup>
  <Card title="Chat API" icon="message-dots" href="/api-reference/chat/chat-with-a-chatbot">
    Send messages and receive AI responses with streaming support
  </Card>

  <Card title="Agent Management" icon="robot" href="/api-reference/chatbots/create-a-new-chatbot">
    Create, update, and configure AI agents programmatically
  </Card>

  <Card title="Conversations" icon="messages" href="/api-reference/conversations/get-conversations-for-a-chatbot">
    Access chat history and conversation analytics
  </Card>

  <Card title="Contacts" icon="users" href="/api-reference/contacts/create-contacts-for-a-chatbot">
    Create and manage contacts for your AI agents
  </Card>
</CardGroup>


# Event Listeners
Source: https://chatbase.co/docs/developer-guides/chatbot-event-listeners

Listen for and respond to real-time chat events including user messages, AI responses, custom actions, and more to create interactive experiences.

Event listeners allow you to monitor and react to everything happening in your AI Agent conversations. From user messages to custom actions, you can build rich, interactive experiences that respond dynamically to user interactions.

## Why Use Event Listeners?

<AccordionGroup>
  <Accordion title="Custom User Experiences">
    Create dynamic, responsive interactions:

    * Show contextual information based on conversation topic
    * Trigger UI changes based on user messages
    * Provide visual feedback for AI responses
    * Integrate chat with other page elements
  </Accordion>

  <Accordion title="Third-party Integrations">
    Connect your chat with external systems:

    * Send data to CRM or analytics platforms
    * Trigger email campaigns or notifications
    * Update user profiles or preferences
    * Sync conversation data with support systems
  </Accordion>
</AccordionGroup>

### Prerequisites

<Info>
  A website with the Chatbase embed script already installed and working.
  New to Chatbase? Check out [Your First Agent](/docs/user-guides/quick-start/your-first-agent) to get started with the embed script first.
</Info>

## Available Events

Listen for these events to monitor and respond to chat activity:

<Tabs>
  <Tab title="Message Events">
    **Track conversation flow**

    <ParamField type="event">
      Triggered when a user sends a message

      **Payload:** `{ data: { content: string }, type: "user-message" }`\
      **Use cases:** Analytics, message validation, auto-suggestions
    </ParamField>

    <ParamField type="event">
      Triggered when your AI Agent responds

      **Payload:** `{ data: { content: string }, type: "assistant-message" }`\
      **Use cases:** UI updates, satisfaction surveys, follow-up actions
    </ParamField>

    ```javascript theme={null}
    // Example: Track conversation topics
    window.chatbase.addEventListener('user-message', (event) => {
      console.log('User asked:', event.data.content);
      
      // Track in analytics
      analytics.track('Chat Message Sent', {
        message_length: event.data.content.length,
        timestamp: new Date().toISOString()
      });
    });

    window.chatbase.addEventListener('assistant-message', (event) => {
      console.log('AI responded:', event.data.content);
      
      // Show satisfaction survey after response
      if (event.data.content.includes('solution') || event.data.content.includes('help')) {
        showSatisfactionSurvey();
      }
    });
    ```
  </Tab>

  <Tab title="Action Events">
    **Monitor custom actions and tools**

    <ParamField type="event">
      Triggered when a custom action or tool is called

      **Payload:** `{ data: { args: object, id: string, name: string, type: string }, type: 'tool-call' }`\
      **Use cases:** Backend API calls, form submissions, third-party integrations
    </ParamField>

    <ParamField type="event">
      Triggered when a tool returns results

      **Payload:** `{ data: { name: string, result: object, toolCallId: string, type: string }, type: 'tool-result' }`\
      **Use cases:** UI updates, error handling, success notifications
    </ParamField>

    ```javascript theme={null}
    // Example: Handle custom actions
    window.chatbase.addEventListener('tool-call', (event) => {
      console.log('Tool called:', event.data.name, event.data.args);
      
      if (event.data.name === 'schedule-meeting') {
        // Show calendar widget
        showCalendarWidget(event.data.args.preferredTime);
      } else if (event.data.name === 'get-pricing') {
        // Track pricing interest
        analytics.track('Pricing Inquiry', event.data.args);
      }
    });

    window.chatbase.addEventListener('tool-result', (event) => {
      if (event.data.name === 'schedule-meeting' && event.data.result.success) {
        // Show confirmation message
        showNotification('Meeting scheduled successfully!');
      }
    });
    ```
  </Tab>
</Tabs>

## Basic Event Listener Usage

### Adding Event Listeners

Add event listeners using the simple syntax:

```javascript theme={null}
window.chatbase.addEventListener(eventName, callbackFunction);
```

<ParamField type="enum">
  Must be one of the event names listed in Available Event Types.
</ParamField>

<ParamField type="function">
  Function to be called when the event is fired. The event payload is passed as an argument.
</ParamField>

### Removing Event Listeners

Remove listeners when they're no longer needed to prevent memory leaks:

<CodeGroup>
  ```javascript Basic Removal theme={null}
  // Store reference to callback function
  const myEventHandler = (event) => {
    console.log('Event received:', event);
  };

  // Add listener
  window.chatbase.addEventListener('user-message', myEventHandler);

  // Remove listener later
  window.chatbase.removeEventListener('user-message', myEventHandler);
  ```

  ```javascript React Component Example theme={null}
  // In React, clean up listeners on unmount
  useEffect(() => {
    const handleUserMessage = (event) => {
      setLastMessage(event.data.content);
    };
    
    window.chatbase.addEventListener('user-message', handleUserMessage);
    
    // Cleanup on unmount
    return () => {
      window.chatbase.removeEventListener('user-message', handleUserMessage);
    };
  }, []);
  ```
</CodeGroup>

## Event Management Best Practices

## Troubleshooting

<AccordionGroup>
  <Accordion title="Events Not Firing">
    **Problem:** Event listeners aren't being called

    **Solutions:**

    * **Check script loading**: Verify that the Chatbase embed script has loaded completely before adding event listeners. The `window.chatbase` object should be available.

    * **Verify event names**: Double-check that you're using the correct event names. Valid events include: `user-message`, `assistant-message`, `tool-call`, and `tool-result`. Typos in event names will prevent listeners from firing.

    * **Check browser console**: Look for JavaScript errors that might prevent your listener functions from being registered or executed properly.
  </Accordion>

  <Accordion title="Memory Leaks">
    **Problem:** Application slowing down over time

    **Solutions:**

    * **Remove unused listeners**: Always remove event listeners when they're no longer needed using `removeEventListener` with the same function reference used in `addEventListener`.

    * **Clean up on page unload**: Remove all event listeners before the user navigates away from the page to prevent memory leaks in single-page applications.

    * **Handle route changes**: In single-page applications, ensure you clean up event listeners when routes change, not just on full page reloads.

    * **Use cleanup patterns**: Create cleanup functions that remove all your event listeners and call them at appropriate lifecycle points in your application.
  </Accordion>

  <Accordion title="Handler Function Issues">
    **Problem:** removeEventListener not working

    **Solutions:**

    * **Avoid inline functions**: Don't use anonymous or inline functions as event handlers if you need to remove them later. Inline functions create new function references each time, making them impossible to remove.

    * **Store function references**: Create named functions or store function references in variables before passing them to `addEventListener`. Use the same reference when calling `removeEventListener`.

    * **Test removal**: Verify that your event listeners are actually being removed by checking if they still fire after calling `removeEventListener`.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Custom Initial Messages" icon="message" href="/developer-guides/custom-initial-messages">
    Create dynamic, personalized initial messages for users
  </Card>

  <Card title="Floating Initial Messages" icon="bullhorn" href="/developer-guides/floating-initial-messages">
    Display floating messages over the chat bubble
  </Card>
</CardGroup>


# Client-Side Custom Actions
Source: https://chatbase.co/docs/developer-guides/client-side-custom-actions

Execute custom actions directly in your user's browser with full control and seamless integration

Client-side custom actions allow you to execute code directly in your user's browser, giving you complete control over the execution environment and enabling seamless integration with your existing frontend systems.

## Benefits of Client-Side Actions

<CardGroup>
  <Card title="Direct Integration" icon="puzzle-piece">
    Integrate seamlessly with your existing frontend architecture and user systems
  </Card>

  <Card title="User Context Access" icon="user">
    Access user-specific information and browser APIs not available on the server
  </Card>

  <Card title="Enhanced User Experience" icon="star">
    Create interactive, responsive experiences with immediate feedback and smooth workflows
  </Card>

  <Card title="Frontend Control" icon="code">
    Use your existing authentication, state management, and API integration patterns
  </Card>
</CardGroup>

## How Client-Side Actions Work

When a user interacts with your chatbot and triggers a client-side action:

1. The Agent sends an event to your website window with action details
2. Your registered tool function executes in the browser
3. The result is sent back to the Agent
4. The conversation continues with the action response

## Setup Guide

### Prerequisites

<Info>
  A website with the Chatbase embed script already installed and working.
  New to Chatbase? Check out [Your First Agent](/docs/user-guides/quick-start/your-first-agent) to get started with the embed script first.
</Info>

<Steps>
  <Step title="Create Your Custom Action">
    Create a new custom action in your Chatbase dashboard:

    1. Go to Chatbase dashboard [dashboard](https://chatbase.co/dashboard) page
    2. Select the agent you want to create the custom action for
    3. Navigate to **Actions** → **Create action** → **Custom action**
    4. Fill in the action details:
       * **Name**: A unique identifier (e.g., `get_weather`)
       * **Description**: What the action does
       * **Parameters**: Define any data needed to have the Agent collect from the user
    5. **Important**: Select **"Client"** as the action type to enable client-side execution
    6. Click on the **Save and Continue** button and enable the action.

    <Frame>
      <img alt="Custom action form" />
    </Frame>
  </Step>

  <Step title="Register Your Action Functions">
    Use the `registerTools` method to provide the actual implementation for your actions:

    ```javascript theme={null}
    window.chatbase("registerTools", {
      get_weather: async (args, user) => {
        try {
          // Access the parameters defined in your action configuration
          const { location } = args;
          
          // Make API requests to your backend
          const response = await fetch(`/api/weather?location=${location}`);

          if (!response.ok) {
            throw new Error('Failed to fetch weather data');
          }

          const weatherData = await response.json();

          return {
            status: "success",
            data: {
              temperature: weatherData.temperature,
              condition: weatherData.condition,
              location: location
            }
          };
        } catch (error) {
          return {
            status: "error",
            error: error.message
          };
        }
      },

      send_notification: async (args, user) => {
        try {
          // Show a simple alert with data collected from the user by the Ai agent
          alert(`${args.title}\n\n${args.message}`);
          
          return {
            status: "success",
            data: "Alert shown successfully"
          };
        } catch (error) {
          return {
            status: "error",
            error: "Failed to show alert"
          };
        }
      }
    });
    ```

    <Tip>
      Register all your tools in a single `registerTools` call. Multiple calls will override previously registered tools.
    </Tip>

    <Warning>
      The action names created in the dashboard must exactly match the function names you register with `registerTools`.
    </Warning>
  </Step>
</Steps>

## Function Parameters

Every client-side action function receives two parameters:

<ParamField type="object">
  Contains all the parameters defined in your custom action configuration. The structure matches exactly what you defined in the dashboard.
</ParamField>

<ParamField type="object">
  Contains user information that varies depending on your identity verification setup.

  <Expandable title="When identity verification is properly configured">
    <ResponseField name="user_id" type="string">
      Unique identifier for the authenticated user as provided during the identify call.
    </ResponseField>

    <ResponseField name="user_hash" type="string">
      Hash of the user\_id used for verification (generated server-side).
    </ResponseField>

    <ResponseField name="anon_user_id" type="string">
      Internal anonymous user identifier. You can ignore this field.
    </ResponseField>

    <ResponseField name="chatbase_anon_id" type="string">
      Internal Chatbase anonymous identifier. You can ignore this field.
    </ResponseField>

    <ResponseField name="user_metadata" type="object">
      Custom user data passed during the identify call (e.g., name, email, company). This field is only present if metadata was provided during identification.
    </ResponseField>
  </Expandable>

  <Expandable title="When identity verification is not properly configured">
    <ResponseField name="anon_user_id" type="string">
      Internal anonymous user identifier. You can ignore this field.
    </ResponseField>

    <ResponseField name="chatbase_anon_id" type="string">
      Internal Chatbase anonymous identifier. You can ignore this field.
    </ResponseField>

    <ResponseField name="user_metadata" type="object">
      Custom user data passed during any identify calls. This field is only present if metadata was provided during identification.
    </ResponseField>
  </Expandable>
</ParamField>

<Note>
  The anonymous IDs (`anon_user_id` and `chatbase_anon_id`) are internal identifiers used by Chatbase and can be safely ignored in your custom form implementations.
</Note>

## Response Format

Your action functions must return responses in a specific format:

<Tabs>
  <Tab title="Success Response">
    When your action succeeds, return both `status` and `data`:

    ```javascript theme={null}
    {
      status: "success",
      data: responseData // Can be string, object, array, etc.
    }
    ```

    **Examples:**

    <CodeGroup>
      ```javascript Object Response theme={null}
      {
        status: "success",
        data: {
          temperature: 72,
          condition: "sunny",
          humidity: 45,
          forecast: ["Clear skies", "Light breeze"]
        }
      }
      ```

      ```javascript String Response   theme={null}
      {
        status: "success",
        data: "The weather in New York is currently 72°F and sunny with light winds."
      }
      ```

      ```javascript Array Response theme={null}
      {
        status: "success", 
        data: [
          { name: "Product 1", price: 29.99 },
          { name: "Product 2", price: 49.99 }
        ]
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Error Response">
    When an error occurs, return `status` and `error`:

    ```javascript theme={null}
    {
      status: "error",
      error: "Descriptive error message"
    }
    ```

    **Examples:**

    ```javascript theme={null}
    // API failure
    {
      status: "error",
      error: "Unable to connect to weather service. Please try again."
    }

    // Validation error
    {
      status: "error", 
      error: "Location parameter is required"
    }

    // Authentication error
    {
      status: "error",
      error: "User must be logged in to perform this action"
    }
    ```
  </Tab>
</Tabs>

## Advanced Examples

This example shows client-side actions utilizing the browser geolocation API to get the user's zip code.

<Frame>
  <img alt="Advanced example of a client-side action using the browser geolocation API" />
</Frame>

<CodeGroup>
  ```javascript Browser Integration theme={null}
  window.chatbase("registerTools", {
    get_zip_code: async (args, user) => {
      try {
        // Use browser geolocation API
        const position = await new Promise((resolve, reject) => {
          navigator.geolocation.getCurrentPosition(resolve, reject);
        });

        const { latitude, longitude } = position.coords;
        
        const response = await fetch(`/api/location-info?lat=${latitude}&lon=${longitude}`);
        const { zip_code } = await response.json();

        return {
          status: "success",
          data: {
            zip_code: zip_code,
          }
        };
      } catch (error) {
        return {
          status: "error",
          error: "Unable to access location information"
        };
      }
    }
  });
  ```
</CodeGroup>

<Frame>
  <img alt="Advanced example of a client-side action using the browser geolocation API result" />
</Frame>

## Best Practices

<AccordionGroup>
  <Accordion title="Error Handling">
    Always wrap your action logic in try-catch blocks and return meaningful error messages:

    ```javascript theme={null}
    window.chatbase("registerTools", {
      my_action: async (args, user) => {
        try {
          // Validate input parameters
          if (!args.requiredParam) {
            return {
              status: "error",
              error: "Required parameter is missing"
            };
          }

          // Your action logic here
          const result = await performAction(args);
          
          return {
            status: "success",
            data: result
          };
        } catch (error) {
          // Log for debugging.
          console.error('Action failed:', error);
          
          return {
            status: "error",
            error: "Action failed. Please try again."
          };
        }
      }
    });
    ```
  </Accordion>

  <Accordion title="Input Validation">
    Always validate user inputs and handle edge cases:

    ```javascript theme={null}
    window.chatbase("registerTools", {
      calculate_shipping: async (args, user) => {
        const { weight, destination, shippingMethod } = args;
        
        // Validate required parameters
        if (!weight || weight <= 0) {
          return {
            status: "error",
            error: "Valid weight is required"
          };
        }
        
        if (!destination || destination.length < 2) {
          return {
            status: "error", 
            error: "Valid destination is required"
          };
        }

        try {
          const result = await calculateShipping(weight, destination, shippingMethod);
          return { status: "success", data: result };
        } catch (error) {
          return { status: "error", error: "Shipping calculation failed" };
        }
      }
    });
    ```
  </Accordion>

  <Accordion title="Performance Optimization">
    * Cache frequently used data in browser storage
    * Use appropriate timeouts for external API calls
    * Minimize the size of returned data

    ```javascript theme={null}
    window.chatbase("registerTools", {
      get_cached_data: async (args, user) => {
        const cacheKey = `data_${args.type}`;
        const cached = localStorage.getItem(cacheKey);
        
        if (cached) {
          const { data, timestamp } = JSON.parse(cached);
          const isStale = Date.now() - timestamp > 300000; // 5 minutes
          
          if (!isStale) {
            return { status: "success", data };
          }
        }
        
        // Fetch fresh data if not cached or stale
        const freshData = await fetchData(args.type);
        localStorage.setItem(cacheKey, JSON.stringify({
          data: freshData,
          timestamp: Date.now()
        }));
        
        return { status: "success", data: freshData };
      }
    });
    ```
  </Accordion>
</AccordionGroup>

<Warning>
  **Environment Limitations**: Client-side custom forms will not function in:

  * Chatbase Playground environment
  * Action Preview mode
  * Compare features

  Testing this action should be done in your actual website environment. Embed the [JavaScript script](/docs/developer-guides/javascript-embed) in your website and test the action.
</Warning>

<Info>
  **Response Size Limits:** Keep your response data under reasonable size limits to ensure good performance. Very large responses may be truncated or cause timeouts.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Action Not Found Error">
    **Problem:** Console shows "Tool \[name] not found"

    **Solutions:**

    * Ensure action names match exactly between dashboard and `registerTools`
    * Check that `registerTools` is called after the chatbot loads
    * Verify the action is marked as "client-side" in dashboard
  </Accordion>

  <Accordion title="No Response from Action">
    **Problem:** Action executes but chatbot doesn't receive response

    **Solutions:**

    * Check browser console for JavaScript errors
    * Ensure you're returning the correct response format
    * Verify async functions are properly awaited
    * Check for uncaught exceptions in your action code
  </Accordion>

  <Accordion title="User Context Issues">
    **Problem:** User parameter is null when expected

    **Solutions:**

    * Verify [identity verification](/docs/developer-guides/identity-verification) is properly configured
    * Test with and without authenticated users in your implementation
    * Add fallback logic for when user context is unavailable
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Client-Side Custom Forms" icon="rectangle-list" href="/developer-guides/client-side-custom-forms">
    Add interactive forms and data collection to your chat
  </Card>

  <Card title="Widget Control" icon="sliders" href="/developer-guides/control-widget">
    Programmatically control the chat interface
  </Card>

  <Card title="Event Listeners" icon="ear" href="/developer-guides/chatbot-event-listeners">
    Learn to listen for and respond to chat events in real-time
  </Card>

  <Card title="Custom Initial Messages" icon="message" href="/developer-guides/custom-initial-messages">
    Create dynamic, personalized initial messages for users
  </Card>
</CardGroup>


# Client-Side Custom Forms
Source: https://chatbase.co/docs/developer-guides/client-side-custom-forms

Create dynamic, interactive forms in your chatbot using client-side JavaScript configuration

## Overview

Client-side custom forms enable you to create dynamic, interactive forms that run directly in the user's browser.

<Info>
  Server-side custom form configuration is not currently available. All custom forms must be configured using client-side JavaScript.
</Info>

### Key Benefits

* **Real-time validation**: Instant feedback as users fill out forms
* **Enhanced UX**: Smooth interactions without server round trips
* **Full customization**: Complete control over form appearance and behavior

### Prerequisites

<Info>
  A website with the Chatbase embed script already installed and working.
  New to Chatbase? Check out [Your First Agent](/docs/user-guides/quick-start/your-first-agent) to get started with the embed script first.
</Info>

## Setup Guide

<Steps>
  <Step title="Create your custom form action">
    Set up the form configuration in your Chatbase dashboard:

    1. Navigate to **Actions** → **Create action** → **Custom form**

    <Frame>
      <img alt="Custom form creation interface" />
    </Frame>

    2. Enter a unique name for your form.
    3. Configure the form when to use.
    4. Click on the **Save and Continue** button.
    5. Enable the action.

    <Frame>
      <img alt="Custom form when to use interface" />
    </Frame>

    <Warning>
      **Environment Limitations**: Client-side custom forms will not function in:

      * Chatbase Playground environment
      * Action Preview mode
      * Compare features

      Testing this action should be done in your actual website environment. Embed the [JavaScript script](/docs/developer-guides/javascript-embed) in your website and test the action.
    </Warning>
  </Step>

  <Step title="Register your form schema">
    On your website, register your form schema by calling the `registerFormSchema` method anywhere in your JavaScript code, with the name of the action you created in the dashboard.

    <Tip>
      Register the form in a root page of your website, or in a component that is loaded on every page.
    </Tip>

    ```javascript theme={null}
    window.chatbase.registerFormSchema({
    "learn_more_form": async (args, user) => {
      return {
        fields: [
          {
            name: "name",
            label: "Full Name",
            type: "text",
            placeholder: "Enter your full name",
            validation: {
              required: {
                value: true,
                message: "Name is required"
              }
            }
          },
          {
            name: "email",
            label: "Email Address", 
            type: "email",
            placeholder: "Enter your email",
            validation: {
              required: {
                value: true,
                message: "Email is required"
              }
            }
          },
          {
            name: "message",
            label: "Message",
            type: "textarea",
            placeholder: "How can we help you?",
            validation: {
              required: {
                value: true,
                message: "Please enter your message"
              }
            }
          }
        ],
        submitButtonText: "Send Message",
        successMessage: "Thank you! We'll get back to you soon.",
        errorMessage: "Failed to send message. Please try again."
      };
    }
    });
    ```

    <Warning>
      **Multiple Registration Override**: Calling `registerFormSchema` multiple times will completely replace all previously registered forms. Always include all your forms in a single registration call.
    </Warning>

    <Frame>
      <video />
    </Frame>

    <Check>
      Your custom form is now ready to use! The chatbot will automatically display your form when the corresponding action is triggered.
    </Check>
  </Step>

  <Step title="Webhooks (Optional)">
    You can also configure webhooks to receive real-time notifications when users submit your custom forms. For detailed configuration instructions, see [Webhooks Integration](#webhooks-integration).

    <Frame>
      <img alt="Webhook configuration interface" />
    </Frame>
  </Step>
</Steps>

## Function Parameters

Each custom form function receives two parameters that provide context and data:

<ParamField type="object">
  Contains all the arguments defined in your custom form configuration. These are the values the ai agent generated and passed from the AI action when the form is triggered.

  <Frame>
    <img alt="Custom form args interface" />
  </Frame>
</ParamField>

<ParamField type="object">
  Contains user information that varies depending on your identity verification setup.

  <Expandable title="When identity verification is properly configured">
    <ResponseField name="user_id" type="string">
      Unique identifier for the authenticated user as provided during the identify call.
    </ResponseField>

    <ResponseField name="user_hash" type="string">
      Hash of the user\_id used for verification (generated server-side).
    </ResponseField>

    <ResponseField name="anon_user_id" type="string">
      Internal anonymous user identifier. You can ignore this field.
    </ResponseField>

    <ResponseField name="chatbase_anon_id" type="string">
      Internal Chatbase anonymous identifier. You can ignore this field.
    </ResponseField>

    <ResponseField name="user_metadata" type="object">
      Custom user data passed during the identify call (e.g., name, email, company). This field is only present if metadata was provided during identification.
    </ResponseField>
  </Expandable>

  <Expandable title="When identity verification is not properly configured">
    <ResponseField name="anon_user_id" type="string">
      Internal anonymous user identifier. You can ignore this field.
    </ResponseField>

    <ResponseField name="chatbase_anon_id" type="string">
      Internal Chatbase anonymous identifier. You can ignore this field.
    </ResponseField>

    <ResponseField name="user_metadata" type="object">
      Custom user data passed during any identify calls. This field is only present if metadata was provided during identification.
    </ResponseField>
  </Expandable>

  <Note>
    The anonymous IDs (`anon_user_id` and `chatbase_anon_id`) are internal identifiers used by Chatbase and can be safely ignored in your custom form implementations.
  </Note>
</ParamField>

## Complete Example

Here's a comprehensive example showing a user profile form with various field types and validation rules:

<Warning>
  The function name in your JavaScript code (e.g., `userProfileForm`) must exactly match the name you assign to your AI Action in the Chatbase dashboard.
</Warning>

```javascript userProfileForm.js theme={null}
window.chatbase.registerFormSchema({
  userProfileForm: async (args, user) => {
    // Pre-populate form with user data if available
    const defaultName = user?.user_metadata?.name || args.name || '';
    const defaultEmail = user?.user_metadata?.email || '';
    
    return {
      fields: [
        {
          name: "name",
          label: "First Name",
          type: "text",
          defaultValue: defaultName,
          placeholder: "Enter your first name",
          validation: {
            required: {
              value: true,
              message: "Name is required"
            },
            minLength: {
              value: 2,
              message: "Name must be at least 2 characters"
            },
            maxLength: {
              value: 50,
              message: "Name cannot exceed 50 characters"
            }
          }
        },
        {
          name: "email",
          label: "Email Address",
          type: "email",
          defaultValue: defaultEmail,
          validation: {
            required: {
              value: true,
              message: "Email is required"
            },
            pattern: {
              value: "^[^\s@]+@[^\s@]+\.[^\s@]+$",
              message: "Please enter a valid email address"
            }
          }
        },
        {
          name: "officeLocation",
          type: "groupselect",
          label: "Office Location",
          options: {
            "North America": [
              { value: "nyc", label: "New York City" },
              { value: "sf", label: "San Francisco" },
              { value: "toronto", label: "Toronto" }
            ],
            "Europe": [
              { value: "london", label: "London" },
              { value: "berlin", label: "Berlin" },
              { value: "paris", label: "Paris" }
            ],
            "Asia Pacific": [
              { value: "tokyo", label: "Tokyo" },
              { value: "singapore", label: "Singapore" }
            ]
          },
          validation: {
            required: {
              value: true,
              message: "Please select your office location"
            }
          }
        },
        {
          name: "skills",
          type: "multiselect",
          label: "Technical Skills",
          options: [
            { value: "javascript", label: "JavaScript" },
            { value: "python", label: "Python" },
            { value: "react", label: "React" },
            { value: "nodejs", label: "Node.js" },
            { value: "sql", label: "SQL" }
          ]
        },
        {
          name: "bio",
          label: "Bio",
          type: "textarea",
          placeholder: "Tell us about yourself...",
          validation: {
            maxLength: {
              value: 500,
              message: "Bio cannot exceed 500 characters"
            }
          }
        },
        {
          name: "profileImage",
          label: "Profile Image",
          type: "image",
          placeholder: "Click or drop your profile image here"
        }
      ],
      submitButtonText: "Update Profile",
      showLabels: true,
      successMessage: "Profile updated successfully!",
      errorMessage: "Failed to update profile. Please try again."
    };
  }
});
```

<Frame>
  <img alt="Example custom form in chatbot interface" />
</Frame>

## API Reference

### Form Schema

The `registerFormSchema` function returns a schema object that defines your form's structure and behavior:

<ResponseField name="fields" type="array">
  Array of form field definitions. Each field must conform to the Field Schema specifications below.
</ResponseField>

<ResponseField name="submitButtonText" type="string">
  Text displayed on the form's submit button.
</ResponseField>

<ResponseField name="showLabels" type="boolean">
  Controls whether field labels are displayed above form inputs.
</ResponseField>

<ResponseField name="successMessage" type="string">
  Message shown to users when the form is successfully submitted.
</ResponseField>

<ResponseField name="errorMessage" type="string">
  Message displayed when form submission fails.
</ResponseField>

### Field Schema

Each field in the `fields` array supports the following properties:

<ResponseField name="name" type="string">
  Unique identifier for the form field. This name is used to reference the field's value in form submissions.
</ResponseField>

<ResponseField name="type" type="string">
  Specifies the input type. Must be one of the supported field types listed below.
</ResponseField>

<ResponseField name="label" type="string">
  Display text shown to users for this field.
</ResponseField>

<ResponseField name="placeholder" type="string">
  Placeholder text displayed inside the input field. If not provided, the label text is used as placeholder.
</ResponseField>

<ResponseField name="defaultValue" type="any">
  Pre-filled value for the field. Type depends on the field type (string for text, number for numeric fields, etc.).
</ResponseField>

<ResponseField name="disabled" type="boolean">
  Whether the field should be read-only and non-interactive.
</ResponseField>

<ResponseField name="validation" type="object">
  Validation rules for the field. See Validation Rules section below for detailed specifications.
</ResponseField>

<ResponseField name="options" type="array | object">
  Required for selection fields (`select`, `multiselect`, `groupselect`, `groupmultiselect`).

  <Expandable title="Options format by field type">
    **For `select` and `multiselect`**: Array of objects with `label` and `value` properties:

    ```javascript theme={null}
    options: [
      { value: "option1", label: "Option 1" },
      { value: "option2", label: "Option 2" }
    ]
    ```

    **For `groupselect` and `groupmultiselect`**: Object where keys are group names and values are arrays of options:

    ```javascript theme={null}
    options: {
      "Group 1": [
        { value: "item1", label: "Item 1" },
        { value: "item2", label: "Item 2" }
      ],
      "Group 2": [
        { value: "item3", label: "Item 3" }
      ]
    }
    ```
  </Expandable>
</ResponseField>

### Field Types

<AccordionGroup>
  <Accordion title="Text Input Fields">
    **`text`** - Single-line text input

    * Supports: `required`, `minLength`, `maxLength`, `pattern` validation
    * Best for: Names, titles, short descriptions

    **`textarea`** - Multi-line text input

    * Supports: `required`, `minLength`, `maxLength` validation
    * Best for: Comments, descriptions, long-form text

    **`email`** - Email address input with built-in format validation

    * Supports: `required`, `pattern` validation
    * Automatically validates email format

    **`phone`** - Phone number input

    * Must follow format: `+[country code][number]` (e.g., +1234567890)
    * Supports: `required`, `pattern` validation
    * Built-in international format validation
  </Accordion>

  <Accordion title="Numeric Fields">
    **`number`** - Numeric input

    * Supports: `required`, `min`, `max` validation
    * Only accepts numeric values
    * Best for: Ages, quantities, prices
  </Accordion>

  <Accordion title="Selection Fields">
    **`select`** - Single selection dropdown

    * Requires: `options` array with `{ value, label }` objects
    * Supports: `required` validation
    * Best for: Categories, single choice selections

    **`multiselect`** - Multiple selection dropdown

    * Requires: `options` array with `{ value, label }` objects
    * Supports: `required` validation
    * Best for: Tags, multiple choice selections

    **`groupselect`** - Grouped single selection dropdown

    * Requires: `options` object with group names as keys
    * Each group contains array of `{ value, label }` objects
    * Supports: `required` validation
    * Best for: Categorized options (e.g., locations by region)

    **`groupmultiselect`** - Grouped multiple selection dropdown

    * Requires: `options` object with group names as keys
    * Each group contains array of `{ value, label }` objects
    * Supports: `required` validation
    * Best for: Multiple selections from categorized options
  </Accordion>

  <Accordion title="File Upload Fields">
    **`image`** - Image file upload with drag & drop

    * Accepts: JPEG, JPG, PNG, GIF, WebP formats
    * Maximum size: 2MB per file
    * Supports: `required` validation
    * Features: Drag & drop, preview, format validation
  </Accordion>
</AccordionGroup>

### Validation Rules

Each validation rule is defined as an object with `value` and `message` properties:

<AccordionGroup>
  <Accordion title="Basic Validation">
    **`required`** - Makes field mandatory

    ```javascript theme={null}
    validation: {
      required: {
        value: true,
        message: "This field is required"
      }
    }
    ```

    **`pattern`** - Regex pattern validation

    ```javascript theme={null}
    validation: {
      pattern: {
        value: "^[A-Za-z]+$", // Only letters
        message: "Only letters are allowed"
      }
    }
    ```
  </Accordion>

  <Accordion title="Length Validation">
    **`minLength`** - Minimum character count

    ```javascript theme={null}
    validation: {
      minLength: {
        value: 3,
        message: "Must be at least 3 characters"
      }
    }
    ```

    **`maxLength`** - Maximum character count

    ```javascript theme={null}
    validation: {
      maxLength: {
        value: 100,
        message: "Cannot exceed 100 characters"
      }
    }
    ```
  </Accordion>

  <Accordion title="Numeric Validation">
    **`min`** - Minimum numeric value

    ```javascript theme={null}
    validation: {
      min: {
        value: 18,
        message: "Must be at least 18"
      }
    }
    ```

    **`max`** - Maximum numeric value

    ```javascript theme={null}
    validation: {
      max: {
        value: 120,
        message: "Cannot exceed 120"
      }
    }
    ```
  </Accordion>

  <Accordion title="Error Handling">
    **`defaultErrorMessage`** - Fallback error message

    ```javascript theme={null}
    validation: {
      min: { value: 18 }, // No custom message
      defaultErrorMessage: "Please enter a valid value"
    }
    ```

    This message is shown when validation fails but no specific message is provided for the failed rule.
  </Accordion>
</AccordionGroup>

## Advanced Configuration

### Webhooks Integration

Configure webhooks to receive real-time notifications when users submit your custom forms:

<Steps>
  <Step title="Access action settings">
    * In the action settings, click on the **Webhooks** tab.
    * Write the webhook URL and click on the **Create Wbhook** button.

    <Frame>
      <img alt="Webhook configuration interface" />
    </Frame>
  </Step>

  <Step title="Configure webhook endpoint">
    <Frame>
      <img alt="Webhook configuration interface" />
    </Frame>

    Set up your webhook endpoint to receive form submission data:

    ```javascript webhook-handler.js theme={null}
    // Example webhook handler (Node.js/Express)
    app.post('/form-webhook', (req, res) => {
      const { formData, userId, timestamp } = req.body;
      
      // Process the form submission
      console.log('Form submitted:', formData);
      
      // Respond with success
      res.status(200).json({ success: true });
    });
    ```
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Form not appearing in chatbot">
    **Possible causes:**

    * Function name mismatch between dashboard and code
    * Chatbase script not loaded before `registerFormSchema` call
    * JavaScript errors preventing form registration

    **Solutions:**

    1. Verify the function name matches exactly (case-sensitive)
    2. Ensure proper script loading order
    3. Check browser console for JavaScript errors
  </Accordion>

  <Accordion title="Validation not working properly">
    **Possible causes:**

    * Incorrect validation rule syntax
    * Missing required properties in validation objects

    **Solutions:**

    1. Ensure validation rules have both `value` and `message` properties
    2. Check field type compatibility with validation rules
    3. Verify regex patterns are valid JavaScript regex strings
  </Accordion>

  <Accordion title="Options not displaying for select fields">
    **Possible causes:**

    * Incorrect options format
    * Missing `options` property

    **Solutions:**

    1. Ensure options follow the correct format for your field type
    2. Verify all option objects have both `value` and `label` properties
    3. For grouped selections, check the nested object structure
  </Accordion>
</AccordionGroup>

<Tip>
  **Best Practices**:

  * Test your forms thoroughly in your actual website environment
  * Keep form schemas simple and focused on specific use cases
  * Use clear, descriptive field names and validation messages
  * Implement proper error handling for form submissions
</Tip>

## Next Steps

<CardGroup>
  <Card title="Widget Control" icon="sliders" href="/developer-guides/control-widget">
    Programmatically control the chat interface
  </Card>

  <Card title="Event Listeners" icon="ear" href="/developer-guides/chatbot-event-listeners">
    Learn to listen for and respond to chat events in real-time
  </Card>

  <Card title="Custom Initial Messages" icon="message" href="/developer-guides/custom-initial-messages">
    Create dynamic, personalized initial messages for users
  </Card>

  <Card title="Floating Initial Messages" icon="bullhorn" href="/developer-guides/floating-initial-messages">
    Display floating messages over the chat bubble
  </Card>
</CardGroup>


# Widget Control
Source: https://chatbase.co/docs/developer-guides/control-widget

Programmatically control your chat widget with JavaScript methods to open, close, and reset conversations.

The Chatbase embed script exposes the `window.chatbase` object with methods to control your chat widget programmatically.

## Methods

### open()

Opens the chat widget.

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

### close()

Closes the chat widget.

```javascript theme={null}
window.chatbase.close();
```

### resetChat()

Clears the current conversation and starts a new session.

```javascript theme={null}
window.chatbase.resetChat();
```

<Info>
  Your widget configuration and [custom initial
  messages](/docs/developer-guides/custom-initial-messages) are preserved after
  reset.
</Info>

## Examples

Combine these methods with [event listeners](/docs/developer-guides/chatbot-event-listeners) to build powerful, context-aware chat experiences.

### Custom Buttons

Trigger widget actions from your own UI elements:

```javascript theme={null}
document.getElementById("help-button").addEventListener("click", () => {
  window.chatbase.open();
});

document.getElementById("close-button").addEventListener("click", () => {
  window.chatbase.close();
});

document.getElementById("new-chat-button").addEventListener("click", () => {
  window.chatbase.resetChat();
});
```

### Time-Based Reset

<Note>
  The 24-hour example uses `localStorage` to persist the last message time
  across page reloads.
</Note>

<CodeGroup>
  ```javascript Reset After 5 Minutes of Inactivity theme={null}
  let inactivityTimer;

  function startInactivityTimer() {
    clearTimeout(inactivityTimer);
    inactivityTimer = setTimeout(
      () => window.chatbase.resetChat(),
      5 * 60 * 1000
    );
  }

  window.chatbase.addEventListener("user-message", startInactivityTimer);
  window.chatbase.addEventListener("assistant-message", startInactivityTimer);
  ```

  ```javascript Reset 24 Hours After Last Message theme={null}
  const STORAGE_KEY = "chatbase_last_message";
  const TWENTY_FOUR_HOURS = 24 * 60 * 60 * 1000;

  function updateLastMessageTime() {
    localStorage.setItem(STORAGE_KEY, Date.now().toString());
  }

  // Check on page load
  const lastMessage = localStorage.getItem(STORAGE_KEY);
  if (lastMessage && Date.now() - parseInt(lastMessage) > TWENTY_FOUR_HOURS) {
    window.chatbase.resetChat();
    updateLastMessageTime(); // Reset the timer after clearing
  }

  // Update timestamp on every message
  window.chatbase.addEventListener("user-message", updateLastMessageTime);
  window.chatbase.addEventListener("assistant-message", updateLastMessageTime);
  ```
</CodeGroup>

### Reset After Tool Completion

<CodeGroup>
  ```javascript After Transaction theme={null}
  let resetTimer;

  window.chatbase.addEventListener("tool-result", (event) => {
    const resetTools = ["complete-booking", "process-payment", "create-ticket"];

    if (resetTools.includes(event.data.name) && event.data.result?.success) {
      clearTimeout(resetTimer);
      // 2 second delay before resetting the chat
      resetTimer = setTimeout(() => window.chatbase.resetChat(), 2000);
    }
  });
  ```

  ```javascript After Support Ticket theme={null}
  let resetTimer;

  window.chatbase.addEventListener("tool-result", (event) => {
    if (event.data.name === "create-ticket") {
      clearTimeout(resetTimer);
      // 2 second delay before resetting the chat
      resetTimer = setTimeout(() => window.chatbase.resetChat(), 2000);
    }
  });
  ```
</CodeGroup>

### Reset on Keywords

<Warning>
  Always add a delay before resetting so users can read the final AI response.
</Warning>

<CodeGroup>
  ```javascript User Says Goodbye theme={null}
  let resetTimer;

  window.chatbase.addEventListener("user-message", (event) => {
    const goodbyePhrases = ["goodbye", "bye", "that's all", "start over"];
    const message = event.data.content.toLowerCase();

    // Use word boundaries to avoid matching substrings (e.g., "nearby" containing "bye")
    const matchesPhrase = goodbyePhrases.some((phrase) => {
      const regex = new RegExp(`\\b${phrase}\\b`);
      return regex.test(message);
    });

    if (matchesPhrase) {
      clearTimeout(resetTimer);
      // 2 second delay before resetting the chat
      resetTimer = setTimeout(() => window.chatbase.resetChat(), 2000);
    }
  });
  ```

  ```javascript AI Confirms Completion theme={null}
  let resetTimer;

  window.chatbase.addEventListener("assistant-message", (event) => {
    const donePhrases = ["order confirmed", "booking complete", "ticket created"];
    const message = event.data.content.toLowerCase();

    const matchesPhrase = donePhrases.some((phrase) => {
      const regex = new RegExp(`\\b${phrase}\\b`);
      return regex.test(message);
    });

    if (matchesPhrase) {
      clearTimeout(resetTimer);
      // 2 second delay before resetting the chat
      resetTimer = setTimeout(() => window.chatbase.resetChat(), 2000);
    }
  });
  ```
</CodeGroup>

### Reset on Navigation

Start fresh conversations when users enter specific sections of your site.

<CodeGroup>
  ```javascript Single-Page App theme={null}
  const resetOnRoutes = ["/checkout", "/new-project", "/support"];

  function checkRouteAndReset() {
    if (resetOnRoutes.includes(window.location.pathname)) {
      window.chatbase.resetChat();
    }
  }

  // Call this from your router's navigation callback
  // e.g., router.afterEach(checkRouteAndReset)
  checkRouteAndReset();
  ```

  ```javascript Multi-Page App theme={null}
  // Add this script to pages where you want fresh conversations
  window.chatbase.resetChat();
  ```
</CodeGroup>

## Best Practices

* **Debounce rapid calls** — Avoid calling methods in quick succession
* **Add delays before reset** — Give users time to read the final response
* **Respect dismissals** — Don't immediately reopen a closed widget
* **Use contextual triggers** — Open chat at moments when help is most relevant

## Next Steps

<CardGroup>
  <Card title="Event Listeners" icon="ear" href="/developer-guides/chatbot-event-listeners">
    Learn to listen for and respond to chat events in real-time
  </Card>

  <Card title="Custom Initial Messages" icon="message" href="/developer-guides/custom-initial-messages">
    Create dynamic, personalized initial messages for users
  </Card>

  <Card title="Floating Initial Messages" icon="bullhorn" href="/developer-guides/floating-initial-messages">
    Display floating messages over the chat bubble
  </Card>
</CardGroup>


# Custom Domains
Source: https://chatbase.co/docs/developer-guides/custom-domains

On this page, you can configure your AI agent to integrate with your own domain. This allows you to hide the Chatbase branding, making it appear as if the AI agent is built entirely by your workspace rather than using a third-party tool.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

To set this up, enter the desired URL for your bot, and then configure a DNS record with your provider. Common DNS providers include Cloudflare, OpenDNS, and Quad9.

You will need to add a CNAME record with the specific values provided on the custom domain page in your dashboard. Please note that it may take up to 6 hours for the records to fully propagate and update.

### What "Custom Domain" Means on Chatbase?

When we say you can add a custom domain, it means you can host your AI agent on a subdomain that belongs to your company or brand, instead of Chatbase's default domain. For example, instead of your AI agent appearing on a URL like chatbase.co/yourbot, it could be hosted on yourbot.yourdomain.com.

This feature enhances your brand's professionalism and trustworthiness by keeping everything under your domain.

By adding a custom subdomain:

1. Your AI agent becomes an integrated part of your website.
2. Visitors' traffic requests won't be redirected to an external Chatbase URL.
3. It improves the user experience with consistent branding across your website and AI agent interactions.

### Step-by-Step Guide to Adding a Custom Subdomain to Your AI agent on Chatbase

1. **Log Into Your Chatbase Account**\
   First, sign in to your Chatbase account using your credentials. If you don't have an account yet, you can easily create one by following the sign-up process on the website.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

2. **Navigate to Your AI agent Settings**\
   Once you're logged in, locate the AI agent you want to associate with a custom subdomain. This could be a newly created bot or an existing one.

   Open the settings tab for that specific AI agent. This is where you customize your bot's behavior, appearance, and technical configurations.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

3. **Locate the Domain Customization Option**\
   In the bottom left corner of the settings tab, look for "Custom Domain" and click on it.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

4. **Enter Your Custom Subdomain**\
   This is where you type in the subdomain (e.g., support.yourbusiness.com) that you own or have control over. Chatbase currently supports subdomains only, so you'll need to ensure you're using a subdomain on your website.

   Adding a custom subdomain gives your AI agent a professional look by branding it with your website's URL instead of Chatbase's default domain.

5. **Configure DNS Settings**\
   You might need to configure additional DNS settings like CNAME records. This step will link the custom subdomain to your AI agent, ensuring it works correctly when users visit the URL.

   Chatbase will provide specific DNS instructions for setting this up, which usually includes pointing the subdomain to Chatbase's servers.

6. **Save and Test Your AI agent**\
   Once you've successfully configured the domain settings and DNS records, save your changes.

   It may take some time for the changes to propagate across the web (usually within a few minutes to 24 hours).

   Test the custom subdomain by entering it into a browser to ensure your AI agent loads correctly.


# Custom Initial Messages
Source: https://chatbase.co/docs/developer-guides/custom-initial-messages

Create personalized welcome experiences by setting custom initial messages that greet users when your AI Agent first loads, with support for dynamic content and user personalization.

### Prerequisites

<Info>
  A website with the Chatbase embed script already installed and working.
  New to Chatbase? Check out [Your First Agent](/docs/user-guides/quick-start/your-first-agent) to get started with the embed script first.
</Info>

## Setting Up Custom Initial Messages

Configure initial messages using the JavaScript embed script to create personalized welcome experiences:

### Personalized Messages

Add user-specific content to your greetings by combining user identification with custom messages for personalized experiences:

```javascript theme={null}
// Get user information (from your auth system)
const user = getCurrentUser();

// Set personalized messages
window.chatbase.setInitialMessages([
  `Hi ${user.name}!`,
  "I remember our last conversation about your project.",
  "How can I help you today?"
]);
```

<Frame>
  <img alt="Personalized messages" />
</Frame>

### Dynamic Content Examples

Create context-aware messages based on user behavior or current page:

```javascript theme={null}
// Based on current page
const currentPage = window.location.pathname;
let messages = ["Hello! I'm here to help."];

if (currentPage.includes('/pricing')) {
  messages = [
    "Looking at our pricing?",
    "I can help you choose the right plan for your needs."
  ];
} else if (currentPage.includes('/support')) {
  messages = [
    "Need technical support?",
    "I'm here to help resolve any issues you're experiencing."
  ];
}

window.chatbase.setInitialMessages(messages);
```

## Method Reference

### setInitialMessages()

Set the messages displayed when the agent first loads:

<ParamField type="string[]">
  Array containing the messages to display in sequence

  **Requirements:**

  * Must be an array of strings
  * Total character count limited to 1000 characters
</ParamField>

<Warning>
  Custom initial messages are shown only once per session. If a user refreshes the page or navigates to another page during the same session, the messages won't appear again to avoid creating an intrusive experience.
</Warning>

## Best Practices

<AccordionGroup>
  <Accordion title="Message Content">
    **Write effective initial messages**

    * **Keep messages concise**: Use short, clear messages that guide users effectively
    * **Avoid lengthy paragraphs**: Break long content into multiple shorter messages
    * **Be specific**: Mention what you can help with rather than generic greetings
    * **Use action-oriented language**: Encourage users to engage with specific questions
  </Accordion>

  <Accordion title="Personalization Strategy">
    **Use user data thoughtfully**

    * **Respect privacy**: Only use information users have explicitly shared
    * **Add value**: Personalization should enhance the experience, not just show off data
    * **Handle missing data**: Always have fallback messages for when user data isn't available
    * **Test thoroughly**: Verify personalized messages work with different user states
  </Accordion>

  <Accordion title="Timing and Performance">
    **Optimize when messages are set**

    * **Set early**: Configure initial messages as soon as possible in your application lifecycle
    * **Wait for embed script**: Ensure Chatbase script has loaded before calling `setInitialMessages`
    * **Consider async operations**: If fetching user data, handle loading states gracefully
    * **Cache when appropriate**: Store computed messages to avoid recalculating on every visit
  </Accordion>
</AccordionGroup>


# Floating Initial Messages
Source: https://chatbase.co/docs/developer-guides/floating-initial-messages

Create eye-catching floating messages that appear above your chat widget to welcome visitors and boost engagement

### Prerequisites

<Info>
  A website with the Chatbase embed script already installed and working.
  New to Chatbase? Check out [Your First Agent](/docs/user-guides/quick-start/your-first-agent) to get started with the embed script first.
</Info>

## Setting Up Floating Initial Messages

This feature takes the initial messages you've configured in your Chatbase dashboard and displays them in an attention-grabbing floating format to welcome visitors and encourage interaction.

### Configuration

Set up floating initial messages using the JavaScript configuration object:

```javascript theme={null}
window.chatbaseConfig = {
  showFloatingInitialMessages: true,  // Enable floating messages
  floatingInitialMessagesDelay: 2,    // Show after 2 seconds
  floatingMessagesOncePerSession: true // Show once per session (default) or on every page load
};
```

## Configuration Reference

### chatbaseConfig Properties

Configure floating initial messages using these parameters in your `chatbaseConfig` object:

<ParamField type="boolean">
  Controls whether initial messages appear in a floating window above the chat widget

  **Requirements:**

  * Must be set before the Chatbase script loads
  * Displays the initial messages configured in your Chatbase dashboard as floating bubbles
</ParamField>

<ParamField type="number">
  Delay in seconds before displaying floating initial messages

  **Requirements:**

  * Minimum value: 0 (immediate display)
  * Maximum recommended: 10 seconds
</ParamField>

<ParamField type="boolean">
  Controls whether floating messages appear once per session or on every page load

  **Behavior:**

  * `true` (default): Messages appear only once per session. They won't reappear if users refresh the page or navigate to other pages during the same session.
  * `false`: Messages appear on every page load/refresh.
</ParamField>

<Warning>
  By default, floating initial messages are displayed only once per user session to maintain a non-intrusive experience. Set `floatingMessagesOncePerSession` to `false` if you want messages to appear on every page load.
</Warning>

## Best Practices

<AccordionGroup>
  <Accordion title="Timing Strategy">
    **Optimize when floating messages appear**

    * **User attention span**: Show messages within 2-4 seconds for best engagement
    * **Page context**: Use longer delays on content-heavy pages, shorter on simple pages
    * **Mobile considerations**: Account for slower loading on mobile devices
  </Accordion>

  <Accordion title="Message Design">
    **Create effective floating experiences**

    * **Keep messages concise**: Floating messages should be brief and attention-grabbing
    * **Maintain brand voice**: Ensure floating messages match your overall messaging tone
    * **Test across devices**: Verify messages display well on different screen sizes
  </Accordion>
</AccordionGroup>


# Help Page Proxy
Source: https://chatbase.co/docs/developer-guides/help-page-proxy



This guide explains how to use rewrites (also known as proxies) to display your
Chatbase help center on your own domain. This provides a seamless and
professional experience for your users, as they can access help content
without leaving your site.

The goal is to make your Chatbase help center, normally available at `https://chatbase.co/{agentId}/help`, appear on a path like `https://your-domain.com/help`.

<Note>
  Proxying is no longer required to use a custom domain with your Help Page.
  If you have configured a custom domain in Chatbase Settings, it will automatically
  apply to your Help Page.
</Note>

## The Core Concept: Rewrites

A rewrite acts as a proxy. When a user visits the `source` path on your domain, your server fetches the content from the `destination` URL and serves it to the user. Crucially, the URL in the user's browser bar does not change.

* **Source**: The path on your website that you want to use.
* **Destination**: The full URL of your Chatbase help center.

<Note>
  Remember to replace `{agentId}` with your actual Chatbase Agent ID. You can
  find this ID in your Chatbase dashboard settings.
</Note>

<Info>
  **Required Routes**

  For the help center to function correctly, you must proxy these paths:

  * `/help` and `/help/*` - The help center pages
  * `/__cb/*` - Static assets (JavaScript, CSS, images)
  * `/api/chat/{agentId}/*` - Chat API endpoints for features like lead submission

  Replace `{agentId}` with your actual Agent ID in all rules.
</Info>

## Implementation Examples

Choose the tab below that corresponds to your website's framework or hosting platform.

<Tabs>
  <Tab title="Next.js">
    For projects using the Next.js framework, you can configure rewrites in your `next.config.js` file. This is the recommended method for Next.js applications.

    1. Open or create the `next.config.js` file at the root of your project.
    2. Add the `rewrites` function to the configuration object.

    ```javascript theme={null}
    // next.config.js

    /** @type {import('next').NextConfig} */
    const nextConfig = {
      async rewrites() {
        return [
          {
            source: "/help",
            destination: "https://chatbase.co/{agentId}/help",
          },
          // This rule is needed to correctly proxy sub-pages of your help center.
          {
            source: "/help/:path*",
            destination: "https://chatbase.co/{agentId}/help/:path*",
          },
          // Proxy static assets (JavaScript, CSS, images)
          {
            source: "/__cb/:path*",
            destination: "https://chatbase.co/__cb/:path*",
          },
          // Proxy chat API endpoints for your agent
          {
            source: "/api/chat/{agentId}/:path*",
            destination: "https://chatbase.co/api/chat/{agentId}/:path*",
          },
        ];
      },
    };

    module.exports = nextConfig;
    ```

    After adding this configuration, restart your Next.js development server to apply the changes.
  </Tab>

  <Tab title="Vercel">
    If you host your site on Vercel (regardless of the framework), you can use a `vercel.json` file to configure rewrites at the platform level.

    1. Create a `vercel.json` file at the root of your project if it doesn't already exist.
    2. Add a `rewrites` array to the file.

    ```json theme={null}
    // vercel.json
    {
      "rewrites": [
        {
          "source": "/help",
          "destination": "https://chatbase.co/{agentId}/help"
        },
        {
          "source": "/help/:path*",
          "destination": "https://chatbase.co/{agentId}/help/:path*"
        },
        {
          "source": "/__cb/:path*",
          "destination": "https://chatbase.co/__cb/:path*"
        },
        {
          "source": "/api/chat/{agentId}/:path*",
          "destination": "https://chatbase.co/api/chat/{agentId}/:path*"
        }
      ]
    }
    ```

    Vercel will automatically apply these rules on your next deployment.
  </Tab>

  <Tab title="Netlify">
    For sites hosted on Netlify, you can configure rewrites in your `netlify.toml` file.

    1. Create or open the `netlify.toml` file at the root of your project.
    2. Add a `[[rewrites]]` rule.

    ```toml theme={null}
    # netlify.toml

    [[rewrites]]
      from = "/help/*"
      to = "https://chatbase.co/{agentId}/help/:splat"
      status = 200 # A 200 status indicates a rewrite, not a redirect

    [[rewrites]]
      from = "/help"
      to = "https://chatbase.co/{agentId}/help"
      status = 200

    # Proxy static assets (JavaScript, CSS, images)
    [[rewrites]]
      from = "/__cb/*"
      to = "https://chatbase.co/__cb/:splat"
      status = 200

    # Proxy chat API endpoints for your agent
    [[rewrites]]
      from = "/api/chat/{agentId}/*"
      to = "https://chatbase.co/api/chat/{agentId}/:splat"
      status = 200
    ```

    Commit and push this file to your repository, and Netlify will apply the rule on the next build.
  </Tab>

  <Tab title="Express (Node.js)">
    If you are running a custom Node.js server with Express, you can use the `http-proxy-middleware` package to create a rewrite.

    1. First, install the necessary packages:
       ```bash theme={null}
       npm install express http-proxy-middleware
       ```

    2. Then, set up the proxy in your Express application.

    ```javascript theme={null}
    // server.js
    const express = require("express");
    const { createProxyMiddleware } = require("http-proxy-middleware");

    const app = express();
    const PORT = process.env.PORT || 3000;

    // The agentId should be stored securely, e.g., in environment variables
    const AGENT_ID = process.env.CHATBASE_AGENT_ID || "{agentId}";

    // Proxy for help center pages
    const helpProxy = createProxyMiddleware({
      target: `https://chatbase.co`,
      changeOrigin: true,
      pathRewrite: {
        [`^/help`]: `/${AGENT_ID}/help`,
      },
      proxyTimeout: 5000,
    });

    // Proxy for static assets (JavaScript, CSS, images)
    const assetsProxy = createProxyMiddleware({
      target: `https://chatbase.co`,
      changeOrigin: true,
      proxyTimeout: 5000,
    });

    // Proxy for chat API endpoints (scoped to your agent only)
    const chatApiProxy = createProxyMiddleware({
      target: `https://chatbase.co`,
      changeOrigin: true,
      proxyTimeout: 5000,
    });

    // Apply proxies to routes
    app.use("/help", helpProxy);
    app.use("/__cb", assetsProxy);
    app.use(`/api/chat/${AGENT_ID}`, chatApiProxy);

    // Your other routes...
    app.get("/", (req, res) => {
      res.send("Your ACME Inc. Homepage");
    });

    app.listen(PORT, () => {
      console.log(`Server listening on port ${PORT}`);
    });
    ```
  </Tab>
</Tabs>

<Note>
  **Sitemaps**

  Your proxied help center content will not be automatically included in your primary domain's sitemap. You may need to add these URLs manually if SEO for your help content is a priority.
</Note>


# Identity Verification
Source: https://chatbase.co/docs/developer-guides/identity-verification

Authenticate users in your AI Agent widget just like they're authenticated on your website.

Identity verification allows you to securely authenticate your users in your AI Agent widget. When an end user is logged into your website, you can identify them to your AI Agent so the widget knows who they are and can provide personalized, authenticated experiences.

Chatbase agents can be configured to verify the identity of your users. This can be done with a JWT or by hashing the User ID. You
can also send additional metadata to the chatbot that can be used to personalize the chatbot experience.

## When to Use Identity Verification

<AccordionGroup>
  <Accordion title="Personalize the Chat Experience">
    Make your AI Agent recognize logged-in users so it can:

    * Greet users by name instead of saying "Hello there"
    * Access their account information and preferences
    * Show content relevant to their subscription or role
    * Provide support based on their history with your service
  </Accordion>

  <Accordion title="Enable Actions with User Data">
    When you need actions that require specific user information from their contact record:

    * Custom actions that need to access user details (name, email, subscription info, etc.)
    * Stripe actions (billing, subscriptions, invoices) [Learn more about Stripe actions](/docs/user-guides/chatbot/actions/stripe-action).

    <Note>
      These actions work by matching the authenticated user's ID with a Contact record that contains their detailed information.
    </Note>
  </Accordion>

  <Accordion title="Sync Contacts with the Chatbot">
    By sending user contact information in the JWT, you can always keep contact information up to date instead of sending contact information separately via the API.
  </Accordion>
</AccordionGroup>

## Implementation Guide

### Prerequisites

<Info>
  A website with the Chatbase embed script already installed and working.
  New to Chatbase? Check out [Your First Agent](/docs/user-guides/quick-start/your-first-agent) to get started with the embed script first.
</Info>

### Get Your Secret Key

Navigate to your Chatbase Dashboard to get your verification secret:

<Steps>
  <Step title="Open Your AI Agent">
    Go to [Chatbase Dashboard](https://www.chatbase.co/dashboard) and select your AI Agent.
  </Step>

  <Step title="Access Embed Settings">
    Navigate to **Deploy** → click on Manage on **Chat widget** → **Embed** tab.
  </Step>

  <Step title="Copy Secret Key">
    Copy the verification secret key shown in the embed code section.

    <Frame>
      <img alt="Chatbase embed code with identity verification secret" />
    </Frame>
  </Step>
</Steps>

## Method 1: JWT (Recommended)

#### JWT Overview

With a JSON Web Token (JWT), you can securely pass a contact's information to Chatbase. This process, known as identification, serves two purposes: it **identifies the user** to the chatbot and **updates the contact's information** in Chatbase.

#### Generating the JWT Payload

The payload of the JWT contains the sensitive information you want to pass. When you provide contact details like email, name, or Stripe information, Chatbase will use it to update or create the user's contact profile.

<Note>The only required field in the JWT payload is `user_id` or `sub`. All other fields are optional.</Note>

<CodeGroup>
  ```javascript Node.js theme={null}
  const jwt = require("jsonwebtoken");

  // Secret key from the Chatbase dashboard
  const secret = "•••••••••"; 

  // The payload contains all the user information you want to pass.
  const payload = {
      user_id: "user_12345", // A unique identifier for the user (required)
      email: "john.doe@example.com", // User's email address
      name: "John Doe", // User's full name
      phonenumber: "+15551234567", // User's phone number
      custom_attributes: { "plan": "premium" }, // Custom attributes defined in your contacts schema
      stripe_accounts: [{ "label": "Default Account", "stripe_id": "cus_12345" }], // Stripe information for integration
      exp: Math.floor(Date.now() / 1000) + (60 * 60) // Token expiration time (e.g., 1 hour from now)
  };

  // Sign the token with the HS256 algorithm
  const token = jwt.sign(payload, secret, { algorithm: 'HS256' });
  ```

  ```python Python theme={null}
  import jwt
  import time

  # Secret key from the Chatbase dashboard
  secret = "•••••••••"

  # The payload contains all the user information you want to pass.
  payload = {
      "user_id": "user_12345",  # A unique identifier for the user (required)
      "email": "john.doe@example.com",  # User's email address
      "name": "John Doe",  # User's full name
      "phonenumber": "+15551234567",  # User's phone number
      "custom_attributes": {"plan": "premium"},  # Custom attributes defined in your contacts schema
      "stripe_accounts": [{"label": "Default Account", "stripe_id": "cus_12345"}],  # Stripe information for integration
      "exp": int(time.time()) + (60 * 60)  # Token expiration time (e.g., 1 hour from now)
  }

  # Sign the token with the HS256 algorithm
  token = jwt.encode(payload, secret, algorithm='HS256')
  ```

  ```php PHP theme={null}
  <?php
  use Firebase\JWT\JWT;
  use Firebase\JWT\Key;

  // Secret key from the Chatbase dashboard
  $secret = "•••••••••";

  // The payload contains all the user information you want to pass.
  $payload = [
      'user_id' => 'user_12345', // A unique identifier for the user (required)
      'email' => 'john.doe@example.com', // User's email address
      'name' => 'John Doe', // User's full name
      'phonenumber' => '+15551234567', // User's phone number
      'custom_attributes' => ['plan' => 'premium'], // Custom attributes defined in your contacts schema
      'stripe_accounts' => [['label' => 'Default Account', 'stripe_id' => 'cus_12345']], // Stripe information for integration
      'exp' => time() + (60 * 60) // Token expiration time (e.g., 1 hour from now)
  ];

  // Sign the token with the HS256 algorithm
  $token = JWT::encode($payload, $secret, 'HS256');
  ?>
  ```

  ```ruby Ruby theme={null}
  require 'jwt'

  # Secret key from the Chatbase dashboard
  secret = "•••••••••"

  # The payload contains all the user information you want to pass.
  payload = {
    user_id: "user_12345", # A unique identifier for the user (required)
    email: "john.doe@example.com", # User's email address
    name: "John Doe", # User's full name
    phonenumber: "+15551234567", # User's phone number
    custom_attributes: { "plan" => "premium" }, # Custom attributes defined in your contacts schema
    stripe_accounts: [{ "label" => "Default Account", "stripe_id" => "cus_12345" }], # Stripe information for integration
    exp: Time.now.to_i + (60 * 60) # Token expiration time (e.g., 1 hour from now)
  }

  # Sign the token with the HS256 algorithm
  token = JWT.encode(payload, secret, 'HS256')
  ```
</CodeGroup>

#### Identifying the User

Once you have the signed JWT on your frontend, you can identify the user to your AI Agent in two ways:

<Tabs>
  <Tab title="Embed script identify method (Recommended)">
    **Dynamically identify end users**

    Data in the token (such as stripe IDs or dates of birth) are not visible to the chatbot to maintain privacy. However, the chatbot can use them to perform actions with your configured integrations. They are passed securely to maintain privacy.

    ```javascript theme={null}
    // Get the signed JWT from your server
    const token = await getJWTFromBackend(); 

    // After end user logs in or when you have their information
    window.chatbase("identify", {
    	// The token contains sensitive data which is protected.
    	token: token,
    	
    	// These public attributes ARE visible to the Chatbot context.
    	"name": user.firstName,
    	"age": user.age
    });
    ```

    This call identifies the user to the chatbot and syncs their contact information.
  </Tab>

  <Tab title="Embed Configuration">
    **Set end user identity before the Chatbase script loads**

    ```html theme={null}
    <script>
    // Get the signed JWT from your server
    const token = await getJWTFromBackend();

    // Set end user configuration before Chatbase script loads
    window.chatbaseUserConfig = {
      token: token,
      "name": user.firstName,
      "age": user.age
    }
    </script>

    <!-- Your normal Chatbase embed script -->
    ```
  </Tab>
</Tabs>

<Warning>
  Attributes passed outside of the JWT are visible to the chatbot. To protect user privacy, never include sensitive information outside of the token.
</Warning>

#### Logging out Users

When a user logs out, call the `resetUser` method to clear their identity from the chatbot session:

```javascript theme={null}
// When the user logs out
window.chatbase("resetUser");
```

#### How Contact Updates Work

* **Adding/Updating Fields:** New fields will be added, and existing ones will be updated.
  ```javascript theme={null}
  // This payload will add or update the user's Stripe information.
  const jwt_payload = {
      user_id: 123,
      stripe_accounts: [{ "label": "account1", "stripe_id": "cust123" }]
  };
  ```

* **Ignoring Fields:** If you don't include a field in the payload, it will be ignored, and the existing value will be preserved.
  ```javascript theme={null}
  // This payload will not change the user's existing Stripe information.
  const jwt_payload = {
      user_id: 123 
  };
  ```

* **Deleting Fields:** To delete a field, pass `null` as its value.
  ```javascript theme={null}
  // This payload will delete the user's Stripe information.
  const jwt_payload = {
      user_id: 123,
      stripe_accounts: null 
  };
  ```

## Complete JWT Implementation Flow

This example shows the complete JWT flow: generating JWT tokens with user data, then using identity verification to enable personalized AI responses and automatic contact updates.

### Step 1: Generate JWT Token on User Login

When users log in, generate a JWT token on your server with their contact information:

<CodeGroup>
  ```javascript Node.js theme={null}
  const jwt = require("jsonwebtoken");

  // Login endpoint
  app.post('/api/login', async (req, res) => {
    const { email, password } = req.body;
    
    // Authenticate user with your existing logic
    const user = await authenticateUser(email, password);
    if (!user) {
      return res.status(401).json({ error: 'Invalid credentials' });
    }
    
    // Create JWT payload with user information
    const payload = {
      user_id: user.id,                    // Required: unique user identifier.
      email: user.email,                   // User's email
      name: user.name,                     // User's full name
      phonenumber: user.phone,            // User's phone number
      stripe_accounts: [                    // Stripe integration
        {
          "label": "Default Account",
          "stripe_id": user.stripe_customer_id
        }
      ],
      custom_attributes: {                 // Custom user data
        "signup_date": user.signup_date,
        "support_tier": user.support_tier,
        "company": user.company
      },
      exp: Math.floor(Date.now() / 1000) + (60 * 60) // 1 hour expiration
    };
    
    // Sign the JWT with your Chatbase secret
    const token = jwt.sign(payload, process.env.CHATBASE_SECRET, { algorithm: 'HS256' });
    
    res.json({
      user: user,
      token: token  // Send JWT to frontend
    });
  });
  ```

  ```python Python theme={null}
  import jwt
  import time
  from datetime import datetime, timedelta

  # Login endpoint
  @app.route('/api/login', methods=['POST'])
  def login():
      data = request.get_json()
      email = data.get('email')
      password = data.get('password')
      
      # Authenticate user with your existing logic
      user = authenticate_user(email, password)
      if not user:
          return jsonify({'error': 'Invalid credentials'}), 401
      
      # Create JWT payload with user information
      payload = {
          'user_id': user.id,                    # Required: unique user identifier
          'email': user.email,                   # User's email
          'name': user.name,                     # User's full name
          'phonenumber': user.phone,            # User's phone number
          'stripe_accounts': [                   # Stripe integration
              {
                  "label": "Default Account",
                  "stripe_id": user.stripe_customer_id
              }
          ],
          'custom_attributes': {                # Custom user data
              "signup_date": user.signup_date,
              "support_tier": user.support_tier,
              "company": user.company
          },
          'exp': int(time.time()) + (60 * 60)    # 1 hour expiration
      }
      
      # Sign the JWT with your Chatbase secret
      token = jwt.encode(payload, os.getenv('CHATBASE_SECRET'), algorithm='HS256')
      
      return jsonify({
          'user': user,
          'token': token  # Send JWT to frontend
      })
  ```

  ```php PHP theme={null}
  <?php
  use Firebase\JWT\JWT;

  // Login endpoint
  if ($_SERVER['REQUEST_METHOD'] === 'POST') {
      $data = json_decode(file_get_contents('php://input'), true);
      $email = $data['email'];
      $password = $data['password'];
      
      // Authenticate user with your existing logic
      $user = authenticateUser($email, $password);
      if (!$user) {
          http_response_code(401);
          echo json_encode(['error' => 'Invalid credentials']);
          exit;
      }
      
      // Create JWT payload with user information
      $payload = [
          'user_id' => $user['id'],                    // Required: unique user identifier
          'email' => $user['email'],                  // User's email
          'name' => $user['name'],                    // User's full name
          'phonenumber' => $user['phone'],           // User's phone number
          'stripe_accounts' => [                      // Stripe integration
              [
                  "label" => "Default Account",
                  "stripe_id" => $user['stripe_customer_id']
              ]
          ],
          'custom_attributes' => [                    // Custom user data
              "signup_date" => $user['signup_date'],
              "support_tier" => $user['support_tier'],
              "company" => $user['company']
          ],
          'exp' => time() + (60 * 60)                // 1 hour expiration
      ];
      
      // Sign the JWT with your Chatbase secret
      $token = JWT::encode($payload, $_ENV['CHATBASE_SECRET'], 'HS256');
      
      echo json_encode([
          'user' => $user,
          'token' => $token  // Send JWT to frontend
      ]);
  }
  ?>
  ```

  ```ruby Ruby theme={null}
  require 'jwt'

  # Login endpoint
  post '/api/login' do
    data = JSON.parse(request.body.read)
    email = data['email']
    password = data['password']
    
    # Authenticate user with your existing logic
    user = authenticate_user(email, password)
    if !user
      status 401
      return { error: 'Invalid credentials' }.to_json
    end
    
    # Create JWT payload with user information
    payload = {
      user_id: user.id,                    # Required: unique user identifier
      email: user.email,                   # User's email
      name: user.name,                     # User's full name
      phonenumber: user.phone,            # User's phone number
      stripe_accounts: [                   # Stripe integration
        {
          "label" => "Default Account",
          "stripe_id" => user.stripe_customer_id
        }
      ],
      custom_attributes: {                # Custom user data
        "signup_date" => user.signup_date,
        "support_tier" => user.support_tier,
        "company" => user.company
      },
      exp: Time.now.to_i + (60 * 60)      # 1 hour expiration
    }
    
    # Sign the JWT with your Chatbase secret
    token = JWT.encode(payload, ENV['CHATBASE_SECRET'], 'HS256')
    
    {
      user: user,
      token: token  # Send JWT to frontend
    }.to_json
  end
  ```
</CodeGroup>

### Step 2: Identify User in Frontend

Use the JWT token to identify the user to Chatbase widget:

```javascript Frontend JWT Identity Verification theme={null}
// After successful login
async function loginUser() {
  const response = await fetch('/api/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email: 'user@example.com', password: 'password' })
  });
  
  const { user, token } = await response.json();
  
  // Identify user to Chatbase and also update/insert this contact
  window.chatbase("identify", {
    token: token,  // JWT contains all user data
    name: user.name // public metadata sent to the chatbot
  });
}
```

***

## Method 2: User Hash (deprecated)

<Warning>Using user hash is not recommended as JWT offers better security and lessens the need to update contacts via API</Warning>

### Generate End User Hash on Your Server

<Warning>
  **Security Critical:** End user hashes must be generated on your server, never in client-side JavaScript, to keep your secret key secure.
</Warning>

<CodeGroup>
  ```javascript Node.js theme={null}
  const crypto = require('crypto');

  const secret = '•••••••••'; // Your verification secret key
  const userId = current_user.id // A string UUID to identify your user

  const hash = crypto.createHmac('sha256', secret).update(userId).digest('hex');
  ```

  ```python Python theme={null}
  import hmac
  import hashlib

  secret = '•••••••••'  # Your verification secret key
  user_id = current_user.id  # A string UUID to identify your user. You can also use 'sub' instead of 'user_id'

  hash = hmac.new(secret.encode('utf-8'), user_id.encode('utf-8'), hashlib.sha256).hexdigest()
  ```

  ```php PHP theme={null}
  <?php
  $secret = '•••••••••';  // Your verification secret key
  $userId = $currentUser->id;  // A string UUID to identify your user

  $hash = hash_hmac('sha256', $userId, $secret);
  ?>
  ```

  ```ruby Ruby theme={null}
  require 'openssl'

  secret = '•••••••••'  # Your verification secret key
  user_id = current_user.id  # A string UUID to identify your user

  hash = OpenSSL::HMAC.hexdigest('sha256', secret, user_id)
  ```
</CodeGroup>

### Identify End Users to Your AI Agent + Update Contact

Once you've generated the end user hash on your server, you can identify the end user to your AI Agent in two ways:

<Tabs>
  <Tab title="Embed script identify method (Recommended)">
    **Dynamically identify end users**

    ```javascript theme={null}
    // After end user logs in or when you have their information
    window.chatbase("identify", {
      user_id: "user-123", 
      user_hash: "generated-hash-from-server",
      user_metadata: {
        "name": "John Doe",
        "email": "john@example.com",
        "company": "Acme Inc" 
      }
    });
    ```
  </Tab>

  <Tab title="Embed Configuration">
    **Set end user identity before the Chatbase script loads**

    ```html theme={null}
    <script>
    // Set end user configuration before Chatbase script loads
    window.chatbaseUserConfig = {
      user_id: "end-user-123",
      user_hash: "generated-hash-from-server", 
      user_metadata: {
        "name": "John Doe",
        "email": "john@example.com", 
        "company": "Acme Inc"
      }
    }
    </script>

    <!-- Your normal Chatbase embed script -->

    ```
  </Tab>
</Tabs>

## Identity Parameters

<ParamField type="string">
  Unique identifier for the user from your authentication system. This tells your AI Agent which end user is currently authenticated. You can use 'sub' instead of 'user\_id' and it will work identically.

  **Format:** Any string (UUID recommended)\
  **Example:** `"end-user-12345"`, `"550e8400-e29b-41d4-a716-446655440000"`

  <Note>
    To enable personalized responses and actions, create a Contact record with `external_id` matching this `user_id` using the [Contacts API](/docs/api-reference/contacts/create-contacts-for-a-chatbot).
  </Note>
</ParamField>

<ParamField type="string">
  HMAC-SHA256 hash of the user\_id using your Chatbase secret key. This proves to Chatbase that the end user is authentically logged in. Must be generated on your server for security.

  **Format:** 64-character hexadecimal string\
  **Example:** `"a1b2c3d4e5f6..."`
</ParamField>

<ParamField type="object">
  Additional session-specific information about the authenticated end user. This provides context to the AI Agent about the current session.

  **Character limit:** 1000 characters total across all fields\
  **Use for:** Session state, temporary preferences, current page context, authentication level

  <Warning>
    **Do not include confidential information** in user\_metadata such as passwords, social security numbers, credit card details, or other sensitive data. If your AI Agent needs access to confidential user information, store it securely in [Contacts](/docs/user-guides/chatbot/contacts/contacts-overview) instead.
  </Warning>

  ```javascript theme={null}
  user_metadata: {
    "current_session": "mobile_app",
    "last_page_visited": "/dashboard",
    "auth_level": "premium_user",
    "session_preferences": { "theme": "dark" }
  }
  ```
</ParamField>

## Security & Best Practices

<AccordionGroup>
  <Accordion title="Server-Side Hash Generation">
    **Always generate end user hashes on your server**, never in client-side JavaScript:

    ✅ **Secure:** Generate hash in your backend API\
    ✅ **Secure:** Use environment variables for Chatbase secret keys\
    ❌ **Insecure:** Generate hash in browser JavaScript\
    ❌ **Insecure:** Include secret key in client-side code
  </Accordion>

  <Accordion title="End User ID Format">
    **Use consistent, unique end user identifiers:**

    ✅ **Good:** UUIDs (`550e8400-e29b-41d4-a716-446655440000`)\
    ❌ **Avoid:** Emails or usernames that might change
  </Accordion>

  <Accordion title="Metadata Management">
    **Keep end user metadata relevant and concise:**

    ✅ **Include:** Information that helps personalize AI responses\
    ✅ **Include:** Context that aids in customer support\
    ❌ **Avoid:** Sensitive data like passwords or SSNs\
    ❌ **Avoid:** Excessive data that exceeds 1000 character limit
  </Accordion>

  <Accordion title="JWT Security Best Practices">
    **Secure JWT implementation and management:**

    ✅ **Secure:** Generate JWTs on your server with proper expiration times\
    ✅ **Secure:** Use strong, unique secret keys stored in environment variables\
    ✅ **Secure:** Include only necessary user data in JWT payload\
    ✅ **Secure:** Implement proper token refresh mechanisms\
    ❌ **Insecure:** Generate JWTs in client-side JavaScript\
    ❌ **Insecure:** Use excessively long expiration times (keep under 24 hours)
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Hash Mismatch Errors">
    **Symptoms:** End user identity not recognized, actions using Contact data fail

    **Solutions:**

    * Verify secret key matches the one from Chatbase Dashboard
    * Ensure user\_id used for hashing exactly matches the one sent
    * Check that hash is generated using HMAC-SHA256
    * Confirm user\_id is a string, not a number
    * Confirm user\_id is the same as the one used in the Contact record

    ```javascript theme={null}
    // ❌ Wrong - user_id as number
    const endUserId = 12345;

    // ✅ Correct - user_id as string  
    const endUserId = "12345";
    ```
  </Accordion>

  <Accordion title="Contact Data Not Available">
    **Symptoms:** End user is verified but Contact data isn't accessible, actions using Contact info fail

    **Solutions:**

    * Verify a Contact exists with `external_id` matching the end user's `user_id`
    * Check Contact was created using [Contacts API](/docs/developer-guides/api/contacts/add-contacts-to-chatbase)
    * Ensure `user_id` and Contact `external_id` match exactly (case-sensitive)
    * Confirm Contact has required fields populated (e.g., Stripe accounts for payment actions)
  </Accordion>

  <Accordion title="Identity Not Persisting">
    **Symptoms:** End user identity lost between page loads, Contact data not maintained

    **Solutions:**

    * Use `chatbaseUserConfig` for page-load identification
    * Call `identify()` early in your application lifecycle
    * Ensure end user hash is available before calling identify
    * Check browser console for JavaScript errors
  </Accordion>

  <Accordion title="Metadata vs Contact Data Confusion">
    **Symptoms:** Expected end user information not available to AI Agent

    **Solutions:**

    * Use Contact data for permanent end user information
    * Use `user_metadata` only for session-specific context
    * Reduce metadata size to under 1000 characters
    * Store comprehensive end user data in [Contact custom attributes](/docs/developer-guides/api/contacts/custom-attributes)
  </Accordion>
</AccordionGroup>

## Complete User Hash Implementation Flow

This example shows the complete flow: creating Contacts with custom attributes, then using identity verification to enable personalized AI responses.

### Step 1: Create Contact on User Registration/Updates

When users sign up or their data changes, create a Contact record in Chatbase with custom attributes and Stripe customer ID:

```javascript Contact Creation API Call theme={null}
const axios = require('axios');

// When user signs up or data changes
async function createChatbaseContact(userData) {
  const contactData = {
    "users": [
      {
        "external_id": userData.id,           // Your user ID
        "name": userData.name,
        "email": userData.email,
        "phonenumber": userData.phone,
        "stripe_accounts": [
          {
            "label": "Default Account",
            "stripe_id": userData.stripe_customer_id  // Stripe customer ID
          }
        ],
        "custom_attributes": {
          "signup_date": userData.signup_date,
          "support_tier": userData.support_tier
        }
      }
    ]
  };

  // Create contact via Chatbase API
  const response = await axios.post(
    `https://www.chatbase.co/api/v1/chatbot/${process.env.AGENT_ID}/contact`,
    contactData,
    {
      headers: {
        'Authorization': `Bearer ${process.env.CHATBASE_API_KEY}`,
        'Content-Type': 'application/json'
      }
    }
  );

  console.log('Contact created:', response.data);
  return response.data;
}
```

### Step 2: Generate Hash on User Login

When users log in, generate the identity hash on your server:

```javascript Server-Side Hash Generation theme={null}
const crypto = require('crypto');

function generateUserHash(userId, secret) {
  return crypto.createHmac('sha256', secret).update(userId).digest('hex');
}

// Login endpoint
app.post('/api/login', async (req, res) => {
  const { email, password } = req.body;
  
  // Authenticate user with your existing logic
  const user = await authenticateUser(email, password);
  if (!user) {
    return res.status(401).json({ error: 'Invalid credentials' });
  }
  
  // Generate secure hash for identity verification
  const userHash = generateUserHash(user.id, process.env.CHATBASE_SECRET);
  
  res.json({
    user: user,
    userHash: userHash  // Send to frontend for identify call
  });
});
```

### Step 3: Identify User in Frontend

Use the hash to identify the user to Chatbase widget:

```javascript Frontend Identity Verification theme={null}
// After successful login
async function loginUser() {
  const response = await fetch('/api/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email: 'user@example.com', password: 'password' })
  });
  
  const { user, userHash } = await response.json();
  
  // Identify user to Chatbase - enables access to Contact data
  window.chatbase("identify", {
    user_id: user.id,
    user_hash: userHash,
    user_metadata: {
      "name": user.name,
      "email": user.email,
      "current_page": "dashboard"
    }
  });
  
  console.log('User identified - AI Agent can now access Contact data and perform Stripe actions');
}
```

### Step 4: Unlock Powerful Custom Actions with Contact Data 🚀

Note: The JWT method allows you to insert and update chatbot contacts without the need for seperate API calls
to the Contacts API.

Now that your AI Agent has access to rich contact data, it can perform incredibly sophisticated custom actions that were previously impossible!

<CardGroup>
  <Card title="Custom Actions User Guide" icon="code" href="/user-guides/chatbot/actions/custom-action">
    Learn how to build powerful custom actions that leverage your contact data for personalized user experiences.
  </Card>
</CardGroup>

### Step 5: Unlock Stripe Actions 💳

Here's where the magic really happens! By adding `stripe_accounts` to your contacts, you've just unlocked the full power of our Stripe integration. Your AI Agent can now handle complex billing operations seamlessly without any additional coding on your part.

<Warning>
  **Game Changer Alert**: Your customers can now say things like "Cancel my subscription", "Show me my last invoice", or "Update my payment method" and your AI Agent will handle these requests intelligently with full context about their account!
</Warning>

**What This Means for Your Business:**

* **Reduced Support Tickets**: Common billing questions are handled instantly
* **Improved Customer Experience**: No more "let me transfer you to billing"
* **Increased Efficiency**: One AI Agent handles both support AND billing operations
* **Personalized Service**: Every interaction is tailored to the customer's specific account details

<CardGroup>
  <Card title="Stripe Actions" icon="stripe" href="/user-guides/chatbot/actions/stripe-action">
    Learn how to use Stripe actions to handle billing, subscriptions, and invoices.
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Contacts API" icon="users" href="/api-reference/contacts/create-contacts-for-a-chatbot">
    Learn how to create and manage Contact records that link to verified end users
  </Card>

  <Card title="Custom Attributes API" icon="sliders" href="/api-reference/contacts/create-custom-attribute">
    Store additional end user data in Contact custom attributes for personalized experiences
  </Card>

  <Card title="Client-Side Custom Actions" icon="wand-magic-sparkles" href="/developer-guides/client-side-custom-actions">
    Call backend actions from the client side
  </Card>

  <Card title="Client-Side Custom Forms" icon="rectangle-list" href="/developer-guides/client-side-custom-forms">
    Add interactive forms and data collection to your chat
  </Card>
</CardGroup>


# JavaScript Embed Script
Source: https://chatbase.co/docs/developer-guides/javascript-embed

Complete guide to embedding Chatbase AI Agents in your web application with advanced customization options.

The JavaScript embed script is perfect for web applications that need rich chat functionality with minimal setup. Add a powerful AI chatbot to your website in minutes.

## What You Can Do

<AccordionGroup>
  <Accordion title="Basic Integration">
    * **Simple embed** - Add a chat widget to your website in minutes
    * **Identity verification** - Add advanced capabilities and customizations to your agent, by leveraging contacts and actions
    * **Widget control** - Programmatically open/close the chat interface
  </Accordion>

  <Accordion title="Advanced Features">
    * **Event listeners** - React to user messages and AI responses
    * **Actions** - Create interactive forms and actions directly in the chat interface
    * **Dynamic content** - Show personalized initial messages
  </Accordion>
</AccordionGroup>

## Quick Start Guide

<Steps>
  <Step title="Get Your Embed Script">
    1. Go to your [Chatbase Dashboard](https://www.chatbase.co/dashboard)
    2. Select your AI Agent → **Deploy** → click on manage on **Chat widget** → select **Embed** tab
    3. Copy the JavaScript embed script

    <Frame>
      <img alt="Deploy embed tab" />
    </Frame>
  </Step>

  <Step title="Add to Your Website">
    Paste the code in your website's `<head>` section or before the closing `</body>` tag.

    <Tip>
      Place in `<head>` for faster loading, or before `</body>` if you have loading performance concerns.
    </Tip>
  </Step>

  <Step title="Test Integration">
    Visit your website and look for the chat bubble. Click it to test!

    <Check>Your AI Agent should respond based on your training data.</Check>
  </Step>

  <Step title="Add Advanced Features (Optional)">
    Enhance your integration with identity verification, custom events, or styling.

    ```javascript theme={null}
    // Example: Listen for user messages
    window.chatbase.addEventListener("user-message", (event) => {
      console.log("User said:", event.content);
      // Your custom logic here
    });
    ```
  </Step>
</Steps>

## JavaScript Embed Core Features

<Tabs>
  <Tab title="Identity Verification">
    **Secure user sessions with verified identities**

    Perfect for authenticated applications where you need to:

    * Verify user identity for actions
    * Pass user context (name, email, etc.) to AI Agent
    * Use data stored in contacts to perform actions.

    [Full Identity Verification Guide →](/docs/developer-guides/identity-verification)
  </Tab>

  <Tab title="Event Listeners">
    **React to chat events in real-time**

    Listen for and respond to:

    * User messages and AI responses
    * Actions calls and results

    [Event Listeners Documentation →](/docs/developer-guides/chatbot-event-listeners)
  </Tab>

  <Tab title="Widget Control">
    **Programmatic control over chat interface**

    Control your chat widget with JavaScript:

    * Open/close programmatically
    * Customize initial messages
    * Show floating prompts over the chat bubble

    [Widget Control Guide →](/docs/developer-guides/control-widget)
  </Tab>

  <Tab title="Client-Side Custom Actions">
    **Create interactive experiences**

    Build custom:

    * Action buttons that trigger your backend
    * Forms for lead capture

    [Custom Actions Guide →](/docs/developer-guides/client-side-custom-actions)

    [Client-Side Custom Forms Guide →](/docs/developer-guides/client-side-custom-forms)
  </Tab>
</Tabs>

## Best Practices

### Performance Optimization

<Tip>
  **Load the embed script asynchronously** to avoid blocking your page load. The provided embed code already handles this automatically.
</Tip>

```html theme={null}
<!-- The embed script loads asynchronously by default -->
<script>
// Your embed code here - it won't block page rendering
</script>
```

### User Experience

<AccordionGroup>
  <Accordion title="Mobile Optimization">
    * Test the chat widget on various mobile devices
    * Ensure the chat bubble doesn't interfere with mobile navigation
    * Consider using smaller initial messages on mobile screens
  </Accordion>

  <Accordion title="Accessibility">
    * The widget includes ARIA labels and keyboard navigation
    * Ensure sufficient color contrast in custom styling
    * Test with screen readers for accessibility compliance
  </Accordion>

  <Accordion title="Context Awareness">
    * Pass relevant page/user context to provide better responses
    * Use identity verification for personalized experiences
    * Clear chat context when users navigate to different sections
  </Accordion>
</AccordionGroup>

### Security Considerations

<Warning>
  **Never expose sensitive data** through the embed script. Use [identity verification](/docs/developer-guides/identity-verification) instead of passing raw user data.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget Not Appearing">
    1. Check that your agent ID is correct in the embed script
    2. Verify the script is placed correctly in your HTML
    3. Check browser console for JavaScript errors
    4. Ensure your website domain is allowed in agent settings
  </Accordion>

  <Accordion title="Events Not Firing">
    1. Ensure event listeners are added after the chatbase script loads
    2. Check that event names are spelled correctly
    3. Verify the chatbase object is properly initialized
    4. Use browser dev tools to debug event flow
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup>
  <Card title="Identity Verification" icon="shield-check" href="/developer-guides/identity-verification">
    Secure your chatbot for authenticated users
  </Card>

  <Card title="REST API Integration" icon="code" href="/developer-guides/api-integration">
    Integrate Chatbase with your existing backend
  </Card>

  <Card title="Client-Side Custom Actions" icon="wand-magic-sparkles" href="/developer-guides/client-side-custom-actions">
    Call backend actions from the client side
  </Card>

  <Card title="Client-Side Custom Forms" icon="rectangle-list" href="/developer-guides/client-side-custom-forms">
    Add interactive forms and data collection to your chat
  </Card>
</CardGroup>


# Developer Overview
Source: https://chatbase.co/docs/developer-guides/overview

Welcome to the Chatbase Developer Guide! Whether you're embedding a simple chat widget or building complex integrations, this guide will help you implement AI-powered conversations in your application.

<Frame>
  <div>
    <img alt="Chatbase Logo" />

    <img alt="Chatbase Logo" />
  </div>
</Frame>

## Choose Your Integration Path

<CardGroup>
  <Card title="JavaScript Embed Script" icon="js" href="/developer-guides/javascript-embed">
    Perfect for web developers who want to add a chat widget with custom behavior, event handling, and rich user experiences.
  </Card>

  <Card title="REST API Integration" icon="terminal" href="/developer-guides/api-integration">
    Ideal for backend developers building custom chat interfaces, mobile apps, or server-to-server integrations.
  </Card>

  <Card title="API v2" icon="bolt" href="/api-v2/overview">
    The latest API with structured errors, streaming via SSE, and cursor-based pagination.
  </Card>
</CardGroup>

## JavaScript Embed Integration

Perfect for web developers who want rich chat functionality with minimal complexity. The JavaScript embed script provides:

* **Simple Integration**: Add to any website with one script tag.
* **Advanced Features**: Event listeners, custom actions, and custom initial message.
* **Identity Verification**: Secure user sessions for authenticated apps and contact management.
* **Real-time Events**: React to user messages and AI responses.

<CardGroup>
  <Card title="Complete JavaScript Embed Guide" icon="js" href="/developer-guides/javascript-embed">
    Get the full implementation guide with examples, advanced features, and best practices →
  </Card>
</CardGroup>

## REST API Integration

Ideal for backend developers who need complete control over AI conversations. The REST API provides:

* **Chat API**: Send messages and receive AI responses with streaming support
* **Agent Management**: Create, update, and configure AI agents programmatically
* **Data Access**: Retrieve conversations, leads, and analytics
* **Webhooks**: Real-time notifications for chat events

<CardGroup>
  <Card title="Complete REST API Guide" icon="terminal" href="/developer-guides/api-integration">
    Get the full API documentation with examples, authentication, and best practices →
  </Card>
</CardGroup>

## Common Integration Patterns

<AccordionGroup>
  <Accordion title="E-commerce Support Bot">
    **Perfect for online stores**

    * **Embed Script**: Chat bubble on product pages
    * **Identity Verification**: Logged-in customer context
    * **Custom Actions**: Order lookup, returns processing
    * **API Integration**: Sync with order management system
  </Accordion>

  <Accordion title="SaaS Customer Success">
    **Help users succeed with your product**

    * **Embed Script**: Contextual help widget
    * **Event Listeners**: Track user interactions
    * **Custom Actions**: Feature tutorials, account management
  </Accordion>

  <Accordion title="Enterprise Knowledge Base">
    **Internal workspace support system**

    * **API Integration**: Custom internal dashboard
    * **Identity Verification**: Employee authentication and identification
    * **Contacts API**: Team directory integration
    * **Analytics**: Usage tracking and insights
  </Accordion>
</AccordionGroup>


# Webhook API Guide
Source: https://chatbase.co/docs/developer-guides/webhooks

Guide to setting up webhooks to receive real-time notifications when users submit your custom forms.

# Webhook API Guide

The Webhook API guide allows you to set-up webhooks to receive a `POST` request on when an event or more is triggered.

## Payload

| Key           | Type   | Description                                        |
| :------------ | :----- | :------------------------------------------------- |
| **eventType** | string | [Event type](#event-types)                         |
| **chatbotId** | string | Chatbot ID                                         |
| **payload**   | Object | Payload of the event. [Learn more](#event-payload) |

## Event types[](#event-types)

These are the list of events supported in webhooks:

* `leads.submit` : When a customer submit his info (Name, Email, and Phone) to your chatbot.

## Event payload[](#event-payload)

The payload of each event:

* `leads.submit` :

```json theme={null}
{
  conversationId: string,
  customerEmail: string,
  customerName: string,
  customerPhone: string
}
```

## Receiving the request

You can receive the payload by accessing the body same as any request. But it is recommended to to check the request header `x-chatbase-signature` for securing your endpoint from spam from anyone knows your endpoint.

You can achieve this by using SHA-1 (Secure Hash Algorithm 1) function to generate a signature for the request and compare it with `x-chatbase-signature` found in the request headers. If the are identical then the request is from Chatbase.

```javascript Next.js theme={null}
import crypto from 'crypto'
import {NextApiRequest, NextApiResponse} from 'next'
import getRawBody from 'raw-body'

// Raw body is required.
export const config = {
  api: {
    bodyParser: false,
  },
}

async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method === 'POST') {
    const {SECRET_KEY} = process.env

    if (typeof SECRET_KEY != 'string') {
      throw new Error('No secret key found')
    }

    const rawBody = await getRawBody(req)

    const requestBodySignature = sha1(rawBody, SECRET_KEY)

    if (requestBodySignature !== req.headers['x-chatbase-signature']) {
      return res.status(400).json({message: "Signature didn't match"})
    }

    const receivedJson = await JSON.parse(rawBody.toString())

    console.log('Received:', receivedJson)

    /*
    Body example for leads.submit event
    {
      eventType: 'leads.submit',
      chatbotId: 'xxxxxxxx',
      payload: {
        conversationId: 'xxxxxxxx',
        customerEmail: 'example@chatbase.co',
        customerName: 'Example',
        customerPhone: '123'
      }
    }
    */

    res.status(200).end('OK')
  } else {
    res.setHeader('Allow', 'POST')
    res.status(405).end('Method Not Allowed')
  }
}

function sha1(data: Buffer, secret: string): string {
  return crypto.createHmac('sha1', secret).update(data).digest('hex')
}

export default webhookHandler
```

```javascript Node.js theme={null}
import crypto from 'crypto'
import {Request, Response} from 'express'

// Note: In this example json body parser is enabled in the app

export async function webhookHandler(req: Request, res: Response) {
  if (req.method === 'POST') {
    const {SECRET_KEY} = process.env

    if (typeof SECRET_KEY != 'string') {
      throw new Error('No secret key found')
    }

    const receivedJson = req.body

    const rawBody = Buffer.from(JSON.stringify(receivedJson))

    const bodySignature = sha1(rawBody, secretKey)

    if (requestBodySignature !== req.headers['x-chatbase-signature']) {
      return res.status(400).json({message: "Signature didn't match"})
    }

    console.log('Received:', receivedJson)

    /*
    Body example for leads.submit event
    {
      eventType: 'leads.submit',
      chatbotId: 'xxxxxxxx',
      payload: {
        conversationId: 'xxxxxxxx',
        customerEmail: 'example@chatbase.co',
        customerName: 'Example',
        customerPhone: '123'
      }
    }
    */

    res.status(200).end('OK')
  } else {
    res.setHeader('Allow', 'POST')
    res.status(405).end('Method Not Allowed')
  }
}

function sha1(data: Buffer, secret: string): string {
  return crypto.createHmac('sha1', secret).update(data).digest('hex')
}
```


# AI Widget Builder
Source: https://chatbase.co/docs/developer-guides/widgets/ai-widget-builder

Generate widgets from natural language descriptions or pre-built templates using the AI builder.

The AI Widget Builder lets you create fully functional widgets using natural language. Describe what you want in plain English and the AI generates the code, schema, default example, and all supporting configuration for you.

No manual coding required. Just describe your widget and refine it through conversation.

## Getting Started

You have two ways to get started:

* **Use a pre-built template.** Click one of the available templates to instantly generate a widget based on a common use case.
* **Type your own description.** Enter a plain-language description of the widget you want to create (e.g., "a contact form with name, email, and message fields").

## What the AI Generates

When you submit a prompt or select a template, the AI generates a complete widget including:

* **Code** -- the full widget implementation ready to render.
* **Schema** -- the data schema that defines the widget's structure and input fields.
* **Default example** -- a pre-populated example so you can see the widget in action immediately.
* **Functions and states** -- relevant functions and UI states scaffolded for you automatically.

<Tip>
  The AI Builder handles the entire widget structure in one step. You do not need to configure code, schema, and example separately.
</Tip>

## Refining Your Widget

After the initial generation, you can send follow-up messages to refine the widget. The AI Builder works as a conversation, so you can iterate naturally.

Examples of refinement prompts:

* "Make the button blue"
* "Add a phone number field"
* "Change the heading text to Welcome Back"
* "Remove the email validation"

Each follow-up updates the widget's code, schema, and example together.

<Warning>
  **Important: Stub functions and states**

  The AI Builder creates placeholder functions and states that require manual configuration:

  * **Functions** are created as dismiss functions by default. After generation, you need to update each function's type and configuration in the **Functions** tab.
  * **States** are created with simple always-visible or always-hidden visibility. After generation, you need to configure conditional visibility rules in the **States** tab.

  Always review the Functions and States tabs after generating or refining a widget.
</Warning>

## Undo

If a generation does not meet your needs, you can restore to the previous version. This lets you experiment freely without losing your earlier work.

<Note>
  Use undo to roll back to the last known good version before trying a different prompt.
</Note>

## Live Preview

The preview panel on the right side of the builder updates in real time as the AI generates your widget. You can see changes appear as they are being written, giving you immediate visual feedback without waiting for the full generation to complete.


# Code Editor
Source: https://chatbase.co/docs/developer-guides/widgets/code-editor

Write widget code, define schemas, and preview with examples using the code editor.

The **Code** tab is the manual editor for writing and editing widget code and data. It is split into two sections: the **main editor** (top) where you write the widget's visual layout, and the **footer panel** (bottom) where you define the schema and manage examples.

## Main Editor

The main editor is where you write the widget's visual layout using the built-in component library. It includes:

* **Autocomplete and type hints** for all available components and their properties.
* **Syntax highlighting** for readable, structured code.
* A **Copy button** next to the JSON toggle for quick clipboard access.

<Tip>
  Use autocomplete to discover available components and their supported props without leaving the editor.
</Tip>

## Code Syntax

The code editor uses a JSX-like syntax. Below are the key patterns for working with data in your widget code.

### Variables

Reference data fields using curly braces. Each variable maps to a field defined in the schema.

```jsx theme={null}
<Title value={title} size="sm" />
<Text value={description} size="sm" color="secondary" />
```

### Nested Data

Access nested objects using dot notation.

```jsx theme={null}
<Text value={speaker.name} />
<Text value={speaker.title} />
```

### Loops

Repeat elements over an array using `.map()`.

```jsx theme={null}
{speakers.map((speaker) => (
  <Row key={speaker.id} gap={3}>
    <Image src={speaker.image} />
    <Text value={speaker.name} size="sm" />
  </Row>
))}
```

### String Interpolation

Combine static text with data fields using backticks and `${}` syntax.

```jsx theme={null}
<Text value={`Tax (${taxPercent})`} />
```

## Schema

The **Schema** editor lives in the footer panel. It defines the data fields the agent needs to provide when rendering the widget. Schemas are written using **Zod**.

The footer panel includes a **Zod/JSON toggle**:

* **Zod** -- the editable schema definition.
* **JSON Schema** -- a read-only, auto-generated view derived from the Zod schema.

<Info>
  The schema is how the agent knows what data to pass into the widget. Each field in the schema maps to a variable you can reference in the code.
</Info>

## Default Example

The **Default** tab in the footer panel contains the initial values for all schema fields. These values are used when the widget first renders in the preview.

```json theme={null}
{
  "title": "Hello World",
  "description": "This is a sample widget"
}
```

## Named Examples

Named examples let you visualize different data scenarios without changing the default values. Use them to test how the widget looks with varying data -- for example, 1 item vs 5 items, or an empty state vs a post-submission state.

<Steps>
  <Step title="Create an example">
    Click the **+** button in the footer panel to add a new named example.
  </Step>

  <Step title="Edit the name and values">
    Each named example has an editable name and its own set of field values.
  </Step>

  <Step title="Switch between examples">
    Click any example tab to update the preview with that example's data.
  </Step>
</Steps>

<Note>
  Named examples are for previewing in the builder only. At runtime, data comes from the action. See the [Overview](/docs/developer-guides/widgets/overview) page for details on data sources.
</Note>


# Data Display
Source: https://chatbase.co/docs/developer-guides/widgets/components/data-display

Components for displaying structured data — Table and Chart.

## Table

A structured data table built from rows and cells. Use `TableRow` and `TableCell` to define the table structure declaratively.

```jsx theme={null}
<Table>
  <TableRow header>
    <TableCell>Name</TableCell>
    <TableCell>Price</TableCell>
  </TableRow>
  <TableRow>
    <TableCell>{name}</TableCell>
    <TableCell>{price}</TableCell>
  </TableRow>
</Table>
```

<Tip>
  Mark a `TableRow` with `header` to render it with bold text and a background color, making it easy to distinguish column headings from data rows.
</Tip>

### TableRow Props

| Prop     | Type    | Default | Description                                                   |
| -------- | ------- | ------- | ------------------------------------------------------------- |
| `header` | boolean | `false` | Render as a header row with bold text and background styling. |

### TableCell Props

| Prop      | Type                                 | Default | Description                                                                   |
| --------- | ------------------------------------ | ------- | ----------------------------------------------------------------------------- |
| `width`   | number \| string                     | —       | Custom cell width.                                                            |
| `colSize` | `xs` \| `sm` \| `md` \| `lg` \| `xl` | —       | Preset width. `xs`: 60px, `sm`: 100px, `md`: 160px, `lg`: 240px, `xl`: 320px. |
| `colSpan` | number                               | —       | Number of columns this cell spans.                                            |
| `rowSpan` | number                               | —       | Number of rows this cell spans.                                               |
| `padding` | spacing                              | —       | Cell padding.                                                                 |
| `align`   | `start` \| `center` \| `end`         | —       | Horizontal alignment of the cell content.                                     |
| `vAlign`  | `start` \| `center` \| `end`         | —       | Vertical alignment of the cell content.                                       |

***

## Chart

Data visualization component supporting bar, line, and area charts. You can combine multiple series in a single chart to overlay different visualization types.

```jsx theme={null}
<Chart
  data={salesData}
  xAxis="month"
  series={[
    { dataKey: "revenue", label: "Revenue", type: "bar", color: "#4f46e5" },
    { dataKey: "target", label: "Target", type: "line", color: "#ef4444" }
  ]}
/>
```

<Info>
  Each entry in the `series` array defines one data series. You can mix `bar`, `line`, and `area` types in the same chart to create composite visualizations like a bar chart with a trend line overlay.
</Info>

### Props

| Prop             | Type                                  | Default | Description                                                                            |
| ---------------- | ------------------------------------- | ------- | -------------------------------------------------------------------------------------- |
| `data`           | array of objects                      | —       | The dataset to visualize. Each object represents one data point.                       |
| `series`         | array                                 | —       | Array of series definitions. See [series options](#series-options) below.              |
| `xAxis`          | string \| `{dataKey, hide?, labels?}` | —       | The data key for the x-axis, or an object for advanced configuration.                  |
| `yAxis`          | `{domain?}`                           | —       | Y-axis configuration. `domain` accepts numbers, `"auto"`, `"dataMin"`, or `"dataMax"`. |
| `showLegend`     | boolean                               | `true`  | Show or hide the chart legend.                                                         |
| `showTooltip`    | boolean                               | `true`  | Show or hide tooltips on hover.                                                        |
| `showYAxis`      | boolean                               | `false` | Show or hide the y-axis labels.                                                        |
| `barGap`         | number                                | —       | Gap between bars within the same category.                                             |
| `barCategoryGap` | number                                | —       | Gap between bar categories.                                                            |
| `width`          | number \| string                      | —       | Explicit chart width.                                                                  |
| `height`         | number \| string                      | —       | Explicit chart height.                                                                 |
| `minHeight`      | number                                | `200`   | Minimum chart height in pixels.                                                        |
| `flex`           | number \| string                      | —       | Flex grow/shrink behavior.                                                             |

### Series Options

Each object in the `series` array accepts:

| Prop        | Type                      | Description                                                                    |
| ----------- | ------------------------- | ------------------------------------------------------------------------------ |
| `dataKey`   | string                    | The key in the data objects for this series' values.                           |
| `label`     | string                    | Display label for the series in legend and tooltip.                            |
| `type`      | `bar` \| `line` \| `area` | Visualization type.                                                            |
| `color`     | string                    | Series color.                                                                  |
| `stack`     | string                    | Optional stack group. Series with the same `stack` value are stacked together. |
| `curveType` | string                    | Optional curve interpolation type for line and area charts.                    |


# Form Inputs
Source: https://chatbase.co/docs/developer-guides/widgets/components/form-inputs

Form and input components for collecting user data — Form, Input, Textarea, Select, DatePicker, Checkbox, and RadioGroup.

## Common Form Input Props

`Input`, `Textarea`, `Select`, `DatePicker`, `Checkbox`, and `RadioGroup` all share the following props for handling form data and interaction.

| Prop             | Type    | Default | Description                                                                                                     |
| ---------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `name`           | string  | —       | Field name used as the key in form submission data.                                                             |
| `required`       | boolean | `false` | Whether the field must be filled before the form can be submitted.                                              |
| `disabled`       | boolean | `false` | Disables the input, preventing user interaction.                                                                |
| `onChangeAction` | action  | —       | Function to run when the value changes. Available on `Select`, `DatePicker`, `Checkbox`, and `RadioGroup` only. |

<Info>
  The `name` prop on a form input automatically creates a variable in the widget's data. For example, an `<Input name="email" />` creates an `email` variable that you can reference elsewhere in the widget using `{email}`, use in template tokens as `{{email}}`, or check in state conditions.
</Info>

<Tip>
  Make sure each `name` is unique within a `Form` to avoid collisions.
</Tip>

***

## Form

A container that groups input components and handles submission. Wrap your inputs inside a `Form` to collect their values together when the user submits.

```jsx theme={null}
<Form onSubmitAction={{ functionName: "submitForm" }}>
  <Input name="email" placeholder="Enter your email" required />
  <Button label="Submit" submit />
</Form>
```

### Props

`Form` accepts all [Box props](/docs/developer-guides/widgets/components/layout#box) plus:

| Prop             | Type   | Default | Description                                                                            |
| ---------------- | ------ | ------- | -------------------------------------------------------------------------------------- |
| `onSubmitAction` | action | —       | Function to run when the form is submitted. Receives all field values keyed by `name`. |

<Info>
  Place a `Button` with the `submit` prop inside the `Form` to trigger submission. All inputs within the form will have their values collected automatically.
</Info>

***

## Input

A single-line text input for collecting short-form data like emails, names, or numbers.

```jsx theme={null}
<Input name="email" inputType="email" placeholder="you@example.com" required />
```

### Props

In addition to all [common form input props](#common-form-input-props), `Input` accepts:

| Prop                      | Type                                                                     | Default   | Description                                                                                    |
| ------------------------- | ------------------------------------------------------------------------ | --------- | ---------------------------------------------------------------------------------------------- |
| `inputType`               | `text` \| `email` \| `password` \| `number` \| `tel` \| `url`            | `text`    | The type of data the input accepts. Controls keyboard layout on mobile and browser validation. |
| `placeholder`             | string                                                                   | —         | Hint text displayed when the input is empty.                                                   |
| `defaultValue`            | string                                                                   | —         | Initial value of the input.                                                                    |
| `variant`                 | `soft` \| `outline`                                                      | `outline` | Visual style of the input.                                                                     |
| `size`                    | `3xs` \| `2xs` \| `xs` \| `sm` \| `md` \| `lg` \| `xl` \| `2xl` \| `3xl` | `md`      | Controls the overall size of the input.                                                        |
| `gutterSize`              | `2xs` \| `xs` \| `sm` \| `md` \| `lg` \| `xl`                            | —         | Inner horizontal padding of the input.                                                         |
| `pattern`                 | string                                                                   | —         | A regex pattern the input value must match for validation.                                     |
| `pill`                    | boolean                                                                  | `false`   | Renders the input with fully rounded corners.                                                  |
| `autoFocus`               | boolean                                                                  | `false`   | Automatically focuses the input when the widget loads.                                         |
| `autoSelect`              | boolean                                                                  | `false`   | Selects all text in the input when it receives focus.                                          |
| `allowAutofillExtensions` | boolean                                                                  | `false`   | Allows browser autofill extensions to interact with the input.                                 |

***

## Textarea

A multi-line text input for collecting longer-form content like messages or descriptions.

```jsx theme={null}
<Textarea name="message" placeholder="Type your message..." rows={4} />
```

### Props

In addition to all [common form input props](#common-form-input-props), `Textarea` accepts:

| Prop                      | Type                                                                     | Default   | Description                                                                     |
| ------------------------- | ------------------------------------------------------------------------ | --------- | ------------------------------------------------------------------------------- |
| `placeholder`             | string                                                                   | —         | Hint text displayed when the textarea is empty.                                 |
| `defaultValue`            | string                                                                   | —         | Initial value of the textarea.                                                  |
| `rows`                    | number                                                                   | —         | Number of visible text lines.                                                   |
| `autoResize`              | boolean                                                                  | `false`   | Automatically adjusts the height as the user types.                             |
| `maxRows`                 | number                                                                   | —         | Maximum number of rows the textarea can expand to when `autoResize` is enabled. |
| `variant`                 | `soft` \| `outline`                                                      | `outline` | Visual style of the textarea.                                                   |
| `size`                    | `3xs` \| `2xs` \| `xs` \| `sm` \| `md` \| `lg` \| `xl` \| `2xl` \| `3xl` | `md`      | Controls the overall size of the textarea.                                      |
| `gutterSize`              | `2xs` \| `xs` \| `sm` \| `md` \| `lg` \| `xl`                            | —         | Inner horizontal padding of the textarea.                                       |
| `autoFocus`               | boolean                                                                  | `false`   | Automatically focuses the textarea when the widget loads.                       |
| `autoSelect`              | boolean                                                                  | `false`   | Selects all text in the textarea when it receives focus.                        |
| `allowAutofillExtensions` | boolean                                                                  | `false`   | Allows browser autofill extensions to interact with the textarea.               |

***

## Select

A dropdown for choosing one option from a list. Supports search, clearing, and custom option descriptions.

```jsx theme={null}
<Select name="country" placeholder="Choose a country" options={countries} />
```

### Props

In addition to all [common form input props](#common-form-input-props), `Select` accepts:

| Prop           | Type                                                                     | Default   | Description                                                       |
| -------------- | ------------------------------------------------------------------------ | --------- | ----------------------------------------------------------------- |
| `options`      | `{label, value, disabled?, description?}[]`                              | —         | The list of options to display in the dropdown.                   |
| `placeholder`  | string                                                                   | —         | Hint text displayed when no option is selected.                   |
| `defaultValue` | string                                                                   | —         | The initially selected value.                                     |
| `variant`      | `soft` \| `outline` \| `ghost`                                           | `outline` | Visual style. `ghost` renders a minimal, borderless appearance.   |
| `size`         | `3xs` \| `2xs` \| `xs` \| `sm` \| `md` \| `lg` \| `xl` \| `2xl` \| `3xl` | `md`      | Controls the overall size of the select.                          |
| `block`        | boolean                                                                  | `false`   | Makes the select stretch to fill the full width of its container. |
| `pill`         | boolean                                                                  | `false`   | Renders the select with fully rounded corners.                    |
| `clearable`    | boolean                                                                  | `false`   | Shows a clear button to reset the selection.                      |
| `searchable`   | boolean                                                                  | `false`   | Enables a search field within the dropdown to filter options.     |

<Note>
  Each option in the `options` array requires a `label` (displayed text) and a `value` (submitted data). You can optionally include `disabled` to gray out an option or `description` to show helper text below the label.
</Note>

***

## DatePicker

A calendar-based date selector rendered inside a popover. Use it for collecting dates with optional min/max constraints.

```jsx theme={null}
<DatePicker name="startDate" placeholder="Pick a date" min="2025-01-01" max="2025-12-31" />
```

### Props

In addition to all [common form input props](#common-form-input-props), `DatePicker` accepts:

| Prop           | Type                                                                     | Default   | Description                                                            |
| -------------- | ------------------------------------------------------------------------ | --------- | ---------------------------------------------------------------------- |
| `placeholder`  | string                                                                   | —         | Hint text displayed when no date is selected.                          |
| `defaultValue` | string (`yyyy-MM-dd`)                                                    | —         | The initially selected date.                                           |
| `min`          | string (`yyyy-MM-dd`)                                                    | —         | The earliest selectable date.                                          |
| `max`          | string (`yyyy-MM-dd`)                                                    | —         | The latest selectable date.                                            |
| `variant`      | `soft` \| `outline` \| `ghost`                                           | `outline` | Visual style. `ghost` shows a compact, minimal format.                 |
| `size`         | `3xs` \| `2xs` \| `xs` \| `sm` \| `md` \| `lg` \| `xl` \| `2xl` \| `3xl` | `md`      | Controls the overall size of the date picker trigger.                  |
| `side`         | `top` \| `bottom` \| `left` \| `right`                                   | —         | Preferred side for the calendar popover to open.                       |
| `align`        | `start` \| `center` \| `end`                                             | —         | Alignment of the calendar popover relative to the trigger.             |
| `block`        | boolean                                                                  | `false`   | Makes the date picker stretch to fill the full width of its container. |
| `pill`         | boolean                                                                  | `false`   | Renders the trigger with fully rounded corners.                        |
| `clearable`    | boolean                                                                  | `false`   | Shows a clear button to reset the selected date.                       |

***

## Checkbox

A single toggle for boolean choices, rendered with an accompanying label.

```jsx theme={null}
<Checkbox name="agree" label="I agree to the terms" />
```

### Props

In addition to all [common form input props](#common-form-input-props), `Checkbox` accepts:

| Prop             | Type              | Default | Description                                |
| ---------------- | ----------------- | ------- | ------------------------------------------ |
| `label`          | string            | —       | Text displayed next to the checkbox.       |
| `defaultChecked` | boolean \| string | `false` | Whether the checkbox is initially checked. |

***

## RadioGroup

A group of radio buttons for selecting exactly one option from a set. Supports horizontal or vertical layout.

```jsx theme={null}
<RadioGroup name="plan" options={[
  { label: "Free", value: "free" },
  { label: "Pro", value: "pro" }
]} defaultValue="free" direction="col" />
```

### Props

In addition to all [common form input props](#common-form-input-props), `RadioGroup` accepts:

| Prop           | Type                          | Default | Description                                                               |
| -------------- | ----------------------------- | ------- | ------------------------------------------------------------------------- |
| `options`      | `{label, value, disabled?}[]` | —       | The list of radio options to display.                                     |
| `defaultValue` | string                        | —       | The initially selected value.                                             |
| `direction`    | `col` \| `row`                | `row`   | Controls whether options are stacked vertically or laid out horizontally. |
| `ariaLabel`    | string                        | —       | Accessible label for the radio group, used by screen readers.             |


# Interactive
Source: https://chatbase.co/docs/developer-guides/widgets/components/interactive

Interactive components for user actions — Button.

## Button

A clickable button that triggers a function when pressed. Buttons are the primary way users interact with your widget, whether submitting forms, navigating between views, or performing actions.

```jsx theme={null}
<Button label="Submit" onClickAction={{ functionName: "submit" }} variant="solid" color="primary" />
```

### Props

| Prop            | Type                                                                                                 | Default     | Description                                       |
| --------------- | ---------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------- |
| `label`         | string                                                                                               | —           | Button text.                                      |
| `onClickAction` | action                                                                                               | —           | Function to run when clicked.                     |
| `variant`       | `solid` \| `soft` \| `outline` \| `ghost`                                                            | `solid`     | Visual style of the button.                       |
| `color`         | `primary` \| `secondary` \| `success` \| `danger` \| `warning` \| `info` \| `discovery` \| `caution` | `secondary` | Button color.                                     |
| `size`          | `3xs` \| `2xs` \| `xs` \| `sm` \| `md` \| `lg` \| `xl` \| `2xl` \| `3xl`                             | `md`        | Button size.                                      |
| `iconStart`     | icon name                                                                                            | —           | Icon displayed before the label.                  |
| `iconEnd`       | icon name                                                                                            | —           | Icon displayed after the label.                   |
| `iconSize`      | `sm` \| `md` \| `lg` \| `xl` \| `2xl`                                                                | —           | Size of the start and end icons.                  |
| `submit`        | boolean                                                                                              | `false`     | Submit the parent form when clicked.              |
| `block`         | boolean                                                                                              | `false`     | Stretch the button to full width.                 |
| `pill`          | boolean                                                                                              | `false`     | Apply fully rounded corners.                      |
| `uniform`       | boolean                                                                                              | `false`     | Equal width and height, creating a square button. |
| `disabled`      | boolean                                                                                              | `false`     | Disable the button, preventing interaction.       |

<Tip>
  The `onClickAction` prop accepts an object with a `functionName` key that maps to one of your widget's defined functions. You can also pass an `additionalInputs` object to send extra data along with the action.
</Tip>

***

### Examples

#### Basic Action Button

A simple button that triggers a named function when clicked.

```jsx theme={null}
<Button
  label="Refresh"
  onClickAction={{ functionName: "refresh" }}
  variant="solid"
  color="primary"
/>
```

#### Form Submit Button

Use the `submit` prop to make the button submit its parent form. Pair this with a `Card` that has `asForm` set to `true`.

```jsx theme={null}
<Card asForm>
  <Col gap={3}>
    <TextInput name="email" label="Email" />
    <Button label="Subscribe" submit variant="solid" color="success" />
  </Col>
</Card>
```

<Info>
  When `submit` is `true`, clicking the button collects all input values from the parent form and passes them to the function defined in the `Card`'s `confirm` action or the button's own `onClickAction`.
</Info>

#### Icon Button

Add icons before or after the label using `iconStart` and `iconEnd`. Use the `uniform` prop to create a square icon-only button.

```jsx theme={null}
<Button
  label="Download"
  onClickAction={{ functionName: "download" }}
  iconStart="arrow-down-to-line"
  variant="outline"
  color="info"
/>
```

```jsx theme={null}
<Button
  label=""
  onClickAction={{ functionName: "settings" }}
  iconStart="gear"
  uniform
  variant="ghost"
/>
```

#### Full-Width Button

Set `block` to `true` to make the button span the entire width of its container.

```jsx theme={null}
<Button
  label="Continue to Checkout"
  onClickAction={{ functionName: "checkout" }}
  variant="solid"
  color="primary"
  block
/>
```

#### Button with Additional Inputs

Pass extra data alongside the action using `additionalInputs`. This is especially useful when rendering buttons in a loop, where each button needs to reference a specific item.

```jsx theme={null}
{items.map((item) => (
  <Button
    label={item.name}
    onClickAction={{
      functionName: "selectItem",
      additionalInputs: { itemId: item.id }
    }}
    variant="outline"
  />
))}
```

<Tip>
  The `additionalInputs` object is merged with any form data when the action is triggered. Use it to attach contextual identifiers like IDs, indexes, or metadata to button clicks.
</Tip>


# Layout
Source: https://chatbase.co/docs/developer-guides/widgets/components/layout

Layout components for structuring widget content — Card, Box, Col, Row, Spacer, Divider, ListView, and ListViewItem.

## Common Layout Props

`Box`, `Col`, and `Row` all share the following props for controlling spacing, sizing, and alignment.

| Prop         | Type                                                                           | Description                                                    |
| ------------ | ------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| `padding`    | spacing                                                                        | Inner spacing.                                                 |
| `border`     | border                                                                         | Border width, color, and style.                                |
| `radius`     | radius                                                                         | Corner rounding.                                               |
| `background` | color                                                                          | Background color.                                              |
| `width`      | number \| string                                                               | Explicit width.                                                |
| `height`     | number \| string                                                               | Explicit height.                                               |
| `minWidth`   | number \| string                                                               | Minimum width constraint.                                      |
| `maxWidth`   | number \| string                                                               | Maximum width constraint.                                      |
| `minHeight`  | number \| string                                                               | Minimum height constraint.                                     |
| `maxHeight`  | number \| string                                                               | Maximum height constraint.                                     |
| `gap`        | number \| string                                                               | Spacing between children.                                      |
| `align`      | `start` \| `center` \| `end` \| `baseline` \| `stretch`                        | Cross-axis alignment.                                          |
| `justify`    | `start` \| `center` \| `end` \| `between` \| `around` \| `evenly` \| `stretch` | Main-axis distribution.                                        |
| `flex`       | number \| string                                                               | Flex grow/shrink behavior.                                     |
| `flush`      | boolean                                                                        | Extend to parent edges, ignoring padding. Defaults to `false`. |
| `scrollable` | boolean                                                                        | Enable scrolling when content overflows. Defaults to `false`.  |

<Tip>
  These common props let you control layout behavior consistently across `Box`, `Col`, and `Row` without needing to remember different APIs for each.
</Tip>

***

## Card

The root container for widget content. Every widget code starts with a `Card` component as the outermost wrapper.

```jsx theme={null}
<Card size="md">
  <Title value={title} size="sm" />
  <Text value={description} color="secondary" />
</Card>
```

### Props

| Prop         | Type                                          | Default | Description                                         |
| ------------ | --------------------------------------------- | ------- | --------------------------------------------------- |
| `size`       | `sm` \| `md` \| `lg` \| `full`                | `md`    | Controls the overall width of the card.             |
| `padding`    | spacing                                       | —       | Inner spacing of the card.                          |
| `background` | color                                         | —       | Background color.                                   |
| `border`     | border                                        | —       | Border width, color, and style.                     |
| `status`     | `{text, icon?}` or `{text, favicon?, frame?}` | —       | Displays a status indicator at the top of the card. |
| `confirm`    | `{label, action}`                             | —       | Adds a confirm button to the card footer.           |
| `cancel`     | `{label, action}`                             | —       | Adds a cancel button to the card footer.            |
| `asForm`     | boolean                                       | `false` | Wraps the card content in a form element.           |
| `collapsed`  | boolean                                       | `false` | Renders the card in a collapsed state.              |
| `theme`      | `light` \| `dark`                             | —       | Forces a specific color theme for the card.         |

<Note>
  When `confirm` or `cancel` are provided, the card automatically renders action buttons in the footer. If `asForm` is `true`, the confirm button acts as the form submit button.
</Note>

***

## Box

A generic flex container for arranging child elements in any direction.

```jsx theme={null}
<Box direction="row" align="center" gap={3} padding={4}>
  <Icon name="star" />
  <Text value="Featured" />
</Box>
```

### Props

In addition to all [common layout props](#common-layout-props), `Box` accepts:

| Prop          | Type                                 | Default | Description                                                        |
| ------------- | ------------------------------------ | ------- | ------------------------------------------------------------------ |
| `direction`   | `row` \| `col`                       | —       | Sets the flex direction of the container.                          |
| `wrap`        | `nowrap` \| `wrap` \| `wrap-reverse` | —       | Controls whether children wrap to new lines.                       |
| `size`        | number \| string                     | —       | Shorthand for setting both `width` and `height` to the same value. |
| `minSize`     | number \| string                     | —       | Shorthand for setting both `minWidth` and `minHeight`.             |
| `maxSize`     | number \| string                     | —       | Shorthand for setting both `maxWidth` and `maxHeight`.             |
| `aspectRatio` | number \| string                     | —       | Sets a fixed aspect ratio for the container.                       |

***

## Col

A vertical flex container. This is a shorthand for `Box` with a column direction, making it the go-to choice for stacking elements vertically.

```jsx theme={null}
<Col gap={2}>
  <Title value={title} size="sm" />
  <Text value={subtitle} color="secondary" />
</Col>
```

### Props

`Col` accepts all [common layout props](#common-layout-props) and the same additional props as `Box` (`wrap`, `size`, `minSize`, `maxSize`, `aspectRatio`), except `direction`, which is always set to column.

***

## Row

A horizontal flex container. This is a shorthand for `Box` with a row direction, making it the go-to choice for placing elements side by side.

```jsx theme={null}
<Row gap={3} align="center">
  <Image src={avatar} size={40} radius="full" />
  <Text value={name} weight="semibold" />
  <Spacer />
  <Button label="View" variant="outline" />
</Row>
```

### Props

`Row` accepts all [common layout props](#common-layout-props) and the same additional props as `Box` (`wrap`, `size`, `minSize`, `maxSize`, `aspectRatio`), except `direction`, which is always set to row.

<Info>
  Combine `Row` with `Spacer` to push elements to opposite ends of a container — a common pattern for headers, toolbars, and list items.
</Info>

***

## Spacer

A flexible empty space that expands to fill available room along the main axis. Use it to push sibling elements apart within a `Row` or `Col`.

```jsx theme={null}
<Row>
  <Text value="Left" />
  <Spacer />
  <Text value="Right" />
</Row>
```

### Props

| Prop      | Type             | Default | Description                                                                     |
| --------- | ---------------- | ------- | ------------------------------------------------------------------------------- |
| `minSize` | number \| string | —       | Sets a minimum size for the spacer, ensuring it never shrinks below this value. |

***

## Divider

A horizontal line separator for visually breaking content into sections.

```jsx theme={null}
<Col>
  <Text value="Section 1" />
  <Divider />
  <Text value="Section 2" />
</Col>
```

### Props

| Prop      | Type             | Default | Description                                               |
| --------- | ---------------- | ------- | --------------------------------------------------------- |
| `spacing` | number \| string | —       | Vertical space above and below the divider.               |
| `color`   | color            | —       | Color of the divider line.                                |
| `size`    | number \| string | —       | Thickness of the divider line.                            |
| `flush`   | boolean          | `false` | Extend the divider to the parent edges, ignoring padding. |

***

## ListView

A scrollable list container for rendering collections of items. Use with `ListViewItem` to define each entry.

```jsx theme={null}
<ListView orientation="vertical" gap={2} limit={5}>
  <ListViewItem>
    <Text value={itemName} />
  </ListViewItem>
</ListView>
```

### Props

| Prop          | Type                                          | Default | Description                                       |
| ------------- | --------------------------------------------- | ------- | ------------------------------------------------- |
| `orientation` | `horizontal` \| `vertical`                    | —       | Scroll direction of the list.                     |
| `gap`         | number                                        | —       | Spacing between list items.                       |
| `limit`       | number \| `"auto"`                            | —       | Maximum number of visible items before scrolling. |
| `status`      | `{text, icon?}` or `{text, favicon?, frame?}` | —       | Displays a status indicator on the list.          |
| `theme`       | `light` \| `dark`                             | —       | Forces a specific color theme for the list.       |

<Tip>
  Set `limit` to control how many items are visible at once. Items beyond the limit become accessible through scrolling, keeping the widget compact.
</Tip>

***

## ListViewItem

An individual item inside a `ListView`. Items can be made interactive by providing an `onClickAction`.

```jsx theme={null}
<ListViewItem onClickAction={{ functionName: "selectItem" }} gap={3} align="center">
  <Image src={thumbnail} size={40} />
  <Text value={itemName} />
</ListViewItem>
```

### Props

| Prop            | Type       | Default | Description                                                             |
| --------------- | ---------- | ------- | ----------------------------------------------------------------------- |
| `align`         | flex align | —       | Cross-axis alignment of the item's children.                            |
| `gap`           | number     | —       | Spacing between child elements within the item.                         |
| `onClickAction` | action     | —       | Action to execute when the item is clicked. Makes the item interactive. |

<Info>
  When `onClickAction` is set, the item renders as a clickable element with hover and focus styles applied automatically.
</Info>


# Media & Visual
Source: https://chatbase.co/docs/developer-guides/widgets/components/media

Visual components for icons, images, badges, and animations.

## Icon

Displays an icon from the built-in icon set. Use icons to add visual context to labels, buttons, cards, and other elements.

```jsx theme={null}
<Icon name="map-pin" size="xl" color="primary" />
```

### Props

| Prop      | Type                                                                 | Default | Description                                                                                                                                                                                              |
| :-------- | :------------------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **name**  | `string`                                                             | —       | The icon to display. Available icons include `star`, `map-pin`, `check-circle`, `mail`, `phone`, `calendar`, `search`, `globe`, `profile`, `document`, `sparkle`, `bolt`, `info`, `lightbulb`, and more. |
| **size**  | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` \| `"3xl"` | `"md"`  | Controls the rendered size of the icon.                                                                                                                                                                  |
| **color** | `string`                                                             | —       | Sets the icon color. Accepts theme tokens like `primary`, `secondary`, `success`, `danger`, etc.                                                                                                         |

<Tip>
  Browse the full icon set by typing `<Icon name="` in the code editor — autocomplete will show all available options.
</Tip>

***

## Image

Displays an image with flexible sizing, fitting, and theme-aware source support.

```jsx theme={null}
<Image src={productImage} width={120} height={120} radius="md" fit="cover" />
```

You can also provide separate images for light and dark themes:

```jsx theme={null}
<Image
  src={{ light: lightLogo, dark: darkLogo }}
  width={200}
  height={60}
  fit="contain"
/>
```

### Props

| Prop              | Type                                                                                                                                 | Default    | Description                                                                                                          |
| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------- | :--------- | :------------------------------------------------------------------------------------------------------------------- |
| **src**           | `string` \| `{ light: string, dark: string }`                                                                                        | —          | Image source URL. Pass an object with `light` and `dark` keys to display different images based on the active theme. |
| **alt**           | `string`                                                                                                                             | —          | Alternative text for accessibility.                                                                                  |
| **size**          | `number`                                                                                                                             | —          | Square shorthand — sets both `width` and `height` to the same value.                                                 |
| **width**         | `number`                                                                                                                             | —          | Image width in pixels.                                                                                               |
| **height**        | `number`                                                                                                                             | —          | Image height in pixels.                                                                                              |
| **minWidth**      | `number`                                                                                                                             | —          | Minimum width constraint.                                                                                            |
| **maxWidth**      | `number`                                                                                                                             | —          | Maximum width constraint.                                                                                            |
| **minHeight**     | `number`                                                                                                                             | —          | Minimum height constraint.                                                                                           |
| **maxHeight**     | `number`                                                                                                                             | —          | Maximum height constraint.                                                                                           |
| **minSize**       | `number`                                                                                                                             | —          | Minimum size shorthand (applies to both dimensions).                                                                 |
| **maxSize**       | `number`                                                                                                                             | —          | Maximum size shorthand (applies to both dimensions).                                                                 |
| **aspectRatio**   | `number`                                                                                                                             | —          | Aspect ratio for the image container (e.g., `16/9`).                                                                 |
| **radius**        | `string`                                                                                                                             | —          | Border radius token (e.g., `"sm"`, `"md"`, `"lg"`, `"full"`).                                                        |
| **background**    | `string`                                                                                                                             | —          | Background color behind the image.                                                                                   |
| **flex**          | `number`                                                                                                                             | —          | Flex grow/shrink value for layout sizing.                                                                            |
| **fit**           | `"cover"` \| `"contain"` \| `"fill"` \| `"scale-down"` \| `"none"`                                                                   | —          | How the image fills its container, matching the CSS `object-fit` property.                                           |
| **position**      | `"center"` \| `"top"` \| `"bottom"` \| `"left"` \| `"right"` \| `"top left"` \| `"top right"` \| `"bottom left"` \| `"bottom right"` | `"center"` | Alignment of the image within its container when `fit` causes cropping.                                              |
| **frame**         | `boolean`                                                                                                                            | —          | When `true`, wraps the image in a subtle border frame.                                                               |
| **flush**         | `boolean`                                                                                                                            | —          | When `true`, removes default padding around the image.                                                               |
| **onClickAction** | `string`                                                                                                                             | —          | Function name to invoke when the image is clicked.                                                                   |

<Info>
  Use `fit="cover"` with a fixed `width` and `height` to crop images into consistent thumbnails. Use `fit="contain"` when you need to show the full image without cropping.
</Info>

***

## Badge

A small label used to indicate status, categories, or tags.

```jsx theme={null}
<Badge label="Active" color="success" variant="soft" />
```

```jsx theme={null}
<Badge label="Overdue" color="danger" variant="solid" pill />
```

### Props

| Prop        | Type                                                                                   | Default       | Description                                                                                                         |
| :---------- | :------------------------------------------------------------------------------------- | :------------ | :------------------------------------------------------------------------------------------------------------------ |
| **label**   | `string`                                                                               | —             | The text displayed inside the badge.                                                                                |
| **color**   | `"secondary"` \| `"success"` \| `"danger"` \| `"warning"` \| `"info"` \| `"discovery"` | `"secondary"` | Semantic color of the badge.                                                                                        |
| **variant** | `"solid"` \| `"soft"` \| `"outline"`                                                   | `"soft"`      | Visual style. `solid` uses a filled background, `soft` uses a tinted background, and `outline` shows only a border. |
| **size**    | `"sm"` \| `"md"` \| `"lg"`                                                             | `"sm"`        | Controls the size of the badge.                                                                                     |
| **pill**    | `boolean`                                                                              | —             | When `true`, applies fully rounded corners for a pill shape.                                                        |

<Tip>
  Combine badges with layout components to build tag lists or status indicators inside cards and tables.
</Tip>

***

## Transition

Wraps a child element with a fade-in and fade-out animation. Use this to add polish when content appears or disappears — for example, when toggling visibility with states.

```jsx theme={null}
<Transition>
  <Text value="This fades in" />
</Transition>
```

The animation applies a 0.2-second fade with a slight vertical slide. There are no configurable props — simply wrap any element to enable the effect.

<Info>
  Transition works well with [States](/docs/developer-guides/widgets/states) to animate content that conditionally appears based on user input or data changes.
</Info>


# Text
Source: https://chatbase.co/docs/developer-guides/widgets/components/text

Text components for displaying content — Text, Title, Caption, Label, and Markdown.

Text components handle all readable content in your widget — from body copy and headings to form labels and Markdown-formatted blocks. Five components cover the full range of text needs: **Text**, **Title**, **Caption**, **Label**, and **Markdown**.

## Common Props

The **Text**, **Title**, and **Caption** components share a set of common props for controlling content and appearance.

| Prop        | Type                         | Default | Description                                                           |
| ----------- | ---------------------------- | ------- | --------------------------------------------------------------------- |
| `value`     | `string`                     | —       | The text content to display.                                          |
| `color`     | `color`                      | —       | Text color.                                                           |
| `textAlign` | `start` \| `center` \| `end` | —       | Horizontal text alignment.                                            |
| `truncate`  | `boolean`                    | `false` | Truncate overflowing text with an ellipsis.                           |
| `maxLines`  | `number`                     | —       | Maximum number of visible lines. Content beyond this limit is hidden. |

***

## Text

The most common component for displaying body text. Use it for dynamic content such as descriptions, paragraphs, and inline values.

```jsx theme={null}
<Text value={description} size="sm" color="secondary" maxLines={3} />
```

### Props

In addition to the [common props](#common-props), `Text` supports:

| Prop          | Type                                         | Default  | Description                                                  |
| ------------- | -------------------------------------------- | -------- | ------------------------------------------------------------ |
| `size`        | `xs` \| `sm` \| `md` \| `lg` \| `xl`         | `md`     | Font size.                                                   |
| `weight`      | `normal` \| `medium` \| `semibold` \| `bold` | `normal` | Font weight.                                                 |
| `width`       | `number`                                     | —        | Fixed width for the text element.                            |
| `italic`      | `boolean`                                    | —        | Render text in italic.                                       |
| `lineThrough` | `boolean`                                    | —        | Apply a strikethrough style.                                 |
| `tabularNums` | `boolean`                                    | —        | Use tabular (monospaced) number figures for aligned columns. |
| `minLines`    | `number`                                     | —        | Minimum number of lines the element occupies.                |

<Tip>
  Use `tabularNums` when displaying numbers in tables or lists — it ensures digits are evenly spaced so columns stay aligned.
</Tip>

***

## Title

Heading text with larger, bolder sizing. Use it for section headers, card titles, and any prominent label.

```jsx theme={null}
<Title value="Order Summary" size="lg" />
```

### Props

In addition to the [common props](#common-props), `Title` supports:

| Prop          | Type                                                                                        | Default | Description                              |
| ------------- | ------------------------------------------------------------------------------------------- | ------- | ---------------------------------------- |
| `size`        | `xs` \| `sm` \| `md` \| `base` \| `lg` \| `xl` \| `2xl` \| `3xl` \| `4xl` \| `5xl` \| `6xl` | `md`    | Font size.                               |
| `weight`      | `normal` \| `medium` \| `semibold` \| `bold`                                                | `bold`  | Font weight.                             |
| `width`       | `number`                                                                                    | —       | Fixed width for the title element.       |
| `tabularNums` | `boolean`                                                                                   | —       | Use tabular (monospaced) number figures. |

***

## Caption

Smaller secondary text for annotations, timestamps, and supplementary details. Caption preserves line breaks in the provided value.

```jsx theme={null}
<Caption value="Last updated 2 minutes ago" size="sm" color="secondary" />
```

### Props

In addition to the [common props](#common-props), `Caption` supports:

| Prop     | Type                                         | Default  | Description  |
| -------- | -------------------------------------------- | -------- | ------------ |
| `size`   | `sm` \| `md` \| `lg`                         | `md`     | Font size.   |
| `weight` | `normal` \| `medium` \| `semibold` \| `bold` | `normal` | Font weight. |

<Info>
  Caption automatically preserves line breaks (`\n`) in the value string, so you can pass multi-line content without additional formatting.
</Info>

***

## Label

A text label designed for form fields. Place it directly above an `Input`, `Select`, or other form control to provide a visible, accessible label.

```jsx theme={null}
<Label value="Email address" fieldName="email" />
<Input name="email" placeholder="you@example.com" />
```

### Props

| Prop        | Type                                         | Default | Description                                            |
| ----------- | -------------------------------------------- | ------- | ------------------------------------------------------ |
| `value`     | `string`                                     | —       | The label text.                                        |
| `fieldName` | `string`                                     | —       | The `name` of the input this label is associated with. |
| `size`      | `xs` \| `sm` \| `md` \| `lg` \| `xl`         | `md`    | Font size.                                             |
| `weight`    | `normal` \| `medium` \| `semibold` \| `bold` | —       | Font weight.                                           |

<Tip>
  Always set `fieldName` to match the `name` prop of the corresponding input. This links the label to the field for accessibility and click-to-focus behavior.
</Tip>

***

## Markdown

Renders Markdown-formatted text, including headings, lists, links, code blocks, and inline formatting.

```jsx theme={null}
<Markdown value={instructions} />
```

### Props

| Prop    | Type     | Default | Description                     |
| ------- | -------- | ------- | ------------------------------- |
| `value` | `string` | —       | The Markdown content to render. |


# Functions
Source: https://chatbase.co/docs/developer-guides/widgets/functions

Configure what happens when users interact with widget elements — API calls, messages, navigation, and data updates.

Functions define the behavior behind interactive widget elements like buttons and forms. You attach a function to an element by referencing its **function name**, and the function's **type** determines what happens when a user triggers it.

## Function Types

Each function type serves a different purpose. Select the type that matches the action you want to perform.

<AccordionGroup>
  <Accordion title="Server Function">
    Makes a request to an external API. The configuration is never visible to the end user.

    | Setting               | Description                                                                                     |
    | :-------------------- | :---------------------------------------------------------------------------------------------- |
    | **URL**               | The endpoint to send the request to. Supports [template tokens](#template-tokens).              |
    | **Method**            | HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`.                                        |
    | **Headers**           | Key-value pairs sent as request headers. Supports [template tokens](#template-tokens).          |
    | **Parameters**        | Query parameters appended to the URL. Supports [template tokens](#template-tokens).             |
    | **Body**              | Request body (for `POST`, `PUT`, `PATCH`). Supports [template tokens](#template-tokens).        |
    | **Return Fields**     | Fields to extract from the response for use in follow-up actions.                               |
    | **On Success**        | [Follow-up action](#after-a-function-runs) when the request succeeds.                           |
    | **On Failure**        | [Follow-up action](#after-a-function-runs) when the request fails.                              |
    | **Additional Inputs** | Extra data passed in at the call site in the code. See [Additional Inputs](#additional-inputs). |
  </Accordion>

  <Accordion title="Client Function">
    Sends a message to the parent webpage. This is designed for widgets embedded inside iframes that need to communicate with the host page.

    | Setting               | Description                                                                                     |
    | :-------------------- | :---------------------------------------------------------------------------------------------- |
    | **Wait for Response** | Whether to wait for a response from the parent page (up to 60 seconds).                         |
    | **Inputs**            | Key-value pairs sent in to the client side code. Supports [template tokens](#template-tokens).  |
    | **Return Fields**     | Fields to extract from the client side code's response.                                         |
    | **On Success**        | [Follow-up action](#after-a-function-runs) when the parent responds successfully.               |
    | **On Failure**        | [Follow-up action](#after-a-function-runs) when the communication fails.                        |
    | **Additional Inputs** | Extra data passed in at the call site in the code. See [Additional Inputs](#additional-inputs). |
  </Accordion>

  <Accordion title="Send Message Function">
    Sends a message into the current conversation.

    | Setting               | Description                                                                                            |
    | :-------------------- | :----------------------------------------------------------------------------------------------------- |
    | **Message Template**  | The message content. Use `{{fieldName}}` [template tokens](#template-tokens) to insert dynamic values. |
    | **Hide Message**      | When enabled, the message is sent in the background and not displayed to the user.                     |
    | **On Execute**        | [Follow-up action](#after-a-function-runs) that runs after the message is sent.                        |
    | **Additional Inputs** | Extra data passed in at the call site in the code. See [Additional Inputs](#additional-inputs).        |
  </Accordion>

  <Accordion title="Link Function">
    Opens a URL in a new browser tab.

    | Setting               | Description                                                                                     |
    | :-------------------- | :---------------------------------------------------------------------------------------------- |
    | **URL**               | The URL to open. Supports [template tokens](#template-tokens).                                  |
    | **On Execute**        | [Follow-up action](#after-a-function-runs) that runs after the link is opened.                  |
    | **Additional Inputs** | Extra data passed in at the call site in the code. See [Additional Inputs](#additional-inputs). |
  </Accordion>

  <Accordion title="Dismiss Function">
    Closes the widget. There are two ways to use this:

    1. **Directly** — Attach it to a button so the user can close the widget on click.
    2. **As a follow-up** — Use it as the follow-up action on another function (e.g., close the widget after a successful API call).

    <Note>
      Dismissal state is persisted. If a user dismisses a widget, it stays dismissed even after a page refresh.
    </Note>
  </Accordion>

  <Accordion title="Set Variables Function">
    Updates widget data values without making any external calls. Useful for storing user selections or transforming data between steps.

    | Setting               | Description                                                                                     |
    | :-------------------- | :---------------------------------------------------------------------------------------------- |
    | **Variables**         | Key-value pairs to set. Values support [template tokens](#template-tokens).                     |
    | **Additional Inputs** | Extra data passed in at the call site in the code. See [Additional Inputs](#additional-inputs). |
  </Accordion>
</AccordionGroup>

## Loading Behavior

When a function runs, you can control how the UI indicates progress.

| Value         | Behavior                                   |
| :------------ | :----------------------------------------- |
| **None**      | No loading indicator is shown.             |
| **Self**      | The triggering element displays a spinner. |
| **Container** | The entire widget shows a loading overlay. |

## Additional Inputs

Sometimes a function needs extra context that depends on where it is called. For example, you might have a list of classes, each with a "Book" button that should pass a different `classId` to the same function.

```jsx theme={null}
{classes.map((item) => (
  <Button
    label={item.name}
    onClickAction={{ functionName: "bookClass", additionalInputs: { classId: item.id } }}
  />
))}
```

Once provided, you can reference additional inputs as [template tokens](#template-tokens) anywhere the function accepts them — in the URL, headers, body, or parameters. For the example above, use `{{classId}}` to insert the value.

<Warning>
  Additional inputs are **not** variables. They only exist for the duration of the function execution. If you need to persist a value, use a **Set Variables** follow-up action to save it after the function runs.
</Warning>

## After a Function Runs

Every function supports a follow-up action that runs after it completes.

* **Server Function** and **Client Function** provide two follow-up slots: **On Success** and **On Failure**.
* **Send Message**, **Link**, **Dismiss**, and **Set Variables** functions provide a single **On Execute** slot.

Each follow-up action can do one of the following:

| Action            | Description                                                                                                                                       |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Dismiss**       | Closes the widget. The dismissal is persisted across page refreshes.                                                                              |
| **Set Variables** | Updates widget data values. For server and client function follow-ups, you can reference response data using [template tokens](#template-tokens). |

## Template Tokens

Template tokens are placeholders written as `{{fieldName}}` that get replaced with current values at runtime. You can use them in any setting that supports dynamic content, including URLs, headers, body content, messages, and variables.

<Tip>
  For follow-up actions on **Server** and **Client** functions, template tokens can also reference fields from the response data. This lets you capture API results and store them as widget variables for use elsewhere.
</Tip>

## Results

Every function produces one of two outcomes:

| Outcome     | Description                                                                                                                                                                        |
| :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Success** | The function completed. For server and client functions, the result may include response data that can be referenced in follow-up actions via [template tokens](#template-tokens). |
| **Error**   | The function failed. The result includes an error message describing what went wrong.                                                                                              |


# Widgets Overview
Source: https://chatbase.co/docs/developer-guides/widgets/overview

Build interactive UI components that your AI agent can display inline during conversations — forms, cards, tables, charts, and more.

## What are Widgets?

Widgets are interactive UI components that your AI agent can display inline during conversations. Instead of responding with plain text, the agent renders rich elements — forms, cards, tables, charts, buttons, and more — directly in the chat.

This lets your agent collect structured input, present data visually, and trigger actions, all without leaving the conversation.

## What You Can Do with Widgets

<CardGroup>
  <Card title="Collect Structured Input" icon="input-text">
    Build forms with text inputs, dropdowns, date pickers, checkboxes, and other controls to gather data from users.
  </Card>

  <Card title="Display Rich Content" icon="table-layout">
    Show cards, tables, charts, images, and Markdown-formatted text to present information clearly.
  </Card>

  <Card title="Trigger Actions" icon="bolt">
    Connect buttons and form submissions to API calls, chat messages, URL navigation, or data updates.
  </Card>

  <Card title="React to User Input" icon="arrows-split-up-and-left">
    Use conditions to show, hide, or switch views based on the current values in the widget.
  </Card>

  <Card title="Import and Export" icon="file-import">
    Share widgets across agents and teams by exporting and importing `.widget` files.
  </Card>

  <Card title="AI-Assisted Building" icon="wand-magic-sparkles">
    Generate widgets from natural language descriptions or start from pre-built templates.
  </Card>
</CardGroup>

## Key Concepts

Understanding these core concepts will help you build and configure widgets effectively.

| Concept             | Description                                                                          |
| ------------------- | ------------------------------------------------------------------------------------ |
| **Code**            | The visual layout of the widget, written using a built-in component library.         |
| **Schema**          | Defines the data fields the widget expects from the agent and their types.           |
| **Default Example** | Initial values for all fields when the widget first renders.                         |
| **Named Examples**  | Saved data presets for previewing different scenarios in the builder.                |
| **Functions**       | Actions attached to interactive elements that define what happens on interaction.    |
| **States**          | Named wrappers whose visibility is controlled by conditions based on current values. |

<Info>
  The **Schema** is how the agent knows what data to pass into the widget. Each field in the schema maps to a variable you can reference in the widget code.
</Info>

## Connecting Widgets to Actions

Widgets are always attached to an **action**. You create and manage widgets from within the [Custom Action](/docs/user-guides/chatbot/actions/custom-action) configuration page.

When creating a custom action, select the **Server with UI (Widget)** or **Widget only (UI only)** action type to attach a widget. The action type determines how data flows into the widget. There are two types:

<Tabs>
  <Tab title="Widget-Only Actions">
    These actions have **no API URL** configured. The widget receives data directly from the action's input fields.

    You can either sync inputs with the widget schema automatically or define them manually.

    **Best suited for:**

    * Forms that collect user input
    * Informational cards and menus
    * Interactive elements that don't need external data
  </Tab>

  <Tab title="Server Actions with Widgets">
    These actions have an **API URL** configured. The action calls your API first, then displays the widget using the response data.

    **Best suited for:**

    * Data lookups (order status, account details)
    * Live data displays (inventory, analytics)
    * Multi-step workflows that depend on server-side logic
  </Tab>
</Tabs>

### Data Flow for Server Actions

<Steps>
  <Step title="Agent triggers the action">
    The AI agent decides to trigger the action and provides the required input data.
  </Step>

  <Step title="Action calls the API">
    The action sends a request to your configured API URL with the input data.
  </Step>

  <Step title="API returns a response">
    Your server processes the request and returns a JSON response.
  </Step>

  <Step title="Response is merged with action input">
    The API response is combined with the original action input data. If both contain the same field, the API response takes priority.
  </Step>

  <Step title="Widget renders with combined data">
    The widget receives the merged data and renders the UI accordingly.
  </Step>
</Steps>

## Where Widget Data Comes From

When a widget renders, its data can come from multiple sources. Higher-priority sources override lower ones.

| Priority    | Source              | Description                                            |
| ----------- | ------------------- | ------------------------------------------------------ |
| 1 (lowest)  | **Default example** | The widget's default values defined in the builder.    |
| 2           | **Action input**    | Data from the action's configured input fields.        |
| 3 (highest) | **API response**    | Data returned from the API call (server actions only). |

<Note>
  If a field is present in both the action input and the API response, the API response value wins. Default example values are only used when no other source provides the field.
</Note>

## AI Response Transform

Sometimes the data returned by your API doesn't match the widget's schema exactly. The **AI Response Transform** uses AI to automatically map the API response fields to the widget's expected schema.

<Tip>
  The AI Response Transform is especially useful when you're connecting to third-party APIs where you don't control the response format, or when your API returns nested or differently-named fields that need to be flattened into the widget schema.
</Tip>

## Import and Export

You can share widgets between agents, teams, or projects using `.widget` files.

<AccordionGroup>
  <Accordion title="Exporting a Widget">
    1. Open the widget in the builder.
    2. Click the **more options** menu (three dots) in the top-right corner.
    3. Select **Export** to download the widget as a `.widget` file.

    The exported file contains the widget's code, schema, default example, named examples, functions, and states.
  </Accordion>

  <Accordion title="Importing a Widget">
    1. Navigate to the **Widgets** list page.
    2. Click the **Import** button.
    3. Upload a `.widget` file from your computer.

    The imported widget will appear in your widgets list and can be attached to any action.
  </Accordion>
</AccordionGroup>

<Warning>
  Imported widgets do not include action configurations. After importing, you'll need to attach the widget to an action and configure the data flow.
</Warning>


# States
Source: https://chatbase.co/docs/developer-guides/widgets/states

Conditionally show or hide parts of your widget based on data values using states and conditions.

## What are States?

States let you conditionally show or hide parts of your widget based on current data values. Each state has a **name**, a **visibility condition**, and wraps a section of content in the widget code. When a state is active, the content inside it is visible. When inactive, the content is hidden.

## Using States in the Code

To use a state, wrap the components you want to control in a tag that matches the state name. For example, a state named "Loading" wraps content in a `<Loading>` tag:

```jsx theme={null}
<Card size="md">
  <Loading>
    <Text value="Please wait..." />
  </Loading>
  <Title value={title} size="sm" />
  <Text value={description} />
</Card>
```

When the "Loading" state is active, the `<Text value="Please wait..." />` element is visible. The rest of the widget renders normally regardless of the state.

## Multiple Active States

Multiple states can be active at the same time. Each state independently controls the visibility of its own wrapped content.

```jsx theme={null}
<Card size="md">
  <LoggedIn>
    <Text value={`Welcome back, ${userName}`} />
  </LoggedIn>
  <HasItems>
    <Text value={`You have ${itemCount} items in your cart`} />
  </HasItems>
  <Button label="Continue" onClickAction={{ functionName: "next" }} />
</Card>
```

In this example, if both "LoggedIn" and "HasItems" states are active, the user sees the welcome message, the item count, and the button. If only "LoggedIn" is active, the item count is hidden but the welcome message and button still appear.

## Visibility Modes

Each state has a visibility mode that determines when its content is shown.

| Mode               | Behavior                                                         |
| ------------------ | ---------------------------------------------------------------- |
| **Always visible** | The state is always active. Wrapped content is always shown.     |
| **Always hidden**  | The state is never active. Wrapped content is always hidden.     |
| **Conditional**    | The state is active only when its configured conditions are met. |

<Tip>
  Use **Always visible** and **Always hidden** modes to quickly toggle sections on and off during development without removing conditions.
</Tip>

## Operators

When using conditional visibility, each condition compares a data field against a value using an operator.

| Operator         | Description                                                     |
| ---------------- | --------------------------------------------------------------- |
| **equal to**     | Exact match against the comparison value.                       |
| **not equal to** | Does not match the comparison value.                            |
| **contains**     | The field contains the comparison value as a substring.         |
| **not contains** | The field does not contain the comparison value as a substring. |
| **greater than** | The field is greater than the comparison value.                 |
| **less than**    | The field is less than the comparison value.                    |
| **is empty**     | The field has no value. No comparison value is needed.          |
| **is not empty** | The field has a value. No comparison value is needed.           |

## Combining Conditions

You can combine multiple conditions using **AND** and **OR** connectors.

* **AND** — All conditions must be true for the state to be active.
* **OR** — At least one condition must be true for the state to be active.

Each condition after the first specifies its connector to the previous condition. This lets you build expressions like:

> `status` equal to "active" **AND** `role` equal to "admin"

<Info>
  The connector (AND/OR) is set on each condition individually, starting from the second condition onward. The first condition has no connector.
</Info>

## Condition Groups

For more complex logic, you can nest conditions into groups. Each group is evaluated as a unit, and groups are connected to each other with AND or OR.

This lets you express logic like:

> (`status` equal to "active" **AND** `role` equal to "admin") **OR** (`status` equal to "active" **AND** `role` equal to "editor")

In this example, the state is active when the status is "active" and the role is either "admin" or "editor."

## States Tab in the Builder

You manage states from the **States** tab in the widget builder. Each state is displayed as a card with the following controls:

* **Name** — The state name, which must match the tag used in the widget code.
* **Visibility dropdown** — Choose between Always visible, Always hidden, or Conditional.
* **Conditions** — When set to Conditional, configure one or more conditions with fields, operators, values, and connectors.
* **Cancel / Done** — Discard or save your changes to the state.

<Note>
  States are different from **Named Examples**. Named Examples are data presets used for previewing different scenarios in the builder. States control conditional visibility of widget content at runtime based on actual data values.
</Note>


# Frequently Asked Questions
Source: https://chatbase.co/docs/faq/faq

Find answers to common questions about Chatbase AI Agents, pricing, features, and technical implementation.

Get quick answers to the most common questions about Chatbase. Can't find what you're looking for? [Contact our support team](https://www.chatbase.co/help) for personalized assistance.

## Getting Started

<AccordionGroup>
  <Accordion title="What is Chatbase?">
    Chatbase is a powerful AI platform that lets you create intelligent AI Agents trained on your specific data. Whether it's your website content, documents, or custom text, Chatbase transforms your information into an intelligent assistant that can:

    * **Handle customer support** 24/7 with accurate, relevant responses
    * **Capture and qualify leads** through intelligent conversations
    * **Provide instant answers** to frequently asked questions
    * **Integrate seamlessly** into websites, apps, or messaging platforms

    Think of it as creating your own custom ChatGPT, but trained specifically on your business information.
  </Accordion>

  <Accordion title="How quickly can I get started?">
    You can have a fully functional AI Agent live on your website in **under 5 minutes**!

    Our [Quick Start guide](/docs/user-guides/quick-start/your-first-agent) walks you through each step.
  </Accordion>

  <Accordion title="Do I need technical skills to use Chatbase?">
    **Not at all!** Chatbase is designed for non-technical users:

    ✅ **No coding required** - Simple copy-paste embed codes\
    ✅ **Drag-and-drop** training data upload\
    ✅ **Visual interface** for all configurations

    That said, developers love our powerful [API](/docs/api-reference/chat/chat-with-a-chatbot) for custom integrations.
  </Accordion>
</AccordionGroup>

## Features & Capabilities

<AccordionGroup>
  <Accordion title="What languages does Chatbase support?">
    Chatbase supports **95+ languages** with intelligent language detection:

    * **Automatic detection:** Your AI Agent will respond in the same language users ask questions in
    * **Multi-language training:** Train with content in one language, get responses in another
    * **Popular languages include:** English, Spanish, French, German, Portuguese, Italian, Dutch, Russian, Chinese, Japanese, Korean, Arabic, and many more

    The AI automatically adapts to your users' preferred language, making it perfect for global businesses.
  </Accordion>

  <Accordion title="What types of data can I use to train my AI Agent?">
    You can train your AI Agent with various data sources:

    <Tabs>
      <Tab title="Websites">
        **Automatic crawling of your entire website**

        * Paste any URL and we'll crawl all linked pages
        * Perfect for businesses with existing websites
        * Automatically updates with new content
      </Tab>

      <Tab title="Documents">
        **Upload files directly**

        * **Supported formats:** PDF, DOC, DOCX, TXT
        * **Use cases:** Manuals, FAQs, product docs, policies
      </Tab>

      <Tab title="Text snippets">
        **Direct text input**

        * Paste content directly into the platform
        * Ideal for structured information
      </Tab>

      <Tab title="Q&A">
        **Structured question and answer pairs**

        * Add specific questions with exact answers
        * Perfect for consistent responses to common queries
        * Helps ensure accurate answers to frequently asked questions
        * Easy to update and maintain specific information
      </Tab>

      <Tab title="Notion Integration">
        **Connect your Notion workspace**

        * Sync with your existing knowledge base
        * Automatic updates when Notion content changes
        * Perfect for workspaces already using Notion
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

## Pricing & Credits

<AccordionGroup>
  <Accordion title="How do message credits work?">
    Message credits power your AI Agent conversations. Each response from your AI Agent consumes credits based on the AI model used:

    **Credit consumption per response:**

    * **GPT-5.2 | Gemini 2.5 Pro | Gemini 3.1 Pro | Gemini 3.5 Flash:** 2 credits ⚡ (Fast & efficient)
    * **Grok 3 | Claude 4.5 Sonnet | Claude 4.6 Sonnet:** 3 credits ⚡ (Enhanced performance, balanced power & speed)
    * **Grok 4 | GPT-5.5:** 4 credits ⚡ (Advanced reasoning)
    * **Claude 4.5 Opus | Claude 4.6 Opus:** 5 credits ⚡ (Deep analysis & long-form reasoning)
    * **Claude 4.7 Opus:** 6 credits ⚡ (Enhanced deep analysis & advanced reasoning)
    * **All other models**: 1 credit 💰 (Most economical)
  </Accordion>

  <Accordion title="When do my credits reset?">
    Message credits renew **monthly on the 1st of each month**, regardless of when you subscribed.

    **Example:** If you subscribe on March 15th, your credits will renew on April 1st.
  </Accordion>

  <Accordion title="What happens if I run out of credits?">
    When credits are exhausted, your AI Agent will display: *"This AI Agent is currently unavailable. If you are the owner, please check your account."*

    You can monitor usage in your dashboard under **Workspace → Usage**.
  </Accordion>

  <Accordion title="Can I upgrade or downgrade my plan anytime?">
    **Yes!** You can change your plan anytime:
  </Accordion>
</AccordionGroup>

## Technical Questions

<AccordionGroup>
  <Accordion title="Where is my data stored and is it secure?">
    Your data security is our top priority:

    **Storage & Security:**

    * **AWS servers** with enterprise-grade security
    * **Encrypted in transit** and at rest
    * **SOC 2 compliance**
    * **GDPR compliant** data handling

    **Data Usage:**

    * Your data is **never used** to train other models
    * **Isolated per account** - your data stays private
    * **Delete anytime** - full data portability

    Read our full [Privacy Policy](https://www.chatbase.co/legal/privacy) for complete details.
  </Accordion>

  <Accordion title="How do I check my training data character count?">
    When uploading training data, Chatbase automatically displays the character count.
  </Accordion>

  <Accordion title="Can I use my own custom domain?">
    **Yes!** Custom domains let you brand your AI Agent URLs:

    **What it includes:**

    * Custom embedding URLs (e.g., `chat.yourcompany.com`)
    * Branded sharing links for your AI Agent
    * Professional appearance for enterprise customers

    check out our [Custom Domains](/docs/developer-guides/custom-domains) guide for more information.

    <Warning>
      You'll need to configure DNS records to point your domain to Chatbase servers.
    </Warning>
  </Accordion>

  <Accordion title="Can I integrate Chatbase with my existing tools?">
    Absolutely! Chatbase offers multiple integration options:

    **Direct Integrations:**

    * **Slack, WhatsApp, Messenger** - Native messaging platform support
    * **Stripe** - Handle billing and payment customer support
    * **Zapier, Make.com** - Connect to 5,000+ apps
    * **WordPress** - E-commerce and CMS plugins

    **Developer Tools:**

    * **REST API** - Build custom integrations
    * **Webhooks** - Real-time event notifications
    * **JavaScript Embed** - Advanced embed customization

    Explore our [Integrations](/docs/user-guides/integrations/webflow) section for setup guides.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="My AI Agent isn't responding correctly. What can I do?">
    If your AI Agent isn't performing as expected, try these steps:

    **1. Review your training data:**

    * Ensure content is clear and well-structured
    * Add more specific information about common topics
    * Remove outdated or irrelevant content

    **2. Test different questions:**

    * Try variations of the same question
    * Check if the issue is with specific topics or general responses

    **3. Adjust settings:**

    * Lower temperature for more consistent responses
    * Try a different AI model
    * Add custom instructions for behavior

    **4. Add more training data:**

    * Include FAQs with question/answer pairs
    * Add examples of preferred responses
    * Cover more topics your users ask about
  </Accordion>

  <Accordion title="The chat widget isn't appearing on my website">
    If your chat widget isn't showing up, check these common issues:

    **1. Verify the embed code:**

    * Ensure you copied the complete script tag
    * Check that your AI Agent is enabled
    * Confirm the agent ID matches your AI Agent

    **2. Check website integration:**

    * Script should be in `<head>` or before closing `</body>` tag
    * No JavaScript errors in browser console
    * Test on different browsers/devices

    **3. Cache issues:**

    * Clear browser cache and refresh
    * Check if your website uses caching plugins
    * Try viewing in incognito/private mode

    **4. Content blockers:**

    * Ad blockers may prevent the widget from loading
    * Test with ad blockers disabled

    Need technical help? Our [support team](https://www.chatbase.co/help) can help debug integration issues.
  </Accordion>
</AccordionGroup>

## Still Need Help?

Can't find the answer you're looking for? We're here to help!

<CardGroup>
  <Card title="Contact Support" icon="headset" href="https://www.chatbase.co/help">
    Get personalized help from our support team
  </Card>
</CardGroup>


# Chatbase Experts Program
Source: https://chatbase.co/docs/user-guides/chatbase-experts/experts-program



The Chatbase Experts Program is built for agencies, consultants and freelancers who create AI agents for clients. It enables you to design, test, and configure agents in one place, then seamlessly copy them to your clients' own Chatbase workspaces when they're ready to go live.

## Overview

Here's what you'll learn in this guide:

<Steps>
  <Step title="Apply to Chatbase Experts Program">
    Apply to join the Experts Program and get approved
  </Step>

  <Step title="Build agents">
    Access Pro features to build agents for clients
  </Step>

  <Step title="Copy Agents to Clients">
    Use Remix Links to hand off agents to your clients' workspaces
  </Step>

  <Step title="Earn Commissions">
    Get rewarded for bringing new customers to Chatbase
  </Step>
</Steps>

## Apply to Chatbase Experts Program

Joining the Experts Program requires approval.

### How to Apply

<Steps>
  <Step title="Visit the Application Page">
    Go to the [Apply for the experts program](https://www.chatbase.co/experts-program/apply) page.
  </Step>

  <Step title="Submit the Application Form">
    Complete the form with details about your business and how you plan to use Chatbase.
  </Step>
</Steps>

### What Happens Next

<Info>
  Your application will be reviewed by the Chatbase team. You'll receive an email notification once your application is approved or declined.
</Info>

## Your Agency Workspace

Once approved, a dedicated workspace on "Agency" plan is added to your Chatbase account.

### What You Get

<CardGroup>
  <Card title="Pro Features" icon="star">
    Full access to all Chatbase Pro features
  </Card>

  <Card title="More agents" icon="arrow-up">
    Effectively manage more agents for different clients
  </Card>

  <Card title="Multi-Client Support" icon="users">
    Ability to copy agents to clients when they are production-ready
  </Card>
</CardGroup>

### Agency Workspace Limits

Your Agency workspace includes:

| Resource         | Limit           |
| ---------------- | --------------- |
| **Credits**      | 1,000 per month |
| **Agents**       | Up to 20        |
| **Team members** | Up to 10        |
| **Source size**  | Up to 60 MB     |
| **Actions**      | Up to 15        |

<Warning>
  **Not for production use.** Agents created in an Agency workspace should be copied to a client's workspace before being used in production. The credits provided are intended for development and testing only.
</Warning>

## Copying Agents to Clients

Chatbase uses **Remix Links** to copy agents from your Agency workspace to a client.

<Info>
  A Remix Link creates an exact copy of your agent at the time the copy process began and allows your client to import it into their own workspace.
</Info>

### Create a Remix Link

<Steps>
  <Step title="Go to Your Agents Page">
    Navigate to your Agents page in the Agency workspace.
  </Step>

  <Step title="Locate the Agent">
    Find the agent you want to copy to your client.
  </Step>

  <Step title="Open the Menu">
    Click the three dots (**...**) button on the agent card.
  </Step>

  <Step title="Copy the Remix Link">
    Select **Copy remix link** from the menu.
  </Step>

  <Step title="Share with Your Client">
    Send the link to your client via email, messaging, or your preferred communication channel.
  </Step>
</Steps>

### When a Client Uses a Remix Link

When your client confirms the Remix:

* A copy of the agent is added to the client's workspace
* The new agent becomes fully owned and managed by the client
* The agency and client agents operate independently

## Additional Setup After Copying

Some extra setup may be **needed by the client** after importing the agent:

<AccordionGroup>
  <Accordion title="Webhook Secret Keys">
    We create new secrets for your webhooks. If you use the webhook secrets to verify the sender identity, you need to update them with the new secrets.

    Learn more about [webhook configuration](/docs/developer-guides/webhooks).
  </Accordion>

  <Accordion title="Deployments">
    Deployment integrations such as WhatsApp, Slack, Instagram, or other channels are not copied and must be manually connected by the client.
  </Accordion>

  <Accordion title="Add-ons">
    Add-ons (e.g., remove branding, auto-recharge credits) must be purchased separately as needed.

    Learn more about [workspace usage and add-ons](/docs/user-guides/workspace/usage).
  </Accordion>

  <Accordion title="Training">
    The agent's sources will be copied but the agent won't be trained on them yet. The client needs to trigger the agent's training after import.
  </Accordion>
</AccordionGroup>

### What's Not Copied

While most agent settings are copied, the following are **not** included:

* **Deployment integrations** such as WhatsApp, Zendesk, Instagram, Email channel, etc.
* **Slack Notify action** as Slack workspaces can't be connected to multiple agents at the same time
* **Shopify actions** as Shopify stores can't be connected to multiple agents at the same time
* **Notion sources** as Notion workspaces can't be connected to multiple accounts

## Important Things to Know

<Warning>
  **Remix links expire after 7 days.** Generate a new link if your client needs more time.
</Warning>

Keep these key points in mind:

* Clients must be on a subscription plan that supports the agent's features (e.g., number of actions, source size limits, ...)
* Changes made to the original agent **do not** affect the client's copy
* Deleting the original agent **does not** impact copied agents
* Each copy creates a completely independent agent

### Working Together After Remix

If you need to continue collaborating with a client after the remix, you can:

* Create and share a new Remix Link with an updated version of the agent. The client can import it alongside the existing agent.
* Have the client invite you as a collaborator to their workspace. This gives you direct access to manage and update the agent together.

## Experts Commissions

Chatbase Experts can earn commissions for bringing new customers to Chatbase.

### How Commissions Work

<Info>
  You earn a commission when a **first-time paying Chatbase customer** imports your Remix Link. No commission is earned if the client already has a paid Chatbase account.
</Info>

### Commission Details

| Detail              | Value                            |
| ------------------- | -------------------------------- |
| **Commission rate** | 30% of the client's subscription |
| **Duration**        | Paid for the first 12 months     |
| **Eligibility**     | First-time paying customers only |

### Tracking & Payouts

All commissions are tracked and paid through [Dub.co](https://dub.co).

You can view your earnings and payout status:

* In your Dub.co dashboard
* Via your [rewards dashboard](https://www.chatbase.co/affiliate)

<Info>
  **Need more help?** Contact our support team at [support@chatbase.co](mailto:support@chatbase.co) for assistance with the Experts Program.
</Info>


# Overview
Source: https://chatbase.co/docs/user-guides/chatbot/actions/actions-overview

AI actions are a set of functions or tasks that your AI agent can trigger or execute during a conversation with users. These actions enhance the conversational experience, improve efficiency, and allow the AI agent to go beyond just responding to queries. Some of these actions may include performing specific tasks, gathering information, providing insights, or even integrating with other systems.

A **Custom Action** allows users to extend the functionality of their AI agent by executing a custom code or integrating with other systems. This is useful for triggering specific backend processes, such as processing payments, handling unique queries, or fetching data from external sources.

<Frame>
  <img alt="Available AI Actions" />
</Frame>

**Example:**

An AI agent could use a custom action to check the user's record status by querying a backend system and returning the response ("You have a premium account").

**Best Suited For:**

* Advanced use cases requiring custom code execution
* Integration with third-party systems (e.g., internal databases, payment systems)
* Custom workflows where standard actions are insufficient

***

**Stripe Actions** enable your AI agent to access and display billing information directly from your Stripe account. These actions allow customers to retrieve their subscription details, invoice history, manage billing addresses, and handle subscription changes through the chat interface.

<Info>
  Before using Stripe actions, you must first integrate your Stripe account with Chatbase. [Learn how to set up the Stripe integration](/docs/user-guides/integrations/stripe).
</Info>

**Available Stripe Actions:**

* **Get Invoices** - Retrieve and display customer invoices from Stripe
* **Get Subscriptions** - Show current subscription details and status
* **Change Billing Address** - Allow customers to update their billing information
* **Manage Subscriptions** - Enable subscription updates, cancellations, or new subscriptions

**Example:**

A customer asks, "What's my current subscription status?" The AI agent retrieves their subscription details from Stripe and displays their plan, billing cycle, and next payment date.

**Best Suited For:**

* SaaS businesses with subscription models
* E-commerce platforms with recurring billing
* Customer support automation for billing inquiries
* Self-service customer portals for account management

***

The **Slack Action** enables your AI agent to send messages to Slack channels or direct messages. It is ideal for automating workflows that involve workspace notifications or collaboration within Slack.

**Example:**

When a user mentions a topic during a conversation with the AI agent, a Slack message is automatically sent to a channel of your choice to notify you that the topic has been mentioned.

**Best Suited For:**

* Team collaboration tools (e.g., notifying Slack channels about new leads, support tickets)
* Automated internal communication workflows
* Real-time alerts for customer support or sales workspaces

***

A **Custom Button Action** allows you to create custom buttons within the AI agent interface, enabling users to locate other pages easily.

**Example:**

After providing information on product categories, the AI agent displays buttons like "Browse Products" or "View Details," which redirects your users to the respective pages.

**Best Suited For:**

* E-commerce and product recommendation systems
* Scenarios where you want users to take action directly in the chat interface (e.g., selecting options, completing forms)
* Quick decision-making processes with predefined responses

***

The **Calendly Action** integrates the AI agent with Calendly, a scheduling platform, or you can connect to your **Cal.com account.** The actions allow users to view available time slots and schedule appointments directly through the AI agent.

**Example:**

A user asks, "When can I book a call?" The AI agent shows available time slots pulled from your Calendly/Cal account, and the user can book directly through the chat.

**Best Suited For:**

* Appointment booking and calendar synchronization
* Service providers offering consultations or meetings (e.g., coaching, sales calls)
* Businesses with regular meeting requirements needing automated scheduling

***

The **Web Search Action** allows the AI agent to perform web searches in real-time to provide answers that are outside of its pre-trained knowledge base. It can retrieve up-to-date information, helping the bot answer questions about current events, trending topics, or less common queries.

**Example:**

If a user asks, "What is the weather in New York today?", the AI agent uses the web search action to pull up the latest weather details from a search engine or API.

**Best Suited For:**

* Answering questions with dynamic or real-time data (e.g., weather, news, stock prices)
* When the AI agent needs to answer uncommon or specific queries that aren't in its knowledge base
* Content-driven platforms that require the latest information

***

The **Collect Leads Action** enables the AI agent to gather user information (e.g., name, email, phone number) and automatically store it as a lead on the dashboard. This action is vital for capturing potential customers during interactions.

**Example:**

The AI agent prompts your users with a form asking for their details after an interaction about a product or service.

**Best Suited For:**

* Lead generation for sales and marketing workspaces
* E-commerce businesses looking to capture customer information
* Businesses seeking to automate and streamline the lead nurturing process

***

The **Escalate to human Action** enables your AI agent to automatically create a ticket on behalf of your user with a summary of their conversation. This action can help you allow your users to escalate their requests to a human through your preferred CRM, including **Zendesk**, **Salesforce**, **Intercom**, **Freshdesk**, and **Zohodesk**.

**Example:**

Your AI agent automatically creates a ticket with a summary of the issue or request, directed to your integrated CRM, when the user is requesting human support or your AI agent is failing to resolve thier issue.

**Best Suited For:**

* CRM-focused systems
* Involving a human in the loop via email without allowing direct Live Chat
* Scenarios where you want users to escalate issues and requests directly to a human

***

These actions provide extensive customization, real-time functionality, and powerful integrations that enhance the AI agent capabilities, making them more dynamic and useful for businesses in various sectors.


# Cal.com
Source: https://chatbase.co/docs/user-guides/chatbot/actions/cal



All you need to do to connect your Cal account is to add your Event URL under 'Cal.com Event URL'. You **do not** need an integration for Cal.com.

First of all go to Actions, then Select "Calcom Get Slots"

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

**When to use**

This is where you specify when exactly this action should be triggered or what type of customer queries would trigger it.

You also need to give your Action (make sure it's descriptive as this helps the AI understand when to use it).

Finally add your Cal Event URL into the correct field. This tells which Event to making bookings into.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

### Examples: 

"Call this action when the user mentions that he/she wants to book an appointment."

"Check if the user booked an appointment or not from the tool result." 

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>


# Calendly
Source: https://chatbase.co/docs/user-guides/chatbot/actions/calendly



In order to create this action, you would first need to integrate with your Calendly account.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

Once connected go to the Actions tab and select the "Calendly Get Slots" Action.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

Next select the Event from the dropdown that you want your Agent to use for bookings.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

### When to use:

This is where you specify when exactly this action should be triggered or what type of customer queries would trigger it. You can also add in some instructions that the bot should adhere to when this action is triggered.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

### Examples:

"Use when the user mentions booking an appointment for Essay Feedback.

If no date is specified, automatically set the window from today to 1 week from today and display these dates to the user without asking for confirmation.

If a date window is specified, set the search window to that specific date window and display it to the user.

After performing the search, respond with either "I have found available slots" or "I have not found available slots"

Display the search window but do not provide a list of slots or links.

After using the tool, check whether the user attempted to book an appointment. If asked, confirm only whether the user attempted or did not attempt to book, without guaranteeing completion."

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>


# Chatbase Live Chat
Source: https://chatbase.co/docs/user-guides/chatbot/actions/chatbase-live-chat



The Chatbase Live Chat action allows your AI agent to hand over conversations to a human support agent through the Chatbase Help Desk. When triggered, the conversation is routed directly to your Help Desk inbox so your team can continue assisting the user in real time.

***

## How It Works

### End-user experience

When the AI agent determines that a user wants to speak with a human, the conversation is handed over to a live support agent.

The user will see a confirmation message in the chat widget indicating that a support agent will join shortly.

**During this state:**

* The AI agent stops handling the conversation
* The chat is marked as a live chat request
* The user remains connected in the widget while waiting for an agent to respond

<Frame>
  <img alt="Supported Platforms" />
</Frame>

### Support Agents' experience

Support agents are notified immediately when a conversation is escalated to live chat.

Inside their inbox, the conversation is clearly labeled as a Live chat session so agents can prioritize and respond accordingly.

<Frame>
  <img alt="Supported Platforms" />
</Frame>

Agents can then:

* Reply directly to the user in real time
* Add internal notes
* Continue the conversation from the existing thread
* Take over seamlessly from the AI agent

***

## Best Practices

* Only enable live chat if you have support agents available to respond.
* Keep the trigger instructions strict to avoid unnecessary escalations.
* Let the AI handle common questions before escalating to a human.
* Use live chat for sensitive, urgent, or account-specific issues.


# Collect Leads
Source: https://chatbase.co/docs/user-guides/chatbot/actions/collect-leads



Through the Collect Leads action, you will be able to customize when exactly does the 'Lead' form get triggered during the conversation that your customer is having with the bot.

**When to use:** In this field, you specify when exactly you would like for the form to show during the conversation.

You can also specify other instructions related to the action, such as 'Show only the leads form without listing the form's fields'. Previewing the action will help you spot the edits you may like to make.

**Best Practices for Instructions**

* Make sure to use natural language.

* Keep the sentences short and simple.

* Include examples that show the model what a good response looks like.

* Focus on what you'd like the bot to do rather than what to avoid. Start your prompts with action-oriented verbs, e.g., generate, create, and provide.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

You now have the option to enable/disable any of the three available fields in the form (Name, E-mail and Phone Number). You also can set any of them (or all of them) to be a required field.

Note: you can only have a maximum of three fields in a Lead Form.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

**Success Message:** Customize the message that gets displayed once the customer submits the form.

**Dismiss Message:** Customize the message that shows once the customer dismisses the form by clicking on the 'X' button.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

After you're done editing, you can preview all your settings in the AI agent found on the Action page.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

Finally, press enable and your form will be live ready for your agent to serve to users.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>


# Custom Action
Source: https://chatbase.co/docs/user-guides/chatbot/actions/custom-action



## Create Custom Action

This action allows you to instruct the AI agent to provide any information that's included in the response of the API you use.

### Action Types

When creating a custom action, you select a **type** that determines how the action behaves:

| Type                        | Description                                                                                                                                                                                                             |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Server**                  | Calls an external API and returns the response to the agent. The agent uses the response data in its reply.                                                                                                             |
| **Server with UI (Widget)** | Calls an external API, then displays a [widget](/docs/developer-guides/widgets/overview) inline in the chat with the response data. Use this to show rich, interactive UI after fetching data.                               |
| **Client**                  | Executes code in the user's browser via the [JavaScript embed script](/docs/developer-guides/client-side-custom-actions). Useful for accessing browser APIs and frontend context.                                            |
| **Widget only (UI only)**   | Displays a [widget](/docs/developer-guides/widgets/overview) inline in the chat without calling an API. The agent populates the widget from the conversation context. Use this for forms, info cards, and interactive menus. |

<Info>
  **Server with UI** and **Widget only** actions let you attach a widget to the action. You can create and manage widgets directly from the action's configuration page. See the [Widgets documentation](/docs/developer-guides/widgets/overview) for details on building widgets.
</Info>

### General

* Action Name: This is a descriptive name for this action. This will help the AI agent know when to use it.
* When to use: This is the area of instructions that should be provided as a detailed description explaining when the AI agent should use this action and API. It's recommended to include examples of the data this action provides and customer queries it helps answer.
* All custom action requests must send a **JSON body**, and all custom action responses must be **JSON-formatted**.
* You should click on the Save and Continue button after completing the above configuration.

### API

* Collect data inputs from user: Here you should add the list of  information the AI agent needs from the user to perform the action.
  * Name: Name of the data input.
  * Type: Type of the data input.
  * Description: A small sentence that describes to the AI agent the data input that it's expecting to use in the API.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

* API request: The API endpoint that should be called by the AI Agent to retrieve data or to send updates. You can include data inputs (variables) collected from the user in the URL or the request body.
  * Method: Choose the method that the API should use.
  * HTTPS URL: The URL of the API that the AI agent should use to retrieve the needed information.
  * Add variable: This button should be used when you want to add a variable that depends on the user's input.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

When the URL is added, the parameters, Headers and Body of the API should be added automatically.

* Parameters: These are key-value pairs sent as part of the API request URL to provide input data or filter the response.
* Headers: Metadata sent along with the API request to provide information about the request or client.
* Body: The data sent as part of the request, typically for GET, POST, PUT, DELETE methods. The body should be **JSON-formatted**.

You should click on the Save and Continue button after completing the above configuration.

### Test Response

* Live response: Test with live data from the API to make sure it is configured correctly.
* Example response: Use example JSON data if the API is not ready.
* You should click on the Save and Continue button after completing the above configuration.

### Data Access

* Full data access: Allow the AI agent to access all available information from the API's response, ensuring comprehensive responses based on complete data.
* Limited data access: Limit the information the AI agent can access, providing more controlled and specific replies while protecting sensitive data.
* You should click on the Save and Continue button after completing the above configuration.

> **Notes:**
>
> 1. The maximum response size is 20KB. Anything exceeding that will return an error.
> 2. The returned response must be JSON-formatted.

## Use Cases

### Upgrade Subscription

In this example, we use an Upgrade Subscription to allow the user to ask from the AI agent to upgrade their subscription to the premium plan.

In the General section, we added Update\_Subscription as the name of the action. We provided the "When to use" information for the AI agent to use this API whenever the user wants to upgrade the subscription.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

In the API section, we added the API used to retrieve the subscription. We added the status of the plan and new plan requested, and the description of the input as follows: Active or canceledif they want to upgrade to premium, send 'active'.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

In the API request section, we added the API URL ([https://demo-rhythmbox.chatbase.fyi/api/update-subscription](https://demo-rhythmbox.chatbase.fyi/api/update-subscription)) and set the method as GET.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

In the Test Response section, we tested the response of the API when we provided active and premium as a subscription upgrade example.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

In the Data Access section, we choose the Full Data Access option for the AI agent to access all the information from the API response.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

Now, we're ready to ask the AI agent to upgrade or downgrade the subscription when the user user asks about in the Playground area on the left side of the page.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

### Weather API

In this example, we use a Get Weather API to provide the weather information for the cities asked by the user to the AI agent.

In the General section, we added Get\_Weather as a name of the action. We provided the When to use information for the AI agent to use this API whenever it's asked about the weather of any city.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

In the API section, we added the API used to retrieve the weather information. We added the name of the input as City, the type of the input is Text, and the description of the input as follows: The city that you want to know its weather.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

In the API request section, we added the API URL ([https://wttr.in/\\\\\{\\\\\{city}}?format=j1](https://wttr.in/\\\\\{\\\\\{city}}?format=j1)) and set the method as GET. The key value pair in the parameters is added automatically after entering the URL.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

In the Test Response section, we tested the response of the API when we provided London as a city example.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

In the Data Access section, we choose the Full Data Access option for the AI agent to access all the information from the API response.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

Now, we're ready to ask the AI agent the weather of any city the user asks about in the Playground area on the left side of the page.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>


# Custom Button
Source: https://chatbase.co/docs/user-guides/chatbot/actions/custom-button



### Add Custom Button

The Custom Button action allows the AI agent to send a clickable button to the user when he asks about a specific topic. 

* Action name:&#x9;

This field is only showing the name of the action in the dashboard.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

Next scroll donw and select the Custom Button.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

Now give your Custom Button an Action name.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

Next complete tell the AI when to use the custom button.

This is the area of instructions that should be provided as a detailed description explaining when the AI agent should use this action. It's recommended to include examples of the data this action provides and customer queries it helps answer.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

Button text: This is the text shown on the button provided to the users once asked about a specific topic.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

* URL:
  This is where to add the URL that the button should route the users to.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

After finishing the Custom Button configuration, you should click on the Save button. Then the action should be enabled from the top right corner in the page.

On the right side of the page, you can find the Playground area where you try the action before enabling it. It's recommended to try sending a message in the Playground to ensure that the AI agent sends the button with the URL when the desired instructions are fulfilled before enabling the action.

## Example:

"Provide the user a button when they ask about the pricing plans, the difference between any of Chatbase plans or the features available in each one. For example, when the user asks about the number of AI agents in the standard plan, you should let him know that the plan offers 5 AI agents and provide the button of the pricing page."

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>


# Escalate to Human
Source: https://chatbase.co/docs/user-guides/chatbot/actions/escalate-to-human



This action allows the AI agent to escalate a conversation to a human support agent by creating a ticket in one of your integrated helpdesk platforms.

Before creating this action, you must first connect your helpdesk platform under **Settings → Integrations**.

Supported platforms:

* Zendesk
* Salesforce
* Intercom
* Zoho Desk
* Freshdesk
* HubSpot
* Help Scout

<Frame>
  <img alt="Supported Platforms" />
</Frame>

***

### General

**Action Name:**
A descriptive name for this action. This helps the AI Agent understand when to trigger it.

**Example:**

* Escalate\_To\_Human
* Create\_Support\_Ticket
* Handoff\_To\_Agent

**Ticket Platform:**
Select the platform where tickets will be created.\
Only platforms that are already integrated under **Settings → Integrations** will appear in this dropdown.

**When to use:**
Clearly explain when the AI Agent should use this action.

**Include:**

* What this action does (creates a support ticket or escalates the conversation)
* What data is transferred (chat history, user details, issue summary)
* What updates it makes (notifies human agents, stops AI replies if applicable)

**Example instructions:**

* Use this action when the user asks to speak to a human.
* Use this action when the AI cannot resolve the issue after multiple attempts.
* Use this action for billing disputes, account issues, complaints, or sensitive matters.
* Trigger this action if the user expresses frustration or explicitly requests human assistance.

Example user queries that should trigger escalation:

* "I want to speak to a human."
* "Connect me to support."
* "This didn’t solve my issue."
* "I need help with my billing."

**Channels:**
Specify the channels where this action can be used.

For example:

* Chat widget
* Help page

Only select the channels where human escalation is operationally supported by your team.

* You should click on the Save & enable button after completing the above configuration.

<Frame>
  <img alt="Escalate to Human Configuration" />
</Frame>

***

## How It Works

When triggered, the Escalate to Human action will:

* Create a new ticket or conversation in the selected platform
* Transfer the relevant conversation history
* Include user information (if available)
* Allow your human support team to take over

***

## Use Cases

### Explicit Human Request

In this example, the AI agent is instructed to escalate when a user directly asks for human assistance.

Example queries:

* "I want to talk to a real person."
* "Can someone from support contact me?"
* "This is urgent, I need help."

Once triggered, a ticket is created in the selected helpdesk platform, and your team can continue the conversation from there.

***

### Failed Resolution Escalation

In this example, the AI attempts to resolve the issue but cannot provide a sufficient answer.

The action is triggered when:

* The AI confidence is low
* The user repeats the same question multiple times
* The issue involves billing, security, or account access

This ensures smooth human handover without losing context.
<Info> The escalation behavior depends entirely on the instructions you define in the “When to use” section. </Info>


# Salesforce Actions
Source: https://chatbase.co/docs/user-guides/chatbot/actions/salesforce-actions

Create support tickets and connect users to live agents in Salesforce when your AI agent needs to escalate customer issues

## Overview

Salesforce Actions enable your AI agent to seamlessly create support tickets (cases) and connect users to live support agents directly within the chat interface. These actions provide a smooth escalation path when the AI agent cannot resolve customer issues, ensuring users receive the appropriate level of support based on urgency and complexity.

<Info>
  Before using Salesforce actions, you must [set up Salesforce integration](/docs/user-guides/integrations/salesforce) with your Chatbase account
</Info>

## Available Salesforce Actions

### 1. Create Ticket

Create a support ticket (case) in Salesforce when the AI agent cannot solve the user's problem and the issue does not require immediate assistance. This action allows users to receive follow-up support without needing real-time interaction.

<Card title="Best for:" icon="ticket">
  Handling non-urgent issues that can be resolved through asynchronous support, tracking customer inquiries, and ensuring all support requests are logged in Salesforce for proper follow-up.
</Card>

**Common Use Cases:**

* "The chatbot couldn't answer my question about billing"
* "I want to report a bug I found"
* "Can someone follow up with me about this issue?"

#### Setup Instructions

<Steps>
  <Step title="Create the Action">
    Navigate to **Actions** → **Create Action** and select **Create ticket**.
  </Step>

  <Step title="Configure Action Details">
    **Action name:** Enter a unique name for the action.

    **Ticket platform:** Choose Salesforce

    **When to use:** Provide detailed instructions for when the AI should use this action. For example:

    * Use this action when you cannot answer the user's question or solve their problem
    * Use this action when the user explicitly requests to create a ticket or case
    * Use this action for non-urgent issues that don't require immediate human assistance
    * Do not use this action if the user needs immediate help or expresses urgency
  </Step>

  <Step title="Save and Enable">
    Click **Save** and toggle the action to **Enabled** to make it available to your AI agent.
  </Step>
</Steps>

### 2. Live Chat

Connect the user to a real human support agent in Salesforce when the chatbot cannot solve the user's problems and the issue requires immediate resolution. This action enables real-time support escalation for urgent matters.

<Card title="Best for:" icon="headset">
  Handling urgent issues that require immediate human assistance, complex problems that need real-time troubleshooting, and situations where customers express frustration or need instant resolution.
</Card>

**Common Use Cases:**

* "I need to speak to a human right now"
* "This is urgent and I need immediate help"
* "The chatbot isn't helping me, connect me to support"
* "I have a critical issue that needs to be resolved immediately"

#### Setup Instructions

<Steps>
  <Step title="Configure Salesforce Org for Live Chat">
    Set up your Salesforce org to enable messaging and live chat functionality. Complete the following configuration steps in order:

    **1. Enable Messaging Settings**

    Navigate to **Setup** in Salesforce. In the **Quick Find** box, search for "Messaging" and select **Messaging Settings**. Enable messaging by turning on the toggle.

    <Info>
      Messaging Settings must be enabled before you can create messaging channels or use Enhanced Chat features.
    </Info>

    **2. Set Up Omni-Channel**

    Configure Omni-Channel to enable intelligent routing of live chat sessions to available agents:

    1. In **Setup**, search for "Omni-Channel" in the Quick Find box
    2. Follow the Omni-Channel setup wizard to configure:
       * **Service Presence**: Set up agent presence statuses (Available, Busy, Offline)
       * **Routing Configurations**: Define how chats are routed to agents
       * **Service Channels**: Configure the chat channel for Omni-Channel routing
       * **Agent Workload**: Set the maximum number of simultaneous chats per agent

    <Info>
      For detailed Omni-Channel setup instructions, refer to the [Salesforce Omni-Channel preparation guide](https://help.salesforce.com/s/articleView?id=service.miaw_prepare_org_1.htm\&type=5).
    </Info>

    **3. Configure Enhanced Chat User Verification**

    Set up JSON Web Token (JWT) verification to securely authenticate users connecting through Chatbase:

    1. In **Setup**, search for "Enhanced Chat User Verification" in the Quick Find box
    2. Navigate to **JSON Web Keysets**
    3. Click **New** to create a new keyset
    4. Choose **Endpoint** as the type of the keyset
    5. Enter the following URL in the **Endpoint URL** field:
       ```
       https://chatbase.co/api/integrations/salesforce/keys?chatbotId=<YOUR_CHATBOT_ID>
       ```
       Replace `<YOUR_CHATBOT_ID>` with your actual Chatbase chatbot ID (found in your Chatbase dashboard)
    6. Click **Save** to store the keyset configuration

    <Tip>
      Your Chatbot ID can be found in the Chatbase dashboard URL or in the agent settings. This keyset allows Salesforce to verify JWT tokens issued by Chatbase for secure user authentication.
    </Tip>

    **4. Create a Messaging Channel**

    1. Return to the **Messaging Settings** page from step 1
    2. Click **New Channel** to create a new messaging channel
    3. Select **Enhanced Chat** as the channel type
    4. Choose **Mobile** as the deployment type
    5. Configure the routing settings based on your Omni-Channel setup from step 2
    6. Click **Save** to create the channel
    7. Select the **Add User Verification** checkbox
    8. Click **Save** again
    9. Return to the **Messaging Settings** page and open the newly created channel
    10. Scroll down to find the **User Verification Configuration** section
    11. Click **New**, select the keyset created in step 3, and enter a **Configuration Name**
    12. Ensure **Active** is selected and click **Save**

    <Warning>
      Ensure authentication is enabled on the messaging channel to maintain secure communication between Chatbase and Salesforce. Without authentication, the action will not work.
    </Warning>

    **5. Create Embedded Service Deployment**

    Create a deployment for Enhanced Chat with Custom Client configuration:

    1. In **Setup**, search for "Embedded Service Deployments" in the Quick Find box
    2. Click **New Deployment**
    3. Select **Enhanced Chat** as the service type
    4. Choose **Custom Client** as the deployment type
    5. Configure the deployment settings:
       * **Name**: Enter "Chatbase"
       * **API Name**: Enter "Chatbase"
       * **Messaging Channel**: Select the messaging channel created in step 4
    6. Click **Save** to create the deployment
    7. Click **Publish** and ensure the deployment status is set to **Active**
    8. Click **Install Code Snippet** and save the **OrganizationId**, **DeveloperName**, and **Url** fields, as you will need them later

    <Info>
      For detailed instructions on creating a Custom Client deployment, refer to the [Salesforce Enhanced Chat Custom Client deployment guide](https://help.salesforce.com/s/articleView?id=service.miaw_deployment_custom.htm\&type=5).
    </Info>

    <Check>
      After completing all steps, verify that messaging is enabled, the messaging channel is active, Omni-Channel is configured, and the deployment is ready for use. You can test the setup by initiating a test chat session.
    </Check>
  </Step>

  <Step title="Create the Action">
    Navigate to **Actions** → **Create Action** and select **Salesforce Live Chat**.
  </Step>

  <Step title="Configure Action Details">
    **When to use:** Provide detailed instructions for when the AI should use this action. For example:

    * Use this action when you cannot solve the user's problem and they need immediate assistance
    * Use this action when the user explicitly requests to speak with a human agent
    * Use this action for urgent issues that require real-time support
    * Use this action when the user expresses frustration or indicates the issue is time-sensitive
    * Do not use this action for non-urgent issues that can be handled through a support ticket

    **Salesforce Live Chat API URL:** Enter the value from the **Url** field saved in step 1, section 5 (Create Embedded Service Deployment).

    **Developer Name:** Enter the value from the **DeveloperName** field saved in step 1, section 5 (Create Embedded Service Deployment).

    **Org ID:** Enter the value from the **OrganizationId** field saved in step 1, section 5 (Create Embedded Service Deployment).
  </Step>

  <Step title="Save and Test">
    Save the configuration and test with a sample customer request in the embedded widget.

    <Check>
      Verify that live chat connections are properly established and routed to available support agents in Salesforce.
    </Check>
  </Step>
</Steps>

## Best Practices

<CardGroup>
  <Card title="Clear Escalation Criteria" icon="arrow-up">
    Define clear criteria in the "When to use" field to help the AI agent determine when to create a ticket versus connecting to live chat. This ensures users receive the appropriate level of support.
  </Card>

  <Card title="Comprehensive Case Information" icon="file-text">
    Configure case creation to include relevant conversation context, user information, and issue details to help support agents resolve issues efficiently.
  </Card>

  <Card title="Testing Coverage" icon="flask">
    Thoroughly test all actions with various user scenarios, edge cases, and error conditions before going live. Test both urgent and non-urgent escalation paths.
  </Card>
</CardGroup>


# Shopify Actions
Source: https://chatbase.co/docs/user-guides/chatbot/actions/shopify-actions

Help customers browse products, track orders, manage their cart, and update their account through your AI agent

## Overview

Shopify Actions enable your AI agent to provide comprehensive e-commerce support directly within the chat interface. These actions give your agent access to your store's product catalog, order information, and customer data, allowing it to assist shoppers throughout their entire journey.

<Info>
  **Prerequisite:** Before using Shopify Actions, you must [set up the Shopify integration](/docs/user-guides/integrations/shopify) with your Chatbase account.
</Info>

## Available Shopify Actions

### 1. Get Products

Search and display products from your Shopify catalog. Customers can browse by category, filter by criteria, search for specific items, and add products directly to their cart.

<Card title="Best for:" icon="magnifying-glass">
  Helping customers discover products, answering questions about inventory, comparing items, and facilitating add-to-cart actions.
</Card>

**Common Use Cases:**

* "Show me red dresses under \$50"
* "What laptops do you have in stock?"

<Info>
  **Note:** Adding products to the cart only works when the app is embedded in your Shopify store. It will not work in the Playground.
</Info>

#### Cart Update Events

When a customer adds a product to their cart through the chat widget, Chatbase dispatches custom DOM events so your theme can react accordingly (e.g., updating the cart icon count). The following events are fired:

```js theme={null}
document.dispatchEvent(new CustomEvent('cart:updated', { detail: { newCart } }));
document.dispatchEvent(new CustomEvent('cart-update', { detail: { newCart } }));
document.dispatchEvent(new CustomEvent('cart:update', { detail: { newCart } }));
```

You can listen to any of these events in your theme's JavaScript to keep the cart UI **in sync**:

```js theme={null}
document.addEventListener('cart:updated', (event) => {
  const cart = event.detail.newCart;
  // Update your theme's cart count, e.g.:
  document.querySelector('.cart-count').textContent = cart.item_count;
});
```

<Info>
  Multiple event names are dispatched to ensure compatibility across different Shopify themes. You only need to listen to one of them.
</Info>

#### How Product Sync Works

To sync your catalog, expand the **Products** accordion and click **Sync** or **Sync and Enable Action**. Chatbase will then retrieve all products from your Shopify store. After the initial import, Chatbase automatically listens for changes—whenever a product is added, updated, or deleted in your store, the data syncs in real time. This ensures your agent always has access to up-to-date product information. When you delete the action, Chatbase automatically removes its stored product data and stops syncing future updates.

#### Setup Instructions

<Steps>
  <Step title="Navigate to Actions">
    Go to your [Chatbase dashboard](https://www.chatbase.co/dashboard/) and select the agent connected to your Shopify store. Click **Actions** at the top of the page.
  </Step>

  <Step title="Create the Action">
    Click **Create Action** and choose **Shopify show product**.
  </Step>

  <Step title="Configure Action Details">
    **Action Name:** Enter a descriptive name for the action (e.g., "Search Products").

    **When to use:** Provide clear instructions for when the AI should trigger this action. For example:

    * Use this action when the user asks about products, inventory, or availability
    * Use this action when the user wants to browse or search for items
    * Use this action when the user asks to add something to their cart

    <Frame>
      <img alt="Shopify Get Products" />
    </Frame>
  </Step>

  <Step title="Sync Your Products">
    Expand the **Products** accordion and click **Sync** to import your catalog, or click **Sync and Enable Action** to sync and enable the action in one step. The initial sync may take a few minutes depending on your catalog size.

    <Frame>
      <img alt="Shopify Sync Products" />
    </Frame>
  </Step>

  <Step title="Save and Enable">
    If you clicked **Sync** in the previous step, click **Save** and ensure the action is toggled to **Enabled**.

    <Check>
      Test the action by asking your agent product-related questions to verify it returns accurate results.
    </Check>

    <Frame>
      <img alt="Shopify Get Products in action" />
    </Frame>
  </Step>
</Steps>

***

### 2. Get Orders

Retrieve order information for customers. Customers can check order status, view their purchase history, and get details about specific orders using various filters.

<Card title="Best for:" icon="box">
  Answering order status inquiries, providing tracking information, displaying purchase history, and helping customers find specific order details.
</Card>

**Common Use Cases:**

* "Where is my order?"
* "Show me my recent orders"
* "What's the status of order #1234?"
* "When will my package arrive?"

<Info>
  **Order status in the widget:** The widget pulls order status directly from Shopify, so it reflects the latest information Shopify has available on the order status page. Shipped orders appear as "**On its way**". To display delivery confirmation, ensure your store uses a trackable carrier (USPS, UPS, FedEx, etc.) or a third-party app that provides delivery updates to Shopify.
</Info>

#### Setup Instructions

<Steps>
  <Step title="Navigate to Actions">
    Go to your [Chatbase dashboard](https://www.chatbase.co/dashboard/) and select the agent connected to your Shopify store. Click **Actions** at the top of the page.
  </Step>

  <Step title="Create the Action">
    Click **Create Action** and choose **Shopify show order**.
  </Step>

  <Step title="Configure Action Details">
    **Action Name:** Enter a descriptive name for the action (e.g., "Order Lookup").

    **When to use:** Provide clear instructions for when the AI should trigger this action. For example:

    * Use this action when the user asks about their order status
    * Use this action when the user wants to track a shipment
    * Use this action when the user asks about their purchase history
    * Use this action when the user provides an order number

    <Frame>
      <img alt="Shopify Get Orders" />
    </Frame>
  </Step>

  <Step title="Save and Enable">
    Click **Save** and ensure the action is toggled to **Enabled**.

    <Check>
      Test the action by asking your agent about order status to verify it retrieves the correct information.
    </Check>

    <Frame>
      <img alt="Shopify Get Orders in action" />
    </Frame>

    <Info>
      **This action cannot be tested in the Action Preview on the dashboard, as it requires the user to be authenticated in order to work properly.**
    </Info>
  </Step>
</Steps>

***

### 3. Get Cart

Display the current contents of a customer's shopping cart, including items, quantities, prices, and totals.

<Card title="Best for:" icon="cart-shopping">
  Showing customers what's in their cart, displaying cart totals, and helping customers review items before checkout.
</Card>

**Common Use Cases:**

* "What's in my cart?"
* "Show me my cart total"
* "How many items are in my cart?"
* "What did I add to my cart?"

<Info>
  **Note:** Retrieving the cart only works when the app is embedded in your Shopify store. It will not work in the Playground.
</Info>

#### Setup Instructions

<Steps>
  <Step title="Navigate to Actions">
    Go to your [Chatbase dashboard](https://www.chatbase.co/dashboard/) and select the agent connected to your Shopify store. Click **Actions** at the top of the page.
  </Step>

  <Step title="Create the Action">
    Click **Create Action** and choose **Shopify get cart**.
  </Step>

  <Step title="Configure Action Details">
    **Action Name:** Enter a descriptive name for the action (e.g., "View Cart").

    **When to use:** Provide clear instructions for when the AI should trigger this action. For example:

    * Use this action when the user asks about their cart contents
    * Use this action when the user wants to see their cart total
    * Use this action when the user asks what items they've added

    <Frame>
      <img alt="Shopify Get Cart" />
    </Frame>
  </Step>

  <Step title="Save and Enable">
    Click **Save** and ensure the action is toggled to **Enabled**.

    <Check>
      Test the action by asking your agent to show cart contents.
    </Check>

    <Frame>
      <img alt="Shopify Get Cart in action" />
    </Frame>

    <Info>
      **This action cannot be tested in the Action Preview on the dashboard, as it requires the user to be authenticated in order to work properly.**
    </Info>
  </Step>
</Steps>

***

### 4. Update Profile

Enable customers to modify their account profile information through the agent.

<Card title="Best for:" icon="user-pen">
  Account management, updating contact information, and helping customers keep their profile current.
</Card>

**Common Use Cases:**

* "Update my email address"
* "Change my phone number"
* "Update my account information"

#### Setup Instructions

<Steps>
  <Step title="Navigate to Actions">
    Go to your [Chatbase dashboard](https://www.chatbase.co/dashboard/) and select the agent connected to your Shopify store. Click **Actions** at the top of the page.
  </Step>

  <Step title="Create the Action">
    Click **Create Action** and choose **Shopify update profile**.
  </Step>

  <Step title="Configure Action Details">
    **Action Name:** Enter a descriptive name for the action (e.g., "Update Profile").

    **When to use:** Provide clear instructions for when the AI should trigger this action. For example:

    * Use this action when the user wants to update their profile information
    * Use this action when the user asks to change their email or phone number
    * Use this action when the user wants to modify their account details

    <Frame>
      <img alt="Shopify Update Profile" />
    </Frame>
  </Step>

  <Step title="Save and Enable">
    Click **Save** and ensure the action is toggled to **Enabled**.

    <Check>
      Test the action by asking your agent to update profile information.
    </Check>

    <Frame>
      <img alt="Shopify Update Profile in action" />
    </Frame>

    <Info>
      **This action cannot be tested in the Action Preview on the dashboard, as it requires the user to be authenticated in order to work properly.**
    </Info>
  </Step>
</Steps>

***

### 5. Update Billing Address

Allow customers to add new billing addresses or update existing ones directly through the chat interface.

<Card title="Best for:" icon="address-card">
  Self-service address updates, helping customers correct billing information, and streamlining account management.
</Card>

**Common Use Cases:**

* "Update my billing address"
* "Change my payment address"
* "I moved and need to update my address"
* "I want to add a new address and set it as default"

#### Setup Instructions

<Steps>
  <Step title="Navigate to Actions">
    Go to your [Chatbase dashboard](https://www.chatbase.co/dashboard/) and select the agent connected to your Shopify store. Click **Actions** at the top of the page.
  </Step>

  <Step title="Create the Action">
    Click **Create Action** and choose **Shopify update address**.
  </Step>

  <Step title="Configure Action Details">
    **Action Name:** Enter a descriptive name for the action (e.g., "Update Billing Address").

    **When to use:** Provide clear instructions for when the AI should trigger this action. For example:

    * Use this action when the user wants to update their billing address
    * Use this action when the user mentions they moved or changed addresses
    * Use this action when the user asks to change their payment address

    <Frame>
      <img alt="Shopify Update Address" />
    </Frame>
  </Step>

  <Step title="Save and Enable">
    Click **Save** and ensure the action is toggled to **Enabled**.

    <Check>
      Test the action by asking your agent to update a billing address.
    </Check>

    <Frame>
      <img alt="Shopify Update Address in action" />
    </Frame>

    <Info>
      **This action cannot be tested in the Action Preview on the dashboard, as it requires the user to be authenticated in order to work properly.**
    </Info>
  </Step>
</Steps>

***

## Best Practices

<CardGroup>
  <Card title="Clear Action Triggers" icon="bullseye">
    Write specific "When to use" descriptions to help the AI agent accurately determine when to trigger each action. Include example phrases customers might use.
  </Card>

  <Card title="Test Thoroughly" icon="flask">
    Test each action with various customer queries before going live. Verify that product searches return accurate results and order lookups display correct information.
  </Card>

  <Card title="Keep Products Synced" icon="rotate">
    Monitor your product sync status regularly. If you notice discrepancies, you can manually trigger a resync from the action settings.
  </Card>

  <Card title="Combine Actions" icon="layer-group">
    Enable multiple actions together to provide a complete shopping experience. Customers often need to search products, check their cart, and track orders in the same conversation.
  </Card>
</CardGroup>


# Slack
Source: https://chatbase.co/docs/user-guides/chatbot/actions/slack



### Slack message sending

Enabling this action allows your dashboard to send a message to your Slack channel whenever the user mentions any topic that you want to be notified with. 

Check the steps to integrate Slack with Chatbase through this page.

1. Click on the **Create Action** button of Slack in the AI Actions menu:

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

2. Choose the Slack workspace that you want to be connected with this Action:

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

3. In the **When to use** section, provide a detailed description explaining when we should use this action. Include examples of the data this action provides and customer queries it helps answer.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

4. Click on Save button.

5. Make sure to enable this action to allow us to send a message to your Slack channel.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

Now, you can try this action in the Playground on the right side of the page. It's recommended to try sending a message in the Action preview to ensure that the AI agent sends a message to your Slack channel when the desired instructions are fulfilled before enabling the action.

Examples:

"Call this tool to send a message in slack to the channel named: ai-actions-slack whenever the user mentions any of the following topics: standard plan"

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

Once the user mentioned the professional plan, a Slack notification is sent to the channel connected to this action:

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>


# Stripe Actions
Source: https://chatbase.co/docs/user-guides/chatbot/actions/stripe-action

Automate billing and subscription management with powerful Stripe actions

## Overview

Stripe Actions enable your AI agent to seamlessly handle customer billing inquiries, subscription management, and account updates directly within the chat interface. These actions provide secure, real-time access to customer payment information, streamlining support operations and enhancing customer experience.

<Info>
  **Prerequisites Required**: Before using Stripe Actions, you must:

  1. [Set up Stripe integration](/docs/user-guides/integrations/stripe) with your Chatbase account
  2. Configure [identity verification](/docs/developer-guides/identity-verification) for secure customer authentication
  3. Set up [contacts](/docs/user-guides/chatbot/contacts/contacts-overview) with valid `stripe_account` fields for each customer
</Info>

## How Stripe Actions Work

Stripe Actions leverage Chatbase's identity verification system to securely access customer-specific data. Here's the workflow:

1. **User Authentication**: Customers must be identified using `window.chatbase("identify", {...})` with their unique user ID
2. **Contact Matching**: The system matches the authenticated user ID to a contact record containing their Stripe account id.
3. **Secure Data Access**: Actions retrieve only the data associated with the authenticated customer's Stripe account
4. **Real-time Responses**: AI agent provides immediate answers using live Stripe data

<Warning>
  **Environment Limitations**: Stripe Actions will not function in:

  * Chatbase Playground environment
  * Action Preview mode
  * Compare features

  Testing this action should be done in your actual website environment. Embed the [JavaScript script](/docs/developer-guides/javascript-embed) in your website and test the action.
</Warning>

## Available Stripe Actions

### 1. Get Subscription Information

Retrieve and display customer subscription details including current plan, status, billing cycle, and pricing information.

<Card title="Best for:" icon="credit-card">
  Answering questions about current subscription status, plan details, renewal dates, and subscription history.
</Card>

**Common Use Cases:**

* "What's my current plan?"
* "When does my subscription renew?"
* "How much am I paying monthly?"
* "Is my subscription active?"

#### Setup Instructions

<Steps>
  <Step title="Create the Action">
    Navigate to **Actions** → **Create Action** and select **Stripe Get Subscription Info**.

    <Frame>
      <img alt="Selecting get subscription action from Stripe options" />
    </Frame>
  </Step>

  <Step title="Configure Action Details">
    **Action Name:** Enter a unique name for the action.

    **When to use:** Provide detailed instructions for when the AI should use this action.
  </Step>

  <Step title="Save and Enable">
    Click **Save** and toggle the action to **Enabled** to make it available to your AI agent.

    <Frame>
      <img alt="Configuring get subscription action with name and usage instructions" />
    </Frame>

    <Check>
      Test the action in the embedded widget to ensure it correctly retrieves subscription data for authenticated users.
    </Check>
  </Step>
</Steps>

### 2. Get Invoice History

Retrieve and display customer invoice history, payment details, and billing records.

<Card title="Best for:" icon="receipt">
  Providing access to billing history, payment confirmations, invoice downloads, and payment troubleshooting.
</Card>

**Common Use Cases:**

* "Show me my recent invoices"
* "Was my payment processed?"
* "Can you provide my billing history?"

#### Setup Instructions

<Steps>
  <Step title="Create the Action">
    Select **Stripe Get Invoices** from the action creation dialog.

    <Frame>
      <img alt="Selecting get invoices action from Stripe options" />
    </Frame>
  </Step>

  <Step title="Configure Action Details">
    **Action Name:** Enter a unique name for the action.

    **When to use:** Provide detailed instructions for when the AI should use this action.
  </Step>

  <Step title="Save and Test">
    Save the configuration and test with a sample customer request in the embedded widget.

    <Frame>
      <img alt="Configuring get invoices action with detailed usage instructions" />
    </Frame>
  </Step>
</Steps>

### 3. Manage Subscriptions

Comprehensive subscription management including plan changes, upgrades, downgrades, and cancellations.

<Card title="Best for:" icon="credit-card">
  Complete subscription lifecycle management, plan changes, adding payment methods and cancellation handling.
</Card>

**Common Use Cases:**

* "I want to upgrade my plan"
* "Upgrade my plan to the pro"
* "I need to cancel my subscription"
* "What plans are available?"

#### Setup Instructions

<Steps>
  <Step title="Create the Action">
    Select **Stripe** → **Manage Subscriptions** from the Stripe action options.
  </Step>

  <Step title="Configure Subscription Options">
    **Action Name:** Enter a unique name for the action.

    **When to use:** Provide detailed instructions for when the AI should use this action.

    <Frame>
      <img alt="Configuring subscription management action with comprehensive options" />
    </Frame>
  </Step>

  <Step title="Define Available Plans">
    Configure which subscription plans and options are available for customers to choose from:

    <Tabs>
      <Tab title="Plan Configuration">
        Set up available plans with their behavior.

        <Frame>
          <img alt="Configuring available subscription plans and options" />
        </Frame>
      </Tab>

      <Tab title="Cancellation Settings">
        Configure cancellation policies and refund handling.

        <Frame>
          <img alt="Configuring available subscription plans and options" />
        </Frame>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Test All Scenarios">
    Thoroughly test various subscription management scenarios:

    <AccordionGroup>
      <Accordion title="Upgrade Testing">
        Test upgrading from basic to premium plans with proper proration calculations.
      </Accordion>

      <Accordion title="Downgrade Testing">
        Verify downgrades work correctly with appropriate billing adjustments.
      </Accordion>

      <Accordion title="Cancellation Flow">
        Test the complete cancellation process.
      </Accordion>
    </AccordionGroup>

    <Frame>
      <img alt="Testing subscription management action with comprehensive options" />
    </Frame>

    <Check>
      All subscription changes should be immediately reflected in both Stripe and the customer experience.
    </Check>
  </Step>
</Steps>

### 4. Change Billing Information

Allow customers to update their billing address and other account information.

<Card title="Best for:" icon="address-card">
  Self-service billing updates, address changes and other account information updates.
</Card>

**Common Use Cases:**

* "I need to update my billing address"
* "Update my billing email address"
* "Update my billing phone number"

#### Setup Instructions

<Steps>
  <Step title="Create the Action">
    Select **Stripe** → **Change customer information** from the available Stripe actions.

    <Frame>
      <img alt="Selecting change billing address action" />
    </Frame>
  </Step>

  <Step title="Configure Action Details">
    **Action Name:** Enter a unique name for the action.

    **When to use:**
    Provide detailed instructions for when the AI should use this action.
  </Step>

  <Step title="Test Security Measures">
    Test the action with various scenarios to ensure only authenticated users can make changes.

    <Frame>
      <img alt="Testing change billing address action" />
    </Frame>

    <Check>
      Verify that billing information updates are reflected in both Stripe and the customer's account.
    </Check>
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Action Not Triggering">
    **Possible causes:**

    * Action is disabled in the dashboard
    * User is not properly authenticated
    * Contact record missing or invalid `stripe_account`
    * Insufficient "When to use" description

    **Solutions:**

    * Enable the action and verify configuration
    * Check identity verification implementation
    * Validate contact record has correct `stripe_account` field
    * Enhance action description with more specific use cases
  </Accordion>

  <Accordion title="No Data Returned">
    **Possible causes:**

    * Invalid Stripe customer ID in contact record
    * Stripe account has no subscription or invoice data
    * Stripe API permissions insufficient
    * Network connectivity issues

    **Solutions:**

    * Verify Stripe customer ID exists and is active
    * Check Stripe account has relevant data
    * Review Stripe integration permissions
    * Test Stripe API connectivity directly
  </Accordion>

  <Accordion title="Authentication Errors">
    **Possible causes:**

    * User hash validation failing
    * `external_id` doesn't match `user_id`
    * Contact record not found
    * Identity verification not called

    **Solutions:**

    * Verify hash generation matches expected format
    * Ensure `external_id` exactly matches authenticated `user_id`
    * Create contact record for the user
    * Implement proper identity verification flow
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup>
  <Card title="Security First" icon="shield-check">
    Always validate user identity before processing any billing-related requests. Never allow unauthenticated access to financial data.
  </Card>

  <Card title="Testing Coverage" icon="flask">
    Thoroughly test all actions with various user scenarios, edge cases, and error conditions before going live.
  </Card>
</CardGroup>


# Web Search
Source: https://chatbase.co/docs/user-guides/chatbot/actions/web-search



### Web Search

The Web Search action allows the AI Agent to browse the web for information and feed the results back to the AI Agent. 

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

#### When to use

This is where you specify the name of the Action and when exactly this action should be triggered or what type of customer queries would trigger it. You can also add in some instructions that the bot should adhere to when this action is triggered.

The web search action can be used as an additional source of information where the AI agent can get some information that isn't available in the sources. It's recommended to add websites that are related to your business field. 

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

#### Include images

This allows the AI agent to provide images as replies to the users elaborating the answer provided.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

#### Included domains

This option allows you to add specific domains that the AI agent can use to search the answer. If you didn't add any domains, the AI agent will search over the whole web. 

Once you're done, press Enable and your Action will be live and ready for your Agent to use.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>


# Activity
Source: https://chatbase.co/docs/user-guides/chatbot/activity

This section shows the chat logs of the conversations your users had with your AI agent and the Lead forms filled by your users.

## Chat Logs

The chat logs provides a detailed view of all user interactions with your AI agent. It allows you to review individual conversations and evaluate your agent's responses. Each log includes user messages, agent responses, and any triggered actions, helping you identify issues, optimize responses, and improve overall user experience.

<Frame>
  <img alt="AI agent Activity Filters" />
</Frame>

The chat logs can be filtered by the following:

* Date
* Confidence Score
* Source
* Feedback
* Sentiment
* Topic

  <Frame>
    <img alt="AI agent Activity Filters" />
  </Frame>

<br />

**Improve Answer**

This feature allows you adjust the AI Agent's response if it wasn't accurate or satisfactory.

When you click the Improve Answer button, a form appears showing the user's original question, the AI Agent's response, and a field where you can enter the expected answer.
Once the answer is updated, the question and answer are added automatically to the Q\&A section of your sources. 

<Frame>
  <img alt="Improve Answer Feature" />
</Frame>

### Confidence Score

This indicates how confident the AI Agent is in its response based on the sources you've trained it on. You can review responses with low confidence scores and revise them to improve their accuracy.

### Exporting Conversations

You can export the conversations in the chats log directly from the dashboard using the Export button. The export can be downloaded as JSON, PDF, and CSV.

<Frame>
  <img alt="Exporting Conversations" />
</Frame>

## Leads

This section shows the submissions of the Leads form along with their submission date. You can filter them by date and export them as CSV or PDF.

<Frame>
  <img alt="Leads Activity" />
</Frame>

The leads form  can be configured through the settings page of the AI agent or through [the Collect Leads action](./actions/collect-leads)


# Analytics
Source: https://chatbase.co/docs/user-guides/chatbot/analytics



## Chats

This tab displays the Analytics and activity of the AI Agent during the conversations. The tab includes three sections: Chats, Topics and Sentiment.

By default, it shows the activity for all AI Agents under your workspace for the last week.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

It shows the total number of chats, total number of messages, the messages that had thumbs up from the users and the messages that had thumbs down.

The graph below shows the number of chats per country. The countries are detected from the IP of the users having conversations with the AI Agent.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

You can always filter the data by date. There are pre-defined date filters such as last 7 days, last 30 days, last 3 months and last year.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

## Topics

This section shows the topics that were included in the conversations and mentioned by the users.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

Topics Actions:

* Search topics
* Add topic
* Edit topic
* Delete topic
* Freeze topics: Stopping the AI Agent to detect any topics automatically.

The topics are detected automatically by the AI Agent. However, you can add topics manually in the View All button in the the right of the page:

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

## Sentiment

This section shows how the AI Agent detects the sentiment and emotion of the users during the conversations. The sentiment analysis is detected automatically by the AI Agent.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

## Notes

Analytics data is updated with a 1-day delay, reflecting the previous day's information.

Data is recorded once the user subscribes to a specific plan. Topics and sentiment data will only be available after the upgrade; any data from before the upgrade will not be included.

The Activity Tab shows data per chat for users, while the Analytics Tab aggregates the information, including topics, sentiment, and thumbs down.

Analytics can be viewed as either a pie chart or a graph.

The analytics page displays the total number of messages, including all conversation messages. However, credits are only calculated for AI-generated responses, excluding the initial messages.


# Contacts Overview
Source: https://chatbase.co/docs/user-guides/chatbot/contacts/contacts-overview

Learn how to use contacts to enable personalized, secure interactions between your users and AI agents.

Contacts allow you to store and manage user data that your AI agent can access during conversations, enabling personalized interactions while maintaining security and privacy.

## How Contacts Work

Contacts bridge the gap between anonymous visitors and identified users in your system. When users interact with your agent, you can link their session to stored contact data to provide personalized experiences.

<Info>
  Unlike anonymous visitors, contacts represent users who are authenticated and identified within your business system.
</Info>

### The Identification Process

<Steps>
  <Step title="Create contacts">
    Upload user data to Chatbase using the [Contacts API](/docs/api-reference/contacts/create-contacts-for-a-chatbot) or manage them through the dashboard.

    <Note>
      **Recommended:** Use [JWT identity verification](/docs/developer-guides/identity-verification#method-1%3A-jwt-recommended) to automatically create and update contacts when users interact with your agent. This eliminates the need for separate API calls.
    </Note>
  </Step>

  <Step title="Verify user identity">
    When users interact with your agent, use [identity verification](/docs/developer-guides/identity-verification) to securely link them to their contact data.

    <Note>
      The `user_id` from your verification must match the `external_id` of a contact for the data to be accessible.
    </Note>
  </Step>

  <Step title="Enable personalized interactions">
    Once linked, your agent can access contact data to provide personalized responses and perform actions on behalf of the user.
  </Step>
</Steps>

## Key Benefits

<CardGroup>
  <Card title="Secure data storage" icon="shield-check">
    User data is encrypted and access-controlled, ensuring privacy and compliance.
  </Card>

  <Card title="Personalized conversations" icon="user">
    Agents can reference user-specific information to provide tailored responses.
  </Card>

  <Card title="Actions integration" icon="bolt">
    Contact data powers actions, enabling agents to perform user-specific operations such as [Stripe actions](/docs/user-guides/chatbot/actions/stripe-action).
  </Card>

  <Card title="Data synchronization" icon="arrows-rotate">
    Keep Chatbase contacts in sync with your external systems and databases.
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Getting Started" icon="rocket" href="/user-guides/chatbot/contacts/getting-started">
    Learn how to get started with contacts.
  </Card>

  <Card title="Identity Verification" icon="key" href="/developer-guides/identity-verification">
    Implement secure user identification to link sessions with contact data.
  </Card>
</CardGroup>


# Uploading Contacts
Source: https://chatbase.co/docs/user-guides/chatbot/contacts/uploading-contacts



Bulk contact import lets you upload multiple contacts at once through a guided import flow in your agent’s **Contacts** page.

You can use this to:

* Quickly add new contacts
* Update existing contacts by External ID
* Import custom attributes in bulk

***

## Import contacts

The import flow consists of four steps.

### Upload file

Upload a `.csv` or `.xlsx` file by dragging it into the upload area or clicking to select a file.

> **Limits**
>
> * Maximum file size: **5 MB**
> * Maximum rows per upload: **1,000**

You can also download a CSV template with the correct headers.

The template includes:

* Standard contact fields
* Any custom attributes defined for the AI agent

***

### Map columns

After uploading your file, Chatbase automatically matches your file headers to contact fields.

Supported fields include:

* External ID
* Name
* Email
* Phone
* Custom attributes

You can manually adjust mappings using the dropdown menus.

> **Important**
>
> External ID is required. You must map a column to **External ID** before continuing.

#### Mapping rules

* Each CSV header can only be mapped to one field
* Custom attributes appear automatically during mapping
* Unmapped columns are ignored during import

***

### Review and confirm

Before importing, Chatbase displays a paginated preview table with all mapped rows.

Each row is validated against existing contacts and duplicate values.

#### Duplicate handling

| Condition                                        | Result                                                     |
| ------------------------------------------------ | ---------------------------------------------------------- |
| Duplicate External ID in the file                | Row is blocked                                             |
| Duplicate email or phone in the file             | Row is blocked                                             |
| Email or phone already exists in another contact | Row is blocked                                             |
| External ID already exists                       | Row is marked as **Update** to update the existing contact |
| Missing External ID                              | Row is automatically excluded                              |

Rows marked as **Update** will update the existing contact with the same External ID.

You can hover over warning icons or the **Update** badge to see more details, including which fields will change.

> **Note**
>
> Phone numbers are normalized to E.164 format before duplicate checks are performed.

#### Row selection

You can:

* Select individual rows
* Deselect rows you do not want to import
* Use the **Select all** checkbox

***

### Completing the Import

After the import completes, Chatbase displays the import results.

This includes:

* Number of successful imports
* Number of failed rows
* Detailed error messages for failed rows

Example error:

```text theme={null}
A contact with this email already exists
```

You can retry failed rows or close the dialog.

***

## Add a single contact

Contacts can also be added individually.

Go to:

```text theme={null}
Dashboard → AI Agent → Contacts → Add Contact
```

The form includes:

* External ID
* Name
* Email
* Phone
* Any Custom attributes

> **Important**
>
> External ID is required when creating a contact manually.

***

## Custom attributes

Custom attributes allow you to store additional information about contacts.

Manage them from:

```text theme={null}
Contacts → Manage Attributes
```

### Supported attribute types

* Text
* Number
* Boolean
* Date

### Behavior

* Custom attributes appear during import mapping
* Custom attributes appear in the contacts table
* Archived attributes are hidden from forms
* Archived attribute data is preserved


# Data sources
Source: https://chatbase.co/docs/user-guides/chatbot/data-sources



The Data sources tab in the Chatbase dashboard is where you manage all the content that powers your AI agent. It allows you to upload documents, add structured text snippets, crawl websites or sitemaps, create custom Q\&As, integrate with Notion, and import support tickets (requires Salesforce or Zendesk integration via OAuth). These options give you full control over the information your agent is trained on, helping ensure accurate, relevant, and up-to-date responses for your users.

<Tip>
  **Standard** and **Pro** plans include [Auto Retrain](#auto-retrain), which automatically updates your agent's knowledge base every 24 hours.
</Tip>

## Files

The Files tab within the Data sources section of Chatbase allows you to upload and manage various document types to train your AI agent.

### Supported File Types

Chatbase supports the following file formats:

* .pdf (PDF Documents)
* .txt (Plain Text Files)
* .doc / .docx (Microsoft Word Documents)

### Uploading Files

1. Click the Upload Files button.
2. Select one or multiple documents from your device.
3. The files will enter a queue and be uploaded one by one.
   Each file remains in the queue until it has been successfully processed. You can monitor the status of each upload in real time.

<Frame>
  <img alt="Uploading Files" />
</Frame>

### Preview and Metadata

After upload:

* Click on any document to preview its contents directly within the dashboard.
* You can view timestamps indicating exactly when each file was added and last updated.
  This allows you to easily track and verify your training sources over time.

  <Frame>
    <img alt="Preview Files" />
  </Frame>

### File Deletion

* Delete files individually by pressing on the three dots then clicking ‘delete’.
* To delete all files at once, first select the checkbox next to ‘File sources’ to select all documents. Once selected, a Delete button will appear—click this to remove all selected files in one action.

<Frame>
  <img alt="Deleting Files" />
</Frame>

## Text Snippets

The Data sources tab also allows you to add and manage text snippets, providing a flexible way to organize custom content for your AI agent's training. This feature is ideal for maintaining smaller, structured pieces of information separate from document uploads.

### Adding Text Snippets

You can create and store multiple text snippets, each with a unique title to help you easily identify the content at a glance. This is particularly useful for segmenting information by topic, department, or use case.

Text Editing Features
Each snippet can be fully customized using rich text formatting:

* Add headings for clarity
* Format with bold, italic, or strikethrough
* Create ordered or bullet lists
* Insert hyperlinks to external sources
* Include emojis to enhance tone and readability

You can also expand the text input area for better visibility and ease of editing long-form content.

<Frame>
  <img alt="Edit Text" />
</Frame>

### Preview and Metadata

After creating a snippet:

* Click on it to preview or edit the content at any time.
* View precise timestamps showing when the snippet was added and last updated.

### Snippet Deletion

* Delete snippets individually by pressing on the three dots then clicking ‘delete’.
* To delete all snippets at once, first select the checkbox next to 'Text snippets' list to select all snippets. Once selected, a Delete button will appear—click this to remove all selected snippets in one action.

## Website Crawling

The Website Crawling feature in the Data sources tab enables you to train your AI agent using content directly from websites. Whether you're working with a full site, a sitemap, or individual URLs, this tool gives you flexible control over what gets included in your agent's knowledge base.

<Info>
  If you're using Shopify, it’s recommended to add your sitemap (/sitemap.xml) instead of crawling the entire website. This reduces total MB usage and avoids duplicate product and collection pages, since Shopify’s sitemap already provides a clean, structured source of your content.
</Info>

### Crawling Options

You have three ways to fetch content from the web:

1. Crawl a full website – Provide the homepage URL and let Chatbase discover all public pages.
2. Submit a sitemap – Point to an XML sitemap to fetch a structured list of URLs.
3. Add individual links – Manually input specific URLs you want to include.

For website crawling and sitemap submission, you can refine your crawl using:

* Include Paths – Only URLs matching these paths will be fetched.
* Exclude Paths – URLs matching these paths will be skipped.

You can specify multiple paths in both fields, make sure to press the space bar after each one.

Multiple websites or links can be crawled in parallel for efficiency.

<Frame>
  <img alt="Crawl Website" />
</Frame>

### Grouping and Link Management

After crawling a website, Chatbase displays all discovered links so you can review exactly what content your agent will be trained on. Links are automatically grouped into three categories:

**Trained**

These are pages that were successfully crawled and contain valuable content that can be used to train your AI agent — such as product pages, blog posts, and documentation pages.

**Not Found**

These are links that could not be accessed during crawling, usually because the page does not exist or returned an error — such as broken links, deleted pages, and redirect issues.

**Excluded**

Excluded links are pages that are intentionally skipped because they do not contain useful training content for your AI agent — such as login pages, signup pages, and duplicate pages.

<img alt="Edit Website" />

### Editing and Excluding Links

After crawling:

* You can  exclude specific links from a group if you don't want them used in training.

- You can edit include/exclude paths anytime through 'Advanced options', recrawl the website, and update your AI agent accordingly.

<img alt="Edit Website" />

### Link and Group Deletion

You have full control over link cleanup:

* Delete individual links from a group by excluding it.
* Deleting an entire group of links (i.e., all pages fetched from a domain).
* Deleting all the groups at once by selecting the three dots next to the website.

## Custom Q\&A Training

The Q\&A feature in Chatbase lets you train your AI agent with custom question-and-answer pairs, enabling it to respond precisely to frequently asked or business-specific queries.

### Creating Q\&As

* Each Q\&A entry begins with a title, this helps you quickly locate and organize questions.
* You can associate multiple variations of a question with a single answer, improving recognition and response accuracy.
* You can bulk upload Q\&As up to 100 rows per file in .xlsx format, with a maximum file size of 1MB.

### Editing Answers

Answers are fully customizable with rich text formatting tools. You can:

* Add headings for clarity
* Format with bold, italic, or strikethrough
* Create ordered or bullet lists
* Insert hyperlinks to external sources
* Include emojis to enhance tone and readability

  <Frame>
    <img alt="Adding Q&A" />
  </Frame>

### Usage Insights

Click on any Q\&A to open its detail view, where you'll find real-time usage metrics:

* number of times the question has been asked by users (updated instantly)
* Last time the question was asked
* Date the Q\&A was added
* A visual chart showing the frequency of the question over time

These insights help you identify which topics matter most to your users and prioritize updates accordingly.

<img alt="Adding Q&A" />

### Management & Deletion

* Delete any Q\&A individually.
* To delete all at once, check the box next to "Q\&A sources" and click the delete button that appears.

## Notion

This integration enables your AI agent to access and utilize information stored in your Notion databases.

## Auto Retrain

Auto Retrain automatically keeps your AI agent up-to-date by pulling the latest content from your data sources every week. This ensures your agent always has access to the most current information without requiring manual intervention.

<Info>
  Auto Retrain is available on **Standard** and **Pro** plans only. Hobby plan users will need to manually retrain their agent after updating sources.
</Info>

### Supported data sources

Auto Retrain works with the following source types:

* **Website** - Discovers newly added links and updates existing page content
* **Notion** - Syncs changes from your connected Notion workspace
* **Remote storage** - Google Drive, Dropbox, and other remote sources (when available)

### How It Works

* Your agent automatically fetches new content from all connected data sources once every 24 hours
* Newly added pages or links on your website are automatically discovered and included
* No manual action is required—updates happen in the background

## Tickets

The Tickets feature in the Data sources tab enables you to train your AI agent using support tickets from integrated platforms. This requires an active Salesforce or Zendesk integration to be set up first. If no integrations are configured, you'll be prompted to set one up via OAuth.

### Integration Selection

You can import tickets from Salesforce or Zendesk. Select the platform to train on tickets from—you can switch between integrations as needed,
but training occurs from only one at a time.

* **Import from Salesforce**: Requires Salesforce integration. Link to [/user-guides/integrations/salesforce](/docs/user-guides/integrations/salesforce) for OAuth setup details.
* **Import from Zendesk**: Requires Zendesk integration. Link to [/user-guides/integrations/zendesk](/docs/user-guides/integrations/zendesk) for OAuth setup details.

After selecting the integration, click "Save" to confirm. Multiple integrations cannot be active for training simultaneously. Switch integrations by updating your selection and re-importing tickets.

<Frame>
  <img alt="Integration Prompt for Zendesk/Salesforce" />
</Frame>

### Importing Tickets

1. Ensure the desired integration is selected.
2. Ensure training on tickets is enabled.
3. Click the save button.
4. Click Retrain Chatbot.

Now the next training will fetch your tickets from the selected integration and train on them.

<Frame>
  <img alt="Select Integration Options" />
</Frame>

### Limitations

Currently, tickets cannot be filtered (e.g., by status or date), and ticket sources cannot be previewed, edited, or deleted individually.
All eligible tickets from the active integration are imported.

Ensure your integration has the necessary permissions to access ticket data. Press the "Retrain agent" button after enabling or disabling training on tickets.

## General Notes

* When uploading files, make sure they contain selectable text.
* All data should be in plain text, using mark-down language is preferred.
* When integrating with a Notion account that's on a paid plan, make sure you have admin access to provide all necessary permissions for the integration to be successful.
* Make sure to press on the "Retrain agent" button after you're done adding/deleting/updating your sources.


# Deploy
Source: https://chatbase.co/docs/user-guides/chatbot/deploy

Deploy your Chatbase agent across web, messaging, phone, and productivity channels.

The **Deploy** tab lets you make your agent available to users across multiple channels, including your website, a standalone help page, and third-party platforms like Slack, Email, WhatsApp, and Phone.

You can enable one or multiple deployment channels depending on how you want users to interact with your agent.

<Frame>
  <img alt="Deploy Channel" />
</Frame>

***

## All Channels Overview

The Deploy page shows all available channels for your agent. Each channel can be enabled, configured, and managed independently.

Available channels include:

* **Chat widget** — A floating chat widget embedded on your website
* **Help page** — A standalone help page hosted by Chatbase
* **Email** — Let your agent respond to emails
* **Phone** — Let your agent handle inbound phone calls via Twilio
* **Slack** — Use your agent inside Slack
* **Zapier** — Connect your agent to thousands of apps
* **WordPress** — Official WordPress plugin
* **WhatsApp** — Respond to WhatsApp messages
* **Messenger** — Connect your agent to Facebook Messenger
* **Instagram** — Let your agent respond to Instagram messages
* **Zendesk** — Respond to Zendesk support tickets
* **Salesforce** — Connect your agent to Salesforce to assist with CRM workflows
* **Shopify** — Connect your agent to your Shopify store

Use the toggle or **Manage** button on each channel to configure it.

***

## Chat Widget

The **Chat widget** allows you to embed a floating chat window on your website so visitors can interact with your agent directly.

### Enable the Chat Widget

1. Go to **Deploy → Chat widget**
2. Toggle **Enabled** on

Once enabled, you can customize its behavior, appearance, and embed settings.

***

### Content Settings

Under the **Content** tab, you can control what users see when the chat starts.

<Frame>
  <img alt="Chatbase Content Settings" />
</Frame>

* Display name: The name shown at the top of the chat widget.
* Initial message: The message shown before the user opens the chat bubble, designed to grab attention and encourage interaction, also shown once the user opens the bubble. You can customize the initial message per user by following [this guide](/docs/developer-guides/custom-initial-messages)
* Suggested messages: Predefined prompts shown when users open the chat to help them start the conversation quickly. These should reflect your most common questions or actions. You can also use the nested option to group related prompts under a main message, allowing users to select a category first and then choose from more specific follow-up options for a more guided experience.
* Message placeholder: The text shown in the field where the users write their questions.
* Collect feedback: When enabled, it allows the user to provide a feedback by displaying a thumbs up or down button on AI agent messages.
* Copy messages: When enabled, a copy button on agent messages is displayed to allow users to copy the response.
* Dismissable notice: A message shown above the text input area that disappears after the user sends a message.
* Footer: Text shown in the button of the chat. You can use this to add a disclaimer or a link to your privacy policy.
* Auto show initial messages pop-ups after: You can set it to negative to disable.
* Enable voice to text: When enabled, a microphone button is shown in the text input area that converts speech into text for users to review before sending.
* Enable attachments:  Enable or disable sending attachments, allowing your agent to process attachments and respond based on their content.

<Info>
  If you include links in the footer or a dismissible notice, they must be full URLs starting with `http://` or `https://` <br />  <br />
  (e.g., `https://www.example.com`), not just `www.example.com` or `example.com`
</Info>

#### Localization

The Chat Widget supports localization, allowing you to translate action buttons and interface text into multiple languages.

The widget automatically displays in the visitor’s **browser language** if it matches one of the configured languages. If no match is found, the **default language** is used.

<Frame>
  <img alt="Chatbase Content Settings" />
</Frame>

You can add multiple languages by clicking **Add language** and selecting from the available list, including right-to-left (RTL) languages.

<Frame>
  <img alt="Chatbase Content Settings" />
</Frame>

One language must be set as the **default**. This language is used when the browser language cannot be detected or is not supported.

<Frame>
  <img alt="Chatbase Content Settings" />
</Frame>

Once a language is enabled, action buttons and menu items in the chat widget are automatically translated, such as starting a new conversation, ending a conversation, and viewing previous conversations.

<Frame>
  <img alt="Chatbase Content Settings" />
</Frame>

#### Attachments

Chatbase allows your end-users to upload attachments during conversations. The AI agent can analyze supported files and generate responses based on their content.

**Supported Attachment Formats**

* Images: .png, .jpg, .jpeg
* Documents: .pdf

<Info>
  Some platforms (such as Instagram, Messenger, and WhatsApp) may allow users to upload additional file types (e.g., GIF). These formats are not supported. Any unsupported file types will be automatically discarded and not processed.
</Info>

**Attachment Limits**

To maintain performance and reliability, the following limits apply (any ):

* Maximum attachments per message: 5 files
* Maximum file size: 5 MB per file
* Maximum PDF length: 5 pages per file
* Maximum characters per PDF page: 2,000 token (\~8,000 characters)

Any attachments that exceed these limits will be **ignored and not processed.**

**Billing**

When a message contains attachments, the total credits consumed include **both the text response and the attachments processed**.

Each AI model has separate pricing for:

* Text requests
* Image analysis
* PDF file analysis (per page)

So for every reply the agent generates:

* Credits are consumed for the **text response**
* Additional credits are consumed for **each attachment**
  * **Images:** charged per image
  * **PDFs:** charged per page

**Example (Model cost = 1 credit)**

| Message                           | Credit Calculation                            | Total |
| --------------------------------- | --------------------------------------------- | ----- |
| `Hi`                              | 1 (text)                                      | **1** |
| `Hi + 1 image`                    | 1 (text) + 1 × 1 (image)                      | **2** |
| `Hi + 2 images`                   | 1 (text) + 2 × 1 (image)                      | **3** |
| `Hi + 1 PDF (3 pages)`            | 1 (text) + 3 × 1 (PDF pages)                  | **4** |
| `Hi + 2 images + 1 PDF (3 pages)` | 1 (text) + 2 × 1 (images) + 3 × 1 (PDF pages) | **6** |

**Actions + Attachments**

If the message triggers an **action** (for example booking a meeting), the attachments are processed more than once.

They are charged once when the action is executed, and again when the agent generates a response.

**Example (Model cost = 1 credit)**

| Message                           | Credit Calculation                           | Total |
| --------------------------------- | -------------------------------------------- | ----- |
| `Hi + 1 image` (action triggered) | 1 (text) + 1 × 1 (image) (processing action) | **2** |
| `Agent response` (after action)   | 1 (text) + 1 × 1 (image) (generating reply)  | **2** |
| `Total for this message`          | 2 + 2                                        | **4** |

In this case, the image is billed twice: once when processing the action, and again when generating the agent’s response.

**Other Supported Channels**

* Help Page
* E-mail
* Instagram
* Messenger
* WhatsApp

***

### Style Settings

The **Style** tab lets you customize the visual appearance of the chat widget, including colors, theme, and layout.\
Changes are previewed in real time.

Use this section to match the widget to your brand.

* Theme: Light or Dark
* Profile picture: Picture of the AI agent when providing answers.
* Chat Icon: The icon appearing on the website to display the AI agent.
* Primary Color: The accent color used for the user’s message bubbles. You can optionally apply this color to the chat header.
* Chat Bubble Button Color
* Align Chat Bubble Button: Left or Right

<Frame>
  <img alt="Chatbase Style Settings" />
</Frame>

***

### AI Settings

The **AI** tab controls how the agent behaves inside the widget, including response behavior and AI-specific options.

#### Sync with Base Instructions

By default, your agent uses **Base instructions**, which define its core behavior across all channels.

When **Sync with base instructions** is enabled, the chat widget will use the same base instructions as the rest of your agent.

When this setting is disabled, you can define **channel-specific instructions** that apply only to the chat widget and override the base instructions for this channel.

***

### Embed

The **Embed** tab provides the code needed to add the chat widget to your website.

#### Allowed Domains

You can restrict where your agent is allowed to load by specifying approved domains.

When enabled, the agent will only work on the domains listed here.

#### Chat Widget (Recommended)

Embed a floating chat bubble on your website.

* Supports all advanced features of the agent
* Fully customizable using the Content, Style, and AI tabs
* Best option for most use cases

#### iFrame

Embed the chat interface directly using an iframe.

* Simple to integrate
* **Advanced features are not supported**
* Recommended only if iframe embedding is required by your setup

You can copy the embed script and paste it into your site’s HTML, typically before the closing `<body>` tag.

***

## Help Page

The **Help page** is a standalone page hosted by Chatbase.\
It’s ideal for help centers, documentation portals, or internal tools.

### Enable the Help Page

1. Go to **Deploy → Help page**
2. Toggle **Enabled** on

<Frame>
  <img alt="Chatbase Help Page" />
</Frame>

***

### Settings

* Page title: The title shown in the browser tab.
* Favicon: Upload a custom favicon for the help page. Supports JPG, PNG, and SVG files up to 1MB.
* Theme settings: Enable or disable theme switching. Set a default theme for all users. Customize light and dark primary colors.
* Enable voice to text: When enabled, a microphone button is shown in the text input area that converts speech into text for users to review before sending.
* Enable attachments:  Enable or disable sending attachments, allowing your agent to process attachments and respond based on their content.
* Logos: Upload a logo for light mode. Upload a separate logo for dark mode.
* Heros: Upload a hero for light mode. Upload a separate logo for dark mode.

***

### Domain Setup

The **Domain setup** tab lets you configure where your help page is hosted.

You can:

* Use the default Chatbase domain
* Deploy the help page under a path on your own domain (for example, `/help`). Check out [this guide](/docs/developer-guides/help-page-proxy) for detailed steps on how to do it.

***

## Third-Party Channels

### Email (Beta)

Connect your agent to an email address and let it respond automatically to incoming messages. Detailed integration steps can be found on [this guide](/docs/user-guides/integrations/email).

Use this for customer support or inbound inquiries.

***

### Slack

Connect your agent to Slack so it can respond to messages when mentioned or messaged directly. Detailed integration steps can be found on [this guide](/docs/user-guides/integrations/slack).

Ideal for internal knowledge bases and team support.

***

### Phone

Let your AI agent handle inbound phone calls via Twilio. Callers are connected directly to your agent, which responds using its configured voice settings and knowledge base. Detailed integration steps can be found on [this guide](/docs/user-guides/integrations/twilio).

***

### Zapier

Use Zapier to connect your agent with thousands of apps and automate workflows. Detailed integration steps can be found on [this guide](/docs/user-guides/integrations/zapier).

***

### WordPress

Use the official Chatbase WordPress plugin to add the chat widget to your WordPress site without writing code. Detailed integration steps can be found on [this guide](/docs/user-guides/integrations/wordpress).

***

### WhatsApp

Connect your agent to a WhatsApp number and let it respond to WhatsApp messages. Detailed integration steps can be found on [this guide](/docs/user-guides/integrations/whatsapp).

***

### Messenger

Connect your agent to a Facebook Page and let it respond to Messenger conversations. Detailed integration steps can be found on [this guide](/docs/user-guides/integrations/messenger).

***

### Instagram

Connect your agent to an Instagram account and let it respond to messages from your customers. Detailed integration steps can be found on [this guide](/docs/user-guides/integrations/instagram).

***

### Zendesk

Connect your agent to Zendesk to create and respond to support tickets from your customers. Detailed integration steps can be found on [this guide](/docs/user-guides/integrations/zendesk).

***

### Salesforce

Connect your agent to Salesforce and use it to assist with CRM workflows, such as answering questions about records, supporting agents, or automating responses inside your Salesforce environment. Detailed integration steps can be found on [this guide](/docs/user-guides/integrations/salesforce).

***

### Shopify

Use the official Chatbase Shopify app to add the chat widget to your Shopify store without writing code. Detailed integration steps can be found on [this guide](/docs/user-guides/integrations/shopify).

***

## Best Practices

* Start with one channel and expand as needed
* Customize prompts and suggested messages per channel
* Test each deployment before sharing it with users
* Use the Help page for structured support and the chat widget for quick assistance

***


# Email settings
Source: https://chatbase.co/docs/user-guides/chatbot/email-settings

Use your AI agent over email with agent emails, forwarding rules, and authenticated domains.

## Overview

The **Email settings** feature lets you use your AI agent as an email support channel.\
You get a unique **agent email** in the format `agent@subdomain.chatbase-mail.com` that you can:

* **Send** emails and automatically **receive** AI-crafted replies.
* **Connect to your own domains and mailboxes**, so customers see messages coming from your email addresses instead of the default `chatbase-mail.com` domain.

<Info>
  You can add up to **3 custom domains**, and up to **20 email addresses per domain**.
</Info>

<Info>
  Attachments are supported, allowing your agent to process them and respond based on their content. For more information, please refer to [this section](/docs/user-guides/chatbot/deploy#attachments).
</Info>

## How it works

* **Agent email**: When you create an AI agent, we generate an email like `agent@subdomain.chatbase-mail.com`.
* **Inbound messages**: Customers send an email to:
  * Your **agent email**, or
  * One of your own addresses (for example, `support@yourdomain.com`) that automatically forwards to the agent email.
* **AI response**: Your agent processes the email and generates a reply.
* **From address**:
  * If you **don’t** connect a domain, replies are sent from your `agent@subdomain.chatbase-mail.com`.
  * If you **do** connect and authenticate a domain, we can send email **on your behalf** (for example, `support@yourdomain.com`), once DNS is correctly configured.

<Note>
  To send emails from your own domain, you must (1) configure automatic forwarding from at least one mailbox on that domain to your agent email, and (2) add the DNS records we provide to your DNS provider.
</Note>

## Prerequisites

* Access to the **Chatbase dashboard** and the AI agent whose email settings you want to configure.
* Admin access to your **email provider** to set up forwarding rules.
* Admin access to your **DNS provider** (domain registrar or DNS host) to add TXT, MX, and/or CNAME records.

## Accessing Email settings

<Steps>
  <Step title="Open your AI agent settings">
    Go to the **Dashboard**, select your AI agent, and open the **Settings** page.

    Then open the **Email settings** section. If you haven't enabled email settings before, you'll need to enable the email channel first.

    <Frame>
      <img alt="Email settings section in the AI agent settings" />
    </Frame>
  </Step>

  <Step title="Locate your agent email">
    You'll see your automatically generated **agent email**, for example:

    `agent@subdomain.chatbase-mail.com`

    <Frame>
      <img alt="Agent email address displayed in Email settings" />
    </Frame>

    You can use this email address to send and receive emails from your AI agent. Learn more about the [email channel](/docs/email-channel).
  </Step>
</Steps>

## Using the agent email directly

You can start using the feature immediately by sending an email to your **agent email**:

1. Send an email from any mailbox to `agent@subdomain.chatbase-mail.com`.
2. The AI agent processes the email content.
3. You receive a reply from the same `agent@subdomain.chatbase-mail.com` address.

<Note>
  To enable AI agent replies, you must first enable the email channel. Learn more about [enabling the email channel](/docs/user-guides/integrations/email).
</Note>

<Check>
  If you receive a reply from your agent email, your basic email channel is working correctly.
</Check>

To use **your own domain and addresses** (for example, `support@yourdomain.com` or `billing@yourdomain.com`), continue with the next sections.

## Step 1 – Add an email address

To configure a custom email address for your AI agent, start by adding the email address you want to use.

<Steps>
  <Step title="Click New email address">
    In **Email settings**, click the **New email address** button to start the setup process.

    <Frame>
      <img alt="New email address button in Email settings" />
    </Frame>
  </Step>

  <Step title="Enter your email address">
    Enter the email address you want to use (for example, `support@yourdomain.com`).

    <Note>
      The domain will be automatically extracted from the email address. You can add up to **3 domains** per workspace and up to **20 email addresses per domain**.
    </Note>

    <Frame>
      <img alt="Enter email address dialog" />
    </Frame>
  </Step>

  <Step title="Continue to forwarding setup">
    Click **Continue** to proceed to the email forwarding configuration step.
  </Step>
</Steps>

## Step 2 – Configure email forwarding

Next, configure automatic forwarding in your email provider so that emails sent to your support addresses are delivered to your agent email.

### Forwarding flow

1. A customer emails `support@yourdomain.com`.
2. Your email provider forwards that message automatically to `agent@subdomain.chatbase-mail.com`.
3. The AI agent processes the email and generates a reply.
4. The response is sent back via email from your authenticated domain.

<Warning>
  You must configure automatic forwarding for at least **one email address on the domain** before you can complete DNS authentication and send from that domain.
</Warning>

### Set up forwarding in your email provider

The exact steps depend on your provider, but the general pattern is:

1. Sign in to your email provider's admin or mailbox settings.
2. Open the **Forwarding**, **Rules**, or **Filters** section.
3. Create a rule that forwards incoming messages from the mailbox (for example, `support@yourdomain.com`) to your **agent email** (`agent@subdomain.chatbase-mail.com`).
4. If your email provider requires verification before allowing the forwarding rule:
   * The provider will send a verification email to your **agent email**.
   * You can find and approve the verification email in your agent's chatlogs.
5. Click **Verify automatic forwarding** in the Email settings drawer.
   * If everything is set up correctly, you'll be taken to the **authenticate domain** step (Step 3).

### Provider-specific forwarding guides

For detailed instructions on setting up email forwarding, refer to your email provider's documentation.

Here are links to official guides for popular email providers:

#### Gmail and Google Workspace

* **Gmail (personal inbox forwarding)**: [Set up email forwarding in Gmail](https://support.google.com/mail/answer/10957)

##### Configure email forwarding in Google Workspace (Admin Console)

This approach is **recommended** for Google Workspace because it **doesn’t have rate limits** and **doesn’t require creating a mailbox** for the address you’re forwarding.

<Info>
  You need **Google Workspace administrator access** to complete these steps.
</Info>

<Steps>
  <Step title="Open the Google Workspace Admin Console">
    Sign in to the [Admin Console](https://admin.google.com/) using an admin account.
  </Step>

  <Step title="Go to Gmail routing settings">
    Navigate to **Apps** → **Google Workspace** → **Gmail**.

    Find **Default routing**, then click **Configure** or **add another rule** to create a new routing rule.
  </Step>

  <Step title="Create a routing rule for your support address">
    When adding the setting:

    * Set **Envelope Recipient** to the email address you want customers to use (for example, `support@yourdomain.com`).

    * Under **Envelope Recipient**, select **Change Envelope Recipient**.

    * In **Replace Recipient**, enter your **Chatbase agent email** (for example, `agent@subdomain.chatbase-mail.com`).

    <Frame>
      <img alt="Google Workspace Email Settings" />
    </Frame>
  </Step>

  <Step title="Save the rule and enable it for recognized + unrecognized addresses">
    Before saving, confirm the option is set to:

    **Perform this action on non-recognized and recognized addresses**

    <Frame>
      <img alt="Chatbase Embed Code Example" />
    </Frame>

    Then save your changes.
  </Step>

  <Step title="Verify forwarding in Chatbase">
    Return to **Email settings** in Chatbase and click **Verify automatic forwarding**.
  </Step>
</Steps>

<Note>
  Changes can take up to **24 hours** to propagate, although they often take effect sooner.
</Note>

#### Microsoft

* **Outlook (all versions)**: [Turn on automatic forwarding in Outlook](https://support.microsoft.com/en-us/office/turn-on-automatic-forwarding-in-outlook-7f2670a1-7fff-4475-8a3c-5822d63b0c8e) — follow this guide to set up forwarding to your Chatbase agent email. This works for Outlook.com, New Outlook, Classic Outlook, and Outlook on the web.

##### Allow external forwarding in Microsoft 365 (required for work accounts)

After setting up forwarding in Outlook, Microsoft 365 will **block the forwarded emails from leaving your organization** by default. Your Microsoft 365 administrator must allow external forwarding for the emails to reach Chatbase.

Without this step, forwarding appears configured in Outlook but emails are silently blocked and Chatbase verification will fail. For more details, see [Microsoft's documentation on external email forwarding](https://learn.microsoft.com/en-us/defender-office-365/outbound-spam-policies-external-email-forwarding).

<Info>
  You need **Microsoft 365 administrator access** to complete these steps. If you are not the admin, share these instructions with your IT team.
</Info>

<Steps>
  <Step title="Allow external forwarding in the outbound spam policy">
    Sign in to the [Microsoft Defender portal](https://security.microsoft.com).

    Navigate to **Email & Collaboration** → **Policies & Rules** → **Threat policies** → **Anti-spam** (under Policies).

    Select the **outbound spam filter policy** (the default policy or a custom policy that applies to your users).

    Click **Edit protection settings**.

    Find the **Automatic forwarding rules** setting and change it from **"Automatic - System-controlled"** (or **"Off - Forwarding is disabled"**) to **"On - Forwarding is enabled"**.

    Save your changes.

    <Info>
      If you don't want to enable forwarding for the entire organization, you can create a custom outbound spam policy that only applies to specific users or groups, and enable forwarding only in that policy. Alternatively, you can use **Remote domains** in the Exchange admin center to allow forwarding only to the Chatbase mail domain.
    </Info>
  </Step>

  <Step title="Verify forwarding in Chatbase">
    Return to **Email settings** in Chatbase and click **Verify automatic forwarding**.
  </Step>
</Steps>

#### Other email providers

* **Yahoo Mail**: [Automatically forward emails in Yahoo Mail](https://help.yahoo.com/kb/SLN22028.html)
* **ProtonMail**: [Set up email forwarding in ProtonMail](https://proton.me/support/email-forwarding)

## Step 3 – Authenticate your domain with DNS

Once we detect automatic forwarding from at least one email address on the domain, you'll be able to proceed to DNS authentication. This step allows Chatbase to send emails on your behalf from your custom domain.

### View your DNS records

After forwarding is verified, you'll see the DNS records you need to add. In the **Email settings** drawer, you'll see:

* **Record type** (CNAME or TXT)
* **Name** (the DNS record name)
* **Value** (the DNS record value)

Each record will show its authentication status. Copy each record exactly as shown.

<Frame>
  <img alt="DNS records displayed in Email settings" />
</Frame>

### Add records at your DNS provider

Sign in to the DNS provider that manages your domain (this might be your registrar or a DNS host like Cloudflare), then add the records we provided.

<Note>
  The DNS records you need to add include:

  * **CNAME record** for DKIM authentication (e.g., `chatbase._domainkey`)
  * **CNAME record** for SPF authentication (e.g., `outbound.chatbase`)
  * **TXT record** for DMARC policy (e.g., `_dmarc`)

  Copy each record exactly as shown in the Email settings page, including the name and value.
</Note>

### Provider-specific DNS guides

For detailed instructions on DNS authentication, here are links to official guides for popular DNS and domain providers:

#### Domain registrars

* **GoDaddy**: [Add a TXT or CNAME record](https://www.godaddy.com/en/help/add-a-cname-record-19236)
* **Namecheap**: [How to manage DNS records](https://www.namecheap.com/support/knowledgebase/article.aspx/9646/2237/how-to-create-a-cname-record-for-your-domain/)

#### DNS hosting providers

* **Cloudflare**: [Manage DNS records](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/)
* **Amazon Route 53**: [Working with DNS records](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-creating.html)
* **Google Cloud DNS**: [Managing DNS records](https://cloud.google.com/dns/docs/records)
* **Azure DNS**: [Manage DNS records](https://learn.microsoft.com/en-us/azure/dns/dns-operations-recordsets-portal)

### Verify your domain

After you add the DNS records at your DNS provider:

1. Return to the **Email settings** drawer in Chatbase.
2. Click **Validate** to check if the DNS records are correctly configured.

The system will verify each DNS record:

* **DKIM**: Shows as "authenticated" when the CNAME record is found
* **SPF**: Shows as "authenticated" when the CNAME record is found
* **DMARC**: Shows as "authenticated" when the TXT record is found

<Warning>
  DNS changes can take up to **24–48 hours** to fully propagate. If verification fails immediately after adding records, wait a few hours and try again.
</Warning>

<Check>
  Once all DNS records are verified, this email can be configured to be used by the AI agent to respond to emails. Replies will be sent **from your domain addresses** (for example, `support@yourdomain.com`) instead of the default `agent@subdomain.chatbase-mail.com` address. Learn more about [configuring the email channel](/docs/user-guides/integrations/email).
</Check>

## Adding and managing email addresses

After you've added your first email address and completed the setup process, you can add additional email addresses to the same domain or add emails from different domains.

### Adding more email addresses

To add additional email addresses:

1. Click **New email address** in the Email settings page.
2. Enter the new email address (for example, `sales@yourdomain.com`).
3. Follow the same 3-step process:
   * Enter the email address
   * Configure email forwarding
   * Authenticate the domain (if not already done)

<Info>
  You can add up to **20 email addresses per domain**. If you're adding an email from a domain that's already authenticated, you'll only need to complete steps 1 and 2 (email address and forwarding).
</Info>

## Testing your setup

Once forwarding and DNS are configured:

1. Send an email from an external address (for example, your personal Gmail) to one of your connected addresses (for example, `support@yourdomain.com`).
2. Confirm that:
   * The conversation appears under your AI agent’s conversations.
   * The reply is sent back to your external address.
   * The **From** address matches your expectations:
     * If the domain is not verified: it will come from `agent@subdomain.chatbase-mail.com`.
     * If the domain is verified: it will come from your configured address on that domain.

If everything looks correct, your email support channel is fully configured.

## Troubleshooting

### Email forwarding issues

**I don't see emails in my agent conversations**

* Confirm that forwarding is enabled and points to the correct **agent email** (`agent@subdomain.chatbase-mail.com`).
* Check for filters or rules that might be archiving or deleting messages before they are forwarded.
* Verify that your email provider has sent and you've approved any required verification emails.
* Check your agent email's conversation history for any verification emails that need approval.

### DNS authentication issues

**Domain verification fails**

* Ensure there are no typos in the CNAME or TXT record values—copy them exactly as shown.
* Verify that you added records on the correct DNS zone:
  * For `yourdomain.com`, add records at the root level
  * For `subdomain.yourdomain.com`, add records for the subdomain
* Wait for DNS propagation—some providers can take up to 48 hours to update DNS records globally.

**Some DNS records verify but others don't**

* Each record is verified independently. Check each one:
  * DKIM (CNAME): Verify the name includes `chatbase._domainkey`
  * SPF (CNAME): Verify the name includes `outbound.chatbase`
  * DMARC (TXT): Verify the name includes `_dmarc`
* Ensure the record values match exactly what's shown in Email settings.

### Microsoft 365 forwarding blocked

**Verification keeps failing and no emails reach Chatbase**

* Microsoft 365 blocks automatic external forwarding by default. Your admin must enable it in the outbound spam filter policy. See [Allow external forwarding in Microsoft 365](#allow-external-forwarding-in-microsoft-365-required-for-work-accounts) above.
* Check if the sender is receiving a non-delivery report (NDR) with the error: `5.7.520 Access denied, Your organization does not allow external forwarding`. This confirms external forwarding is blocked.
* If using a custom outbound spam policy, ensure the policy applies to the correct users or groups.

### General issues

**I can't add more domains**

* You can add up to **3 domains** per workspace. Remove an existing domain if you need to add a new one.

**I can't add more email addresses**

* You can add up to **20 email addresses per domain**. Consider using a different domain if you need more addresses.

**Emails are being marked as spam**

* Ensure all DNS records (DKIM, SPF, DMARC) are properly configured and verified.
* Check your domain's reputation using tools like [MXToolbox](https://mxtoolbox.com/).


# Ticket Assignment
Source: https://chatbase.co/docs/user-guides/chatbot/help-desk/assignment-algorithm

Automatically assign incoming tickets to the most available teammate, or let your team manually pick up work.

As your support volume grows, you need an efficient way to route tickets to the right people. Chatbase offers three assignment methods so you can match your workflow, whether you prefer full control, even distribution, or simple rotation.

## Assignment methods at a glance

<Columns>
  <Card title="Manual" icon="hand">
    Tickets remain unassigned until a teammate claims one or a manager assigns it.
  </Card>

  <Card title="Balanced" icon="scale-balanced">
    Each new ticket goes to the available agent with the **fewest open tickets**.
  </Card>

  <Card title="Round Robin" icon="arrows-rotate">
    Each new ticket goes to the available agent who has gone **longest without receiving one**.
  </Card>
</Columns>

***

## Manual assignment

With manual assignment, new tickets land in the shared inbox and wait for a teammate to pick them up or for a manager to assign them directly. This is the default for all new helpdesk configurations.

**Best for:**

* Small teams where agents self-select work
* Specialized tickets that require specific expertise
* Low-volume inboxes that don't need automation

***

## Balanced assignment

Balanced assignment automatically routes each incoming ticket to the available agent with the **lowest number of open tickets**. This keeps workloads even across your team, so no single agent gets overwhelmed while others sit idle.

### How it works

1. A new ticket arrives in the helpdesk.
2. The system finds all agents whose status is **Available**.
3. If a max ticket limit is configured, agents who have reached that limit are excluded.
4. The ticket is assigned to the agent with the **fewest open tickets** (non-closed, non-cancelled).
5. If multiple agents are tied, the one who was **least recently assigned** a ticket receives it.

***

## Round robin assignment

Round robin distributes tickets sequentially by assigning each new ticket to the available agent who was **least recently assigned**, regardless of how many tickets they currently have open. It's a good fit for **sales and lead distribution** where equal opportunity matters more than current workload.

### How it works

1. A new ticket arrives in the helpdesk.
2. The system finds all agents whose status is **Available**.
3. If a max ticket limit is configured, agents who have reached that limit are excluded.
4. The ticket is assigned to the agent with the **oldest last-assignment timestamp**, the teammate who has waited longest for a new ticket.

Unlike balanced assignment, round robin does **not** factor in how many tickets an agent currently has open. It purely rotates based on assignment order.

***

## Comparison

| Feature                          | Manual | Balanced                | Round Robin             |
| :------------------------------- | :----- | :---------------------- | :---------------------- |
| Auto-assigns tickets             | No     | Yes                     | Yes                     |
| Selection criteria               | —      | Fewest open tickets     | Least recently assigned |
| Considers current workload       | —      | Yes                     | No                      |
| Respects max ticket limit        | —      | Yes                     | Yes                     |
| Only assigns to available agents | —      | Yes                     | Yes                     |
| Tie-breaking rule                | —      | Least recently assigned | —                       |
| Supports next-shift fallback     | —      | Yes                     | Yes                     |

***

## Unassigned tickets

When no agents are available or all agents have reached their ticket limit, the ticket stays in the shared inbox as **unassigned**. It is not lost. The system will automatically assign it when capacity opens up.

Unassigned tickets are always processed **oldest first** and assigned **incrementally**, one at a time, so that no single agent is swarmed with the entire backlog the moment they come online. You don't need to manually reassign queued tickets.

***

## When all agents are unavailable

If every agent is set to **Away**, **Busy**, or **Paused**, the auto-assignment algorithms (balanced and round robin) cannot find an eligible agent. Here's what happens:

* Incoming tickets stay **unassigned** in the shared inbox with a **New** status.
* Tickets remain queued until an agent becomes available.
* When capacity opens up, unassigned tickets are assigned incrementally, oldest first, one at a time, until the backlog is cleared.

<Tip>To avoid a growing backlog, ensure at least one agent is set to **Available** during business hours.</Tip>

***

## Assign to next available shift

When every agent is unavailable and you use **Balanced** or **Round Robin** assignment, you can enable **Assign to next available shift** so that incoming tickets are automatically routed to an agent whose shift starts soonest, instead of staying unassigned.

### How it works

1. A new ticket arrives and the system finds no available agents (all are `Off shift`, `Away`, `Busy`, or `Paused`).
2. The system looks at all **scheduled** agents and calculates when each agent's next shift begins, skipping any agents who are on time off.
3. The ticket is assigned to the agent (or agents, if tied) whose shift starts the **earliest**.
4. The chosen agent is selected using the same algorithm you configured. **Balanced** picks the one with the fewest open tickets, **Round Robin** picks the one least recently assigned.

<Info>This feature only applies to **scheduled** agents (those assigned to a shift). Manual agents are not considered because their next available time cannot be predicted.</Info>

### Enabling the toggle

<Steps>
  <Step title="Open assignment settings">
    Navigate to your chatbot's **Helpdesk Settings → Assignment** page.
  </Step>

  <Step title="Choose an auto-assignment method">
    Select **Balanced** or **Round Robin**. The toggle is not available for **Manual** assignment.
  </Step>

  <Step title="Enable the toggle">
    Turn on **Assign to next available shift**. When enabled, tickets that would otherwise stay unassigned are routed to the next agent coming on shift.
  </Step>
</Steps>

### Things to know

* **Max ticket limits still apply.** If you have a max tickets per agent configured, the next-shift agent must also be under that limit to receive the ticket.
* **Time off is respected.** Agents on time off are skipped even if their shift is the soonest.
* **Multiple agents on the same shift.** When several agents share the same next shift start time, the configured assignment algorithm (Balanced or Round Robin) breaks the tie.
* **No scheduled agents?** If your team has no scheduled agents, this toggle has no effect since there are no shift start times to predict.

***

## Max tickets per agent

For both automated methods (balanced and round robin), you can optionally set a **maximum number of open tickets per agent**. When an agent reaches this limit, they stop receiving new assignments until they close or resolve existing tickets.

* **Range:** 1–999
* **Default:** Disabled (no limit)

<Steps>
  <Step title="Enable the limit">
    Toggle **Limit open tickets per person** in the assignment settings.
  </Step>

  <Step title="Set the cap">
    Enter a number between 1 and 999. A good starting point is **10** for most support teams. Adjust based on your ticket complexity and team size.
  </Step>
</Steps>

<Warning>When all available agents are at capacity, incoming tickets remain unassigned in the shared inbox. Monitor your team's workload to avoid bottlenecks.</Warning>

***

## Agent availability

Only agents with an **Available** status are eligible for automatic assignment. You can manage each agent's status from the team availability panel in the assignment settings.

| Status        | Receives auto-assigned tickets? | When to use                                                          |
| :------------ | :------------------------------ | :------------------------------------------------------------------- |
| **Available** | Yes                             | Agent is online and ready to handle tickets                          |
| **Away**      | No                              | Agent is temporarily unavailable (lunch, meeting)                    |
| **Busy**      | No                              | Agent is focused on existing work and should not receive new tickets |
| **Paused**    | No                              | Agent is offline or on extended leave                                |

Agents can update their own status at any time from the sidebar.

***

## Setting up assignment

<Steps>
  <Step title="Open assignment settings">
    Navigate to your chatbot's **Helpdesk Settings → Assignment** page.
  </Step>

  <Step title="Choose an assignment method">
    Select **Manual**, **Balanced**, or **Round Robin** based on your team's workflow.
  </Step>

  <Step title="Configure ticket limits (optional)">
    If using balanced or round robin, toggle on **Limit open tickets per person** and set a cap to prevent agent overload.
  </Step>

  <Step title="Set team availability">
    Review your team's availability in the table below the assignment method. Ensure agents who are ready to receive tickets are set to **Available**.
  </Step>
</Steps>

***

## Good to know

* **New agents default to Away.** When an agent is first added to a chatbot, their status is set to **Away**. They will not receive auto-assigned tickets until an admin or the agent themselves switches to **Available**.
* **Ticket limits only apply to auto-assignment.** The max tickets per agent setting does not restrict manual assignment. An admin can still assign tickets to an agent who has exceeded the configured limit.
* **Reassignment does not change ticket status.** When a ticket is reassigned from one agent to another, the ticket's status remains unchanged. It does not reset to **New** or **On You** automatically.
* **The Away toggle only switches between Away and Available.** Agents in **Busy** or **Paused** status cannot use the sidebar toggle. Only an admin can change their status from the Helpdesk Settings → Assignment panel.


# Email Settings
Source: https://chatbase.co/docs/user-guides/chatbot/help-desk/email-settings

Configure email addresses, display names, signatures, and previews for your Help Desk.

## Email Configuration

The Email Configuration card allows you to choose which email addresses will be used as your help desk inboxes and who should be notified about deliverability issues.

### Selecting help desk emails

You can configure one or more email addresses to receive support tickets.

<Steps>
  <Step title="Add an email row">
    Click **Add email** to add a new email row. Each row presents a dropdown of your available verified email addresses.
  </Step>

  <Step title="Select an email address">
    Choose an email address from the dropdown. Only emails from verified domains are listed. Each email can only be selected once - duplicates are automatically filtered out.
  </Step>

  <Step title="Review email status">
    Each selected email displays status badges indicating its readiness:

    * **Forwarding** - Whether email forwarding is enabled
    * **DKIM** - Whether DKIM authentication is configured on the domain
    * **SPF** - Whether SPF records are configured on the domain

    All three must be enabled for the email to function correctly.
  </Step>

  <Step title="Save">
    Click **Save** to apply your email configuration.
  </Step>
</Steps>

<Warning>
  Emails missing any of the three requirements (Forwarding, DKIM, SPF) will display an **Issues** badge. Clicking it reveals which checks are failing. Resolve these in your domain's DNS settings before using the email for help desk support.
</Warning>

### Removing an email

Click the trash icon next to any email row to remove it. You must have at least one email row present, though it can be empty.

### Deliverability alert contact

Configure which team member receives notifications when outgoing help desk emails fail to deliver.

1. Open the **Deliverability alert contact** dropdown.
2. Select a team member from your account's member list.
3. Click **Save**.

The selected contact will receive alerts when emails bounce or encounter delivery issues.

<Info>
  The deliverability alert contact is optional. If not set, no notifications will be sent for failed deliveries.
</Info>

### Validation rules

| Rule                 | Description                                                                                 |
| -------------------- | ------------------------------------------------------------------------------------------- |
| Non-empty email rows | Every added email row must have an email selected                                           |
| No duplicates        | The same email address cannot be selected in multiple rows                                  |
| DNS requirements     | Warnings are shown for emails missing Forwarding, DKIM, or SPF, but saving is still allowed |

***

## Display Name

The Display Name setting controls what recipients see in the **From** field of emails sent from your help desk. This helps establish trust and brand recognition with your customers.

### Auto mode

**Auto** uses the name of the support associate who responds to the ticket. Each outgoing email will show the actual agent's name, creating a more personal support experience.

For example, if agent "Sarah Johnson" responds to a ticket, the email appears as:

```
From: Sarah Johnson <support@yourdomain.com>
```

<Info>
  Auto mode is the default and recommended for teams that want a personal touch in customer communications.
</Info>

### Custom mode

**Custom** uses a fixed name you specify for all outgoing emails, regardless of which agent responds. This is useful for maintaining a consistent brand identity across all support communications.

For example, if you set the custom name to "Acme Support":

```
From: Acme Support <support@yourdomain.com>
```

When selecting custom mode, a text input appears where you enter the desired display name. The name cannot be empty.

### Changing the display name

1. Select either **Auto** or **Custom** using the radio buttons.
2. If **Custom** is selected, enter the desired display name in the text field.
3. Click **Save** to apply.

<Note>
  Changes to the display name take effect on all future outgoing emails. Previously sent emails are not affected.
</Note>

***

## Email Signature

The Signature card lets you create a rich-text signature that is automatically appended to the bottom of every outgoing help desk email, including those sent by the AI agent.

### Creating a signature

1. Open the **Signature** card on the email settings page.
2. Use the rich-text editor to compose your signature. The editor supports bold, italic, underlined text, links, and line breaks.
3. Click **Save** to apply.

### Signature behavior

| Scenario                   | Signature applied?            |
| -------------------------- | ----------------------------- |
| AI agent auto-replies      | Yes                           |
| Manual agent replies       | Yes                           |
| No signature content saved | No signature section rendered |

### Editing or removing a signature

* **Edit:** Modify the content in the rich-text editor and click **Save**.
* **Remove:** Clear all content from the editor and click **Save**. When the content is empty, the signature is saved as disabled.

<Info>
  Keep signatures concise. Long signatures can push the actual email content out of the visible area on mobile devices.
</Info>

***

### Fallback behavior

| Condition                | Fallback                                                               |
| ------------------------ | ---------------------------------------------------------------------- |
| No emails selected       | Uses the auto-generated agent email: `agent@{subdomain}.{mail-domain}` |
| No subdomain configured  | Falls back to `chatbase@mail.com`                                      |
| Display name set to Auto | Shows "Support Associate" as the placeholder name                      |


# Filters
Source: https://chatbase.co/docs/user-guides/chatbot/help-desk/filters

The full set of fields, operators, and values you can use to filter the help desk inbox.

Filters narrow the help desk inbox to a specific slice of tickets. They are used in two places:

* The **Filter** button above the ticket list, for quick ad-hoc filtering of the current view.
* The **Conditions** tab when creating or editing a [saved view](/docs/user-guides/chatbot/help-desk/saved-views), where the same filters are persisted alongside a sort order and column layout.

A filter is made of three parts: a **field**, an **operator**, and a **value**. Tickets must match every active condition to appear. You can stack up to 20 conditions at once.

***

## Available fields

| Field               | What it filters on                                    |
| ------------------- | ----------------------------------------------------- |
| **Status**          | The ticket's current lifecycle state                  |
| **Channel**         | Where the ticket originated                           |
| **Assignee**        | The agent the ticket is assigned to                   |
| **Mentions me**     | Tickets where you are @mentioned in an internal note  |
| **Created**         | When the ticket was first created                     |
| **Last message**    | When the most recent message was sent                 |
| **Last message by** | Who sent the most recent message                      |
| **Type**            | Whether the ticket is a regular ticket or a live chat |

***

## Operators by field

The available operators depend on the field.

| Field           | Operators                                   |
| --------------- | ------------------------------------------- |
| Status          | `is any of`, `is none of`                   |
| Channel         | `is any of`, `is none of`                   |
| Assignee        | `is any of`, `is none of`                   |
| Mentions me     | (none)                                      |
| Created         | `in the last`, `before`, `after`, `between` |
| Last message    | `in the last`, `before`, `after`, `between` |
| Last message by | `is`                                        |
| Type            | `is`                                        |

What each operator means:

* **is any of** / **is none of**: pick one or more values; the ticket must match (or not match) any of them.
* **is**: single fixed value (boolean or single-select).
* **in the last**: relative window such as *the last 7 days*, *the last 2 weeks*, or *the last 3 months*. Maximum 365 days.
* **before** / **after**: absolute date threshold.
* **between**: absolute date range with a start and end date.

***

## Values by field

### Status

One or more of:

* **New**: freshly created, not yet picked up
* **On You**: assigned, awaiting agent action
* **On Customer**: agent replied, awaiting customer response
* **On Hold**: paused on an external dependency
* **Closed**: resolved
* **Cancelled**: spam, duplicate, or opened in error

### Channel

One or more of:

* **Widget**: embedded chatbot on your website
* **Email**: email forwarding
* **WhatsApp**
* **Messenger**
* **Instagram**
* **API**: created programmatically

### Assignee

One or more of:

* **Me**: the currently signed-in agent
* **Unassigned**: no agent assigned
* Any specific agent in the workspace

### Mentions me

This filter has no operator or value to configure. It is either present in your filter list or it isn't. When present, the inbox is restricted to tickets where you are @mentioned in an internal note. To turn it off, remove the filter row.

### Created / Last message

Date values, used with one of the date operators above. Relative windows accept a positive integer up to 365 paired with a unit (`days`, `weeks`, or `months`).

### Last message by

One of:

* **Customer**: most recent message came from the customer
* **Agent**: most recent message came from a teammate

### Type

One of:

* **Ticket**: standard support ticket
* **Live chat**: active live chat session

***

## Combining filters

Conditions are combined with **AND**: every condition must match. Stack different fields to slice the inbox precisely. For example:

* *Channel is any of WhatsApp* + *Status is any of New, On You* + *Created in the last 24 hours* → fresh, unresolved WhatsApp tickets from the past day.
* *Assignee is any of Unassigned* + *Last message by is Customer* → tickets waiting for someone to pick them up where the customer spoke last.

To save a combination for reuse, build it as a [saved view](/docs/user-guides/chatbot/help-desk/saved-views) instead of re-applying it each time.


# Overview
Source: https://chatbase.co/docs/user-guides/chatbot/help-desk/help-desk-overview

Manage customer support tickets from a centralized dashboard.

## Introduction

The Helpdesk is a centralized support dashboard where your team can manage customer tickets across every channel - widget, email, WhatsApp, and API - in one place. Agents can triage, assign, and resolve tickets without switching between tools, keeping response times low and customer satisfaction high.

<Frame>
  <img alt="Helpdesk dashboard overview showing sidebar, ticket list, and details panel" />
</Frame>

### Sidebar

The sidebar is your primary navigation. It can be collapsed into icon-only mode for more screen space.

* **Your Inbox** - tickets assigned to you
* **Mentions** - tickets where you have been @mentioned in an internal note. The badge count shows how many unread mentions you have.
* **All** - every ticket across agents
* **Unassigned** - tickets with no agent assigned
* **Solved** - resolved tickets
* **Conversations** - all chatbot conversations, including those that have not been escalated to tickets

Each view displays a badge count when there are items requiring attention.

### User Profile

Click your avatar at the bottom of the sidebar to open the profile menu:

* **Away mode** - toggle to mark yourself as unavailable for auto-assignment
* **Sound notifications** - toggle notification sounds on or off
* **Dashboard** - navigate to the main Chatbase dashboard
* **Account settings** - manage your account
* **Logout** - sign out of the helpdesk

<Frame>
  <img alt="User profile menu showing away mode, sound notifications, dashboard, account settings, and logout options" />
</Frame>

### Notifications

When you have a specific ticket open, new events on that ticket trigger two notifications:

* **Sound** - a notification sound plays (if sound notifications are enabled in your profile menu)
* **Tab badge** - the browser tab title updates to show the unread count, e.g. `(2) Helpdesk`

This helps agents stay aware of new activity on the ticket they are working on, even when the tab is not in focus. Notifications only apply to the currently open ticket - you will not receive browser notifications for other tickets.

### Search

Click the search button to open a search modal with two tabs: **Tickets** and **Customers**. Results update in real time as you type, and you can click through to the full search results page.

<Frame>
  <img alt="Search modal with Tickets and Customers tabs" />
</Frame>

## Tickets Inbox

### Table Columns

The ticket list displays the following columns:

| Column         | Description                                                     |
| -------------- | --------------------------------------------------------------- |
| Status         | Color-coded badge indicating the ticket's current state         |
| Ticket ID      | Unique identifier, formatted as `#123`                          |
| Requester      | The customer who submitted the ticket (name or email)           |
| Assignee       | The agent responsible for the ticket, or `–` if unassigned      |
| Ticket Details | Subject line and a preview of the last message                  |
| Created At     | When the ticket was created (relative time, e.g. "2 hours ago") |
| Last Updated   | When the most recent message was sent (relative time)           |

Click any row to open the ticket.

### Filters

Click the **Filter** button in the top right, above the ticket list, to narrow the results within the current view without changing it. Add one or more conditions, each made of a field, an operator, and a value. A badge next to the button shows how many conditions are active; **Clear all** resets them and **Apply** confirms your selection. Filters here are temporary, scoped to your session, and do not modify the underlying view.

To make a filter combination permanent, save it as a [saved view](/docs/user-guides/chatbot/help-desk/saved-views), which persists conditions alongside a sort order, columns, and visibility. The full list of fields, operators, and values is documented in the [Filters reference](/docs/user-guides/chatbot/help-desk/filters).

## Ticket Statuses

Every ticket has a status that reflects where it is in the support lifecycle. Statuses are grouped into **active** (New, On You, On Customer, On Hold) and **closed** (Closed, Cancelled).

<AccordionGroup>
  <Accordion title="New">
    A freshly created ticket that hasn't been picked up by any agent yet. New tickets appear in the **Unassigned** view until an agent claims them.
  </Accordion>

  <Accordion title="On You">
    The ticket requires action from the assigned agent. This is the default status when an agent picks up a ticket or when a customer replies.
  </Accordion>

  <Accordion title="On Customer">
    The agent has replied and is waiting for the customer to respond. Use this status after sending a reply so your team knows no agent action is needed right now.
  </Accordion>

  <Accordion title="On Hold">
    The ticket is paused because of an external dependency - for example, waiting on a third-party service or an internal escalation. Use this sparingly and add a note explaining the reason.
  </Accordion>

  <Accordion title="Closed">
    The issue has been resolved. Closed tickets move out of the active queue.
  </Accordion>

  <Accordion title="Cancelled">
    The ticket was spam, a duplicate, or opened in error. Cancelled tickets are removed from the active queue.
  </Accordion>
</AccordionGroup>

## Requester and Assignee

* **Requester** - the end user who submitted the ticket. Their profile can include a name, email, external ID, and phone number.
* **Assignee** - the agent responsible for handling the ticket. Tickets can be assigned manually or through auto-assignment.

<Tip>
  Configure auto-assignment rules in your helpdesk settings to automatically route new tickets to available agents.
</Tip>

## Viewing a Ticket

When you open a ticket, the view splits into a **conversation thread** on the left and a **details panel** on the right.

### Conversation Thread

The conversation thread displays three types of entries:

* **Replies** - customer-visible messages from either the customer or an agent
* **Notes** - internal-only messages visible to your team (shown with an amber background)
* **Events** - system-generated entries for status changes and assignment updates

<Frame>
  <img alt="Conversation thread with customer replies, internal notes, and system events" />
</Frame>

### Ticket Details Panel

The right sidebar contains five collapsible sections:

1. **Assignee** - view or change the assigned agent. Click the edit icon to reassign to another agent or unassign the ticket entirely.
2. **Author** - the requester's information: name, email, external ID, and phone number.
3. **Ticket Details** - ticket ID, status badge, submission date, subject, and a **View conversation** button that links to the original chatbot conversation that created the ticket.
4. **Previous Tickets** - a list of other tickets from the same customer, showing subject, ticket ID, time, and status badge. This gives agents quick context on the customer's support history.
5. **Notes** - a list of internal notes attached to the ticket, including any @mentions.

<Frame>
  <img alt="Ticket details panel showing assignee, author info, ticket details, previous tickets, and notes sections" />
</Frame>

## Replying to Tickets

### Reply vs Note

The message composer at the bottom of the conversation thread has two tabs:

* **Reply** - sends a public message that the customer will see
* **Note** - saves an internal-only message (shown with an amber background) that only your team can see

<Warning>
  Always double-check which tab is selected before sending. Notes are internal-only, but replies go directly to the customer.
</Warning>

### @Mentions

Type `@` in the note composer to mention a team member. A dropdown appears listing available agents along with a colored dot indicating their current availability status. Select an agent to insert the mention into your note.

<Frame>
  <img alt="Agent mention dropdown showing team members with availability status indicators" />
</Frame>

When you @mention someone:

* The mentioned agent receives a notification
* The ticket appears in their **Mentions** sidebar view
* The mention is rendered as a clickable link in the note

Use @mentions to loop in colleagues, escalate to another agent, or flag a ticket for someone's attention without reassigning it.

<Frame>
  <img alt="Ticket view showing an @mention in an internal note and the Mentions count in the sidebar" />
</Frame>

<Warning>
  @mentions are only available in **Notes** (internal messages). They are not supported in customer-facing replies.
</Warning>

### Attachments

Click the **paperclip** icon to attach files to a reply or note. Supported file types include images, text files, PDFs, audio, and video. Each attachment can be removed before sending.

### AI Compose

Click the **sparkle** icon in the composer toolbar to open the AI writing assistant. It offers the following options:

| Option                 | Description                                                       |
| ---------------------- | ----------------------------------------------------------------- |
| Format text            | Cleans up formatting and structure                                |
| More friendly          | Adjusts the tone to be warmer and more approachable               |
| More formal            | Adjusts the tone to be more professional                          |
| Rephrase               | Rewords the text while keeping the same meaning                   |
| Expand                 | Adds more detail and length                                       |
| Fix grammar & spelling | Corrects grammar and spelling errors                              |
| Translate              | Translates the text to another language (opens a language picker) |

You need to have text in the editor for AI Compose to be available.

<Frame>
  <img alt="AI compose dropdown menu with formatting, tone, and translation options" />
</Frame>

## Recommended Ticket Workflow

A typical ticket lifecycle follows these steps:

1. A customer submits a request → ticket is created as **New**
2. An agent picks up the ticket → status changes to **On You**
3. The agent sends a reply → agent sets status to **On Customer**
4. The customer responds → status returns to **On You**
5. An external blocker is identified → agent sets status to **On Hold**
6. The issue is resolved → agent sets status to **Closed**
7. The ticket is spam or a duplicate → agent sets status to **Cancelled**

<Tip>
  **Best practices:**

  * Set the status to **On Customer** after every reply so your team knows you're waiting for a response.
  * Use **On Hold** sparingly - add a Note explaining what you're waiting on.
  * Add **Notes** to document your investigation steps, so other agents can pick up where you left off.
</Tip>

## Ticket Channels

Tickets can arrive from multiple channels. The channel is shown on each ticket so agents know where the conversation originated:

* **Widget** - submitted through the embedded chatbot on your website
* **Email** - received via email forwarding
* **WhatsApp** - from a WhatsApp conversation
* **API** - created programmatically through the API


# Saved Views
Source: https://chatbase.co/docs/user-guides/chatbot/help-desk/saved-views

Save reusable inbox configurations so each agent sees the tickets that matter to them.

A **view** is a saved inbox configuration that controls which tickets show up and how the list looks. Each view bundles together:

* A set of **conditions** built from the [available filters](/docs/user-guides/chatbot/help-desk/filters) (field + operator + value), combined with AND. Up to 20 per view.
* A **sort order** that determines how matching tickets are ordered.
* A list of visible **columns** and their order.
* A **visibility** setting (Personal or Shared) that decides who can see the view.

Five system views are built in for everyone. On top of those, each agent can save up to 10 personal views, and the workspace can hold up to 30 shared views.

***

## System views

Five views are built in. They cannot be edited or deleted.

| View           | Shows                                                    |
| -------------- | -------------------------------------------------------- |
| **Inbox**      | Tickets assigned to you that are not Closed or Cancelled |
| **Mentions**   | Tickets where you are mentioned                          |
| **All**        | All tickets that are not Closed or Cancelled             |
| **Unassigned** | Open tickets with no assignee                            |
| **Solved**     | Closed and Cancelled tickets                             |

If you need a variant of a system view, build a new view with the same conditions and tweak from there.

***

## Create a view

<Steps>
  <Step title="Open the New view dialog">
    In the help desk sidebar, click **New view**.
  </Step>

  <Step title="Name the view">
    Enter a short, descriptive name (up to 100 characters). Examples: *High priority*, *VIP customers*, *Email backlog*.
  </Step>

  <Step title="Choose visibility">
    Pick **Personal** to keep the view to yourself, or **Shared** to make it available to every agent in the workspace. The visibility selector only appears if you have permission to create both kinds; otherwise the view defaults to whichever kind you can create.
  </Step>

  <Step title="Add conditions">
    On the **Conditions** tab, click **Add condition** to add a rule. Each condition is a field, an operator, and a value (for example, *Channel is any of WhatsApp*). See [Filters](/docs/user-guides/chatbot/help-desk/filters) for the full list of fields, operators, and values. You can stack up to 20 conditions per view; tickets must match every condition to appear.
  </Step>

  <Step title="Pick a sort order">
    Use the **Sort by** dropdown to choose how matching tickets are ordered. Defaults to *Last activity (newest)*.
  </Step>

  <Step title="Choose columns">
    Switch to the **Columns** tab. Toggle the checkbox next to a column to show or hide it, and drag the handle to reorder. At least one column must stay visible.
  </Step>

  <Step title="Save">
    Click **Create view**. The view appears in the sidebar under **My views** (Personal) or **Shared views** (Shared).
  </Step>
</Steps>

***

## Available columns

A view can show any of these columns, in any order:

* **Status**
* **Ticket ID**
* **Requester**
* **Ticket details**
* **Assignee**
* **Created at**
* **Last updated**

Hide columns you do not need to keep the inbox compact. Column visibility and order are saved with the view, so different agents can see the same inbox differently without affecting each other.

***

## Sort options

The **Sort by** dropdown offers:

* Last activity (newest)
* Last activity (oldest)
* Ticket # (high to low)
* Ticket # (low to high)
* Status (A to Z)
* Status (Z to A)
* Created (newest)
* Created (oldest)

***

## Edit, favorite, or delete a view

* **Edit**: hover the view in the sidebar and pick **Edit** from the menu. You can change the name, visibility, conditions, sort order, and columns at any time.
* **Favorite**: click the bookmark icon next to a view to favorite it. Favorited views pin to the top of the sidebar.
* **Delete**: open the same menu and pick **Delete**. Confirm in the dialog.

<Note>
  You can edit or delete personal views you created yourself. Shared views can be edited or deleted by anyone with the *Manage shared views* permission. If you don't see the edit or delete options on a view, you don't have permission to change it.
</Note>

<Warning>
  Deleting a view is permanent. Shared views are removed for everyone, not just you.
</Warning>

### Sidebar layout

Each section (Shared views, My views) shows the first 5 views by default; click **Show more** to expand. Within each section, views are ordered by:

1. Favorited views first
2. Then most recently used
3. Then alphabetical

Use the search box at the top of the sidebar to filter views by name when the list grows long.

***

## Personal vs Shared

<Note>
  **Personal** views appear only in your sidebar under **My views**. **Shared** views appear in every agent's sidebar under **Shared views**. Switch a view's visibility at any time by editing it.
</Note>

Use Personal views for your own triage workflow. Use Shared views to standardize how the team works through the queue (for example, a shared *Unanswered for 24h* view that everyone reviews each morning).

***

## Tips

<CardGroup>
  <Card title="Build narrow views for triage" icon="filter">
    Stack conditions to surface the exact slice of work you care about.

    *Example:* `Channel is WhatsApp` + `Assignee is Unassigned` + `Created in the last 24 hours`.
  </Card>

  <Card title="Pair conditions with a sort" icon="arrow-down-wide-short">
    Sort matching tickets so the most urgent ones come first.

    *Example:* `Status is any of New, On You` sorted by `Created (oldest)` puts the oldest open tickets at the top.
  </Card>

  <Card title="Keep shared views generic" icon="users">
    Shared views are seen by every agent. Use them for workflows that apply to the whole team.
  </Card>

  <Card title="Use personal views for yourself" icon="user">
    Personal views are perfect for your own triage workflow or experiments that don't belong in everyone's sidebar.
  </Card>
</CardGroup>


# Scheduling
Source: https://chatbase.co/docs/user-guides/chatbot/help-desk/scheduling

Define shifts and time off so agent availability and ticket auto-assignment run on their own.

The Scheduling feature lets you define recurring **Shifts**, assign agents to them, and add **Time off** entries. When an agent is on a shift, their availability is computed automatically from the shift's working hours and any time off, and that availability decides who is eligible for ticket auto-assignment.

You manage scheduling from **Help desk settings → Scheduling**. The page has three cards: **Shifts**, **Agent schedules**, and **Time off**.

***

## How availability is determined

Each agent is in one of two modes:

* **Scheduled**: the agent has a shift assigned. Their status (`On shift` / `Off shift`) is computed in real time from the shift's working hours plus any time off. They cannot change it manually.
* **Manual**: the agent has no shift. Their status (`Available`, `Away`, `Busy`, `Paused`) is set by an admin, or by the agent themselves if you allow it on the **Ticket assignment** page.

Only agents who are currently `Available` (manual) or `On shift` (scheduled, with no active time off) are eligible for new ticket assignment.

***

## Create a shift

A shift is a named, recurring weekly schedule with a timezone.

<Steps>
  <Step title="Open the Shifts card">
    Go to **Help desk settings → Scheduling** and click **Add shift** in the **Shifts** card.
  </Step>

  <Step title="Name the shift">
    Enter a name like *Weekday Standard* or *EU Mornings*. Names help you tell shifts apart when you assign them.
  </Step>

  <Step title="Choose a timezone">
    Pick the timezone the working hours should be evaluated in. The selector defaults to your browser's timezone.
  </Step>

  <Step title="Set working days and hours">
    Toggle each day you want the shift to be active. For each enabled day, pick a **Start time** and **End time**. Times are in 15-minute increments and default to **09:00 to 17:00**.

    Use the **12h / 24h** toggle in the Shifts card header to switch the time format.

    If the End time is the same as or earlier than the Start time, the shift is treated as overnight and continues into the next day. The dialog shows a **(next day)** label so you can confirm.
  </Step>

  <Step title="Save">
    Click **Save** to create the shift. It now appears in the Shifts card and becomes available in the Agent schedules dropdown.
  </Step>
</Steps>

You can edit or delete shifts at any time. Deleting a shift moves every agent assigned to it back to manual mode.

***

## Assign agents to shifts

The **Agent schedules** card lists every help desk agent with a per-agent shift dropdown.

* Pick a shift name from the dropdown to put the agent on that schedule.
* Pick **No shift (manual)** to remove the schedule and manage their status manually.

The badge at the top of the card shows how many of your agents currently have a shift, in the form **2/5 scheduled**.

<Warning>
  Removing a shift from an agent who has scheduled time off will make those time off entries inert, since time off only applies to scheduled agents. The dashboard will warn you before this happens.
</Warning>

***

## Add time off

Use **Time off** to block dates for scheduled agents (vacation, holidays, sick leave, or anything else that should make them unavailable during their normal shift hours).

<Steps>
  <Step title="Open the Time off card">
    In **Scheduling**, click **Add time off** in the **Time off** card.
  </Step>

  <Step title="Pick agents">
    Select one or more agents from the **Agents** field. Only agents who currently have a shift assigned can be picked, since time off has no effect on manual agents.
  </Step>

  <Step title="Pick a date range">
    Choose a start and end date in the **Dates** picker. You cannot pick dates in the past.
  </Step>

  <Step title="Add a reason (optional)">
    Optionally enter a short reason like *Annual leave* or *Public holiday*.
  </Step>

  <Step title="Save">
    Click **Save**. During the selected dates, every chosen agent is treated as `Off shift` and is not eligible for new ticket assignment, even if their shift covers those days.
  </Step>
</Steps>

Past time off entries are hidden once their end date passes.

***

## Status indicators

| Indicator             | Meaning                                                                  |
| --------------------- | ------------------------------------------------------------------------ |
| **On shift** (green)  | Scheduled agent, currently inside their shift hours and not on time off. |
| **Off shift** (amber) | Scheduled agent, outside shift hours, or on time off.                    |
| **Available** (green) | Manual agent, set as available and eligible for assignment.              |
| **Away** (amber)      | Manual agent, not eligible for assignment.                               |
| **Busy** (red)        | Manual agent, not eligible for assignment.                               |
| **Paused** (grey)     | Manual agent, not eligible for assignment.                               |

On the **Ticket assignment** page, scheduled agents show a tooltip *"Status is managed by the schedule"* followed by the shift name. Their status is read-only because the schedule is in charge.

***

## How scheduling affects auto-assignment

Scheduling acts as the eligibility gate for ticket auto-assignment:

* **Manual agents** are eligible when their stored status is `Available`.
* **Scheduled agents** are eligible when the current time is inside their shift (in the shift's timezone) and they have no active time off.

The assignment algorithm (Balanced or Round robin) then picks one agent from that pool. See [Ticket Assignment](/docs/user-guides/chatbot/help-desk/assignment-algorithm) for how each algorithm chooses.

If nobody is eligible, the ticket stays unassigned until an agent is back on shift or set to `Available`. You can change this by enabling **Assign to next available shift**, which routes tickets to the agent whose shift starts soonest. See [Assign to next available shift](/docs/user-guides/chatbot/help-desk/assignment-algorithm#assign-to-next-available-shift) for details.

***

## Tips and edge cases

* **Overnight shifts** wrap past midnight automatically. Pick an end time that is the same as or earlier than the start time, and the shift continues into the following day.
* **Deleting a shift** moves every assigned agent back to manual mode and resets their status to `Away`.
* **New agents** start as `Away` until you assign them a shift or change their status manually.
* **Time off only applies to scheduled agents.** If you want a manual agent to be unavailable, change their status directly.


# Takeover
Source: https://chatbase.co/docs/user-guides/chatbot/help-desk/takeover

Take over AI conversations and escalate them to help desk tickets for human support.

## Introduction

Takeover lets a support associate step into an ongoing AI conversation and convert it into a help desk ticket. Once taken over, the AI stops responding and the support associate handles the rest of the conversation directly. This is useful when a customer's issue is too complex for the AI, requires a personal touch, or needs escalation.

Takeover is available on all channels - Widget, Email, WhatsApp, Facebook Messenger, and Instagram.

## How It Works

When a support associate takes over a conversation, the system:

1. Stops the AI from responding to the customer
2. Generates an AI-powered summary of the conversation
3. Creates a help desk ticket linked to the conversation
4. Assigns the ticket to the support associate who initiated the takeover

## Taking Over a Conversation

<Steps>
  <Step title="Open the conversation">
    Open the **Conversations** tab in the help desk sidebar and select an ongoing conversation.
  </Step>

  <Step title="Click Take Over">
    Click the **Take Over** button in the conversation header. The button is only available for conversations that are currently ongoing.

    <Frame>
      <img alt="Take Over button in the conversation header" />
    </Frame>
  </Step>

  <Step title="View the ticket">
    After takeover, you are automatically redirected to the newly created help desk ticket. The ticket includes:

    * An AI-generated subject line and summary based on the conversation
    * Customer details (name, email, or other identifiers)

    <Frame>
      <img alt="Help desk ticket created from a taken-over conversation" />
    </Frame>
  </Step>
</Steps>

## Conversation States

Every conversation has an activity state that determines whether takeover is available:

<AccordionGroup>
  <Accordion title="Ongoing">
    The conversation is active and the AI is responding. Takeover **is available**.
  </Accordion>

  <Accordion title="Taken Over">
    A support associate has already taken over the conversation. The **Take Over** button is replaced with a **View Ticket** button that links to the associated help desk ticket.
  </Accordion>

  <Accordion title="Ended">
    The conversation has ended. Takeover **is not available**.
  </Accordion>
</AccordionGroup>

## AI-Generated Summary

When a conversation is taken over, the system uses AI to generate a summary so the support associate can quickly understand the context without reading the entire conversation. The summary includes:

* A **subject line** for the ticket
* A **brief summary** of the customer's issue

The summary is generated in the same language the customer used in the conversation.

## What the Customer Sees

On chat channels (such as the widget), the customer receives real-time feedback when a takeover happens:

1. The AI stops responding immediately
2. A loading spinner appears with the message **"Waiting for support agent to join"**
3. Once the support associate sends their first message, the spinner disappears and the conversation continues as a live chat

<Frame>
  <img alt="Waiting for support agent to join spinner shown to the customer" />
</Frame>

<Info>
  The waiting message is automatically displayed in the customer's language. See [Localization](/docs/user-guides/chatbot/deploy#localization) for more details.
</Info>

## Allow AI Replies

After taking over a conversation, you can re-enable the AI at any time by clicking **Allow AI replies**. This hands the conversation back to the AI so it can continue responding to the customer.

<Steps>
  <Step title="Open the ticket">
    Open the taken-over ticket from the help desk.
  </Step>

  <Step title="Click the menu">
    Click the **three-dot menu** (⋯) in the ticket header.
  </Step>

  <Step title="Select Allow AI replies">
    Click **Allow AI replies**. The AI resumes responding to the customer and the ticket is automatically closed.
  </Step>
</Steps>

## Multiple Takeovers

A single conversation can go through multiple takeover and AI resume cycles. Each time, the conversation is clearly divided into sections so both the support associate and the customer can follow the flow:

* A **"Live Chat"** separator marks where a support associate took over
* An **"AI Resumed"** separator marks where the AI was re-enabled

For example, a conversation might flow like this:

1. Customer chats with the AI
2. Support associate takes over → **Live Chat** separator appears
3. Support associate resolves part of the issue and clicks **Allow AI replies** → **AI Resumed** separator appears
4. Customer continues chatting with the AI
5. A new issue arises and another support associate takes over → another **Live Chat** separator appears

Each cycle creates a new ticket, and the conversation timeline preserves the full history across all transitions.

<Frame>
  <img alt="Conversation timeline showing Live Chat and AI Resumed separators across multiple takeover cycles" />
</Frame>

## Concurrency

Only one support associate can take over a conversation. If two support associates click **Take Over** at the same time, the first one to complete the action wins and gets the ticket. The second support associate will see that the conversation has already been taken over.

<Tip>
  **Best practices:**

  * Review the conversation history before taking over so you have full context.
  * After taking over, set the ticket status to **On You** and begin responding to the customer promptly.
  * Use internal **Notes** to document any steps you've taken so other support associates can pick up if needed.
</Tip>


# Translation
Source: https://chatbase.co/docs/user-guides/chatbot/help-desk/translation

Automatically detect and translate customer messages so your team can support anyone, in any language.

## Introduction

Translation lets your support team communicate with customers regardless of the language they write in. When enabled, the helpdesk automatically detects the language of incoming customer messages and offers one-click translation into your team's preferred language.

Only **customer messages** are translated. Agent replies remain in the language the agent writes them in.

## Enable Translation

<Steps>
  <Step title="Open translation settings">
    Navigate to **Help desk settings** > **Translation** in the sidebar.
  </Step>

  <Step title="Enable AI translation">
    <Frame>
      <img alt="Translation settings page showing the Enable button and how-it-works overview" />
    </Frame>
  </Step>

  <Step title="Choose your preferred language">
    Select your team's **Preferred language** from the dropdown - this is the language that customer messages will be translated into.

    <Frame>
      <img alt="Translation settings with AI translation toggle enabled and preferred language set to English" />
    </Frame>
  </Step>

  <Step title="Save">
    Click **Save** to apply your settings. Translation is now active for all tickets.
  </Step>
</Steps>

To disable translation at any time, toggle **AI translation** off and click **Save**.

## How Translation Works in Tickets

When you open a ticket from a customer who wrote in a different language, the helpdesk automatically detects the language and shows a **translation detection banner** at the top of the ticket.

### Before Translation

The banner displays the detected language (e.g., "Detected language: German") along with a **Translate** button. Customer messages appear in their original language.

<Frame>
  <img alt="Ticket view showing a detected language banner with Arabic messages and a Translate button" />
</Frame>

### After Translation

Click **Translate** to translate all customer messages into your preferred language. The banner updates to show the translation direction (e.g., "Translating German → English") and a **Show original** button appears so you can switch back at any time.

<Frame>
  <img alt="Ticket view showing translated messages in English with the Show original button" />
</Frame>

<Info>
  If you are viewing a ticket with an active live chat, new incoming messages from the customer will be **translated automatically** as they arrive - no need to click Translate again.
</Info>

### Toggle Between Original and Translated

You can switch between the original and translated versions at any time using the buttons in the translation banner:

* **Show original** - displays the customer's messages in their original language
* **Translate** - switches back to the translated view

## What Gets Translated

| Content                                          | Translated? |
| ------------------------------------------------ | ----------- |
| Customer messages (email, widget, WhatsApp, API) | Yes         |
| Agent replies                                    | No          |
| Internal notes                                   | No          |
| System events (status changes, assignments)      | No          |

<Warning>
  Only customer messages are translated. Your replies are sent to the customer exactly as you write them. If you need to reply in the customer's language, use the **AI Compose > Translate** option in the message composer.

  <Frame>
    <img alt="Ticket view showing translated messages in English with the Show original button" />
  </Frame>

  <Frame>
    <img alt="Ticket view showing translated messages in English with the Show original button" />
  </Frame>
</Warning>

## Supported Languages

Translation supports **49 languages**, including:

<Columns>
  <div>
    * Arabic
    * Bengali
    * Bulgarian
    * Bosnian
    * Catalan
    * Chinese (Simplified)
    * Chinese (Traditional)
    * Croatian
    * Czech
    * Danish
    * Dutch
    * English
    * Estonian
  </div>

  <div>
    * Finnish
    * French
    * German
    * Greek
    * Hebrew
    * Hindi
    * Hungarian
    * Indonesian
    * Italian
    * Japanese
    * Korean
    * Latvian
    * Lithuanian
  </div>

  <div>
    * Malay
    * Mongolian
    * Norwegian
    * Persian
    * Polish
    * Portuguese
    * Portuguese (Brazil)
    * Romanian
    * Russian
    * Serbian
    * Slovenian
    * Spanish
    * Swahili
  </div>

  <div>
    * Swedish
    * Thai
    * Turkish
    * Ukrainian
    * Vietnamese
  </div>
</Columns>

Right-to-left (RTL) languages such as Arabic, Hebrew, and Persian are fully supported.


# Models Comparison
Source: https://chatbase.co/docs/user-guides/chatbot/models-comparison



# AI Model Comparison Guide for Customer Support

This guide compares various AI models to help you select the best fit for your customer support AI agent. Each section highlights key strengths, particularly focusing on technical capability, empathy and communication, speed, taking actions (like booking meetings or changing subscriptions), and handling multi-step or complex tasks.

## Highly Recommended Models

### GPT-5 Mini

GPT-5 Mini is OpenAI's streamlined variant of GPT-5, offering high-quality reasoning and multimodal capabilities with enhanced speed and cost efficiency. It maintains a substantial context window of 400,000 tokens for handling extensive documentation and prolonged customer conversations.

**Best Suited For:**

* High-speed, real-time customer support requiring immediate responses
* Cost-effective AI deployments with 83% lower operating costs than full GPT-5
* Long-context scenarios involving extensive documentation, logs, or conversation histories
* High-volume support operations where speed and efficiency are critical

**Note:** GPT-5 Mini operates approximately twice as fast as the full GPT-5 model while maintaining strong performance, making it ideal for customer support workspaces needing rapid, cost-effective, and versatile AI capabilities.

### Grok 4

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

Grok 4 is xAI's flagship multimodal model. It supports text, voice, image input, and real-time search integration.

**Best Suited For:**

* Multimodal customer interactions: Agents can process screenshots, photos, voice recordings, and text in a single conversation.
* Live knowledge retrieval & compliance: Native tool use enables up-to-date policy, product, or service information sourcing during support sessions.
* Structured workflows & actions: Built-in function calling allows agents to book meetings, modify subscriptions, update tickets—seamlessly.
* Long-context case management: The extensive context window supports full conversation histories, enhancing follow-up continuity.

### Kimi K2

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

Kimi K2 is Moonshot AI's open-source Mixture-of-Experts model. It's optimized for agentic tasks, native tool orchestration, and coding support.

**Best Suited For:**

* Autonomous, multi-step support workflows without external orchestration
* Backend automation: code/scripts for CRM updates, diagnostics, analytics
* Highly customizable/self-hosted deployments under MIT license
* Processing long documents (transcripts, logs, user histories) natively

## Other Model Options

### GPT-OSS-120B

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

GPT-OSS-120B is OpenAI's open-weight model with 117 billion parameters, offering strong reasoning capabilities and cost-effective performance for customer support scenarios.

**Best Suited For:**

* Complex customer support scenarios requiring deep reasoning
* High-volume support operations where cost-efficiency is important

### GPT-OSS-20B

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

GPT-OSS-20B is OpenAI's smaller open-weight model with 21 billion parameters, optimized for balanced performance and accessibility in customer support applications.

**Best Suited For:**

* Standard customer support interactions with good reasoning capabilities
* Cost-effective support operations for small to medium businesses

### DeepSeek-V3

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

**Best Suited For:**

* Analyzing extensive data, logs, or complex documentation
* In-house customization for detailed troubleshooting

**Note:** Ideal for complex, detailed support scenarios.

### DeepSeek-R1

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

**Best Suited For:**

* Accurate interactions using detailed documentation
* Conversational search and nuanced, documentation-driven support

**Note:** Strong performance in precise, documentation-based interactions.


# Outbound Campaigns
Source: https://chatbase.co/docs/user-guides/chatbot/outbound-campaigns

Send targeted messages to your contacts at scale. Create campaigns, personalize content, and track delivery in real time.

Outbound campaigns let you proactively reach out to your contacts at scale. Build targeted audiences, personalize message content using contact data, and track delivery in real time.

To get started, open your agent and click **Outbound** in the sidebar.

<Frame>
  <img alt="Outbound section in the dashboard sidebar" />
</Frame>

## Supported Channels

<CardGroup>
  <Card title="WhatsApp Campaigns" icon="whatsapp" href="/user-guides/chatbot/outbound-whatsapp">
    Send campaigns to your contacts using pre-approved WhatsApp message templates. Requires a connected WhatsApp integration and approved templates in Meta.
  </Card>
</CardGroup>

<Info>
  More channels are coming soon. WhatsApp is currently the only supported campaign channel.
</Info>

## Key Features

Every outbound campaign — regardless of channel — includes:

* **Audience selection** — Choose recipients from your contact list. Search by name or phone number, and filter by custom attributes like subscription tier or region.
* **Content personalization** — Use contact fields (name, email, custom attributes) to personalize each message per recipient, or set static values for fixed content.
* **Reply behavior** — Choose how replies are handled:
  * **AI Replies** (default) — Your AI agent responds automatically. Best for support questions and automated follow-ups.
  * **Human Takeover** — Replies create helpdesk tickets tagged with the campaign name. Best for sales outreach and high-touch conversations.
* **Delivery tracking** — Monitor campaign progress in real time with a delivery funnel (Queued → Sent → Delivered → Read → Replied), recipient-level status, and error details for failures.

## How It Works

1. **Pick a channel** — Select the channel you want to send on (e.g., WhatsApp).
2. **Configure content** — Compose your message and personalize it with contact data.
3. **Select your audience** — Pick which contacts should receive the campaign.
4. **Send** — Launch the campaign and monitor delivery from the campaign detail page.

<Info>
  Replies are attributed to your campaign for **72 hours** after sending. After that window, incoming messages are treated as regular inbound conversations.
</Info>

For a full step-by-step walkthrough, see the guide for your channel above.


# WhatsApp Campaigns
Source: https://chatbase.co/docs/user-guides/chatbot/outbound-whatsapp

Send outbound WhatsApp campaigns to your contacts using pre-approved Meta message templates. Step-by-step guide for creating, sending, and tracking WhatsApp campaigns.

WhatsApp campaigns let you send bulk messages to your contacts using pre-approved message templates from Meta. This is the primary way to proactively reach out to customers on WhatsApp outside the 24-hour conversation window.

<Info>
  WhatsApp requires all outbound messages to use **pre-approved templates**. You cannot send free-form text as a campaign — templates must be created in Meta and approved before use. See the [WhatsApp Templates guide](/docs/user-guides/integrations/whatsapp-templates) for how to create and manage templates.
</Info>

## Prerequisites

* A connected WhatsApp integration ([setup guide](/docs/user-guides/integrations/whatsapp))
* At least one approved message template in Meta ([WhatsApp Templates guide](/docs/user-guides/integrations/whatsapp-templates))
* Contacts with phone numbers in your contact list ([Contacts guide](/docs/user-guides/chatbot/contacts/contacts-overview))
* A payment method configured in your [Meta billing settings](https://business.facebook.com/billing_hub)

<Warning>
  Meta charges fees for each template message sent. Fees vary by country and template category. See [Meta's WhatsApp pricing](https://developers.facebook.com/docs/whatsapp/pricing) for current rates.
</Warning>

## Creating a WhatsApp Campaign

1\. Navigate to the **Campaigns** section in the dashboard sidebar and click **+ New campaign**.

<Frame>
  <img alt="Campaigns list page with New campaign button" />
</Frame>

The new campaign page has two tabs: **Configuration** and **Audience**.

### Configuration

<Frame>
  <img alt="New campaign configuration page showing Delivery, Replies, and Content sections with a message preview" />
</Frame>

**Delivery** — Select **WhatsApp** as your channel and choose the phone number to send from. The selected number displays its verified business name.

**Replies** — Choose how your team handles replies from campaign recipients:

* **AI replies** (default) — Your AI agent responds to replies automatically. The conversation continues like any normal inbound chat.
* **Human takeover** — When a recipient replies, a helpdesk ticket is created automatically. Your team picks up the conversation from there.

**Content** — Enter a campaign name, then click **Select from template** to browse your approved templates from Meta. A preview of the message appears on the right as you configure it.

All template categories are supported: **Marketing**, **Utility**, and **Authentication**. Templates with headers (image, video, or document) display a media preview.

<Frame>
  <img alt="Completed campaign configuration with template selected and message preview" />
</Frame>

If your template includes variables (e.g., `{{name}}`), map each one to a data source:

* **Contact field** — Pulls from the recipient's contact data (name, email, phone number, or custom attributes). Each recipient gets a personalized value.
* **Static value** — Enter fixed text that will be the same for all recipients.

Click on a variable in the template body to open the mapping dropdown.

<Frame>
  <img alt="Variable mapping dropdown showing contact fields (Name, Email, Phone), custom attributes (Tag, City), and free text option" />
</Frame>

### Audience

Switch to the **Audience** tab to choose recipients.

<Frame>
  <img alt="Audience tab showing the contact list with name, tag, and city columns" />
</Frame>

Browse your contact list and select who should receive the campaign. You can:

* **Search** contacts by name or phone number
* **Filter** by custom attributes — click a column header like **Tag** or **City** to filter by specific values

<Frame>
  <img alt="Tag filter dropdown showing Customer and VIP Customer options" />
</Frame>

<Frame>
  <img alt="Contact list filtered by Customer tag showing matching contacts" />
</Frame>

You can combine search and filters to narrow down your audience further.

<Frame>
  <img alt="Audience filtered by city and searched by name, showing one matching contact" />
</Frame>

The selected contact count appears at the top of the tab. At least one contact is required to send.

<Info>
  Only contacts with a valid phone number can receive WhatsApp campaign messages. If a contact doesn't appear in the list, make sure their phone number is set in their [contact profile](/docs/user-guides/chatbot/contacts/contacts-overview).
</Info>

## Sending Your Campaign

Once you've configured delivery, content, and audience, click **Send now** in the top right. You'll be redirected to the campaign detail page where you can monitor delivery in real time.

## Monitoring Delivery

After sending, the campaigns list shows the status and activity for each campaign at a glance. Hover over the activity bar to see a breakdown of delivery stages.

<Frame>
  <img alt="Campaign activity bar with tooltip showing Sent, Delivered, and Replied counts" />
</Frame>

Click a campaign to open the detail page with full delivery visibility:

* **Status counters** — Queued, Sending, Sent, Delivered, Read, Replied, and Failed counts at the top.
* **Overview** — Campaign name, channel, reply mode, send time, and recipient count.
* **Content** — The template message that was sent.
* **Delivery funnel** — A visual breakdown showing the percentage of recipients at each stage. Helps you see drop-off between Sent → Delivered → Read → Replied.
* **Recipients table** — A searchable, filterable list of every recipient with their delivery status and timestamps.

<Frame>
  <img alt="Campaign detail page showing overview, content, delivery funnel, and recipients table" />
</Frame>

<Info>
  **Understanding messaging tiers:** Meta assigns a messaging tier to your WhatsApp Business Account based on quality and volume. Your tier determines how many unique contacts you can message per day. The current usage is shown as **Meta limits** in the top right of the campaigns page.
</Info>

## Reply Handling

When contacts reply to your campaign, the behavior depends on the mode you selected during creation:

**AI Replies** — Your AI agent handles the reply automatically. The conversation continues like a normal inbound chat. This works well for product inquiries, support questions, and automated follow-ups.

**Human Takeover** — The reply creates a helpdesk ticket tagged with the campaign name. Your team picks up the conversation and responds manually from the helpdesk inbox.

<Frame>
  <img alt="Helpdesk ticket created from a campaign reply, showing the campaign name in the subject and the recipient's message" />
</Frame>

<Info>
  Replies are attributed to your campaign for **72 hours** after sending. After that window, incoming messages from the same contact are treated as regular inbound conversations.
</Info>

## Troubleshooting

* **Campaign stuck in "Sending"?** Large campaigns are processed in batches and may take a few minutes. If there's no progress after 10 minutes, check that your [WhatsApp integration](/docs/user-guides/integrations/whatsapp) is still connected.
* **Recipients showing "Failed"?** Common causes include an invalid phone number, Meta rate limits being reached, or a missing payment method in your [Meta billing settings](https://business.facebook.com/billing_hub).
* **Template not appearing?** Make sure the template has been approved in Meta. Only approved templates appear in the campaign template picker.
* **Replies not creating tickets?** Verify that reply behavior is set to **Human Takeover** and that the reply arrived within the 72-hour attribution window.
* **Hitting rate limits?** Your Meta messaging tier determines daily send limits. Check your tier on the campaigns page. To increase your tier, maintain high message quality and gradually increase volume.


# Playground
Source: https://chatbase.co/docs/user-guides/chatbot/playground

Test and optimize your AI agent before deployment. Compare different AI models, adjust settings like temperature and system prompts, and evaluate responses to ensure your agent performs exactly as needed for your users.

<Frame>
  <img alt="Playground Settings" />
</Frame>

### AI Model

The AI model refers to the specific machine learning model used to generate responses for your AI agent. Each model has different capabilities, performance characteristics and message credits cost, allowing you to choose the one that best fits your needs.

<AccordionGroup>
  <Accordion title="GPT">
    * **GPT-5**: 1 message credit
    * **GPT-5.1**: 1 message credit
    * **GPT-5.2**: 2 message credits
    * **GPT-5 Mini**: 1 message credit
    * **GPT-5 Nano**: 1 message credit
    * **GPT-5.4**: 2 message credits
    * **GPT-5.4 Mini**: 1 message credit
    * **GPT-5.4 Nano**: 1 message credit
    * **GPT-OSS-120B**: 1 message credit
    * **GPT-OSS-20B**: 1 message credit
    * **GPT-4o**: 1 message credit
    * **GPT-4o Mini**: 1 message credit
    * **o4 Mini**: 1 message credits
  </Accordion>

  <Accordion title="Claude">
    * **Claude 4.6 Opus**: 5 message credits
    * **Claude 4.6 Sonnet**: 3 message credits
    * **Claude 4.5 Haiku**: 1 message credit
    * **Claude 4.5 Sonnet**: 3 message credit
    * **Claude 4.5 Opus**: 5 message credits
  </Accordion>

  <Accordion title="Gemini">
    * **Gemini 3.1 Pro**: 2 message credits
    * **Gemini 3.1 Flash Lite**: 1 message credit
    * **Gemini 3 Flash**: 1 message credit
    * **Gemini 3.5 Flash**: 2 message credits
    * **Gemini 2.5 Pro**: 2 message credit
    * **Gemini 2.5 Flash**: 1 message credit
  </Accordion>

  <Accordion title="Llama">
    * **Llama 4 Scout**: 1 message credit
    * **Llama 4 Maverick**: 1 message credit
  </Accordion>

  <Accordion title="DeepSeek">
    * **DeepSeek-V3**: 1 message credit
    * **DeepSeek-R1**: 1 message credits
  </Accordion>

  <Accordion title="Grok">
    * **Grok 4**: 4 message credits
    * **Grok 3**: 3 message credit
    * **Grok 3 mini**: 1 message credits
  </Accordion>

  <Accordion title="Kimi">
    * **KimiK2**: 1 message credit
  </Accordion>
</AccordionGroup>

## Side bar

### Temperature

<Frame>
  <img alt="Playground Compare" />
</Frame>

Temperature controls how creative and varied your AI agent's responses will be. This setting ranges from 0 to 1 and directly affects response predictability:

* **Lower temperature (close to 0)**: Produces focused, consistent responses by selecting the most probable outputs
* **Higher temperature (closer to 1)**: Generates more creative and varied responses with less predictability

<Note>
  The default temperature is set to 0. You can adjust this value to experiment with different response styles and find what works best for your use case.
</Note>

### AI Actions

AI Actions enable your agent to perform tasks beyond answering questions, including scheduling appointments, collecting lead information, handling billing and payments support requests using Stripe, sending Slack notifications, conducting web searches, and integrating with external systems.

<Tip>
  Test your AI Actions thoroughly with various user inputs to ensure they activate at the right moments and provide the expected functionality.
</Tip>

For complete setup instructions and configuration details, see our [Actions Overview guide](/docs/user-guides/chatbot/actions/actions-overview).

### System Prompt

The system prompt defines your AI agent's personality, behavior, and response style. You can use it to establish your agent's role, set the conversational tone, and provide specific instructions for handling different types of user queries.

**Key benefits:**

* **Brand alignment**: Match your agent's voice to your company's communication style
* **Consistent behavior**: Ensure predictable responses across all user interactions
* **Specialized knowledge**: Guide the agent to focus on specific topics or use cases
* **Professional tone**: Set appropriate formality levels for your audience

**Best practices:**

* Be specific about the agent's role (e.g., "customer support specialist," "sales consultant")
* Include examples of desired response styles
* Set clear boundaries for what the agent should and shouldn't discuss
* Test different prompts to find the most effective approach for your use case

<Tip>
  Start with a simple, clear description of your agent's purpose, then gradually add specific instructions based on user feedback and common queries.
</Tip>

## Compare Area

<Frame>
  <img alt="Playground Compare" />
</Frame>

The "Compare" area allows you to add different AI agents next to each other and assign different settings to each to make testing and figuring out the settings that best suit your needs easier!

The same message will be sent to all chats so that you can test the AI agent's response to the same message under different settings.

You can also configure the below settings (buttons explained from left to right):

1. You can untick the 'Sync' button if you don't want the message sent to this AI agent to reflect on the rest of chats.

<Frame>
  <img alt="Playground Compare Sync" />
</Frame>

2. Adjust the settings for this specific AI agent (AI model, temperature, prompt).
3. Save the settings you've assigned to the AI agent to the main AI agent's settings.
4. From the three dots, you can move the position of the agent either to the left or right, reset the chat, or to delete the chat box completely.

<Frame>
  <img alt="Playground Compare Actions" />
</Frame>

You can also use any of the following options:

* Clear all chats.
* Reset the settings of the AI agent to the main settings.
* Add a new AI agent to test with.

<Frame>
  <img alt="Playground Demo" />
</Frame>

5. To change which AI models you are testing, click the filter icon and select a new model from the dropdown.

<Frame>
  <img alt="Playground Demo" />
</Frame>

> **Note:** If you see the error "***This agent is currently unavailable. If you are the owner please check your account***", it means you have run out of message credits and need to purchase new add-on message credits. You can read all about our add-ons [here](https://www.chatbase.co/docs/user-guides/workspace/settings#add-ons)


# Settings
Source: https://chatbase.co/docs/user-guides/chatbot/settings



## General

This tab shows the AI agent ID, the number of characters, the name of the AI agent, the credit limit, delete AI agent and delete conversations.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

The Credit Limit is activated when you want to set the maximum limit of credits to be used by this AI agent from the credits available on the workspace.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

***DANGER ZONE***

The actions done in the section aren’t reversible. If you deleted the AI agent or the conversations, you can’t retrieve them moving forward.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

## AI

This is the most important section when it comes to the behavior of the AI agent and how it answers the users’ questions.

This section contains the model of the LLM, the instructions prompt, the temperature of the AI, and when was the AI last trained.

### Instructions

This section outlines how the AI agent should behave when answering user questions, helping align its responses with your goals and needs.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

The instructions area allows you to either add a custom prompt or use a pre-defined example of instructions. Customizing the AI agent's behavior through these prompts ensures it matches your brand, tone, and interaction style.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

### Model

You can select the model the AI agent will use to respond to users, with options including the lastest OpenAI, Claude, Cohere, and Gemini models.

You can find [the full list here.](./playground)

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

#### Guidelines

Here are key guidelines to follow:

* **Modify the bot's personality**: Define whether the AI agent should adopt a formal, casual, or specific emotional tone. This will influence its responses in various situations. You could specify, for example: “You are a friendly and casual AI Assistant.”
* **Responding to specific question types**: Determine whether the AI agent should provide short, straightforward answers or more detailed, thoughtful responses depending on the question. It’s important to define how the bot should handle factual vs. opinion-based questions.
* **Handling cases when an answer is not available**: Clarify what the AI agent should do if it doesn't have an answer. For example, should it politely suggest the user check elsewhere, provide general advice, or offer alternative resources?
* **Deciding when and how to provide URLs**: Specify when the AI agent should include URLs in its responses. Should the bot only provide links when directly requested, or should it proactively suggest relevant resources?
* **Direct its focus on certain topics**: If the AI agent needs to specialize in specific areas, you could direct it with a prompt such as: "You are an AI Assistant specializing in environmental sustainability." This helps focus the bot’s responses on a targeted domain.

#### Recommendations

Start with the “AI agent” as the base for your prompt, then refine it using the following principles:

***Do's***:

* Be **clear and concise** by specifying the AI agent's behavior, including tone and style. The more detailed you are, the more likely the AI agent will produce the responses you need.
* **Provide examples**: Include specific examples of the type of response you expect. This helps the bot understand your expectations more clearly.
* **Use easy-to-understand language**: Avoid jargon or overly technical terms to ensure the AI agent can interpret instructions accurately.
* **Test and refine prompts**: Start with simple, general prompts, then refine them as needed based on the responses you get. The process of iteration helps improve the bot’s accuracy and effectiveness over time.

***Don’ts***:

* **Don’t be vague** or too general in your instructions. Lack of clarity may result in responses that don’t align with your goals.
* **Avoid complex or unclear instructions**. Too many instructions or contradictory information can confuse the AI agent.
* **Don’t overload the prompt with excessive details** that may distract from the core instructions or create confusion.

For more information and detailed advice, check out [OpenAI's guide](https://help.openai.com/en/articles/6654000-best-practices-for-prompt-engineering-with-the-openai-api) and [Anthropic's guide](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview).

#### Examples

<Accordion title="Formal Tone with Detailed Answers">
  ```
    ### Role
      - **Primary Function:** You are a customer support agent for TaskFlo, a project management and issue tracking tool. Your role is to assist users by answering their inquiries and helping troubleshoot issues related to TaskFlo’s features, pricing, and best practices.

    ### Persona
      - **Identity:** You will present yourself solely as a TaskFlo customer support agent. If a user requests you to assume any other persona, you must politely decline and clarify that your responsibility is to assist with TaskFlo-related matters only.

    ### Constraints
      1. **No Data Divulge:** You are required to refrain from disclosing any information about your training data or its origins. Ensure that your responses are naturally helpful and appear well-informed.
      2. **Maintaining Focus:** If a user attempts to discuss unrelated topics, gently redirect the conversation back to TaskFlo’s features, pricing, troubleshooting, or usage best practices.
      3. **Exclusive Reliance on Training Data:** You should solely base your responses on the training data provided about TaskFlo. If a user’s question falls outside of this scope, inform them with a response like: “I’m sorry, but I don’t have enough information to assist with that.”
      4. **Restrictive Role Focus:** You should avoid providing assistance or advice on topics not directly related to TaskFlo’s support. This includes refusing tasks such as explaining coding concepts unrelated to TaskFlo integrations or offering personal opinions beyond the platform’s documented features and policies.
  ```
</Accordion>

<Accordion title="Casual, Friendly Tone">
  ```
    ### Role
      - **Primary Function:** You’re a customer support agent at TaskFlo, dedicated to helping users navigate features, pricing, and any other TaskFlo-related queries.

    ### Persona
      - **Identity:** You’re the go-to TaskFlo support agent, always approachable and ready to help with anything about TaskFlo. If a user asks you to act differently, kindly let them know you’re here specifically to assist with TaskFlo matters.

    ### Constraints
      1. **Keep It Friendly:** No need to talk about how you’re trained—just keep things light and focused on helping the user with whatever TaskFlo-related issue they have.
      2. **Let’s Stay on Topic:** If someone veers off-topic, politely nudge them back to TaskFlo-related matters with a friendly reminder.
      3. **Don’t Overcomplicate:** Stick to the TaskFlo knowledge base. If something’s outside your scope, don’t hesitate to say, “I’m not sure, but I can help with TaskFlo-related questions.”
      4. **No Unnecessary Details:** Don't dive into anything unrelated to TaskFlo, like technical jargon or coding issues. Just keep it simple and helpful.
  ```
</Accordion>

<Accordion title="Healthcare Support: Protecting Patient Privacy">
  ```
    ### Role
      - **Primary Function:** You’re a healthcare support assistant, here to help users with general healthcare-related inquiries, procedures, and information related to medical services.

    ### Persona
      - **Identity:** You’re dedicated to assisting with healthcare queries in a secure, professional, and privacy-conscious manner. If a user asks for personal medical advice or attempts to share PII, kindly remind them that you're here for general support.

    ### Constraints
      1. **No Personal Information:** Never request or accept personal health information, including but not limited to patient names, addresses, social security numbers, or any other PII. If a user shares such information, politely inform them to avoid doing so for privacy and security reasons.
      2. **Focus on General Information:** Always provide general healthcare information and refer users to official healthcare channels for specific medical advice or to discuss personal health concerns.
      3. **Maintain Privacy Standards:** Ensure that all conversations maintain strict privacy guidelines, following healthcare privacy regulations (e.g., HIPAA).
      4. **Redirect PII Requests:** If a user attempts to share sensitive information, respond with: “I’m sorry, I cannot assist with personal medical information. Please consult with a healthcare professional for that.” 
  ```
</Accordion>

### Temperature

The temperature is adjusted based on how creative you want your AI agent to be while answering the questions. It’s recommended to set the temperature on 0.2 as it should be reserved and avoid providing answers that aren’t in the sources.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

### Training

The **Training** section displays when your AI agent was last trained and allows you to manage the **Auto-retrain** feature. The **Auto-retrain** feature enables your AI agent to automatically retrain on your sources every week, ensuring it remains up-to-date with your dynamic sources.

<Frame>
  <img alt="AI Settings - Training section" />
</Frame>

## Voice

This section allows you to configure how your AI agent sounds and behaves during voice conversations.

### Credit Usage

Voice sessions consume credits based on two components:

* **Agent voice**: Every voice session consumes **6 message credits per minute**. This is a per-minute cost regardless of the actual messages exchanged.
* **AI model**: Each response from the AI agent during a voice session consumes message credits based on the model used, just like in text conversations. See the [full list of models and their message credit costs](./playground#ai-model).

The total credit cost of a voice session is the sum of both components.

<Frame>
  <img alt="Voice model settings" />
</Frame>

<Accordion title="Pricing Example">
  Suppose your voice agent uses **GPT-5.1** (1 message credit per request).

  If a user has a **10-minute voice call** with **15 AI requests**:

  | Component          | Calculation                    | Message Credits |
  | ------------------ | ------------------------------ | --------------- |
  | Agent voice        | 10 min x 6 credits/min         | 60              |
  | AI model (GPT-5.1) | 15 requests x 1 credit/request | 15              |
  | **Total**          |                                | **75**          |
</Accordion>

### Model

Select the AI model used specifically for voice sessions. This model is separate from the one used for text-based conversations and only applies when users interact with your AI agent through voice.

You can also adjust the **Temperature** to control how creative or reserved the AI agent's responses are during voice conversations.

<Frame>
  <img alt="Voice model settings" />
</Frame>

### Transcriber

Choose the model used to transcribe user speech during voice conversations.

<Frame>
  <img alt="Voice transcriber settings" />
</Frame>

* **Language**: The language used to transcribe user speech. Select **Multilingual (auto-detect)** to let the transcriber detect the language automatically, or pick a specific language to improve accuracy.
* **Model**: The speech-to-text model that converts user audio into text. Each model supports a different range of languages.
* **Silence Threshold**: Seconds of silence before the AI agent considers the user has finished speaking. Lower values switch turns faster but may cut off pauses mid-thought.
* **Noise Sensitivity**: Controls how loud audio must be to count as speech. Lower values pick up quieter speech but are more sensitive to background noise. Higher values filter out noise but may miss soft-spoken users.

### Agent Voice

Choose a voice for your AI agent and fine-tune how it sounds during voice conversations.

<Frame>
  <img alt="Voice agent voice settings" />
</Frame>

Click on the voice selector to open the voice picker, then fine-tune how the selected voice sounds. The available controls depend on the voice you picked, some voices expose sliders such as speed, stability, and similarity, while others let you describe the desired delivery. A few examples:

* **Speed**: Controls how fast or slow the AI agent speaks. Adjust the slider between slower and faster to match your preferred pace.
* **Stability**: Determines how stable the voice is. Lower values introduce a broader emotional range, while higher values produce a more consistent, monotone delivery with limited emotion.
* **Similarity**: Determines how closely the AI adheres to the original voice when replicating it. Higher values result in a closer match to the selected voice.
* **Voice instructions**: For voices that support it, enter a short prompt describing the tone, style, or dialect you want the AI agent to use when speaking.

Make sure to click **Save** on the voice card to apply your changes.

#### Selecting a voice

The voice picker has two tabs: **All voices** for browsing pre-recorded voices, and **Custom voice** for bringing a custom voice from a supported provider.

<Frame>
  <img alt="Voice selection modal" />
</Frame>

Under **All voices**, you can search by name and filter voices by language, accent, age, and gender. Each row shows the voice's supported languages and a **Preview language** dropdown, pick a language and click the play button to hear a sample of the voice speaking it. Select a voice and click **Confirm voice** to apply it to your agent.

<Frame>
  <img alt="Custom voice selection modal" />
</Frame>

Under **Custom voice**, you can add a custom public voice that isn't in the pre-recorded list by referencing it directly from your provider:

* **Provider**: The voice provider that hosts the custom voice (for example, ElevenLabs).
* **Voice ID**: The identifier of the voice in the provider's account. Paste it in and click **Add voice** to make it available for selection, then click **Confirm voice** to apply it to your agent.

<Note>
  Custom voices only work with **publicly available shared voices** from your provider. Private voices in your provider account are not supported.
</Note>

### Messages

Configure the initial greeting and error messages for your voice agent.

<Frame>
  <img alt="Voice messages settings" />
</Frame>

* **Initial message**: The first message the AI agent speaks when a voice session begins. If left empty, the voice agent will wait for the user to speak first.
* **Error message**: The message played if the voice session encounters an error. If left empty, the default error message "The voice session encountered an error. Please try again." will be used.

### Session Configurations

Control how the AI agent handles interruptions, silence, and text input during active voice calls.

<Frame>
  <img alt="Voice session configurations settings" />
</Frame>

* **Allow interruptions**: When enabled, users can speak over the AI agent to interject mid-response. Disable this if you'd prefer the agent to always finish speaking before listening for the user's next turn. Defaults to **enabled**.
* **End conversation after silence**: The number of seconds of inactivity after which the call is automatically ended. Useful for closing out abandoned sessions and avoiding unnecessary credit usage. Defaults to **300 seconds**.
* **Allow text input during voice calls**: When enabled, users can type messages mid-call alongside speaking. Helpful for entering details that are easier to type than to say, such as names, emails, or URLs. Defaults to **disabled**.

### Recordings

Enable recording of voice sessions for quality review and training purposes. You can also toggle **Retain voice recordings forever** to keep recordings indefinitely, or set a custom retention period.

<Frame>
  <img alt="Voice recordings settings" />
</Frame>

### Limits

Control session volume and duration to manage costs and performance.

<Frame>
  <img alt="Voice limits settings" />
</Frame>

* **Max no. of concurrent voice sessions**: The maximum number of voice sessions that can run at the same time. If left empty, your plan's default limit will apply.
* **Max call duration**: The maximum length of a single voice call in minutes. The default is 15 minutes.
* **Allowed no. of daily calls**: The total number of voice calls allowed each day. If left empty, your plan's default limit will apply.

<Note>
  Your subscription plan enforces account-level limits for daily sessions and concurrent sessions across all your AI agents. You can set agent-specific limits here to further restrict usage for individual agents.
</Note>

## Security

You can limit what domains the iframe can be embedded in and also set the rate limits which restricts the amount of messages send from one device over the chosen time period.

You can also embed it on your website so your website visitors are able to use it.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

Additionally you can limit what domains the iframe can be embedded in and also set the rate limits which restricts the amount of messages send from one device over the chosen time period.

Finally, you are also able to set the message you display once this rate limit is hit.

## Notifications 

From this page, you can configure the notifications you get from the bot. You can either opt for getting one email per day that contains all the leads submitted for that day. You can also opt for another email that sends you a daily email with the conversations done on that day. 

You can add multiple email addresses to receive these emails if needed

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

## Webhooks 

On this page, you can configure a webhook to trigger based on a selected action.

<Frame>
  <img alt="Chatbase Embed Code Example" />
</Frame>

Currently, the available action is “lead submitted.” When a new lead is submitted through your bot’s lead form, our system automatically triggers the webhook.

The webhook sends a POST request to your chosen API, including the conversation ID and lead form data (name, email, and phone number).

You can use this to automate workflows with third-party tools by capturing the webhook and using it to send messages or perform other actions.


# Bubble
Source: https://chatbase.co/docs/user-guides/integrations/bubble



## Step 1: Set Up Your Chatbase AI agent

To integrate your Chatbase AI agent into your Bubble application, begin by logging into your Chatbase account. If you haven't already created an account, you can sign up for a free account. After signing in, you can configure your bot within the Chatbase platform by uploading relevant data sources, such as files, text snippets, websites, or question-and-answer pairs, which the bot can use to build its knowledge base.

Here is a [step-by-step roadmap for successfully deploying your Chatbase agent](/docs/user-guides/quick-start/your-first-agent).

## Step 2: Generate and Copy Your Chatbase AI agent Embed Code

1\. Every agent you create on Chatbase has a unique embed code you can use to embed it on your website. Once you've set up your agent on Chatbase, navigate to your [**Dashboard**](https://www.chatbase.co/dashboard/) page, and select the specific bot you wish to integrate with your Bubble application.

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

2\. On the agent preview page, click on the **Deploy** tab.

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

3\. A new page should come up. Click on **Manage** for the Chat Widget.

<Frame>
  <img alt="Chat Widget [Manage]" />
</Frame>

4\. Click on **Embed** and select the **Chat widget** embed type. Scroll down and Click **Copy** to copy the provided script.

<Frame>
  <img alt="Copy Script" />
</Frame>

## Step 3: Embed Chatbase AI agent on Your Bubble App

1\. Once you've copied your Chatbase embed code, sign into your Bubble account and head to your account dashboard.

2\. On your dashboard, pick out the Bubble app or website you wish to embed the agent on and click the **Launch Editor** button next to it.

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

3\. Once your Bubble Editor comes up, scroll down to the section of the page you want to add the embed code.

4\. On the left sidebar of the editor, locate the HTML component and drag it to the section of the page.

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

5\. Double-click on the HTML component to reveal the code editor.

6\. Paste the embed code on the editor and you should automatically see a floating agent icon on the bottom left corner of the editing canvas.

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

7\. You can now preview your Bubble app to test your agent.

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

**Congratulations, your Chatbase agent is now live on your Bubble app!**

> **Note:** You can customize the appearance and colors of your bot on your Chatbase dashboard. To do this, go to your **dashboard**, choose a bot, click the **Settings** tab on the top of the page, and then click **Chat Interface** on the left sidebar to reveal the agent customization options.


# Email
Source: https://chatbase.co/docs/user-guides/integrations/email

Enable AI-powered email responses with automated customer support through email

## Overview

Chatbase's Email Integration enables your AI agent to automatically respond to customer emails, providing instant support and information directly through your company's email system. Set up takes just minutes and provides seamless AI-powered email automation across your organization.

<Info>
  **Prerequisites Required**: Before configuring the Email channel, you must:

  1. [Create a Chatbase account](https://www.chatbase.co/auth/signup) and build your AI agent
  2. Configure your email domain ([Email settings](/docs/user-guides/chatbot/email-settings)) with proper authentication (DKIM, SPF, forwarding)
  3. Have an active Chatbase agent ready for deployment
</Info>

## How Email Integration Works

The Email Integration allows your AI agent to automatically monitor and respond to incoming emails through your configured email addresses. Here's how it works:

1. **Email Reception**: Incoming emails are forwarded to your Chatbase agent
2. **AI Processing**: The agent analyzes the email content and determines the appropriate response
3. **Automated Reply**: AI generates and sends a contextually appropriate response
4. **Delivery Monitoring**: System tracks email delivery and alerts you of any issues

<Warning>
  **Domain Configuration Required**: Email integration will not function until your email domain is properly configured with forwarding, DKIM, and SPF records. Complete domain setup in **Settings** → **Email** before deploying, you must also use a **company email**.
</Warning>

## Setup Instructions

<Steps>
  <Step title="Access Your Chatbase Dashboard">
    Navigate to your [Chatbase dashboard](https://www.chatbase.co/dashboard/) and select the agent you want to integrate with email.

    <Tip>
      If you haven't created an agent yet, follow our [step-by-step guide to creating your first agent](/docs/user-guides/quick-start/your-first-agent) to get started.
    </Tip>
  </Step>

  <Step title="Configure Your Email Domain">
    Navigate to **Settings** → **Email** and follow the domain configuration process. Refer to [Email settings](/docs/user-guides/chatbot/email-settings) for detailed instructions.

    <Check>
      Verify all configuration steps are complete before proceeding. Email addresses with configuration issues will display warnings.
    </Check>
  </Step>

  <Step title="Enable the Email Channel">
    1. Navigate to **Deploy** → **Email**

    <Frame>
      <img alt="Email integration navigation" />
    </Frame>

    2. Click **Manage** to access email deployment settings

    <Frame>
      <img alt="Email manage button" />
    </Frame>

    3. Click **Deploy** and toggle the channel to **Enabled**

    <Frame>
      <img alt="Email deployment interface" />
    </Frame>
  </Step>

  <Step title="Customize Email Settings">
    Configure your AI agent's email behavior and appearance through **AI Settings** and **Email Configurations**.

    <Frame>
      <img alt="Email configuration options" />
    </Frame>
  </Step>
</Steps>

## Email Configuration Options

Customize how your AI agent sends and formats emails to match your brand and communication standards.

### Reply Address

Select which configured email address will appear as the reply-to address for AI-generated emails.

<Card title="Configuration" icon="reply">
  Choose from your verified email addresses. Addresses with configuration issues (forwarding, DKIM, or SPF not enabled) will display warnings, and you will not be able to select them.
</Card>

### Deliverability Alert Contact

Designate a team member to receive notifications about email delivery failures and issues.

<Card title="Monitoring" icon="bell">
  Select from your account members or choose "None" to disable delivery alerts.
</Card>

**Recommended**: Assign this to your technical or support team lead to ensure quick resolution of delivery issues.

### Email Display Name

Set the sender name that appears in recipients' inboxes when they receive emails from your AI agent.

<Card title="Branding" icon="signature">
  This name appears in the "From" field and represents your brand identity in customer communications.
</Card>

**Examples**:

* "CustomerSupport at \[Company Name]"
* "\[Company Name] AI Assistant"
* "Help Desk"

### AI Composition Disclaimer

Add transparency by including a disclaimer that identifies AI-generated content.

<Card title="Transparency" icon="info-circle">
  When enabled, adds a customizable disclaimer at the end of emails (default: "This message is composed by AI.")
</Card>

**Use Cases**:

* Regulatory compliance requirements
* Company transparency policies
* Building customer trust

### Email Signature

Create a professional signature that appears at the bottom of all AI-generated emails.

<Card title="Customization" icon="pen-fancy">
  Supports rich text formatting including multiple lines, links, styling, and contact information.
</Card>

**Signature Elements**:

* Company contact information
* Social media links
* Legal disclaimers
* Unsubscribe options

<Note>
  Remove "**Powered by Chatbase**" branding from your emails by purchasing the white-label addon. See [Pricing](https://www.chatbase.co/pricing) for details.
</Note>

## Common Use Cases

The Email Integration is ideal for:

* **Customer Support Automation**: Handle common inquiries and FAQs automatically
* **Employee Self-Service**: Answer HR, IT, or administrative questions instantly
* **Lead Qualification**: Screen and respond to sales inquiries with relevant information
* **Appointment Scheduling**: Assist with booking and calendar management
* **Order Status Updates**: Provide shipping and order information on demand

<Tip>
  **Getting Started**: Begin with a focused use case like FAQ responses or status inquiries, then expand your agent's capabilities as you refine its performance.
</Tip>


# Framer
Source: https://chatbase.co/docs/user-guides/integrations/framer



## Step 1: Sign Into Your Chatbase Account and Copy Your Embed Code

1\. Log into your Chatbase account and navigate to the [**Dashboard**](https://www.chatbase.co/dashboard/) page.

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

2\. On the list of available agents, click on the one you want to integrate into your Framer website. Once you've clicked on your chosen agent, you'll be directed to the AI Playground page.

3\. On the agent preview page, click on the **Deploy** tab.

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

4\. A new page should come up. Click on **Manage** for the Chat Widget.

<Frame>
  <img alt="Chat Widget [Manage]" />
</Frame>

5\. Click on **Embed** and select the **Chat widget** embed type. Scroll down and Click **Copy** to copy the provided script.

<Frame>
  <img alt="Copy Script" />
</Frame>

## Step 2: Sign Into Your Framer Website and Embed Your Chatbot

1\. Sign in to your Framer website and head to your project dashboard

2\. Click on the website project you wish to embed your Chatbase agent

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

3\. After clicking through to open the website project, locate the page you wish to embed your agent on the left side of the editor and click the three-dot icon next to the name of the page.

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

4\. Click **Settings** to open the settings for that page.

5\. On the Settings page, scroll down to find the section labeled "**Custom Code**."

6\. Right under the Custom Code section, paste your Chatbase agent embed code in the first box labeled *"Start of \<head> tag"* and click **Save** on the top right corner of the panel.

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

7\. If everything was done well, you should now see a floating Chatbase agent icon on the bottom left corner of your Framer website (on the page you added it to)

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

**Congratulations! Your Chatbase bot is now ready to use on your website.**

> **Note:** You can customize the appearance and colors of your bot on your Chatbase dashboard. To do this, go to your [**dashboard**](https://www.chatbase.co/dashboard/), choose a bot, click the **Settings** tab on the top of the page, and then click **Chat Interface** on the left sidebar to reveal the agent customization options.


# Freshdesk
Source: https://chatbase.co/docs/user-guides/integrations/freshdesk



Integrating Freshdesk with Chatbase allows your custom agent to automatically escalate complex customer issues to your human support team by creating a ticket directly in Freshdesk. The AI agent generates a Freshdesk ticket that includes a clear summary of the user’s issue along with the relevant conversation context.

This ensures that when a case requires human attention, your support team receives all the necessary information upfront, eliminating the need for customers to repeat themselves. The AI handles routine inquiries instantly, and when escalation is needed, Freshdesk becomes the system where your human agents step in to resolve the issue.

This guide will walk you through the steps required to connect your agent to Freshdesk and configure automated ticket creation for smooth handoffs to your support team.

## Setup Guide

Here's how to integrate a Chatbase agent with your Freshdesk account

### Step 1: Connect to Freshdesk

* Login to your Chatbase dashboard
* Select your Agent
* Choose **Settings**
* Select **Integrations**
* Click **Connect** under Freshdesk

***

### Step 2: Locate Your Freshdesk API Key & Subdomain

To authorize the integration, you’ll need your Freshdesk subdomain and API key.

Find your Freshdesk API Key:

1. Log in to your Freshdesk account.
2. Click your profile picture (top-right corner).
3. Select **Profile Settings**.
4. On the right-hand side, locate **Your API Key**.

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

***

### Step 3: Create 'Escalate to human' action

Now you're ready to configure your Escalate to Human action to route tickets to Freshdesk. You can follow [this step-by-step guide](https://www.chatbase.co/docs/user-guides/chatbot/actions/escalate-to-human) to set up the action properly.

***

That’s it! Your Freshdesk integration is now fully set up and ready to go. Whenever human intervention is required, your Chatbase agent will automatically create a ticket in Freshdesk with a summary of the user’s issue and relevant context, allowing your support team to step in and resolve the case seamlessly.


# Help Scout
Source: https://chatbase.co/docs/user-guides/integrations/helpscout



Integrating Help Scout with Chatbase allows your custom agent to automatically escalate complex customer issues to your human support team by creating a ticket directly in Help Scout. The AI agent generates a Help Scout ticket that includes a clear summary of the user’s issue along with the relevant conversation context.

This ensures that when a case requires human attention, your support team receives all the necessary information upfront, eliminating the need for customers to repeat themselves. The AI handles routine inquiries instantly, and when escalation is needed, Help Scout becomes the system where your human agents step in to resolve the issue.

This guide will walk you through the steps required to connect your agent to Help Scout and configure automated ticket creation for smooth handoffs to your support team.

## Setup Guide

Here's how to integrate a Chatbase agent with your Help Scout account

### Step 1: Connect to Help Scout

* Login to your Chatbase dashboard
* Select your Agent
* Choose **Settings**
* Select **Integrations**
* Click **Connect** under Help Scout to enter your credentials and finish the integration

***

### Step 2: Create 'Escalate to human' action

Now you're ready to configure your Escalate to Human action to route tickets to Help Scout. You can follow [this step-by-step guide](https://www.chatbase.co/docs/user-guides/chatbot/actions/escalate-to-human) to set up the action properly.

***

That’s it! Your Help Scout integration is now fully set up and ready to go. Whenever human intervention is required, your Chatbase agent will automatically create a ticket in Help Scout with a summary of the user’s issue and relevant context, allowing your support team to step in and resolve the case seamlessly.


# HubSpot
Source: https://chatbase.co/docs/user-guides/integrations/hubspot

Connect HubSpot to Chatbase so your AI agent can create tickets.

## Setup Guide

### Before you start

* A Chatbase account with an agent
* A HubSpot account with permissions to install apps
* A paid Chatbase plan with Integrations enabled

<Steps>
  <Step title="Open your Chatbase agent">
    Go to your Chatbase dashboard and select the agent you want to connect.

    <Frame>
      <img alt="Chatbase dashboard showing agents" />
    </Frame>
  </Step>

  <Step title="Connect HubSpot">
    Go to **Settings → Integrations**, find **HubSpot**, and click **Connect**.

    <Frame>
      <img alt="Integrations page with the HubSpot card" />
    </Frame>
  </Step>

  <Step title="Approve the requested scopes">
    You will be redirected to HubSpot. Review the requested permissions and click **Connect app**.

    <Frame>
      <img alt="HubSpot OAuth page" />
    </Frame>
  </Step>

  <Step title="Confirm the connection">
    After approval, you will return to Chatbase and see HubSpot marked as **Connected**.
  </Step>
</Steps>

## Configure the ticket action

Create a ticket action so your agent can open tickets in HubSpot.

<Steps>
  <Step title="Create a ticket action">
    Go to **Actions → Create action → Create ticket**.

    <Frame>
      <img alt="Create ticket action" />
    </Frame>
  </Step>

  <Step title="Select HubSpot">
    Choose **HubSpot** as the ticket platform, then fill in the ticket fields.
  </Step>

  <Step title="Save and test">
    Save the action and run a test conversation to verify a ticket is created in HubSpot.
  </Step>
</Steps>

## Use the integration

Once connected, your agent can create tickets in HubSpot when the action is triggered. You can check out [the action guide here](https://www.chatbase.co/docs/user-guides/chatbot/actions/escalate-to-human).

## Disconnect HubSpot

To disconnect, go to **Settings → Integrations**, find HubSpot, and click **Disconnect**.

## Uninstall the app

To uninstall Chatbase from HubSpot, follow HubSpot's [uninstall guide](https://knowledge.hubspot.com/integrations/connect-apps-to-hubspot#uninstall-an-app).


# Instagram
Source: https://chatbase.co/docs/user-guides/integrations/instagram



Integrating Instagram with Chatbase allows your custom agent to communicate directly with customers via your Instagram pages. This integration also enables you to take over the conversation whenever you want and communicate with users yourself through Instagram's direct messaging. It provides a seamless and efficient way to handle inquiries and automate responses, while giving you the freedom to interact with your customers whenever you choose. This guide will walk you through the necessary steps to connect your agent to Instagram, ensuring smooth and effective customer interactions.

<Info>
  Attachments are supported, allowing your agent to process them and respond based on their content. For more information, please refer to [this section](/docs/user-guides/chatbot/deploy#attachments).
</Info>

## Prerequisites

You will need the following:

* An Instagram [Professional Account](https://www.facebook.com/help/instagram/138925576505882).

* A Facebook Page connected to that account.

## Connecting Instagram

1\. First navigate to the instagram page settings for you Professional Account, then under '**How others can interact with you**', click on **Messages and story replies** > **Message controls** > **Allow Access to Messages**

2\. Navigate to your dashboard, and pick an agent.

3\. Navigate to **Deploy**.

4\. Click on **Connect** then **I understand**.

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

5\. Click on **Continue.**

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

6\. Login on **Get Started**. This will allow you to login to instagram and turn your account to a Professional Account if it is not already.

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

7\. Login to instagram.

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

8\. Choose the businesses affiliated with you Instagram page. If you have no business select **Opt in all current future businesses.**

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

9\. Choose the Facebook Page(s) linked to your Instagram.

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

10\. Select the Instagram page(s) you want to integrate.

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

11\. Click save.

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

12\. Your page should be integrated successfully, to see the integrated page click on **Manage.**

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

13\. You can add more pages or delete existing ones from the manage page.

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

## The Human Takeover Feature

The human takeover feature allows you to takeover the conversation whenever you would like so you can respond to your users directly. It works on a conversation level meaning you would be able to choose a specific conversation from the dashboard and stop the agent from answering.

<Note> some conversations may not have the human takeover icon, that happens when you delete a page from instagram's integration, you would still have access to your conversations in the chat logs, but since the integration was deleted you will not have access to the takeover feature. This will also happen if you delete a page and add it again. </Note>

#### Enable Human Takeover for a Specific Conversation

1\. Navigate to Activity > Chat logs

2\. in the **Chat logs section** make sure to show only Instagram chats.

3\. Click the human takeover icon.

4\. You can click the icon again to restore access to the agent.

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

## Connecting different agents to different pages

With the Chatbase Instagram integration, you can connect different agents to various pages. This capability allows multiple agents to manage different Instagram pages, providing specialized interactions for each page. here are the steps to adding different agents to different pages.

1\. After connecting the first page(s) you should now have access to the **manage Instagram pages** integrations page. navigate to the agent you want to connect then **Deploy > Manage.**

2\. Click the **Manage** button to navigate to the dashboard. If you want to connect another agent to an already connected page, click, then delete the page.

3\. Navigate to the agent you want to integrate to the page deleted, then reinitialize the integrations steps.

> **Note:** if you deleted an agent it will be selected in the integration steps, don't deselect any agent you want to stay connected to the instagram or facebook integrations on chatbase as deselecting the agent will result in disabling that agent for chatbase.

## Troubleshooting Authentication Issues

If you're having trouble completing the Instagram authentication flow, check the following:

<AccordionGroup>
  <Accordion title="Off-Meta activities tracking is disabled">
    If your Facebook account has **Off-Meta activities** set to "Don't track", this can block the Instagram authentication. To check this setting, go to your Facebook account settings and look under privacy settings for Off-Meta activities tracking, then enable it temporarily during the connection process.
  </Accordion>

  <Accordion title="Network redirect blocking authentication">
    Some networks redirect Facebook from `facebook.com` to `web.facebook.com` during login, which can block the authentication flow. When this happens, the Instagram login popup completes successfully and closes, but the first Meta window doesn't move to the next step. If you experience this, try switching to a different network (such as mobile data or a different WiFi connection) and attempt the connection again.
  </Accordion>
</AccordionGroup>

<Info>
  You can now enable or disable Instagram integration without disconnecting it. Disabling pauses messages while keeping your setup intact, and you can re-enable anytime to resume. New chats will still appear in your Chatbase dashboard chat logs.
</Info>

Now this brings an end to the Instagram integration guide, for any further questions please do not hesitate to [contact us](https://www.chatbase.co/help).


# Intercom
Source: https://chatbase.co/docs/user-guides/integrations/intercom



Integrating Intercom with Chatbase allows your custom agent to automatically escalate complex customer issues to your human support team by creating a ticket directly in Intercom. The AI agents generates an Intercom ticket that includes a clear summary of the user’s issue along with the relevant conversation context.

This ensures that when a case requires human attention, your support team receives all the necessary information upfront, eliminating the need for customers to repeat themselves. The AI handles routine inquiries instantly, and when escalation is needed, Intercom becomes the system where your human agents step in to resolve the issue.

This guide will walk you through the steps required to connect your agent to Intercom and configure automated ticket creation for smooth handoffs to your support team.

## Setup Guide

Here's how to integrate a Chatbase agent with your Intercom account

### Step 1: Connect to Intercom

* Login to your Chatbase dashboard
* Select your Agent
* Choose **Settings**
* Select **Integrations**
* Connect your Intercom to authorize access

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

***

### Step 2: Create 'Escalate to human' action

Now you're ready to configure your Escalate to Human action to route tickets to Intercom. You can follow [this step-by-step guide](https://www.chatbase.co/docs/user-guides/chatbot/actions/escalate-to-human) to set up the action properly.

***

That’s it! Your Intercom integration is now fully set up and ready to go. Whenever human intervention is required, your Chatbase agent will automatically create a ticket in Intercom with a summary of the user’s issue and relevant context, allowing your support team to step in and resolve the case seamlessly.


# Messenger
Source: https://chatbase.co/docs/user-guides/integrations/messenger



Integrating Messenger with Chatbase allows your custom agent to communicate directly with customers via your Facebook pages. It also allows you to takeover the conversation whenever you want and communicate with users yourself through messenger. This provides a seamless and efficient way to handle inquiries and automate responses, while giving you the freedom to talk to your customers whenever you want. This guide will walk you through the necessary steps to connect your agent to Messenger for your facebook pages, ensuring smooth and effective customer interactions.

<Info>
  Attachments are supported, allowing your agent to process them and respond based on their content. For more information, please refer to [this section](/docs/user-guides/chatbot/deploy#attachments).
</Info>

## Connecting to Messenger

1\. First navigate to your dashboard, and pick an agent.

2\. Navigate to **Deploy**.

3\. Click on 'Setup' if it is the first time you use the integration or manage, if you already connected pages before.

4\. If this is the first time you will be asked for permission to allow chatbase to use your information. **Note:** if you integrated some pages and would like to modify your selection pick the **Edit Previous Settings** option.

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

5\. Choose which pages you would like to integrate the agent with by selecting the **Opt into current pages only** option, if you want to integrate all pages on your account select the **Opt all current pages** option.

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

6\. Review the permissions and click save.

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

7\. click on **done** and wait for the integration to connect, this should take only a few seconds.

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

8\. Once connected you can manage you pages through the Messenger dashboard. It allows you to add new pages by clicking the **Connect a new Facebook page** button or delete existing pages using the three dots next to the page.

## Human Takeover Feature

The human takeover feature allows you to takeover the chat whenever you would like and chat with users yourself! It works on a conversation level meaning you would be able to choose a specific conversation from the dashboard and stop the agent from answering that conversation.

> **Note:** some conversations may not have the human takeover icon, that happens when you delete a page from the integrations dashboard, you would still have access to your conversations in the chat logs, but since the integration was deleted you will not have access to the takeover feature since this page's integration was deleted. This will also happen if you delete a page and add it again, so be careful when deleting pages from the messenger dashboard.

#### Enable human takeover for a specific conversation

1\. Navigate to Activity either through the Navbar or through the messenger dashboard.

2\. in the **Chat logs section** make sure to show only messenger chats.

3\. Click the human **takeover icon** to the right of source.

4\. Click the icon to enable human takeover.

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

5\. You can click the icon again to restore access to the agent.

## Connecting Different Agents to Different Pages

With the Chatbase Messenger integration, you can connect different agents to various pages. This capability allows multiple agents to manage different Facebook pages, providing specialized interactions for each page. here are the steps to adding different agents to different pages.

1\. After connecting the first page(s) you should now have access to the **manage Facebook pages** integrations page. navigate to the agent you want to connect then **Deploy > Manage.**

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

2\. As shown in the screenshot below, you will find all the pages connected to the same agent. To connect a new page to the same agent, click on **Connect a new Facebook Page.**

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

3\. Click on **Edit previous settings.**

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

4\. A list of pages connected will be displayed, if you deleted an agent in **step 2** it will be selected here, don't deselect any agent you want to stay connected to chatbase as deselecting the agent will result in disabling that agent for chatbase.

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

5\. Select the page you want to add the new agent to, and click the next button. if the page was already selected click the next button.

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

6\. Click the save button.

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

7\. The new page was added to the dashboard, and is now integrated with the new agent.

<Info>
  You can now enable or disable Messenger integration without disconnecting it. Disabling pauses messages while keeping your setup intact, and you can re-enable anytime to resume. New chats will still appear in your Chatbase dashboard chat logs.
</Info>


# Salesforce
Source: https://chatbase.co/docs/user-guides/integrations/salesforce



Chatbase provides a quick and easy way to add an intelligent AI-powered agent to your Salesforce organization.

In just a few minutes, you can make a Chatbase agent available across your company's Salesforce organization. The agent will be able to respond to users' cases and help the workspace provide round-the-clock automated support.

## Setup Guide

Here's how to integrate a Chatbase agent into your Salesforce organization:

### Step 1: Access and Configure Your Chatbase Agent

These steps assume that you have already created a Chatbase account and that you have a Chatbase agent already available for use. If you haven't yet, [<u>create a Chatbase account</u>](https://www.chatbase.co/auth/signup) and build your first AI agent. For example, you can create a company FAQ agent to handle common employee questions or build a recruiting assistant to screen candidates and schedule interviews. Get your agent ready before moving to the integration.

**Read More:** [<u>A step-by-step guide to creating a Chatbase agent in just a few minutes</u>](/docs/user-guides/quick-start/your-first-agent).

### Step 2: Connect the Salesforce Integration

1\. Once you have a Chatbase account and an agent set up, head over to your [dashboard](https://www.chatbase.co/dashboard/). On your dashboard, you'll find a list of all the agents you have created. Locate and click on the agent you wish to integrate with Salesforce.

2\. Click on the **Deploy** tab from the sidebar.

3\. Find the **Salesforce** integration and click on **Connect**.

4\. A new tab will open. It will ask you to login to your Salesforce account to authorize the integration.

### Step 3: Configure the Salesforce Integration

1\. Once you have authorized the integration, click **Manage** on the Salesforce integration card to configure the integration.

2\. You should see the following:

* Select the Salesforce user that the agent will reply as.
* Choose to either sync the agent's Salesforce with the base instructions or write a different instructions prompt. This is useful if you want to instruct the agent to escalate the case to a human agent in certain cases (e.g. escalate to a human agent if the user asks for a refund ...etc)

and then click on **Save**.

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

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

### Step 4: Enable the **Generate Draft Response** feature

Don’t want the agent to respond directly? You can also enable the **Generate Draft Response** feature. This allows you to review and edit the AI-generated response before sending it to your users.

Once you have configured the integration, you will have the option to enable the **Generate Draft Response** with a single click by following the below steps:

1\. Navigate to any of your cases and click on the gear icon at the top right then select "Edit Page"

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

2\. Select the section where you want the button to appear (for example, the Highlights Panel). Then click “Add Action”, search for “Chatbase AI Draft Response”, and add it to the layout.

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

The “Generate Draft Response” button should be available across all cases, allowing agents to easily generate responses when needed.


# Shopify
Source: https://chatbase.co/docs/user-guides/integrations/shopify



Connect your Shopify store to Chatbase and turn your AI agent into a powerful e-commerce assistant. Your agent will be able to help customers browse products, track orders, manage their cart, and update their account details—all through natural conversation.

<Warning>
  **You do not need to add any embed code manually.** Once you install the Chatbase Shopify app — whether from Chatbase or the Shopify App Store — the chat widget is automatically added to your store. You do not need to copy or paste any embed script into your theme code.
</Warning>

## Integration Methods

You can connect your Shopify store to Chatbase in two ways:

| Feature           | Via Chatbase (Recommended)                                                                                  | Via Shopify Marketplace    |
| ----------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------- |
| Billing           | Through Chatbase                                                                                            | Through Shopify            |
| Available Add-ons | Auto recharge credits, Extra message credits, Extra AI agents, Custom Domains, Remove 'Powered By Chatbase' | Auto recharge credits only |
| Number of Agents  | Multiple Agents (only a single agent connected to the Shopify store though)                                 | Single agent per account   |
| Setup Location    | Chatbase Dashboard                                                                                          | Shopify App Store          |

<Note>
  We recommend connecting via Chatbase for full access to all features and add-ons.
</Note>

## Method 1: Connect via Chatbase (Recommended)

This method gives you access to all Chatbase features and add-ons.

### Step 1: Set Up Your Chatbase Agent

Before connecting Shopify, you'll need a Chatbase account and an agent ready to use. If you haven't set this up yet, [create a free Chatbase account](https://www.chatbase.co/auth/signup) and build your first AI agent. Make sure to make your agent public.

**Read More:** [Create your first Chatbase agent in minutes](/docs/user-guides/quick-start/your-first-agent).

### Step 2: Find the Shopify Integration

1. Go to your [Chatbase dashboard](https://www.chatbase.co/dashboard/) and select the agent you want to connect to Shopify.

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

2. Click **Deploy** from the sidebar and make sure the **Chat Widget** toggle is switched on.

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

3. Find the Shopify card and click **Setup**.

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

### Step 3: Connect Your Store

1. Enter your Shopify store name, this is the subdomain of your myshopify.com URL. For example, if your store is at `mystore.myshopify.com,`enter`mystore`.

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

2. Click **Submit** to start the authorization process.
3. Shopify will ask you to authorize Chatbase. Review the requested permissions and click **Install**.

4) Once authorized, you'll be redirected back to Chatbase with a confirmation message.

### Step 4: Manage your integration

1. On the same Deploy page, click **Manage** on the Shopify card

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

2. Choose the theme you wish to embed your widget in and open your Shopify theme editor to configure the widget's display settings.

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

***

## Method 2: Connect via Shopify Marketplace

Choose this method if you prefer to manage billing through Shopify. Keep in mind that this option has limited add-ons and only allows a single AI agent.

### Step 1: Install the Chatbase App

1. Go to the **Chatbase** app listing on the **Shopify App Store:** [https://apps.shopify.com/chatbase](https://apps.shopify.com/chatbase)
2. Click **Install**.
3. Review the permissions Chatbase requires and click **Install** to approve.

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

### Step 2: Complete Setup

1. After installation, you'll be redirected to Chatbase onboarding process to finish setting up your account.
2. Follow the prompts to configure your agent.
3. Open your Shopify theme editor to configure the widget's display settings.

<Warning>
  Accounts created through the Shopify Marketplace are limited to a single agent. For multiple AI agents or additional add-ons, use Method 1 instead.
</Warning>

***

## Next Steps

Once your Shopify store is connected, you'll need to enable **actions** that allow your agent to assist customers with product searches, order lookups, cart management, and more.

<Frame>
  <img alt="Shopify Actions" />
</Frame>

<Card icon="bolt" href="/user-guides/chatbot/actions/shopify-actions" title="Shopify Actions">
  Learn how to configure and use Shopify actions to help customers browse products, track orders, manage their cart, and update their account information.
</Card>

<iframe title="YouTube video player" />


# Slack
Source: https://chatbase.co/docs/user-guides/integrations/slack



Chatbase provides a quick and easy way to add an intelligent AI-powered agent to your Slack workspace. Integrating Chatbase into Slack enables your workspace to instantly leverage a wealth of AI capabilities right within your Slack workspace.

In just a few minutes, you can make a Chatbase agent available across your company's Slack channels to improve communication, boost productivity, and enhance the employee experience. The agent will be able to understand natural language and respond to common queries, resolve issues, look up information, and supercharge your Slack with round-the-clock automated support

Here's how to integrate a Chatbase agent into your Slack workspace:

## Step 1: Access and Configure Your Chatbase Agent

These steps assume that you have already created a Chatbase account and that you have a Chatbase agent already available for use. If you haven't yet, [<u>create a Chatbase account</u>](https://www.chatbase.co/auth/signup), subscribe to a plan then build your first AI agent. For example, you can create a company FAQ agent to handle common employee questions or build a recruiting assistant to screen candidates and schedule interviews. Get your agent ready before moving to the integration.

**Read More:** [<u>A step-by-step guide to creating a Chatbase agent in just a few minutes</u>](/docs/user-guides/quick-start/your-first-agent).

## Step 2: Locate the Slack Integration

1\. Once you have a Chatbase account and a agent set up, head over to your [dashboard](https://www.chatbase.co/dashboard/). On your dashboard, you'll find a list of all the agents you have created. Locate and click on the agent you wish to integrate with Slack.

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

2\. After clicking on a agent, the agent preview page should come up, click on **Connect** at the top of the page and then the **Integrations** tab on the left side of the page. This will take you to a page with a list of integration options.

3\. Click on **Connect** under the Slack card

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

4\. Up next, you'll be asked to authorize Chatbase to access your Slack account and workspace.

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

5\. Scroll down and click on **Allow**.

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

5\. If all goes well, you should get a message saying "**Chatbase has been successfully added to your workspace.**"

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

6\. Click on **Open Slack** to launch your Slack workspace.

7\. You'll be prompted to sign into your Slack workspace or select from a list of Slack workspaces you are currently signed into. Click open beside the target workspace.

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

## Step 3: Deploy Slack Agent

Once you've launched the Slack workspace that hosts your Chatbase agent, you can start setting up the agent as a Slack agent. To do this:

1\. Open any channel on your Slack workspace, and type **@chatbase** followed by any question related to the purpose of your agent. This should trigger a prompt by Slack asking you to invite the agent to the channel or take no action.

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

2\. Click on **Invite Them**. The agent will then be available in the channel to answer any questions you might have.

## Step 4: Start Chatting!

That's it! Your Chatbase agent is now integrated and ready to elevate workspace communication in your Slack workspace.

Anytime you or any member of your workspace needs a question answered, just type @chatbase followed by your question, and your agent will respond.

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

***

## Message Appearance in Slack

Replies sent by your agent in Slack use the agent name and avatar configured in your Widget settings.

**How it works**

If a custom name and avatar are set in your Widget settings, those will be reflected in Slack messages.

If no custom values are provided, default values will be used:

* **Name:** Chatbase
* **Avatar:** Chatbase logo

### Customize your agent's response appearance

To change how your agent appears in Slack, update the profile picture and display name that are inside the Widget's settings in your Chatbase dashboard.

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

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

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

<Info>
  If the agent is mentioned inside a thread, it will reply within that same thread (instead of the main channel). Each Slack thread is treated as a separate conversation, allowing the agent to maintain more accurate context within each discussion.
</Info>

***

Team members can direct questions to your intelligent agent in any channel that has the agent. The agent provides helpful responses powered by conversational AI, giving your workspace access to an advanced virtual assistant 24/7.

Integrating Chatbase into Slack unlocks game-changing possibilities. Your employees gain a productivity-boosting agent that enriches the collaboration experience.

So go ahead, and give your new AI-powered workspace member a try! Intelligent automation is just a chat away.


# Stripe
Source: https://chatbase.co/docs/user-guides/integrations/stripe



Integrating Stripe with Chatbase allows your custom agent to access and display key billing information directly to users, enhancing customer support and transparency. With this integration, your agent can securely retrieve and show users their subscriptions and invoice history, streamlining common billing inquiries. This setup provides a fast, automated way to manage subscription details, while giving users a clear view of their payment status and history—all within the chat experience. This guide will walk you through the steps to connect Stripe to your Chatbase agent, enabling smooth and secure access to subscription and invoice data.

## Step 1: Access and Configure Your Chatbase Chatbot

These steps assume that you have already created a Chatbase account and that you have a Chatbase agent already available for use. If you haven't yet, [<u>create a free Chatbase account</u>](https://www.chatbase.co/auth/signup) and build your first AI agent. For example, you can create a company FAQ agent to handle common employee questions or build a recruiting assistant to screen candidates and schedule interviews. Get your agent ready before moving to the integration.

**Read More:** [<u>A step-by-step guide to creating a Chatbase agent in just a few minutes</u>](/docs/user-guides/quick-start/your-first-agent).

## Step 2: Locate the Stripe Integration

1\. Once you have a Chatbase account and a agent set up, head over to your [dashboard](https://www.chatbase.co/dashboard/). On your dashboard, you'll find a list of all the agents you have created. Locate and click on the agent you wish to integrate with Stripe.

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

2\. After clicking on a agent, the agent preview page should come up, click on **Actions** at the top of the page and then the **Integrations** tab on the left side of the page. This will take you to a page with a list of integration options.

3\. Click on **Connect** under the Stripe card

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

4\. Up next, you'll be asked to authorize Chatbase to access your Stripe account.

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

5\. After clicking on  **Continue** you will be asked to choose the account you want to connect to.

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

5\. If all goes well, you should be redirected back to Chatbase with a message saying "**Stripe integration successful.**"

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

6\. Add Stripe accounts to your customers' contacts. For more information, see [Contacts](/docs/developer-guides/api/contacts/contact).

## Step 3: Start Chatting!

That's it! Your Chatbase agent is now integrated and ready to provide superb customer support.


# Sunshine
Source: https://chatbase.co/docs/user-guides/integrations/sunshine



As part of Zendesk, Sunshine Conversations serves as a live chat solution. This integration centralizes communication, enabling support workspaces to efficiently track and resolve customer inquiries, ultimately improving response times and customer satisfaction.

Chatbase offers an integration with Sunshine Conversations in order to give the agent the ability to connect the user to a live chat agent for fixing problems that require human interaction with the user.

> **Note** This requires your Zendesk Account to have a minimum Suite plan of **Professional** or above

## Step 1: Sign Into Your Zendesk Account

1. Sign in to your Zendesk Account as an Admin and navigate to the **Admin Center**

2. Navigate to **Apps and integrations** > **APIs** > **Conversations API**

3. Click on **Create API Key**, enter **Chatbase** as the name and press **Next**

4. Copy the **App ID**, **Key ID** and **Secret key** displayed

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

## Step 2: Set up the Sunshine Integration

1\. Go to the [dashboard](https://www.chatbase.co/dashboard/) of your Chatbase account.

2\. You should see a list of agents, click the agent you wish to enable live chat for. You should be taken to the agent's preview page.

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

3\. Navigate to **Actions** > **Integrations**. Click **Connect** on the Sunshine Integration card.

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

4\. Enter the copied **App ID**, **Key ID** and **Secret key**, and press **Submit**.

## Step 3: Enable Multi-Conversations Option in Zendesk

We need to enable the multi-conversations option in Zendesk to allow for the same user to open multiple tickets, one per conversation, at the same time. Since the same user can have multiple conversations opened at the same time, then this option must be enabled for a smooth experience.

1\. Sign in to your Zendesk Account as an Admin and navigate to the **Admin Center**

2\. Click **Channels** in the sidebar, then select **Messaging and social** > **Messaging**.

3\. At the top of the page, click **Manage settings**.

4\. Under Web Widget and Mobile SDKs, expand **Multi-conversations**.

5\. Click **Set up multi-conversations**.

6\. Click **Turn on multi-conversations for your account**, then select the channels on which you want to offer multi-conversations, then click **Save**.

For more information regarding multi-conversations for messaging, visit [Understanding multi-conversations for messaging](https://support.zendesk.com/hc/en-us/articles/8195486407706-Understanding-multi-conversations-for-messaging).

## Step 4: Enable End Messaging Sessions in Zendesk

To allow agents to end conversations when issues are resolved, you'll need to enable the messaging session end feature in Zendesk.

1\. Sign in to your Zendesk Account as an Admin and navigate to the **Admin Center**

2\. Click **Channels** in the sidebar, then select **Messaging and social** > **Messaging**.

3\. At the top of the page, click **Manage settings**.

4\. Under Advanced, expand **Ending sessions**.

5\. Select **Agents can end messaging sessions at any time**.

6\. Click **Save settings**.

For more information regarding ending messaging sessions, visit [About ending messaging sessions](https://support.zendesk.com/hc/en-us/articles/8009788438042-About-ending-messaging-sessions).

## Step 5: Add the User Identification

To use the Sunshine integration, you must identify your user. You can find the guide [here](https://www.chatbase.co/docs/developer-guides/identity-verification).

## Step 6: Enable the Live Chat Action

1\. Go to the [dashboard](https://www.chatbase.co/dashboard/) of your Chatbase account.

2\. Choose the agent you have integrated with Sunshine Conversations.

3\. Navigate to **Actions**.

4\. Click on **Create Action** under the Sunshine Live Chat card.

5\. Customize the **When to use**, then save and enable the action.


# Twilio (Phone)
Source: https://chatbase.co/docs/user-guides/integrations/twilio



Integrating Twilio with Chatbase allows your AI agent to handle inbound phone calls. Your AI agent will answer calls using its configured voice, personality, and data sources.

In just a few minutes, you can connect your Twilio account, import your phone numbers, and assign them to your agent.

<Info>
  Make sure the phone channel is supported on your plan. Check the [pricing page](https://www.chatbase.co/pricing) for details. You will also need a [Twilio account](https://www.twilio.com/try-twilio) with at least one phone number to get started.
</Info>

## Before you start

* You need a Twilio account. If you don't have one, [sign up for Twilio](https://www.twilio.com/try-twilio).
* You need at least one phone number purchased in your Twilio account.
* Your Twilio **Account SID** and **Auth Token** are available on your [Twilio Console dashboard](https://console.twilio.com/).
* Make sure your Chatbase agent is set up with the voice settings you want callers to hear. You can configure voice, language, and greeting under your agent's **Settings > Voice** tab.

## Step 1: Connect your Twilio account

1\. Navigate to your [Chatbase dashboard](https://www.chatbase.co/dashboard/) and select the agent you want to enable phone calls for.

2\. Go to **Settings > Integrations** in the left sidebar.

3\. Find the **Twilio** card and click **Connect**.

4\. Enter your **Account SID** and **Auth Token** from the [Twilio Console](https://console.twilio.com/).

* **Account SID** starts with `AC` followed by 32 characters (e.g., `ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`).
* **Auth Token** is a 32-character string.

5\. Click **Connect Twilio**.

Chatbase will validate your credentials against the Twilio API. Once connected, your Account SID will be displayed in a read-only field.

<Info>
  Your Twilio credentials are encrypted before being stored. Chatbase never displays your Auth Token after the initial connection. Each agent has its own Twilio connection — you can use the same or different Twilio accounts for different agents.
</Info>

## Step 2: Import phone numbers

Once your Twilio account is connected to this agent, you can import your phone numbers.

1\. On the same Twilio integration page, click **Import from Twilio**.

2\. A dialog will show all available phone numbers from your Twilio account.

3\. Select the numbers you want to import. For each number, you can optionally set a **friendly name** to help you identify it later (e.g., "Sales line" or "Support US").

4\. Click **Import selected**.

Chatbase will automatically configure a SIP trunk on your Twilio account and register each number for call routing. Imported numbers will appear in the phone numbers table with their status shown as **Inactive** until you enable them from the Deploy page.

<Info>
  Each phone number can only be imported to one agent at a time. Numbers that are already imported will appear grayed out in the import dialog.
</Info>

## Step 3: Enable a phone number

After importing, you need to enable the number to start receiving calls.

1\. Navigate to your agent's **Deploy** page.

2\. Find the **Phone** channel card and click **Setup** (or **Manage** if you have already enabled numbers).

3\. Click **Assign number**.

4\. Select one or more numbers from the list of imported numbers.

5\. Click **Assign selected**.

The enabled numbers will appear as cards on the page showing the phone number, a green **Active** badge, and the friendly name if one was set. Your agent is now ready to receive calls on those numbers.

## How calls work

Once a phone number is enabled for an agent:

* **Inbound calls** to that number are automatically routed to the assigned agent.
* The agent uses its configured **voice settings** (voice provider, model, and language) to speak with the caller.
* The agent greets the caller with the **first message** defined in its voice settings.
* The conversation follows the agent's instructions, knowledge base, and actions, just like a chat conversation.
* Each call creates a conversation entry visible in your agent's **Activity > Chat logs** with the source marked as **Phone**.

## Managing phone numbers

### Disable a number

1\. Go to your agent's **Deploy** page and click **Manage** on the Phone channel card.

2\. Click the menu icon on the number card and select **Unassign**.

The number will stop receiving calls but remains imported to this agent. You can re-enable it at any time from the same page.

### Remove a number from the agent

1\. Go to your agent's **Settings > Integrations** and click **Manage** on the Twilio card.

2\. In the phone numbers table, click the menu icon next to the number and select **Remove**.

The number will be removed from this agent but will remain in your Twilio account. You can import it again at any time.

### Disconnect Twilio

1\. Go to your agent's **Settings > Integrations** and click **Manage** on the Twilio card.

2\. Click **Disconnect** in the danger zone at the bottom.

<Info>
  Disconnecting Twilio from an agent will remove all imported phone numbers and delete the SIP trunk from your Twilio account. This action cannot be undone. Your phone numbers will remain in your Twilio account, but you will need to reconnect and re-import them if you want to use them again with this agent.
</Info>


# Vercel
Source: https://chatbase.co/docs/user-guides/integrations/vercel

Install Chatbase AI Agent directly from the Vercel Marketplace with one-click integration

The Chatbase Vercel integration allows you to add an AI-powered chatbot to your Vercel-hosted applications directly from the Vercel Marketplace. No code required—just a few clicks to get started.

## Overview

The Chatbase native integration for Vercel provides a seamless way to add conversational AI to your web applications. With this integration, you can:

* Install Chatbase directly from the Vercel Marketplace
* Create and configure your AI chatbot without leaving Vercel
* Automatically inject environment variables into your project
* Deploy AI-powered chat experiences instantly
* Scale automatically with Vercel's global edge network

<Info>
  The Chatbase integration works seamlessly with all frameworks supported by Vercel, including Next.js, React, Vue.js, SvelteKit, and static HTML sites.
</Info>

## Prerequisites

Before you begin, ensure you have:

* A Vercel account ([Sign up for free](https://vercel.com/signup))
* An existing Vercel project or [use our template here](https://github.com/Chatbase-co/nextjs-marketplace-template)

## Installation Guide

Follow these steps to install and configure Chatbase from the Vercel Marketplace:

### Step 1: Install Chatbase from Vercel Marketplace

<Steps>
  <Step title="Navigate to Vercel Marketplace">
    1. Log into your [Vercel Dashboard](https://vercel.com/dashboard)
    2. Click on the **Marketplace** tab in the top navigation
    3. In the search bar, type **"Chatbase"**
    4. Click on the Chatbase integration from the search results

    <Tip>
      You can also access the Chatbase integration directly at [vercel.com/integrations/chatbase](https://vercel.com/integrations/chatbase)
    </Tip>
  </Step>

  <Step title="Click Install">
    On the Chatbase integration page, click the **Install** button to begin the installation process.

    <Check>
      You'll be redirected to the Chatbase configuration wizard.
    </Check>
  </Step>
</Steps>

### Step 2: Configure Your Chatbot

<Steps>
  <Step title="Choose Chatbot Preset">
    Select the preset that best matches your use case:

    * **AI Agent** - A general-purpose intelligent assistant
    * **Customer Support Agent** - Optimized for answering customer questions and providing support
    * **Sales Agent** - Helps guide customers through product selection and purchase decisions
    * **Language Tutor** - Designed for language learning and practice
    * And more preset options tailored to specific use cases

    <Info>
      You can customize any preset later. This just provides a starting point for your chatbot's behavior.
    </Info>
  </Step>

  <Step title="Select AI Model">
    * If you're on a paid plan, you can select an AI model.
    * If you're on a free plan, it will use the default model which you can change from your Chatbase dashboard.

    <Tip>
      You can change both the personality, AI model, and styles anytime from your Chatbase dashboard.
    </Tip>
  </Step>
</Steps>

### Step 3: Choose Your Subscription Plan

<Steps>
  <Step title="Select a Plan">
    Choose the plan that fits your needs:

    * **Free** - Perfect for testing and small projects (limited messages/month)
    * **Hobby** - For personal projects and small websites
    * **Standard** - For growing businesses
    * **Professional** - For high-traffic applications

    Review the features and message limits for each plan before selecting.
  </Step>

  <Step title="Complete Billing">
    After selecting your plan:

    1. An invoice will be sent to your registered email address
    2. Follow the payment link in the invoice to complete your subscription
    3. Your plan will become active once the invoice is paid

    <Warning>
      Your selected plan will only take effect after the invoice is paid. Until then, you'll have access to the free tier features.
    </Warning>

    <Info>
      Billing is handled securely through Vercel's payment system. You can manage your subscription from the Vercel dashboard.
    </Info>
  </Step>
</Steps>

### Step 4: Name Your Chatbot

<Steps>
  <Step title="Enter Chatbot Name">
    Provide a descriptive name for your chatbot. This name will:

    * Appear in your Chatbase dashboard
    * Help you identify the chatbot if you create multiple agents
    * Be visible in your Vercel integration settings

    **Examples:**

    * "Website Support Bot"
    * "Product Assistant"
    * "Sales Lead Qualifier"
    * "Documentation Helper"

    <Tip>
      Choose a name that clearly describes the chatbot's purpose, especially if you plan to create multiple chatbots for different projects.
    </Tip>
  </Step>
</Steps>

### Step 5: Customize in Chatbase Dashboard

<Steps>
  <Step title="Access Your Chatbase Dashboard">
    After creating your chatbot, you'll be provided with a link to access your Chatbase dashboard. Alternatively, visit [chatbase.co/dashboard](https://www.chatbase.co/dashboard) and log in with your account.
  </Step>

  <Step title="Customize Appearance (Optional)">
    Navigate to **Settings** → **Chat Interface** to customize:

    * **Theme colors** - Match your brand colors
    * **Widget position** - Bottom left, bottom right, or custom
    * **Chat bubble style** - Icon style and size
    * **Avatar image** - Upload your logo or brand image
    * **Initial message** - Set the greeting message
    * **Placeholder text** - Customize the input field text

    <Frame>
      <img alt="Chatbase dashboard customization options" />
    </Frame>
  </Step>

  <Step title="Add Training Data Sources (Optional)">
    Train your chatbot with your content:

    1. Navigate to the **Data sources** tab
    2. Add training data from various sources:
       * **Website URLs** - Scrape content from your website
       * **Documents** - Upload PDF, DOCX, or TXT files
       * **Text snippets** - Paste content directly
       * **Q\&A pairs** - Add specific question-answer pairs
       * **Sitemaps** - Import entire website structures

    <Info>
      The more relevant training data you provide, the better your chatbot will respond to user queries. Learn more in [Adding Data Sources](/docs/user-guides/chatbot/data-sources).
    </Info>
  </Step>

  <Step title="Configure Actions (Optional)">
    Add interactive capabilities to your chatbot:

    * **Lead Collection** - Capture visitor information
    * **Calendar Booking** - Integrate with Calendly or Cal.com
    * **Stripe Payments** - Accept payments directly in chat
    * **Custom Actions** - Create custom workflows and API calls
    * **Web Search** - Allow the bot to search the internet for current information

    [Learn more about Actions →](/docs/user-guides/chatbot/actions/actions-overview)
  </Step>

  <Step title="Set Up Integrations (Optional)">
    Connect your chatbot with other tools:

    * **Slack** - Send notifications to Slack channels
    * **Zapier** - Connect with 5,000+ apps
    * **Webhooks** - Send data to your own endpoints
    * **CRM systems** - Sync contacts with your CRM

    [Explore all integrations →](/docs/user-guides/integrations/zapier)
  </Step>
</Steps>

### Step 6: Connect to Your Vercel Project

<Steps>
  <Step title="Return to Vercel">
    Go back to your Vercel dashboard where you initiated the Chatbase installation.
  </Step>

  <Step title="Click Connect Project">
    1. In the Chatbase integration settings, click **Connect Project**
    2. A dialog will appear showing all your Vercel projects
    3. Select the project(s) where you want to add the Chatbase chatbot

    <Info>
      You can connect the same chatbot to multiple projects if needed.
    </Info>
  </Step>

  <Step title="Confirm Connection">
    Click **Connect** to finalize the connection. Vercel will automatically inject the environment variables into your selected project(s).

    <Check>
      Your environment variables are now configured and ready to use!
    </Check>
  </Step>
</Steps>

### Step 7: Redeploy Your Project

<Steps>
  <Step title="Trigger a New Deployment">
    For the environment variables to take effect, you need to redeploy your project:

    1. Go to your project in the Vercel dashboard
    2. Click on the **Deployments** tab
    3. Click the three-dot menu (⋯) on your latest deployment
    4. Select **Redeploy**

    <Info>
      Environment variables are injected at **build time**, not runtime. This is why a redeployment is necessary.
    </Info>
  </Step>
</Steps>

### Step 8: Verify Installation

<Steps>
  <Step title="Visit Your Deployed Project">
    Once the deployment is complete:

    1. Click the **Visit** button in your Vercel dashboard
    2. Or navigate directly to your project's URL

    Your Chatbase chat widget should now appear on your website, typically in the bottom-right corner.
  </Step>

  <Step title="Test the Chat Widget">
    Verify that your chatbot is working correctly:

    1. **Look for the chat bubble** - Should be visible in the corner of your page
    2. **Click to open** - The chat interface should expand
    3. **Send a test message** - Try asking a question related to your training data
    4. **Verify response** - The AI should respond based on the sources you configured

    <Check>
      If the chatbot responds appropriately to your test questions, your integration is successful!
    </Check>
  </Step>
</Steps>

## Managing Your Integration

### Updating Your Chatbot

Changes made in your Chatbase dashboard apply instantly without requiring redeployment:

* **Appearance customization** - Colors, position, styling
* **Training data updates** - Add or remove sources
* **Response behavior** - Adjust personality and model
* **Actions and integrations** - Enable or disable features

<Tip>
  Only environment variable changes require redeployment. All chatbot configuration changes are live immediately.
</Tip>

## Advanced Features

### Multiple Projects

You can connect the same Chatbase chatbot to multiple Vercel projects:

1. Go to your Vercel dashboard
2. Navigate to **Integrations** → **Chatbase**
3. Click **Manage** on your Chatbase integration
4. Click **Add Project** to connect additional projects

<Tip>
  This is useful if you have multiple frontends (web app, marketing site, documentation) that should use the same chatbot.
</Tip>

### Different Chatbots for Different Environments

To use different chatbots for production, preview, and development environments:

1. Create separate chatbots in Chatbase for each environment
2. In Vercel, manually override environment variables:
   * Go to **Settings** → **Environment Variables**
   * Set different `NEXT_PUBLIC_CHATBOT_ID` values for Production, Preview, and Development

This allows you to:

* Test changes without affecting production conversations
* Maintain separate training data per environment
* Monitor environment-specific analytics separately

### Managing Your Subscription Plan

To change your Chatbase subscription:

1. Go to your Vercel dashboard
2. Navigate to **Integrations** → **Chatbase** → **Settings**
3. Click **Change Plan**
4. Select your desired plan option

#### Upgrading Your Plan

Choose a higher-tier plan and complete the invoice payment.

<Check>
  Plan upgrades take effect **immediately** once the invoice is paid. You'll have instant access to all the features and increased limits of your new plan.
</Check>

**What happens when you upgrade:**

* Your new plan features activate right away
* Increased message limits are available immediately
* Any prorated charges are calculated automatically
* Your billing cycle continues with the new plan pricing

#### Downgrading Your Plan

Choose a lower-tier plan to switch to.

<Info>
  Plan downgrades take effect at the **end of your current billing period**. This ensures you don't lose access to features you've already paid for.
</Info>

**What happens when you downgrade:**

* You continue to enjoy your current plan features until period end
* The new plan activates automatically when your billing cycle renews
* You'll receive a confirmation email with the effective date

<Tip>
  Downgrading at period end means you get full value for what you've paid. Use the remaining time to adjust to the new plan's limits or export any data if needed.
</Tip>

#### Canceling Your Subscription

Select the **Free** plan and confirm your cancellation.

<Warning>
  Subscription cancellations also take effect at the **end of your current billing period**. Your chatbot will continue working until then, ensuring you receive full value for your payment.
</Warning>

**What happens when you cancel:**

* Your chatbot remains active until the end of your billing period
* You retain access to all current plan features until period end
* No future charges will be processed
* You can resubscribe at any time if you change your mind
* After cancellation takes effect, your plan reverts to the Free tier

<Info>
  You can undo a cancellation before the period end by selecting a paid plan again from the same settings page.
</Info>

## Uninstalling the Integration

If you need to remove the Chatbase integration:

1. Go to your Vercel dashboard
2. Navigate to **Integrations** → **Chatbase**
3. Click **Manage** → **Remove Integration**
4. Confirm removal

<Warning>
  Removing the integration will immediately stop the chatbot from appearing on your Vercel deployments. Make sure to redeploy after removing environment variables.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Chat widget not appearing after installation">
    **Common solutions:**

    1. **Redeploy your project**
       * Environment variables are injected at build time
       * Go to **Deployments** → Select latest → **Redeploy**

    2. **Verify environment variables**
       * Check **Settings** → **Environment Variables**
       * Ensure `NEXT_PUBLIC_CHATBOT_ID` is present
       * Verify they're enabled for all environments

    3. **Check browser console**
       * Open DevTools (F12)
       * Look for any JavaScript errors related to Chatbase
       * Verify the embed script is loading successfully

    4. **Clear browser cache**
       * Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
       * Try in an incognito/private window
  </Accordion>

  <Accordion title="Integration installation failed">
    **Solution steps:**

    1. **Remove and reinstall**
       * Go to Vercel → **Integrations** → **Chatbase**
       * Click **Manage** → **Remove Integration**
       * Reinstall from the Vercel Marketplace

    2. **Check permissions**
       * Ensure you have admin access to the Vercel team/project
       * Verify your Vercel account is properly authenticated

    3. **Contact support**
       * If issues persist, contact [Chatbase Support](https://chatbase.co/help)
       * Provide your Vercel project ID and integration details
  </Accordion>

  <Accordion title="Environment variables not taking effect">
    **Solution:**

    Environment variables require redeployment to take effect:

    1. Make your environment variable changes
    2. Trigger a new deployment:
       * Option A: Push a commit to your Git repository
       * Option B: Manual redeploy from Vercel dashboard
    3. Clear browser cache and test
  </Accordion>

  <Accordion title="Plan billing issues">
    **Common scenarios:**

    1. **Invoice not received**
       * Check your email spam/junk folder
       * Verify email address in Vercel account settings
       * Contact Vercel support for invoice resend

    2. **Plan not activating after payment**
       * Allow up to 10 minutes for payment processing
       * Check payment status in Vercel billing dashboard
       * Contact Vercel support if payment is confirmed but plan isn't active

    3. **Subscription changes**
       * Upgrades activate immediately after payment
       * Downgrades and cancellations take effect at the end of current billing period
       * You retain current plan features until period end for downgrades/cancellations
  </Accordion>
</AccordionGroup>

## Optimizing Response Quality

For the best chatbot performance:

1. **Add comprehensive training data** - More sources = better responses
2. **Test regularly** - Use the Chatbase playground to verify quality
3. **Monitor conversations** - Review chat logs in Chatbase dashboard
4. **Iterate on sources** - Remove irrelevant content, add missing information
5. **Use custom actions** - Add interactive features for complex workflows

[Learn more about Response Quality →](/docs/user-guides/quick-start/response-quality)

## Next Steps

Now that your Chatbase chatbot is live on Vercel, explore these features to enhance your implementation:

<CardGroup>
  <Card title="Add Training Data Sources" icon="book" href="/user-guides/chatbot/data-sources">
    Upload documents, connect websites, and add Q\&A pairs
  </Card>

  <Card title="Customize Appearance" icon="palette" href="/user-guides/chatbot/settings">
    Match your brand colors and style
  </Card>

  <Card title="Enable Actions" icon="bolt" href="/user-guides/chatbot/actions/actions-overview">
    Add lead collection, bookings, and custom workflows
  </Card>

  <Card title="Monitor Analytics" icon="chart-line" href="/user-guides/chatbot/analytics">
    Track conversations and measure performance
  </Card>

  <Card title="Connect More Apps" icon="plug" href="/user-guides/integrations/zapier">
    Integrate with Slack, CRMs, and 5,000+ apps
  </Card>

  <Card title="Developer Features" icon="code" href="/developer-guides/overview">
    Explore API, webhooks, and advanced integrations
  </Card>
</CardGroup>

## Additional Resources

<AccordionGroup>
  <Accordion title="Vercel Documentation">
    * [Vercel Integrations Overview](https://vercel.com/docs/integrations)
    * [Vercel Environment Variables](https://vercel.com/docs/concepts/projects/environment-variables)
    * [Vercel Deployments](https://vercel.com/docs/concepts/deployments/overview)
    * [Vercel Analytics](https://vercel.com/docs/analytics)
  </Accordion>

  <Accordion title="Chatbase Documentation">
    * [Getting Started Guide](/docs/user-guides/quick-start/introduction)
    * [Your First Agent](/docs/user-guides/quick-start/your-first-agent)
    * [Best Practices](/docs/user-guides/quick-start/best-practices)
    * [Response Quality Tips](/docs/user-guides/quick-start/response-quality)
    * [JavaScript Embed Options](/docs/developer-guides/javascript-embed)
  </Accordion>

  <Accordion title="Support & Community">
    Need help? We're here for you:

    * **Chatbase Help Center:** [chatbase.co/help](https://chatbase.co/help)
    * **Vercel Support:** [vercel.com/support](https://vercel.com/support)
    * **Email Support:** Contact us through your dashboard
    * **Documentation:** Browse our comprehensive guides

    <Tip>
      When contacting support, include your Vercel project ID and Chatbase chatbot ID for faster assistance.
    </Tip>
  </Accordion>
</AccordionGroup>


# ViaSocket
Source: https://chatbase.co/docs/user-guides/integrations/viasocket



Integrating Chatbase with viaSocket opens up endless opportunities to connect your Agent with your favorite apps and tools—no coding required. Simply drag and drop to automate tasks across your apps.

## Key Automation Ideas

* **Lead Generation:** Automatically capture leads through form submissions and add them to your CRM (e.g., HubSpot, Salesforce) for follow-up.
* **Customer Support:** Set up an automation to trigger support tickets in systems like Zendesk or Freshdesk when your Agent receives a customer inquiry.
* **Email Campaigns:** Automatically add contacts from Agent to your email marketing platforms like Mailchimp or ActiveCampaign, then send personalized follow-up emails.
* **Multi-Platform Support:** Deploy AI agents across various platforms, including websites, mobile apps, and messaging services, to reach users wherever they are.
* **Social Media Management:** Trigger social media updates or create posts based on user interactions with your Agent.
* **E-commerce Notifications:** Automate stock updates, order confirmations, or promotional notifications to customers based on their interactions with your Agent.

## Integrate your Agent with viaSocket

Learn how to receive leads from your Agent, process them, and automatically add them to a Google Docs document using viaSocket.

### Step 1: Set Up a Trigger in viaSocket

1. Sign in to your viaSocket account.
2. Click on **Create New Flow** on the top left corner of the viaSocket app homepage.

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

3. In the Flow editor, click on **Select Trigger**.

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

4. Select **Webhook** as the trigger then copy the generated Webhook URL.

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

### Step 2: Configure the Trigger in Chatbase

1. Go to the [dashboard](https://www.chatbase.co/dashboard/) of your Chatbase account.
2. You should see a list of Agents, click the Agent you wish to integrate with viaSocket.

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

3. Click **Settings** and select **Webhooks**.

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

4. Select the events you want to trigger, then paste the copied Webhook URL into the **Endpoint** field, then **Create Webhook**.

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

### Step 3: Set Up an Action to Automate Tasks

1. Go back to the viaSocket Flow Builder and click on **Select Action**.

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

2. Choose the **Google Docs** action: *Append Text to Document*.

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

3. Establish a connection and configure your action with the required details.

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

### Step 4: Test and Publish the Flow

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

With this setup, every time a lead is captured by your Agent on your website, it will be automatically added to your designated Google Docs file.


# Webflow
Source: https://chatbase.co/docs/user-guides/integrations/webflow



## Step 1: Sign Into Your Chatbase Account and Set Up Your Chatbot

1. Sign up for a free Chatbase account if you don't already have one.

2. Log into your Chatbase account and navigate to the bot creation page.

3. Provide training data for your new bot by uploading sources like text snippets, documents, website content, or Q\&A pairs.

4. Train and test your bot in Chatbase until it responds accurately to queries.

<Info>
  New to Chatbase? Check out [Your First Agent](/docs/user-guides/quick-start/your-first-agent) to get started with the embed script first.
</Info>

## Step 2: Copy Your AI Agent Embed Code

Once you've set up and tested your Chatbase bot, you'll need the embed code to display the bot widget on your website. To do this:

1\. Go to the [dashboard](https://www.chatbase.co/dashboard/) of your Chatbase account.

2\. You should see a list of agents, click the agent you wish to integrate into your Webflow website. You should be taken to the agent's preview page.

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

3\. On the agent preview page, click on the **Deploy** tab.

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

4\. A new page should come up. Click on **Manage** for the Chat Widget.

<Frame>
  <img alt="Chat Widget [Manage]" />
</Frame>

5\. Click on **Embed** and select the **Iframe** embed type. Scroll down and Click **Copy** to copy the provided HTML code.

<Frame>
  <img alt="Copy Iframe" />
</Frame>

## Step 3: Set Up a Container to Display Your Chatbot Widget 

Before adding the embed code to your Webflow site, you will need to create a container to display the widget. This will ensure that the widget is displayed in the correct place on your website and doesn't extend the entire width of the page.

1\. To create a container, on Webflow, log into your Webflow account and go to your dashboard.

2\. On your Webflow dashboard, you'll find a list of all your website projects, hover on the website you want to add the agent to and click on **Open Designer**.

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

3\. On the designer page, click on the file icon (**Pages**) on the top left corner of the webflow site designer and select the page you want to embed the agent.

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

4\. Once you've selected the page, click the Plus button (**Add elements**) on the top left corner of the designer screen, and a list of available elements should come up.

5\. Drag the **Section** element to the portion of the page you want to embed your agent.

6\. Drag a **Container** element unto the **Section.**

7\. Drag a **Div** element unto the Container element and set the size of the Div element to ensure that the bot will be contained within the Div and does not span the entire width of the page.

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

8\. Now, scroll down down the list of elements and drag the **Embed** element unto the Div you added on the Webflow canvas.

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

9\. Select and double-click the Embed element to reveal the HTML Embed code editor.

10\. Paste the Chatbase agent embed code from Step 2 above and click **Save & Close**.

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

If all goes well, you should see a preview of the agent on the live preview of your Webflow website right inside the designer.

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

After completing these steps, your agent should be ready to serve your website visitors!

If you are having difficulties with managing the dimension of your Embed and agent element, it is a common problem. Webflow components take a bit of getting used to. You can follow this [official Webflow documentation on the Embed element](https://university.webflow.com/lesson/custom-code-embed?topics=elements) to learn more about embedding a third-party tool like Chatbase agent on a Webflow website.

> **Note:** You can customize the appearance and colors of your bot on your Chatbase dashboard. To do this, go to your **dashboard**, choose a bot, click the **Settings** tab on the top of the page, and then click **Chat Interface** on the left sidebar to reveal the agent customization options.


# Weebly
Source: https://chatbase.co/docs/user-guides/integrations/weebly



## Step 1: Sign Into Your Chatbase Account and Set up your Bot

To embed your Chatbase bot into your Weebly website, first sign in to your Chatbase account. If you don't have an account yet, you can create one for free. Once signed in, you can set up your bot in Chatbase by uploading data sources like files, text snippets, websites, or Q\&A pairs that the bot can learn from. Here is a [<u>step-by-step guide for setting up your Chatbase agent</u>](/docs/user-guides/quick-start/your-first-agent).

## Step 2: Generate and Copy Chatbot Embed Code

1\. After setting up your agent, head to your [dashboard](https://www.chatbase.co/dashboard/), and click on the bot you want to embed on your Weebly website to reveal the bot's Playground page.

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

2\. On the agent preview page, click on the **Deploy** tab.

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

3\. A new page should come up. Click on **Manage** for the Chat Widget.

<Frame>
  <img alt="Chat Widget [Manage]" />
</Frame>

4\. Click on **Embed** and select the **Iframe** embed type. Scroll down and Click **Copy** to copy the provided HTML code.

<Frame>
  <img alt="Copy Iframe" />
</Frame>

## Step 3: Add Embed Code to Your Weebly Website

To add a Chatbase agent to your Weebly website:

1\. Sign in to your Weebly account and head to the **Edit site** page.

2\. Select the page to edit.

3\. From the Basic toolbar on the left side of the editing page, locate the widget that says **Embed Code**.

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

4\. Drag the **Embed Code** element to wherever you want your agent to appear on the page.

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

5\. You should then see a text element that says **Click to set custom HTML** where the Embed code widget was placed. Click on the text, and then click on **Edit Custom HTML.**

6\. Paste your Chatbase embed code into the custom HTML box.

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

7\. Click outside the element and your agent should appear on the page.

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

Congratulations, your agent is now live on your Weebly website!

> **Note:** You can customize the appearance and colors of your bot on your Chatbase dashboard. To do this, go to your **dashboard**, choose a bot, click the **Settings** tab on the top of the page, and then click **Chat Interface** on the left sidebar to reveal the agent customization options.


# WhatsApp
Source: https://chatbase.co/docs/user-guides/integrations/whatsapp



Integrating WhatsApp with Chatbase allows your custom agent to communicate directly with customers via WhatsApp, providing a seamless and efficient way to handle inquiries and automate responses. This guide will walk you through the necessary steps to connect your agent to a WhatsApp phone number, ensuring smooth and effective customer interactions.

<Info>
  Attachments are supported, allowing your agent to process them and respond based on their content. For more information, please refer to [this section](/docs/user-guides/chatbot/deploy#attachments).
</Info>

## Before we start

* The WhatsApp phone number integrated with the agent can only be used by the agent, and can't be used on WhatsApp or WhatsApp business. If you already use the phone number with WhatsApp, you must delete your account in the app first.

* To delete WhatsApp

  * Navigate to WhatsApp or WhatsApp Business app.

  * Navigate to **Settings > Account.**

  * Select **Delete my account.** This may take a few minutes, but after that, the number will be available to use.

* If you previously used WhatsApp through Meta Developer for business you must disable **two-step verification**

  * Navigate to you [**Whatsapp Business Account**](https://business.facebook.com/wa/manage/home/) and login.

  * Choose the phone number you would like to integrate.

  * Navigate to **Settings > Two-step verification** and choose turn off two-step verification.

* Make sure you have an approved display name before integrating with your agent, you can read more about it [**here**](https://www.facebook.com/business/help/338047025165344)

## Setting up the WhatsApp Integration

1\. Navigate to the Agent you would like to integrate with WhatsApp.

2\. Select 'Deploy' to setup WhatsApp.

3\. Log in with your personal Facebook Account.

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

4\. Click **Get started**

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

5\. Choose or create a business profile.

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

6\. Create a WhatsApp business profile or select an existing one.

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

7\. Fill in the information for the Business profile.

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

8\. Add a phone number, , it is recommended to have only one associate number in this profile.

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

9\. Click **Continue**.

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

10\. Wait a few seconds for information verification.

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

11\. Click on **Finish**.

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

12\. (Optional) Navigate to **Profile** and update your WhatsApp settings then click the **Save** button.

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

## Automatic Lead Collection

Chatbase allows you to automatically collect basic user information from WhatsApp conversations, including the user’s phone number and name (when available).

**To enable automatic lead collection:**

* Go to Deploy → WhatsApp → Leads
* Toggle Enable Automatic Collection of Leads
* Select the WhatsApp number(s) you want to apply this to

Once enabled, Chatbase will automatically capture lead details whenever a user messages your WhatsApp number.

<Note> For more advanced lead capture and customization, you can use the **Collect Leads** action within your agent. </Note>

Now that your integration is active you can send 1000 free messages monthly. Make sure to add a payment method on your [Meta billing settings](https://business.facebook.com/billing_hub) to be able to send more than 1000 messages per month.

<Info>
  You can now enable or disable WhatsApp integration without disconnecting it. Disabling pauses messages while keeping your setup intact, and you can re-enable anytime to resume. New chats will still appear in your Chatbase dashboard chat logs
</Info>

Congratulations! You finished integrating your Chatbase agent to WhatsApp, your agent is now ready to reply to all the messages received through your WhatsApp!


# WhatsApp Templates
Source: https://chatbase.co/docs/user-guides/integrations/whatsapp-templates

Learn how to create WhatsApp message templates in WhatsApp Manager and send them to customers from the Chatbase Helpdesk.

WhatsApp message templates are pre-approved messages required by Meta to contact customers outside the 24-hour conversation window. When a customer hasn't messaged you in the last 24 hours, you must use an approved template to re-initiate the conversation.

Chatbase supports **Utility**, **Authentication**, and **Marketing** templates. Utility and Authentication templates can be sent from the Helpdesk, while Marketing templates are available for [Outbound Campaigns](/docs/user-guides/chatbot/outbound-campaigns).

<Info>
  Before you begin, make sure you have already connected your WhatsApp integration. If you haven't, follow the [WhatsApp integration setup guide](/docs/user-guides/integrations/whatsapp) first.
</Info>

## Prerequisites

* A connected WhatsApp integration in Chatbase ([setup guide](/docs/user-guides/integrations/whatsapp))
* Access to [WhatsApp Manager](https://business.facebook.com/wa/manage/message-templates/)
* An approved WhatsApp Business Account

## Part 1: Creating a Template in WhatsApp Manager

1\. Navigate to [WhatsApp Manager](https://business.facebook.com/wa/manage/message-templates/) and open **Message Templates**.

<Frame>
  <img alt="WhatsApp Manager Message Templates page" />
</Frame>

2\. Click **Create Template**.

<Frame>
  <img alt="Click Create Template" />
</Frame>

3\. Choose a template category:

* **Utility** — for order updates, account notifications, and transaction confirmations
* **Authentication** — for verification codes and login confirmations

<Frame>
  <img alt="Choose template category" />
</Frame>

<Info>
  **Utility** and **Authentication** templates can be used in both the Helpdesk and Outbound Campaigns. **Marketing** templates are available for [Outbound Campaigns](/docs/user-guides/chatbot/outbound-campaigns) only.
</Info>

4\. Enter a name for your template and select the language.

<Frame>
  <img alt="Enter template name and select language" />
</Frame>

5\. Write your template body text. Keep it plain text — variables are not supported.

<Frame>
  <img alt="Write template body text" />
</Frame>

6\. Click **Submit for Review**.

<Frame>
  <img alt="Submit template for review" />
</Frame>

<Info>
  Meta reviews templates before they can be used. The review usually takes a few minutes, but can take longer. Your template must be approved before it appears in Chatbase.
</Info>

<Frame>
  <img alt="Submit template for review" />
</Frame>

<Tip>
  To improve your chances of approval, keep your message clear and concise, avoid promotional language, and clearly specify the transactional or authentication purpose of the template.
</Tip>

<Warning>
  Meta charges fees for each template message sent. Fees vary by country and template category. See [Meta's WhatsApp pricing](https://developers.facebook.com/docs/whatsapp/pricing) for current rates.
</Warning>

## Part 2: Sending a Template from Helpdesk

Once your template is approved in Meta, you can use it to message customers from the Chatbase Helpdesk.

1\. Open the **Helpdesk** inbox.

<Frame>
  <img alt="Helpdesk inbox" />
</Frame>

2\. Navigate to or open a conversation with the contact you want to message.

<Frame>
  <img alt="Open a conversation with a contact" />
</Frame>

3\. When the 24-hour reply window has closed, you'll see a notice that sending messages is no longer allowed. Click **Choose template** to send a pre-approved message template.

<Frame>
  <img alt="Select option to send a WhatsApp template" />
</Frame>

4\. Browse and select from your list of approved templates.

<Frame>
  <img alt="Browse and select an approved template" />
</Frame>

5\. Preview the template content.

<Frame>
  <img alt="Preview the template content" />
</Frame>

6\. Click **Send**.

<Frame>
  <img alt="Send the template message" />
</Frame>

<Info>
  **Understanding the 24-hour window:** WhatsApp allows free-form messaging only within 24 hours of the customer's last message. After that window expires, you must use an approved template to re-initiate the conversation. Once the customer replies, the 24-hour window resets and you can send free-form messages again.
</Info>

<Warning>
  Make sure you have added a payment method in your [Meta billing settings](https://business.facebook.com/billing_hub). Without a payment method, template messages may fail to send.
</Warning>

## Troubleshooting

* **Template not appearing in Chatbase?** Check that the template has been fully approved in Meta. For the Helpdesk, only Utility and Authentication templates appear. Marketing templates are available in [Outbound Campaigns](/docs/user-guides/chatbot/outbound-campaigns).
* **Message failed to send?** Ensure the contact has a valid WhatsApp phone number and that you have a payment method configured in your [Meta billing settings](https://business.facebook.com/billing_hub).


# Wix
Source: https://chatbase.co/docs/user-guides/integrations/wix



## Step 1: Set Up Your Chatbase AI agent

To begin the integration process, you'll need to sign into your Chatbase account. If you haven't created an account yet, [sign up for a free account](https://www.chatbase.co/auth/signup). Once logged in, proceed to set up your agent by uploading relevant data sources. These data sources can include files, text snippets, websites, or question-and-answer pairs, which will form the knowledge base for your agent.

If you need help with setting up a functional Chatbase agent, here is a [step-by-step guide for setting up and deploying your Chatbase agent](/docs/user-guides/quick-start/your-first-agent).

## Step 2: Generate and Copy the Chatbase AI agent Embed Code

1\. After configuring your agent, navigate to your [**dashboard**](https://www.chatbase.co/dashboard/) page and select the specific bot you wish to embed. Clicking on the chosen bot should take you to the bot's preview page.

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

2\. On the agent preview page, click on the **Deploy** tab.

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

3\. A new page should come up. Click on **Manage** for the Chat Widget.

<Frame>
  <img alt="Chat Widget [Manage]" />
</Frame>

4\. Click on **Embed** and select the **Chat widget** embed type. Scroll down and Click **Copy** to copy the provided script.

<Frame>
  <img alt="Copy Script" />
</Frame>

With the embed code in hand, you are now ready to proceed with the integration process within your Wix application.

## Step 3: Sign Into Your Wix Account and Embed Your AI agent

1\. Sign in to your Wix website and head to your dashboard.

2\. On your dashboard, locate and click on **Design Site** in the top right corner of the page.

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

3\. Your site should load your site on the Wix website editor.

4\. Scroll down to any section of the website you wish to add the Chatbase agent.

5\. Click the big plus (**Add Elements**) button on the left sidebar of the Wix site editor.

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

6\. Scroll down to locate and click on **Embed Code**, followed by **Popular Embeds** and then **Custom Code**.

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

7\. The custom code widget should pop up, click **+ Add Custom Code** in the top right

8\. Paste the code snippet into the custom code editor.

9\. Provide a name for your code.

10\. Choose an option under **Add Code to Pages**.

11\. Choose where to place your code under Place Code in

12\. Click Apply. Once you've applied the changes, preview your website and you should see the floating Chatbase chat icon on your website.

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

**Congratulations, your Chatbase agent is now live on your Wix website.**

> **Note:** You can customize the appearance and colors of your bot on your Chatbase dashboard. To do this, go to your **dashboard**, choose a bot, click the **Settings** tab on the top of the page, and then click **Chat Interface** on the left sidebar to reveal the agent customization options.


# WordPress
Source: https://chatbase.co/docs/user-guides/integrations/wordpress



## **Step 1: Sign Into Chatbase and Configure Your Chatbase AI agent**

To add a Chatbase agent to your WordPress website, you'll need to first sign into your Chatbase account to create and set up an agent. You must also make sure that **[the agent is enabled](/docs/user-guides/quick-start/your-first-agent#navigate-to-the-deploy-section)**. If you don't have an account, you can start by [creating a Chatbase account for free](https://www.chatbase.co/auth/signup). If you are not sure how to create a agent, read this [detailed guide on how to create a agent on Chatbase](/docs/user-guides/quick-start/your-first-agent).

## Step 2: **Install Chatbase on Your WordPress Website**

**1. Log in to your WordPress admin dashboard:**

Your dashboard URL is typically *yourdomainname.com/wp-admin/*. You can also access it through your web hosting control panel.

**2. Install and activate the Chatbase plugin:**

* In the left sidebar of your WordPress admin dashboard, click on **Plugins**.

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

* Click **Add New Plugin** at the top of the next page.

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

* In the search bar on the next page, type "**Chatbase**" to search for the Chatbase plugin.

* Find the Chatbase WordPress plugin, click **Install Now**, then **Activate**.

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

**3. Add your Agent ID:**

1. In the left sidebar of the WordPress Admin dashboard, click **Settings**.

2. Look for **Chatbase options** and click on it.

3. In the Chatbase settings, find the text box labeled "Agent ID".

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

**4. Copy and paste your Agent ID:**

* Go to your Chatbase account and navigate to your [dashboard](https://www.chatbase.co/dashboard/).

* Select the agent you want to embed.

* Click on the "**Settings**" tab. At the top of the **General Settings** page, you'll find the Agent ID. Copy it.

* Paste the copied Agent ID into the text box in your WordPress settings.

  <Frame>
    <img alt="Agent ID" />
  </Frame>

**5. Save your changes:**

Click **Save Changes**. Your Chatbase agent should now be live on your WordPress website!

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


# Zapier
Source: https://chatbase.co/docs/user-guides/integrations/zapier



## Step 1: Sign Into Your Chatbase Account and Set Up Your Chatbot

1\. Sign up for a free Chatbase account.

2\. Log in and go to the bot creation page.

3\. Upload training data like text, documents, websites or Q\&A pairs.

4\. Train and test your bot until its responses meet your requirements.

Not familiar with creating a Chatbase agent? Here is a [<u>step-by-step guide to building a agent with Chatbase</u>](/docs/user-guides/quick-start/your-first-agent).

You can automate a lot of things with Chatbase and Zapier, it all boils down to what you want to achieve and your creativity. Here are some of the things you can do when you integrate your Chatbase bot with Zapier:

**1. Draft responses to customer emails**

* Send new customer emails from your inbox to Chatbase.

* Using your company's documentation, Chatbase can draft a relevant response.

* Automatically save the AI-generated response as a draft in your email client or send it directly.

**2. Categorize and prioritize incoming support emails**

* Connect Chatbase with your email client (e.g., Gmail, Outlook).

* Chatbase can analyze the tone and content of incoming emails.

* Categorize emails as urgent, non-urgent, or by specific topics.

* Add notes or tasks to your project management tool or spreadsheet for follow-up.

**3. Add AI-generated instructions or solutions to support tickets**

* Integrate Chatbase with tools like Jira, Intercom, or Zendesk

* When a new support ticket is created, send the details to Chatbase

* Chatbase can analyze the issue using your documentation and suggest initial solutions or step-by-step instructions

* Automatically add the AI-generated response or context to the support ticket

**4. Analyze customer feedback forms**

* Integrate Chatbase with form tools like Typeform or Google Forms

* Chatbase can analyze the feedback for intent, tone, and sentiment

* Generate summaries or insights from the feedback

* Send the analysis to your support workspace via email, Slack, or a spreadsheet

There's so much you can achieve with a combination of the two apps. For this guide, we'll work you through how to set up Chatbase to collect leads and add the leads to a Google Docs file using Zapier.

## Step 2: Set Up Chatbase to Collect Leads

1\. Sign in to your Chatbase account and head to your account dashboard.

2\. Click on the agent you want to set up lead collection for .

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

3\. Clicking on the bot should bring up the bot preview page. On the page, click on the **Setting** tab at the top of the page, and then **Leads** on the left sidebar of the page.

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

4\. Toggle on the switch beside each lead form field.

5\. Click **Save** on the bottom right corner of the page to apply the changes.

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

Once lead collection has been set up on the Chatbase end, you can now connect the agent to Zapier.

## **Step 3: Connect Chatbase to Zapier**

This step assumes that you have an active Zapier account. Remember, the idea is to set up set up the Zapier account to receive leads from from Chatbase agent, process it and add it to a Google docs file. To do this:

#### **Step 1: Set Up a Trigger**

1\. Sign in to your Zapier account.

2\. Click on **Create** and then **Zaps** on the top left corner of the Zapier app homepage.

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

3\. On the Zap editor click on **Trigger**.

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

4\. On the pop-up menu, search for Chatbase on the search bar and click on it.

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

5\. Next, on the right side of the page, click on the form field labeled **Event** and select **Form Submission**.

6\. Click on **Continue.**

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

7\. To use your Chatbase account on Zapier, you'll need to give Zapier access to your Chatbase account. To do this, click on **Sign in** on the next page after you click **Continue**.

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

8\. An authentication page should come up, provide your Chatbase API key (and optionally a display name) and then click **Yes, Continue to Chatbase** to link your Chatbase account.

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

***Note**: To get your API keys, head to your* [*account dashboard*](https://www.chatbase.co/dashboard/) *and click on the **Settings** tab at the top of the page. Click on **API keys** on the left sidebar and then copy out your API keys if you have one or click on Create API Key to create a new one.*

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

9\. Up next, click on **Continue** on the screen that comes up after authenticating your Chatbase account.

10\. On the next screen, you will be asked to provide your agent ID. Paste your agent ID in the provided input field and click **Continue**.

***Note**: To find your agent ID, head over to your* [*dashboard*](https://www.chatbase.co/dashboard/)*, click on any agent you wish to link with your Zapier account and you should find a agent ID on the agent preview page.*

11\. On the next page, click on **Test Trigger.**

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

12\. If all goes well, you should see an option asking you to **Continue with selected records**, click on it.

#### **Step 2: Set up an Action to Automate**

To set up Zapier to send your Chatbase leads to Google Docs:

1\. After clicking on **Continue with selected records**, on the previous step above, a pop up window should come up with a list of apps. Search for Google Docs on the search bar and click on it.

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

2\. On the next screen, click on the input field labeled **Event**, and select **Append Text to Document** and then click **Continue.**

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

3\. On the next page, sign into your Google account and click **Continue**.

4\. On the next page, select the document you wish to append the information to, on the filed labeled **Document Name**.

5\. On the field labeled **Text to Append**, select the leads form field you want to add to the document and click **Continue**.

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

6\. On the next page, click to test the setup, and then click **Publish** to go live.

With that, any time any lead is captured by your Chatbase agent on your website, it will automatically be added to your target Google docs file.


# Zendesk
Source: https://chatbase.co/docs/user-guides/integrations/zendesk



Chatbase makes it quick and easy to add an intelligent AI-powered agent to your Zendesk environment.

In just a few minutes, you can deploy a Chatbase agent to either respond directly to customer tickets within Zendesk or automatically escalate conversations to your human support team by creating a Zendesk ticket with a detailed summary of the interaction. This flexibility allows you to automate routine inquiries while ensuring complex cases are seamlessly handed off to your agents, improving response times, reducing manual workload, and delivering reliable, round-the-clock support.

## AI Ticket Responses in Zendesk

### Step 1: Access and Configure Your Chatbase Chatbot

These steps assume that you have already created a Chatbase account and that you have a Chatbase agent already available for use. If you haven't yet, [<u>create a Chatbase account</u>](https://www.chatbase.co/auth/signup) and build your first AI agent. For example, you can create a company FAQ agent to handle common employee questions or build a recruiting assistant to screen candidates and schedule interviews. Get your agent ready before moving to the integration.

[A step-by-step guide to creating a Chatbase agent in just a few minutes](/docs/user-guides/quick-start/your-first-agent).

### Step 2: Connect the Zendesk Integration

1\. Once you have a Chatbase account and an agent set up, head over to your [dashboard](https://www.chatbase.co/dashboard/). On your dashboard, you'll find a list of all the agents you have created. Locate and click on the agent you wish to integrate with Zendesk.

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

2\. Click on the **Deploy** tab, find the **Zendesk** integration and click on **Connect**.

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

3\. A new tab will open. Enter your Zendesk subdomain and click on **Submit**. It will ask you to login to your Zendesk account to authorize the integration.

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

### Step 3: Configure the Zendesk Integration

1\. Once you have authorized the integration, click **Manage** to configure the integration.

2\. You should see the following screen:

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

Select the following options:

* The Zendesk agent that the bot will reply as.
* Determine if tickets should be automatically assigned to the agent.
* Change agent's instructions specifically on Zendesk. This is useful if you want to instruct the agent to escalate the ticket to a human agent in certain cases (e.g. escalate to a human agent if the user asks for a refund ...etc)

And then click on **Save**.

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

### Step 4: Enable the **Generate Draft Response** feature

Don’t want the agent to respond directly? You can also enable the **Generate Draft Response** feature. This allows you to review and edit the AI-generated response before sending it to your users.

1\. Once you have configured the integration, you will have the option to enable the **Generate Draft Response** with a single click.

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

2\. To generate a draft response in a Zendesk ticket, please navigate to the **composer toolbar** located at the bottom of the ticket editor → Click on the Chatbase icon → Generate Draft Response.

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

### Tag Management System

You can use the tags that are assigned to the tickets by the agent to track its performance.

* `chatbase-involved`: This tag is applied to all tickets that chatbase replied to.
* `chatbase-routed-to-workspace`: This tag is applied to tickets that the agent couldn't resolve or was instructed to route to the workspace.
* `chatbase-soft-resolved`: This tag is applied to tickets that the agent thinks it is resolved, but the user hasn't yet confirmed the solution.
* `chatbase-hard-resolved`: This tag is applied to tickets where the user has confirmed that the problem is resolved.
* `chatbase-no-ai`: This tag is applied to tickets to stop the bot from auto-assigning itself or replying to the ticket.

## Human Escalation via Zendesk Ticket Creation

Here's how to integrate a Chatbase agent with your Intercom account

### Step 1: Connect to Zendesk

* Choose **Settings > Integrations**
* Connect your Zendesk to authorize access

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

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

***

### Step 2: Create 'Escalate to human' action

Now you're ready to configure your Escalate to Human action to route tickets to Zendesk. You can follow [this step-by-step guide](https://www.chatbase.co/docs/user-guides/chatbot/actions/escalate-to-human) to set up the action properly.

***

That’s it! Your Zendesk integration is now fully set up and ready to go. Whenever human intervention is required, your Chatbase agent will automatically create a ticket in Zendesk with a summary of the user’s issue and relevant context, allowing your support team to step in and resolve the case seamlessly.

<iframe title="YouTube video player" />


# Zoho Desk
Source: https://chatbase.co/docs/user-guides/integrations/zohodesk



Integrating Zoho Desk with Chatbase allows your custom agent to automatically escalate complex customer issues to your human support team by creating a ticket directly in Zoho Desk. The AI agent generates a Zoho Desk ticket that includes a clear summary of the user’s issue along with the relevant conversation context.

This ensures that when a case requires human attention, your support team receives all the necessary information upfront, eliminating the need for customers to repeat themselves. The AI handles routine inquiries instantly, and when escalation is needed, Zoho Desk becomes the system where your human agents step in to resolve the issue.

This guide will walk you through the steps required to connect your agent to Zoho Desk and configure automated ticket creation for smooth handoffs to your support team.

## Setup Guide

Here's how to integrate a Chatbase agent with your Zoho Desk account

### Step 1: Connect to Zoho Desk

* Login to your Chatbase dashboard
* Select your Agent
* Choose **Settings**
* Select **Integrations**
* Click **Connect** under Zoho Desk to authorize access

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

***

### Step 2: Create 'Escalate to human' action

Now you're ready to configure your Escalate to Human action to route tickets to Zoho Desk. You can follow [this step-by-step guide](https://www.chatbase.co/docs/user-guides/chatbot/actions/escalate-to-human) to set up the action properly.

***

That’s it! Your Zoho Desk integration is now fully set up and ready to go. Whenever human intervention is required, your Chatbase agent will automatically create a ticket in Zoho Desk with a summary of the user’s issue and relevant context, allowing your support team to step in and resolve the case seamlessly.


# Best Practices
Source: https://chatbase.co/docs/user-guides/quick-start/best-practices

This page offers tips to help you improve your AI agent's performance and user experience. It covers improving the instructions, teaching the bot how to send links.

## Refine the AI agent's Instructions

The instructions shape your AI agent's behavior and responses. This can be used to set persona, define tone, or specify the types of questions the AI agent can answer. Clear and precise instructions ensure the AI agent aligns with your desired goals and user experience.

Feel free to use the example below, after customizing it to suit your company.

<Accordion title="Friendly Support Agent Instructions">
  ```
  ### Role
  - **Primary Function:** You are a friendly customer support agent for TaskFlo, a project management and issue tracking tool. Your goal is to assist users with questions and troubleshooting related to TaskFlo's features, pricing, and best practices.

  ### Persona
  - **Identity:** You are a dedicated TaskFlo customer support agent. You will not adopt any other persona or impersonate another entity. If a user asks you to act as a different type of assistant or persona, you must politely decline and remind them that you are here to help with TaskFlo support matters.

  ### Constraints
  1. **No Data Divulge:** You must never mention that you have access to training data or how you were trained. Your responses should sound naturally helpful and informed.
  2. **Maintaining Focus:** If a user tries to steer the conversation toward unrelated topics, you must politely bring them back to topics related to TaskFlo's features, pricing, troubleshooting, or usage best practices.
  3. **Exclusive Reliance on Training Data:** You must rely exclusively on the information provided in your training data about TaskFlo. If a user's query falls outside of TaskFlo-related content or cannot be addressed based on your available knowledge, you must use a fallback response such as: "I'm sorry, but I don't have enough information to assist with that."
  4. **Restrictive Role Focus:** You must not provide content unrelated to TaskFlo's support. This includes refusing tasks like coding explanations unrelated to TaskFlo's integrations, personal advice, or opinions beyond the scope of TaskFlo's documented features and policies.
  ```
</Accordion>

You can find more detailed information about refining your instruction [here](/docs/user-guides/chatbot/settings#instructions).

## Improve Readability of Data Sources

The quality of your AI agent's responses depends heavily on the quality of the data sources you provide. Chatbase relies on readable text to generate accurate responses, so make sure the websites or PDFs you upload contain readable text.

Some websites may not be scraper-friendly. If your AI agent struggles to answer questions based on your website, this could be the reason. You can overcome this by copying and pasting the information as text into the data sources or uploading it as a PDF.

<AccordionGroup>
  <Accordion title="Bad Product Example">
    Product: Widget123, colors not specified, possibly red or blue. Discount details unclear. Weight: Approx. 1 kg or 1.5 kg? Shipping: Delivery time uncertain, could be fast or delayed. Availability: Global shipping not confirmed. Packaging: Uncertain if it comes in a box. Assembly: Information unclear. Limited stock? Not confirmed.
  </Accordion>

  <Accordion title="Good Product Example">
    Product: Widget123\
    Colors: Red, Blue\
    Discount: 50% off\
    Weight: 1.5 kg\
    Shipping: Estimated delivery within 1-2 weeks (depends on location)\
    Availability: Ships worldwide\
    Packaging: Comes in a standard-sized box\
    Assembly: Some assembly required\
    Order Now: Limited stock available, don't miss out!
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Bad Description Example">
    The product is a thing. Its color is unspecified, and its size is unknown. The product might be useful, but it's not clear. Its availability is uncertain, and shipping times are not mentioned. There might be a discount, but it's not specified. Assembly instructions? Unclear. Get it soon? It's unclear when stock might run out.
  </Accordion>

  <Accordion title="Good Description Example">
    The Widget123 is a premium-quality product available in two colors: red and blue.\
    It offers a 50% discount, making it an excellent deal.\
    The product weighs 1.5 kg and is shipped worldwide.\
    You can expect delivery within 1-2 weeks, depending on your location.\
    The item comes in a standard-sized box and requires minimal assembly.\
    Act fast—stock is limited!
  </Accordion>
</AccordionGroup>

> **Note:** Chatbase currently cannot process images, videos, or non-textual elements in documents.

## Add Suggestable Links

To have links suggested by the bot, they must be explicitly included in your training data. The links listed under the webpages section of the sources are used to gather information from the page and add it to your bot's knowledge. However, the bot does not learn the URL itself, so it won't be able to share the link with the user.

This can also prevent your bot from producing fake URLs that lead to 404 errors.

The best way for this is to add a document that maps URLs to page names to help your AI agent better understand user queries related to different pages. Here is an example of a mapping inputted as text in the data sources:

<Frame>
  <img alt="Adding suggested URLs to the training data." />
</Frame>

## Add Suggestable Images

To enable image display in the chat widget, agents can use markdown format when sending image links.

Ensure the URL ends with .png or .jpg for the image to render correctly.

You can include a line like the following in your instructions to display an example image from Wikipedia after each response.

```
Always end your reply with ![Example Image](https://upload.wikimedia.org/wikipedia/commons/7/79/ELIZA_conversation.png)
```

Once added, every agent response will display the image, as illustrated in the screenshot below:

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

## Choose the suitable AI model

Selecting the right AI model is crucial for optimal performance. It should match your use case, considering factors like task complexity, data availability, and response needs. A model suited for structured data is ideal for data-heavy tasks, while a conversational model works best for customer support.

Also, consider scalability and adaptability. Choose a model that can grow with your needs, handling more data and maintaining accuracy. Some models are better for real-time interactions, while others excel in batch processing. Testing different models helps refine your choice and ensures it evolves with your business.

### AI Model Recommendations Based on Use Cases

### **Customer Support & FAQ**

For quick, clear responses to general inquiries.

* **Models to use**:
  * **`gpt-5-mini`**: Delivers fast, concise answers.
  * **`gemini-2.5-flash`**: Ideal for real-time, simple queries.

### **Content Creation & Marketing**

For crafting creative, engaging content like blogs or marketing materials.

* **Models to use**:
  * **`claude-4-sonnet`**: Excels at poetic and creative content.

### **E-commerce & Lead Generation**

For product suggestions or moderately complex questions.

* **Models to use**:
  * **`gpt-5`**: Balances speed and precision in customer interactions.
  * **`gemini-2.0-pro`**: Effective for product recommendations and medium-complexity queries.

### **Advanced Research & Technical Support**

For in-depth research, troubleshooting, and solving complex issues.

* **Models to use**:
  * **`gpt-5`**: Advanced model for complex research and deep problem-solving.
  * **`gemini-2.0-pro`**: Highly accurate, advanced technical support.

> **Note:** If you are still unsure about which model to use, please refer to our [models comparison](https://www.chatbase.co/docs/user-guides/ai-agent/models-comparison) page.

## Utilize the "Revise" Feature and Q\&A Data Type

After launching your AI agent, you can monitor its responses in the [Activity tab](https://www.chatbase.co/docs/user-guides/ai-agent/activity). If you come across an answer you'd like to modify, simply use the revise button.

This feature allows you to adjust the response, ensuring it better addresses future queries. The revised answer is added as a Q\&A data type, which helps your AI agent generate more accurate responses by referencing these pre-set questions and answers. You can find the updated responses in the Q\&A tab under [Data sources](https://www.chatbase.co/docs/user-guides/ai-agent/data-sources).

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


# Welcome to Chatbase
Source: https://chatbase.co/docs/user-guides/quick-start/introduction

Get started with Chatbase and discover how to build intelligent agents trained on your business data.

<Frame>
  <div>
    <img alt="Chatbase Logo" />

    <img alt="Chatbase Logo" />
  </div>
</Frame>

## Why Choose Chatbase?

<CardGroup>
  <Card title="Smart & Trainable" icon="brain">
    Train your AI Agent with your own documents, websites, or databases for accurate, relevant responses
  </Card>

  <Card title="Easy Integration" icon="plug">
    Embed anywhere with simple copy-paste code - no technical expertise required
  </Card>

  <Card title="Interactive Actions" icon="bolt">
    Pre-built actions for Slack, Stripe, Calendly, lead collection, and web search - Plus custom actions for any API integration
  </Card>

  <Card title="Powerful Analytics" icon="chart-line">
    Track conversations, monitor performance, and continuously improve your AI Agent
  </Card>

  <Card title="Lead Generation" icon="users">
    Capture and manage leads automatically through intelligent conversations
  </Card>

  <Card title="Deploy Everywhere" icon="globe">
    Experience our lush integrations across 15+ platforms including WordPress, Shopify, WhatsApp, Slack, Zendesk, and more.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Ready to get started?" icon="rocket" href="/user-guides/quick-start/your-first-agent">
    Let's build your first AI agent! The entire process takes less than 10 minutes.
  </Card>
</CardGroup>


# Response Quality
Source: https://chatbase.co/docs/user-guides/quick-start/response-quality

On this page, discover tips to improve your response quality. Learn how to refine prompts, optimize AI agent settings, and analyze behavior to deliver clearer, more effective, and engaging interactions.

## Refine the AI agent's Instructions

The instructions shapes your AI agent's behavior and responses. To ensure your bot only answers questions about the given document, specify this in the instructions. For instance, you can state, "You will only provide answers based on the information in \[document name]." The default is the following:

I want you to act as a support agent. Your name is "AI Assistant". You will provide me with answers from the given info. If the answer is not included, say exactly "Hmm, I am not sure." and stop after that. Refuse to answer any question not about the info. Never break character.

You can find more information about the instructions in the previous article, \[AI agent Settings]\([https://www.chatbase.co/guide/AI](https://www.chatbase.co/guide/AI) agent-settings)

## Ensure Readability of Uploaded Data Sources

The quality of your AI agent's responses largely depends on the quality of the data sources you provide. Chatbase uses readable text to generate responses, so ensure that the websites or PDFs you upload contain readable text. Note that Chatbase can't process images, videos, or non-textual elements in documents. Some websites are not scraper friendly, so if you see your AI agent is unable to answer questions on your website, this might be the case. You can work-around this by copy and pasting information as text into the data sources, or uploading it as a PDF instead.

## Utilize the "Revise" Feature and Q\&A Data Type

The "revise" feature is accessible from the dashboard in your conversation history. It is a tool for tweaking responses.

<Frame>
  <img alt="[object Object]" />
</Frame>

If you're not satisfied with how your AI agent answered a particular query, you can use this feature to alter the response to fix it for the future. Additionally, using the Q\&A data type can help your AI agent generate better answers by referring to pre-set questions and answers. The responses you revise will appear in the Q\&A tab under "**Manage**"

## Leverage the Power of GPT-5

If you want your AI agent to generate more nuanced and sophisticated responses, consider using the GPT-5 model. It is the most sophisticated GPT model available, producing more accurate and contextually aware responses. You can change what language model you use.

<Frame>
  <img alt="[object Object]" />
</Frame>

## Create a Document Mapping Website URLs to Page Names

If you notice your bot produces fake URLs that lead to 404 errors, try to make a PDF document that maps all of the correct URLs with the page names. This can be very helpful if your AI agent operates on a website with multiple pages. Having a document that maps URLs to page names can help your AI agent better understand user queries related to different pages. Here is an example of a mapping inputted as text in the data sources:

<Frame>
  <img alt="Suggested links" />
</Frame>

Additionally, you can add these links in Q\&A format, and follow the suggestions previously mentioned.

## Next Steps

By implementing these strategies, you can significantly enhance your Chatbase AI agent's ability to provide useful responses, leading to more successful interactions.


# Build Your First AI Agent
Source: https://chatbase.co/docs/user-guides/quick-start/your-first-agent

Create, train, and deploy your first AI Agent in under 5 minutes. Follow this step-by-step guide to get your intelligent assistant live on your website.

In just a few minutes, you'll have a fully functional AI Agent answering questions about your business and engaging with your website visitors. Let's get started!

## Prerequisites

<Info>
  You'll need an active Chatbase account to follow this guide. [Sign up here](https://www.chatbase.co/auth/signup) if you haven't already.
</Info>

## Overview

Here's what we'll accomplish in this guide:

<Steps>
  <Step title="Create & Train Your Agent">
    Set up a new AI Agent and train it using your website or documents
  </Step>

  <Step title="Test & Optimize">
    Use the Playground to test responses and fine-tune performance using the Compare feature
  </Step>

  <Step title="Deploy to your Website">
    Add your AI Agent to your website with a simple embed code
  </Step>
</Steps>

<Tip>
  **Estimated time:** 5 minutes from start to finish
</Tip>

## Step 1: Create & Train Your AI Agent

### Navigate to Your Dashboard

After signing into your Chatbase account, go to your main dashboard.

Click the **"New AI Agent"** button to get started.

<Frame>
  <img alt="Chatbase dashboard with New AI Agent button highlighted" />
</Frame>

### Choose Your Training Data

Your AI Agent needs information to learn from. You can train it using various data sources:

<Tabs>
  <Tab title="Files">
    **Upload your documents**

    Train your agent on your documents.

    **Best for:** Business documents, manuals, FAQs, product information, etc.

    <Frame>
      <img alt="Data sources tab with Files option selected and a file being uploaded" />
    </Frame>
  </Tab>

  <Tab title="Text snippets">
    **Direct text input**

    Paste your content directly into the platform. Useful for specific information or custom training content.

    **Best for:** Specific information or custom training content

    <Frame>
      <img alt="Data sources tab with Text snippets option selected and a text being added" />
    </Frame>
  </Tab>

  <Tab title="Website">
    **Crawl your website**

    Our crawlers will discover and learn from all your pages.

    **Best for:** Your entire website or sitemap

    <Info>
      Our intelligent crawlers will explore your website and all linked pages for training. After crawling completes, you'll see all discovered pages and the total character count available for training.
    </Info>

    <Frame>
      <img alt="Data sources tab with Text snippets option selected and a text being added" />
    </Frame>
  </Tab>

  <Tab title="Q&A">
    **Add your own Q\&A**

    Add your own Q\&A to your agent. This is useful for specific questions and answers that you want your agent to know.

    **Best for:** Specific questions and answers

    <Frame>
      <img alt="Data sources tab with Q&A option selected and a Q&A being added" />
    </Frame>
  </Tab>

  <Tab title="Notion">
    **Connect your Notion workspace**

    Connect your Notion workspace to your agent. This is useful for your entire knowledge base.

    **Best for:** Teams using Notion

    <Tip>
      To connect your Notion workspace, you'll need to click on **Import** to authorize the connection and select the specific pages you want to include.
    </Tip>

    <Frame>
      <img alt="Data sources tab with Notion option selected and a Notion workspace being connected" />
    </Frame>
  </Tab>
</Tabs>

### Review & Start Training

Click **"Create Agent"** to begin the training process.

<Frame>
  <img alt="Data sources tab with Create Agent button highlighted" />
</Frame>

<Check>
  Training typically takes 2-5 minutes depending on the amount of data. You can proceed to the next step while training completes.
</Check>

<Info>
  **Character Limits:** Different plans have different character limits for training data. Check your plan if you hit any limits.
</Info>

## Step 2: Test & Optimize Your AI Agent

### Access the Playground

Once training begins, you'll automatically be taken to the [**Playground**](/docs/user-guides/chatbot/playground) - your testing environment where you can chat with your AI Agent and fine-tune it before making it live.

<Frame>
  <img alt="Playground interface showing chat testing area" />
</Frame>

### Evaluate Response Quality

As you test, look for:

<Check>**Accuracy** - Are responses factually correct?</Check>
<Check>**Relevance** - Does it answer what was asked?</Check>
<Check>**Completeness** - Are responses comprehensive but concise?</Check>
<Check>**Tone** - Does it match your brand voice?</Check>

### Fine-tune Settings

<Tabs>
  <Tab title="AI Model">
    ### Test responses with different models

    <Steps>
      <Step title="Test with different models">
        Ask the same questions to different models and compare:

        * **Response quality and accuracy**
        * **Response time and speed**
        * **Tone and personality**
        * **Handling of edge cases**

        <Frame>
          <img alt="Playground interface showing select models button" />
        </Frame>
      </Step>

      <Step title="Make Your Decision">
        Based on the comparison, select the model that best fits your specific use case and brand voice.
      </Step>
    </Steps>

    <Tip>
      For detailed model comparisons and advanced testing strategies, check out our [comprehensive model comparison guide](/docs/user-guides/chatbot/playground#compare-area).
    </Tip>
  </Tab>

  <Tab title="Instructions">
    Define how your AI Agent should behave and respond to users. These instructions shape your agent's personality, tone, and approach to conversations.

    <Tip>
      **Get inspired:** Use the dropdown examples below to see instruction templates for different business types and scenarios. You can copy and customize them for your specific needs.

      <Frame>
        <img alt="Instructions dropdown showing different examples" />
      </Frame>
    </Tip>

    **How to write effective instructions:**

    * Be specific about your desired tone (professional, friendly, casual, etc.)
    * Set clear boundaries about what topics to discuss or avoid
    * Include your business goals (lead collection, support, sales, etc.)
    * Specify when to escalate to human support
    * Define your brand voice and personality
  </Tab>

  <Tab title="Temperature">
    Controls response creativity:

    * **Low (0.1-0.3)** - Consistent, factual responses
    * **Medium (0.4-0.7)** - Balanced creativity
    * **High (0.8-1.0)** - More creative, varied responses
  </Tab>
</Tabs>

## Step 3: Deploy to Your Website

### Navigate to the Deploy Section

Once you're satisfied with your AI Agent's responses, it's time to make it live! Navigate to the **"Deploy"** tab in the sidebar, and toggle the switch on the **"Chat widget"** card to enable the agent.

<Frame>
  <img alt="All channels view showing Chat widget card with toggle switch to enable the agent" />
</Frame>

<Info>
  **Disabled vs Enabled:** Disabled agents are only accessible to workspace
  members. Enabled agents can be embedded on websites and accessed by anyone
  with the link.
</Info>

### Choose Your Deployment Method

Chatbase offers multiple deployment methods including chat widget, help page, and integrations with WhatsApp, WordPress, and other platforms.

<Frame>
  <img alt="Deploy tab showing many different deployment methods" />
</Frame>

In this guide, we'll use the **Chat widget** option as it's most common. Click on Manage on chat widget then select Embed.

<Frame>
  <img alt="chat widget embed tab" />
</Frame>

<Tabs>
  <Tab title="Chat Widget (Recommended)">
    **Perfect for most websites**

    Adds a floating chat icon that users can click to start conversations. Non-intrusive and mobile-friendly.

    **Pros:**

    * Can utilize advanced features like [identity verification](../../developer-guides/identity-verification).
    * Doesn't interfere with your site's design
    * Users can minimize/maximize as needed
    * Works great on mobile devices
    * Familiar UX pattern

    **Best for:** Business websites, blogs, e-commerce stores
  </Tab>

  <Tab title="iFrame">
    **For dedicated chat sections**

    Embeds the full chat interface directly into your page layout. Always visible and ready for interaction.

    **Pros:**

    * Always visible to users
    * More prominent than chat bubble
    * Good for dedicated support pages
    * Customizable dimensions

    **Best for:** Support pages, help centers, dedicated chat sections
  </Tab>
</Tabs>

### Get Your Embed Code

In this guide we'll use the **Chat widget** option.

Copy the provided JavaScript code snippet:

<Frame>
  <img alt="JavaScript embed code ready to copy" />
</Frame>

### Add Code to Your Website

<Steps>
  <Step title="Locate Your Site's HTML">
    Find where you can add JavaScript code to your website. This is usually in the `<head>` section or before the closing `</body>` tag.

    <Tip>
      **For fast loading:** Place the script just before the closing `</body>` tag to ensure your page content loads first, then the chat widget appears.

      **For immediate availability:** Place the script in the `<head>` section to load the chat widget as early as possible, though this may slightly delay your page's initial render.
    </Tip>
  </Step>

  <Step title="Paste the Code">
    Copy and paste the embed script into your website's HTML. If you're using a CMS like WordPress, there's usually a "Custom HTML" or "Scripts" section.
  </Step>

  <Step title="Save and Publish">
    Save your changes and publish your website updates.
  </Step>
</Steps>

### Verify Installation

Visit your website and look for the chat bubble. Click it to test the integration!

<Frame>
  <img alt="Live AI Agent chat bubble on a website" />
</Frame>

<Check>
  **Success!** Your AI Agent is now live and ready to help your website visitors.
</Check>

<Tip>
  Need more control over your widget? Check out our [Developer Guides](/docs/developer-guides/overview) for more information on JavaScript embed, [widget control options](/docs/developer-guides/control-widget), and advanced features like [client-side custom actions](/docs/developer-guides/client-side-custom-actions) and [event listeners](/docs/developer-guides/chatbot-event-listeners).
</Tip>

### Customize Appearance (Optional)

Want to match your brand? Check out our settings guide for [style](/docs/user-guides/chatbot/deploy#style-settings) and [content](/docs/user-guides/chatbot/deploy#content-settings).

<Frame>
  <img alt="Chat interface customization options" />
</Frame>

<AccordionGroup>
  <Accordion title="Branding Options">
    * Upload custom chat bubble icon
    * Change bubble colors to match your brand
    * Customize welcome messages
    * Set initial questions users can click
  </Accordion>

  <Accordion title="Behavior Settings">
    * Auto-open chat after delay
    * Collect user feedback
  </Accordion>
</AccordionGroup>

## 🎉 Congratulations!

You've successfully created, trained, tested, and deployed your first AI Agent! Here's what you've accomplished:

<Check>✅ Created an intelligent AI Agent trained on your data</Check>
<Check>✅ Tested and validated response quality</Check>
<Check>✅ Deployed it live on your website</Check>
<Check>✅ Made it accessible to your visitors 24/7</Check>

### What's Next?

<CardGroup>
  <Card title="Monitor Performance" icon="chart-line" href="/user-guides/chatbot/analytics">
    Track conversations and optimize your AI Agent's performance
  </Card>

  <Card title="Advanced Features" icon="wand-magic-sparkles" href="/user-guides/chatbot/actions/actions-overview">
    Add actions like lead capture, appointment booking, and more
  </Card>

  <Card title="Best Practices" icon="lightbulb" href="/user-guides/quick-start/best-practices">
    Learn proven strategies to maximize your AI Agent's effectiveness
  </Card>

  <Card title="API Integration" icon="code" href="/developer-guides/api/create-a-chatbot">
    Build custom integrations with our powerful API
  </Card>
</CardGroup>

<Info>
  **Need help?** Our support workspace is here to assist you. Visit our [Help Center](https://www.chatbase.co/help) or check out the [FAQ section](/docs/faq/faq) for common questions.
</Info>


# HIPAA compliance
Source: https://chatbase.co/docs/user-guides/workspace/hipaa-compliance

How Chatbase supports HIPAA-eligible workloads on Enterprise plans through a Business Associate Agreement and Zero Data Retention.

## Overview

Chatbase is HIPAA-eligible for Enterprise customers. A workspace becomes HIPAA compliant once two things are in place:

* A signed Business Associate Agreement (BAA) between Chatbase and the Covered Entity or Business Associate .
* Zero Data Retention (ZDR), which Chatbase enables automatically on the workspace after the BAA is in effect.

While the workspace is HIPAA compliant, Chatbase applies the safeguards described below and disables features that are not compatible with HIPAA.

## How HIPAA compliance works in Chatbase

1. The customer (the covered entity or business associate) signs a Business Associate Agreement with Chatbase. BAAs are available on the Enterprise plan only.
2. Chatbase marks the workspace as HIPAA compliant and **automatically enables Zero Data Retention** on it. The customer does not toggle ZDR manually.
3. From that point on, the safeguards in the next section take effect automatically across the workspace and its AI agents.

## Shared responsibility model

HIPAA compliance is a shared responsibility between Chatbase and our customers. The sections below outline what we cover and what remains your responsibility.

### Chatbase's responsibilities

* **Direct liability** — As a business associate, Chatbase is directly accountable for complying with the applicable provisions of the HIPAA Rules. This means we implement the safeguards required to protect electronic Protected Health Information (ePHI) and notify customers of any qualifying breach.
* **BAA compliance** — Chatbase upholds the terms of every BAA we sign, including the appropriate administrative, physical, and technical safeguards needed to protect ePHI across our platform.
* **Vendor management** — Any sub-processors or vendors with potential access to ePHI must themselves comply with HIPAA. Chatbase manages this by signing a BAA with such vendors.
* **Enforcing Zero Data Retention** — Once a workspace is marked HIPAA compliant, Chatbase automatically enables and enforces Zero Data Retention on it. ZDR redacts the **entire content of every message** in chat logs and leads across the workspace — not just specific PII or PHI fields — so no message text is retained. Customers do not need to configure ZDR themselves.
* **Internal logs** — All conversation messages and user-identifiable data are redacted from Chatbase's internal logs.
* **Internal audit logging** — Chatbase maintains internal audit logs that record HIPAA-relevant events on HIPAA-compliant accounts, supporting investigation and accountability.

### Your responsibilities

<Warning>
  Chatbase secures the platform; you are responsible for what you put into it, how your team accesses it, and which features you choose to use.
</Warning>

* **Sources and training data** — Do not upload PHI or PII into sources. You are responsible for the content you ingest into your agent's knowledge base.
* **Contacts and contact attributes** — You are responsible for the data you store on contact records and their custom attributes.
* **Two-factor authentication (2FA)** — All workspace members must enable 2FA on their accounts. See [Two-factor authentication](/docs/user-guides/workspace/two-factor-auth) for setup steps.

#### Features disabled by default

Chatbase disables the following features by default on HIPAA-compliant workspaces. Even with these defaults in place, **you remain responsible for ensuring that your team does not attempt to use any of them with PHI**:

* Voice-recording retention
* Topic analysis
* Sentiment analysis
* Daily chats email digest
* Daily leads email digest
* Knowledge gaps analysis
* Chatbase Helpdesk (currently disabled)
* End-user Attachments (currently disabled)

## HIPAA Compliant AI providers

Only the following providers are available on a HIPAA-compliant workspace.

### Large language models (LLM)

Any model offered by:

* OpenAI
* Anthropic

### Speech-to-text (STT)

* Deepgram
* Cartesia

<Note>
  On HIPAA-compliant accounts:

  * Some voices are restricted and will not be available for selection in the voice picker.
  * Configuring a custom voice is curerntly not available.
</Note>

## HIPAA-Compliant Channels

The following deploy channels can be used on a HIPAA-compliant workspace:

* Chat widget (web embed)
* Help page
* API
* Phone (voice)
* Android SDK
* iOS SDK
* WordPress
* Shopify
* Zendesk
* Zendesk Messaging
* Salesforce
* Zapier

These channels operate under the same redaction and retention rules as the rest of the workspace.

## HIPAA Compliant Integrations

The following integrations are HIPAA compliant on Chatbase:

* Shopify
* Stripe
* Calendly

### Conditionally HIPAA compliant integrations

The following integrations are HIPAA compliant only if the covered entity has their own BAA in place with the connected provider:

* Zendesk
* Zendesk Messaging
* Salesforce
* Intercom
* Freshdesk
* HubSpot
* Zoho Desk
* Help Scout
* Slack

## HIPAA Compliant Actions

The following actions are HIPAA compliant:

* Collect leads
* Custom button
* Custom action
* Custom form
* Customize suggested messages
* Web search
* Slack notify
* Cal.com: Get available slots
* Calendly: Get available slots
* Stripe actions
* Shopify actions

### Conditionally HIPAA compliant actions

The following actions are HIPAA compliant only if the covered entity has their own BAA in place with the connected provider:

* Escalate action
* Zendesk Messaging live chat action

## Conversation lifecycle and API behavior

### Conversation auto-end rules

On a HIPAA workspace, an ongoing conversation ends automatically when either of the following is true:

* The conversation has been idle for more than **12 hours**, or
* The conversation is more than **7 days** old.

### API behavior

The `/conversations` endpoints in both API v1 and API v2 return **redacted** conversation data on a HIPAA workspace.

## Requesting a BAA

HIPAA support is available on the Enterprise plan. To request a BAA, contact your account representative or get in touch with the Chatbase sales team.

<Card title="Contact Enterprise sales" icon="building" href="https://www.chatbase.co/enterprise">
  Submit the Enterprise contact form to start the BAA process and discuss HIPAA-compliant deployment for your workspace.
</Card>


# Manage  
Source: https://chatbase.co/docs/user-guides/workspace/manage

Organize your users in Chatbase workspaces for better collaboration and permission control.

## Workspace Management

### Creating a Team

To create a new workspace, click on the **Create or join workspace** button on the **Select workspace** dropdown menu.

<Frame>
  <img alt="Workspace Settings General" />
</Frame>

On the next page, you need to add the details for the workspace, which includes:

* **Workspace Name:** Defines the agent's display name within the dashboard.
* **Workspace URL:** Specifies the workspace slug, visible only in the URL when accessing the workspace on the dashboard.

***Important Note:*** You can choose any workspace URL you prefer, as long as it's unique and doesn't match with any existing workspace.

<Frame>
  <img alt="Workspace Settings General" />
</Frame>

After creating the workspace, you will be taken to a new page where you can press 'New AI agent' and start adding your sources to start your Chatbase journey!

<Frame>
  <img alt="Workspace Settings General" />
</Frame>

### Duplicating your Agent

You can easily duplicate any agent by clicking the three dots icon and choosing Duplicate Agent.

<Frame>
  <img alt="Workspace Agent Duplication" />
</Frame>

#### What's Not Copied

While most agent settings are copied, the following are **not** included:

* **Deployment integrations** such as WhatsApp, Zendesk, Instagram, Email channel, etc.
* **Slack Notify action** as Slack workspaces can't be connected to multiple agents at the same time
* **Notion sources** as Notion workspaces can't be connected to multiple accounts

### General Notes

* **Each workspace** has its own AI agents, billing information, and plan. These are not shared between workspace.

* **Owners** can change workspace settings (billing, plan, name), delete the workspace, and manage all AI agents within the workspace.

* **Members** can only manage AI agents (train them, see data, delete them). They cannot change workspace settings.

* **Invite links** expire 24 hours after it has been sent to an invitee.


# Settings
Source: https://chatbase.co/docs/user-guides/workspace/settings

This page provides all the details for the specified workspace, including member information, plan and billing details, Chatbase API keys, and API keys for the external LLM.

## General

This tab provides general information about the agent, including the Workspace Name and Workspace URL. The Workspace Name is displayed on the dashboard and in the AI agent path, while the Workspace URL appears in the address bar when accessing the workspace or its agents.

To modify the name or URL, simply edit the text in the field and click "Save."

You can also delete the entire workspace and all its AI agents by clicking the "Delete" button at the bottom of the page.

<Frame>
  <img alt="Workspace Settings General" />
</Frame>

### Members

This tab displays all the information about your workspace members, as well as those you've invited but haven't responded yet.

<Frame>
  <img alt="Workspace Settings Members" />
</Frame>

### Number of members

This shows the number of workspace members and invited members. In this example, the user has 3 members and invitations, with a maximum limit of 5.

<Frame>
  <img alt="Workspace Settings Members Limit" />
</Frame>

### Modify workspace member role

To modify a workspace member's role or remove them, click the three dots next to their name.

* **Owners**: Can change billing information, modify plans, rename or delete the workspace, and manage all AI agents within the workspace.
* **Members**: Can update training data, view analytics, and delete AI agents. They cannot alter workspace settings.
* **Viewer**: Provides read-only access to view resources and analytics. Users cannot modify any settings, but they can still test the agent through the playground and compare sections.

#### Custom Roles

On **the Enterprise plan**, custom roles can be created to control what different members of your workspace can access and manage. This allows teams to assign permissions based on responsibilities and maintain better control over sensitive features.

Each custom role includes configurable permissions across different areas of the platform, such as:

* **Agents** – View, create, edit, or delete agents
* **Sources** – Manage knowledge sources used by agents
* **Chatlogs** – View, delete, or export conversation history
* **Contacts** – Access and manage stored contacts
* **Integrations** – Configure external integrations
* **Billing** – View or manage billing settings
* **Subscription** – Manage the workspace subscription
* **Members** – View or manage workspace users
* **Webhooks** – Configure webhook integrations
* **Workspace** – Manage workspace-level settings
* **API Keys** – Create and manage API keys
* **Actions** – View automation actions
* **Analytics** – Access analytics dashboards
* **Leads** – View and export collected leads

Custom roles appear alongside the default roles (Owner, Member and Viewer) and can be assigned to workspace members to provide the appropriate level of access.

### Remove workspace member

To remove a member from the workspace

<Frame>
  <img alt="Workspace Settings Members Remove Member" />
</Frame>

### Modify Invitations

You can resend the invitation if it expired after 24 hours or if the invitee didn't see it in their inbox. You can also revoke the invitation to cancel it and prevent the invitee from joining the workspace.

<Frame>
  <img alt="Workspace Settings Revoke Resend Invite" />
</Frame>

### Invite Members

You can use this button to send new invitations to your workspace from the dashboard. To invite multiple members at once, click "Add Member."

<Info>
  New members can be added either by manually adding an extra member from the add-on card inside the dashboard or when an invited member accepts their invitation
</Info>

<Info>
  When an owner removes team members, the number of extra member slots does not decrease automatically, so billing remains the same. You’ll need to manually reduce the extra member count from the Plans page.
</Info>

## Plans

This tab provides information about all available plans and lets you modify your current plan or add new add-ons.

### Current Plan

This section is optional and will only appear if you're on a legacy plan. It provides details about the current plan, including your allowed features and limits.

<Frame>
  <img alt="Workspace Settings Plans" />
</Frame>

### Available Plans

This section displays all available plans for subscription. You can switch between monthly and yearly by toggling the option. It's important to note that subscribing annually lets you pay for 10 months instead of 12.

For more details about the available plans, please check out [our Pricing page](https://www.chatbase.co/pricing).

Please note that if you're on the old pricing packages, you won't be affected unless you want to upgrade your payment to annual or change the plan.

<Frame>
  <img alt="Legacy plan" />
</Frame>

If you choose to downgrade to a lower plan, such as from Standard to Hobby, the downgrade will take effect immediately. You'll receive a prorated credit based on the remaining time on your current plan, which will be applied to your new plan and any future invoices until the credit is used up.

Clicking "Cancel Plan" under your active plan disables auto-renewal. Your current plan will remain active until the next renewal date, after which you'll be downgraded to the free plan to avoid further charges. Your addons will also be active until the end of your billing period then removed when the plan expires.

***Note:*** Legacy plan users can now see the "Cancel Plan" button, as their active plan is listed. To downgrade to the free plan, please click on the cancel plan button, as shown below:

<Frame>
  <img alt="Legacy plan" />
</Frame>

### Add Ons

This section is responsible for adding extra features on top of your current plan.

If you are choosing an add-on that can have quantities like extra AI agents, you will see a prompt similar to this:

<Frame>
  <img alt="Extra Agents Addon" />
</Frame>

<Info>
  Free users must subscribe to a base plan before adding any add-ons.
</Info>

#### Auto recharge credits

When your credits fall below the threshold you set, we'll automatically add credits that don't expire to your account, ensuring uninterrupted service.

#### Extra AI agents

You can add extra AI agents to help you scale your service by managing multiple agents simultaneously.

#### Custom Domains

Use your own custom domains for the embed script, iframe, and AI agent link, offering a personalized and branded experience for your users.\
Note that this add-on is available only for the Enterprise plan.

<Info>
  Custom Domains add-on is only available on the Enterprise plan.
</Info>

<Info>
  Custom Domains add-on is only available on the Enterprise plan.
</Info>

#### Remove 'Powered By Chatbase'

Remove the Chatbase branding from the iframe and widget for a cleaner, custom experience.

<Info>
  Add-ons can be subscribed to on a monthly or yearly basis.  \
  \
  The billing interval must be consistent: monthly plans can only include monthly add-ons, and yearly plans can only include yearly add-ons.
</Info>

<Warning>
  Cancelling an addon will remove it immediately and credit your account for the remaining days of your billing period.
</Warning>

## Billing

This section displays your billing details, including the email addresses receiving invoice copies, the data on the invoices, the payment methods used, and all past invoices.

### Billing Details

This section displays your billing information, this information will appear on your invoices. You can edit it as needed and click "Save" to update the details.

<Frame>
  <img alt="Workspace Settings Billing Details" />
</Frame>

### Billing Email

This section shows the email address that will receive automated copies of all invoices for this workspace.

<Frame>
  <img alt="Workspace Settings Billing Email" />
</Frame>

### Tax ID

In this section, you can add a tax ID to be displayed on the invoice if needed.

<Frame>
  <img alt="Workspace Settings Billing Tax" />
</Frame>

### Billing Method

In this section, you can add payment methods and set one as your default. You can also delete payment methods, provided they are not set as the default.

<Frame>
  <img alt="Workspace Settings Billing Method" />
</Frame>

### Billing History

In this section, you can view all your past invoices along with their statuses. Click on an invoice to view it, and you'll also have the option to download it.

<Frame>
  <img alt="Workspace Settings Billing History" />
</Frame>

<Info>
  Starting the 5th of January 2026, new users (or users with only one existing plan) will receive a single consolidated invoice instead of separate invoices for each subscription.
</Info>

## API Keys

On this page, you'll find your Chatbase API keys, which allow you to interact with your agent using API calls.

***Note :*** This page is not available on all plans. If your plan doesn't include API access, you won't be able to view this page.

<Frame>
  <img alt="Workspace Settings API Keys" />
</Frame>

## Audit Logs

This section allows you to monitor activity across your workspace, including who made changes and what was modified on the dashboard.

Audit Logs provide a chronological record of configuration updates to help teams maintain visibility, accountability, and operational control.

<Info>
  Audit Logs are only available on the Enterprise plan.
</Info>

### Activity Overview

In this section, you can view all recorded workspace activity, including:

* Agent updates
* Source creation and deletion
* Action creation and deletion
* Integration creation and deletion

Each log entry displays:

* The event type (Created, Updated, Deleted)
* The object type (Agent, Source, Action, etc.)
* The object name or ID
* The user who performed the action
* The timestamp of the change

<Frame>
  <img alt="Workspace Settings API Keys" />
</Frame>

<Frame>
  <img alt="Workspace Settings API Keys" />
</Frame>

### Filters & Search

You can filter audit logs to quickly find specific changes using:

* Date range selector
* Agent filter
* Event type filter
* Search by user name or object ID

This makes it easier to investigate unexpected behavior or review activity within a specific timeframe.


# Two-factor authentication (2FA)
Source: https://chatbase.co/docs/user-guides/workspace/two-factor-auth

Secure your Chatbase workspace with two-factor authentication and backup recovery codes.

## What two-factor authentication does

Two-factor authentication (2FA) adds an extra step when you sign in or perform sensitive actions, so your account stays protected even if someone knows your password.

With 2FA enabled in Chatbase, you:

* Sign in with your email and password
* Then confirm using:
  * A 6‑digit code from an authenticator app (TOTP), or
  * A one-time recovery code as backup

<Tip>
  We strongly recommend enabling 2FA for all workspaces.
</Tip>

## Enable 2FA for your account

<Steps>
  <Step title="Open your account security settings">
    1. Sign in to the Chatbase dashboard.
    2. Click your avatar in the top-right corner.
    3. Go to **Account settings** and open the **Two-step verification** section.

    <Frame>
      <img alt="Account settings page showing the Two-step verification section in Chatbase" />
    </Frame>
  </Step>

  <Step title="Scan the QR code with your authenticator app">
    1. Select **Set up two-step verification**.
    2. Open your authenticator app (for example, Google Authenticator, 1Password, or Authy).
    3. Scan the QR code shown in Chatbase.

    <Warning>
      Anyone with access to this QR code or secret can generate valid 2FA codes for your account. Do not share it or store screenshots in insecure places.
    </Warning>

    <Frame>
      <img alt="Two-factor authentication setup dialog in Chatbase showing the QR code and secret key" />
    </Frame>
  </Step>

  <Step title="Confirm with a 6‑digit code">
    1. In Chatbase, enter the 6‑digit code from your authenticator app.
    2. Select **Confirm** to finish setup.

    <Check>
      After confirmation, you’ll be prompted for a 2FA code the next time you sign in.
    </Check>
  </Step>
</Steps>

## Recovery codes

Recovery codes let you sign in when you don’t have access to your authenticator app (for example, if you lost your phone).

Key rules:

* You see recovery codes **only once** when you generate them
* Each code is **single-use**
* Generating a new set of codes **invalidates all previous codes**

<Warning>
  Treat recovery codes like physical keys. Store them in a secure password manager or print them and keep them in a safe place.
</Warning>

### Generate and download recovery codes

1. In the Chatbase dashboard, go to **Account settings → Two-step verification**.
2. Open **Manage recovery codes**.
3. Select **Generate codes**.
4. Copy or download the codes and store them securely.

<Frame>
  <img alt="Manage recovery codes dialog in Chatbase showing a list of one-time backup codes with copy and download options" />
</Frame>

If you close the recovery codes dialog without saving, you will need to generate a new set. Old codes are invalidated when you regenerate.

## Sign in with 2FA

When 2FA is enabled, the sign-in flow looks like this:

1. Enter your email and password as usual.
2. If your account requires 2FA, Chatbase redirects you to a **Two-factor authentication** page.
3. On this page you can:
   * Enter a 6‑digit code from your authenticator app, or
   * Select **Use a recovery code** and enter one of your single‑use codes.

If the code is valid, you’re redirected back to the page you were trying to access.

<Frame>
  <img alt="Two-factor authentication challenge page in Chatbase with fields for authenticator code and a link to use a recovery code" />
</Frame>

<Note>
  If you close or navigate away from the 2FA challenge page without completing it, Chatbase signs you out to protect your session.
</Note>

## Change email or 2FA settings

Some actions in Chatbase are protected by 2FA, including:

* Changing your account email
* Managing or regenerating recovery codes
* Removing 2FA from your account

When you try one of these actions, you’ll be asked to confirm with:

* A 6‑digit authenticator code, or
* A recovery code (for most actions)

<Warning>
  If you remove 2FA, your account will fall back to password-only protection. Do this only if you have a strong, unique password and understand the risk.
</Warning>


# Usage
Source: https://chatbase.co/docs/user-guides/workspace/usage

This tab displays the usage details of all AI agents in the selected workspace. You can also filter usage data for a specific workspace. 

By default, it shows the usage for all agents under your workspace for the current month.

<Frame>
  <img alt="Usage Overview" />
</Frame>

## Configuration

### AI agents

You can view usage for all your agents, a specific agent, or deleted agents to check the credits used by removed agents.

To switch between AI agents:

<Frame>
  <img alt="Usage Agent Configuration" />
</Frame>

### Time Interval

You can configure the time interval to view usage for a specific period, such as last week. The selected time interval is highlighted in blue, as shown below.

To adjust the time interval:

<Frame>
  <img alt="Usage Date Configuration" />
</Frame>

## Usage Summary

This section shows a summary for credits used and the number of AI agents used within the time interval you specified.

### Credits Used

The section displays the number of message credits used. You can hover over the tooltip to see a detailed breakdown of the credits consumed.

<Frame>
  <img alt="Usage Credits Used" />
</Frame>

### AI agents Used

This section shows the number of AI agents in use compared to the total allowed. For example, this workspace has 4 AI agents out of a maximum of 60.

<Frame>
  <img alt="Usage Agents Used" />
</Frame>

### Usage History

The usage history displays the number of message credits used per day for the selected time interval. Hover over a specific histogram to see the exact credits used on that day.

<Frame>
  <img alt="Usage History" />
</Frame>

### Credits used per AI agent

This section compares credit usage across AI agents for the selected time interval.

Hover over any color in the pie chart to see the exact number of credits used by the AI agent assigned to that color.

<Frame>
  <img alt="Usage Credits Piechart" />
</Frame>