# 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.
# 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
# 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
# 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.
## 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.
Chat with your AI agents and handle real-time streaming responses
Create, configure, and update AI agents with custom training data
Retrieve conversations, leads, and analytics from your AI interactions
## Quick Start
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
Store your API key securely and never expose it in client-side code.
1. Select your AI Agent in the dashboard
2. Go to **Settings** → **General**
3. Copy the **Chatbot ID** (UUID format)
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?"
}
```
### Chat API Streaming
The [chat API](/api-reference/chat) supports real-time streaming responses for better user experience.
```javascript Node.js theme={null}
// streamer.js
const axios = require('axios')
const {Readable} = require('stream')
const apiKey = ''
const chatId = ''
const apiUrl = 'https://www.chatbase.co/api/v1/chat'
const messages = [{content: '', 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 = ''
chat_id = ''
messages = [
{ 'content': '', '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()
```
## Performance Best Practices
**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
## 🚀 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.
Test APIs instantly • No setup required • Real-time responses • Copy working code snippets
### Key API Endpoints
Send messages and receive AI responses with streaming support
Create, update, and configure AI agents programmatically
Access chat history and conversation analytics
Create and manage contacts for your AI agents
# 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?
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
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
### Prerequisites
A website with the Chatbase embed script already installed and working.
New to Chatbase? Check out [Your First Agent](/user-guides/quick-start/your-first-agent) to get started with the embed script first.
## Available Events
Listen for these events to monitor and respond to chat activity:
**Track conversation flow**
Triggered when a user sends a message
**Payload:** `{ data: { content: string }, type: "user-message" }`\
**Use cases:** Analytics, message validation, auto-suggestions
Triggered when your AI Agent responds
**Payload:** `{ data: { content: string }, type: "assistant-message" }`\
**Use cases:** UI updates, satisfaction surveys, follow-up actions
```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();
}
});
```
**Monitor custom actions and tools**
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
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
```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!');
}
});
```
## Basic Event Listener Usage
### Adding Event Listeners
Add event listeners using the simple syntax:
```javascript theme={null}
window.chatbase.addEventListener(eventName, callbackFunction);
```
Must be one of the event names listed in Available Event Types.
Function to be called when the event is fired. The event payload is passed as an argument.
### Removing Event Listeners
Remove listeners when they're no longer needed to prevent memory leaks:
```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);
};
}, []);
```
## Event Management Best Practices
## Troubleshooting
**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.
**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.
**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`.
## Next Steps
Create dynamic, personalized initial messages for users
Display floating messages over the chat bubble
# 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
Integrate seamlessly with your existing frontend architecture and user systems
Access user-specific information and browser APIs not available on the server
Create interactive, responsive experiences with immediate feedback and smooth workflows
Use your existing authentication, state management, and API integration patterns
## 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
A website with the Chatbase embed script already installed and working.
New to Chatbase? Check out [Your First Agent](/user-guides/quick-start/your-first-agent) to get started with the embed script first.
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-side action"** to enable client-side execution
6. Click on the **Save and Continue** button and enable the action.
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"
};
}
}
});
```
Register all your tools in a single `registerTools` call. Multiple calls will override previously registered tools.
The action names created in the dashboard must exactly match the function names you register with `registerTools`.
## Function Parameters
Every client-side action function receives two parameters:
Contains all the parameters defined in your custom action configuration. The structure matches exactly what you defined in the dashboard.
Contains user information that varies depending on your identity verification setup.
Unique identifier for the authenticated user as provided during the identify call.
Hash of the user\_id used for verification (generated server-side).
Internal anonymous user identifier. You can ignore this field.
Internal Chatbase anonymous identifier. You can ignore this field.
Custom user data passed during the identify call (e.g., name, email, company). This field is only present if metadata was provided during identification.
Internal anonymous user identifier. You can ignore this field.
Internal Chatbase anonymous identifier. You can ignore this field.
Custom user data passed during any identify calls. This field is only present if metadata was provided during identification.
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.
## Response Format
Your action functions must return responses in a specific format:
When your action succeeds, return both `status` and `data`:
```javascript theme={null}
{
status: "success",
data: responseData // Can be string, object, array, etc.
}
```
**Examples:**
```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 }
]
}
```
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"
}
```
## Advanced Examples
This example shows client-side actions utilizing the browser geolocation API to get the user's zip code.
```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"
};
}
}
});
```
## Best Practices
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."
};
}
}
});
```
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" };
}
}
});
```
* 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 };
}
});
```
**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](/developer-guides/javascript-embed) in your website and test the action.
**Response Size Limits:** Keep your response data under reasonable size limits to ensure good performance. Very large responses may be truncated or cause timeouts.
## Troubleshooting
**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
**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
**Problem:** User parameter is null when expected
**Solutions:**
* Verify [identity verification](/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
## Next Steps
Add interactive forms and data collection to your chat
Programmatically control the chat interface
Learn to listen for and respond to chat events in real-time
Create dynamic, personalized initial messages for users
# 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.
Server-side custom form configuration is not currently available. All custom forms must be configured using client-side JavaScript.
### 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
A website with the Chatbase embed script already installed and working.
New to Chatbase? Check out [Your First Agent](/user-guides/quick-start/your-first-agent) to get started with the embed script first.
## Setup Guide
Set up the form configuration in your Chatbase dashboard:
1. Navigate to **Actions** → **Create action** → **Custom form**
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.
**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](/developer-guides/javascript-embed) in your website and test the action.
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.
Register the form in a root page of your website, or in a component that is loaded on every page.
```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."
};
}
});
```
**Multiple Registration Override**: Calling `registerFormSchema` multiple times will completely replace all previously registered forms. Always include all your forms in a single registration call.
Your custom form is now ready to use! The chatbot will automatically display your form when the corresponding action is triggered.
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).
## Function Parameters
Each custom form function receives two parameters that provide context and data:
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.
Contains user information that varies depending on your identity verification setup.
Unique identifier for the authenticated user as provided during the identify call.
Hash of the user\_id used for verification (generated server-side).
Internal anonymous user identifier. You can ignore this field.
Internal Chatbase anonymous identifier. You can ignore this field.
Custom user data passed during the identify call (e.g., name, email, company). This field is only present if metadata was provided during identification.
Internal anonymous user identifier. You can ignore this field.
Internal Chatbase anonymous identifier. You can ignore this field.
Custom user data passed during any identify calls. This field is only present if metadata was provided during identification.
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.
## Complete Example
Here's a comprehensive example showing a user profile form with various field types and validation rules:
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.
```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."
};
}
});
```
## API Reference
### Form Schema
The `registerFormSchema` function returns a schema object that defines your form's structure and behavior:
Array of form field definitions. Each field must conform to the Field Schema specifications below.
Text displayed on the form's submit button.
Controls whether field labels are displayed above form inputs.
Message shown to users when the form is successfully submitted.
Message displayed when form submission fails.
### Field Schema
Each field in the `fields` array supports the following properties:
Unique identifier for the form field. This name is used to reference the field's value in form submissions.
Specifies the input type. Must be one of the supported field types listed below.
Display text shown to users for this field.
Placeholder text displayed inside the input field. If not provided, the label text is used as placeholder.
Pre-filled value for the field. Type depends on the field type (string for text, number for numeric fields, etc.).
Whether the field should be read-only and non-interactive.
Validation rules for the field. See Validation Rules section below for detailed specifications.
Required for selection fields (`select`, `multiselect`, `groupselect`, `groupmultiselect`).
**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" }
]
}
```
### Field Types
**`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
**`number`** - Numeric input
* Supports: `required`, `min`, `max` validation
* Only accepts numeric values
* Best for: Ages, quantities, prices
**`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
**`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
### Validation Rules
Each validation rule is defined as an object with `value` and `message` properties:
**`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"
}
}
```
**`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"
}
}
```
**`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"
}
}
```
**`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.
## Advanced Configuration
### Webhooks Integration
Configure webhooks to receive real-time notifications when users submit your custom forms:
* In the action settings, click on the **Webhooks** tab.
* Write the webhook URL and click on the **Create Wbhook** button.
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 });
});
```
## Troubleshooting
**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
**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
**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
**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
## Next Steps
Programmatically control the chat interface
Learn to listen for and respond to chat events in real-time
Create dynamic, personalized initial messages for users
Display floating messages over the chat bubble
# Widget Control
Source: https://chatbase.co/docs/developer-guides/control-widget
Programmatically control your chat widget with simple JavaScript methods.
The Chatbase JavaScript embed script provides simple methods to control your chat widget's visibility programmatically. This gives you control over when users can interact with your AI Agent.
## Available Widget Controls
### Open & Close Widget
Control the chat widget's visibility state with two simple methods:
```javascript Basic Usage theme={null}
// Open the chat widget
window.chatbase.open();
// Close the chat widget
window.chatbase.close();
```
```javascript With User Interactions theme={null}
// Open chat when user clicks a custom button
document.getElementById('help-button').addEventListener('click', () => {
window.chatbase.open();
});
// Close chat after user completes an action
function handleFormSubmission() {
// Your form logic here
// Close chat after successful submission
window.chatbase.close();
}
// Auto-open chat for new users after delay
setTimeout(() => {
if (isFirstTimeUser()) {
window.chatbase.open();
}
}, 5000);
```
## Common Use Cases
Open the chat widget based on user's current location or action:
```javascript theme={null}
// Open chat when user visits pricing page
if (window.location.pathname.includes('/pricing')) {
window.chatbase.open();
}
// Open chat when user encounters an error
function handleError(errorType) {
// Log the error for your records
console.log(`User encountered error: ${errorType}`);
// Open chat to provide immediate help
window.chatbase.open();
}
// Open chat for specific page sections
document.querySelectorAll('.complex-feature').forEach(element => {
element.addEventListener('mouseenter', () => {
// Open chat when user hovers over complex features
window.chatbase.open();
});
});
```
Guide new users through your application:
```javascript theme={null}
// Step-by-step onboarding with chat
const onboardingSteps = [
'#create-account',
'#first-project',
'#completed-setup'
];
onboardingSteps.forEach(selector => {
const element = document.querySelector(selector);
if (element) {
element.addEventListener('click', () => {
window.chatbase.open();
});
}
});
// Open chat for new users after they complete their profile
function handleProfileCompletion() {
// Your profile completion logic
// Open chat to offer additional help
window.chatbase.open();
}
```
## Best Practices
* **Debounce calls**: Avoid rapid open/close calls that can cause UI glitches
* **Contextual timing**: Open chat at relevant moments, not randomly
* **Respect user preference**: Remember if user has dismissed chat recently
* **Keyboard navigation**: Provide keyboard shortcuts for chat control
* **Respectful timing**: Don't interrupt user workflows
## Next Steps
Learn to listen for and respond to chat events in real-time
Create dynamic, personalized initial messages for users
Display floating messages over the chat bubble
# 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.
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.
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.
3. **Locate the Domain Customization Option**\
In the bottom left corner of the settings tab, look for "Custom Domain" and click on it.
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
A website with the Chatbase embed script already installed and working.
New to Chatbase? Check out [Your First Agent](/user-guides/quick-start/your-first-agent) to get started with the embed script first.
## 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?"
]);
```
### 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:
Array containing the messages to display in sequence
**Requirements:**
* Must be an array of strings
* Total character count limited to 1000 characters
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.
## Best Practices
**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
**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
**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
# 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
A website with the Chatbase embed script already installed and working.
New to Chatbase? Check out [Your First Agent](/user-guides/quick-start/your-first-agent) to get started with the embed script first.
## 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
};
```
## Configuration Reference
### chatbaseConfig Properties
Configure floating initial messages using these parameters in your `chatbaseConfig` object:
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
Delay in seconds before displaying floating initial messages
**Requirements:**
* Minimum value: 0 (immediate display)
* Maximum recommended: 10 seconds
Floating initial messages are displayed only once per user session to maintain a non-intrusive experience. They won't reappear if users refresh the page or navigate to other pages during the same session.
## Best Practices
**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
**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
# 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`.
## 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.
Remember to replace `{agentId}` with your actual Chatbase Agent ID. You can
find this ID in your Chatbase dashboard settings.
## Implementation Examples
Choose the tab below that corresponds to your website's framework or hosting platform.
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 second rule is needed to correctly proxy asset requests
// like CSS, JS, and images from your help center.
{
source: "/help/:path*",
destination: "https://chatbase.co/{agentId}/help/:path*",
},
];
},
};
module.exports = nextConfig;
```
After adding this configuration, restart your Next.js development server to apply the changes.
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*"
}
]
}
```
Vercel will automatically apply these rules on your next deployment.
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
```
Commit and push this file to your repository, and Netlify will apply the rule on the next build.
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}";
const chatbaseProxy = createProxyMiddleware({
target: `https://chatbase.co`,
changeOrigin: true,
pathRewrite: {
[`^/help`]: `/${AGENT_ID}/help`,
},
// Optional: Add a timeout for the proxy request
proxyTimeout: 5000,
});
// Apply the proxy to your desired route
app.use("/help", chatbaseProxy);
// Your other routes...
app.get("/", (req, res) => {
res.send("Your ACME Inc. Homepage");
});
app.listen(PORT, () => {
console.log(`Server listening on port ${PORT}`);
});
```
**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.
# 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
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
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](/user-guides/chatbot/actions/stripe-action).
These actions work by matching the authenticated user's ID with a Contact record that contains their detailed information.
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.
## Implementation Guide
### Prerequisites
A website with the Chatbase embed script already installed and working.
New to Chatbase? Check out [Your First Agent](/user-guides/quick-start/your-first-agent) to get started with the embed script first.
### Get Your Secret Key
Navigate to your Chatbase Dashboard to get your verification secret:
Go to [Chatbase Dashboard](https://www.chatbase.co/dashboard) and select your AI Agent.
Navigate to **Deploy** → click on Manage on **Chat widget** → **Embed** tab.
Copy the verification secret key shown in the embed code section.
## 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.
The only required field in the JWT payload is `user_id`. All other fields are optional.
```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}
'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')
```
#### Identifying the User
Once you have the signed JWT on your frontend, you can identify the user to your AI Agent in two ways:
**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.
**Set end user identity before the Chatbase script loads**
```html theme={null}
```
Attributes passed outside of the JWT are visible to the chatbot. To protect user privacy, never include sensitive information outside of the token.
#### 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:
```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}
'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
```
### 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)
Using user hash is not recommended as JWT offers better security and lessens the need to update contacts via API
### Generate End User Hash on Your Server
**Security Critical:** End user hashes must be generated on your server, never in client-side JavaScript, to keep your secret key secure.
```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
hash = hmac.new(secret.encode('utf-8'), user_id.encode('utf-8'), hashlib.sha256).hexdigest()
```
```php PHP theme={null}
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)
```
### 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:
**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"
}
});
```
**Set end user identity before the Chatbase script loads**
```html theme={null}
```
## Identity Parameters
Unique identifier for the user from your authentication system. This tells your AI Agent which end user is currently authenticated.
**Format:** Any string (UUID recommended)\
**Example:** `"end-user-12345"`, `"550e8400-e29b-41d4-a716-446655440000"`
To enable personalized responses and actions, create a Contact record with `external_id` matching this `user_id` using the [Contacts API](/api-reference/contacts/create-contacts-for-a-chatbot).
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..."`
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
**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](/user-guides/chatbot/contacts/contacts-overview) instead.
```javascript theme={null}
user_metadata: {
"current_session": "mobile_app",
"last_page_visited": "/dashboard",
"auth_level": "premium_user",
"session_preferences": { "theme": "dark" }
}
```
## Security & Best Practices
**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
**Use consistent, unique end user identifiers:**
✅ **Good:** UUIDs (`550e8400-e29b-41d4-a716-446655440000`)\
❌ **Avoid:** Emails or usernames that might change
**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
**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)
## Troubleshooting
**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";
```
**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](/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)
**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
**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](/developer-guides/api/contacts/custom-attributes)
## 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!
Learn how to build powerful custom actions that leverage your contact data for personalized user experiences.
### 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.
**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!
**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
Learn how to use Stripe actions to handle billing, subscriptions, and invoices.
## Next Steps
Learn how to create and manage Contact records that link to verified end users
Store additional end user data in Contact custom attributes for personalized experiences
Call backend actions from the client side
Add interactive forms and data collection to your chat
# 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
* **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
* **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
## Quick Start Guide
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
Paste the code in your website's `` section or before the closing `` tag.
Place in `` for faster loading, or before `` if you have loading performance concerns.
Visit your website and look for the chat bubble. Click it to test!
Your AI Agent should respond based on your training data.
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
});
```
## JavaScript Embed Core Features
**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 →](/developer-guides/identity-verification)
**React to chat events in real-time**
Listen for and respond to:
* User messages and AI responses
* Actions calls and results
[Event Listeners Documentation →](/developer-guides/chatbot-event-listeners)
**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 →](/developer-guides/control-widget)
**Create interactive experiences**
Build custom:
* Action buttons that trigger your backend
* Forms for lead capture
[Custom Actions Guide →](/developer-guides/client-side-custom-actions)
[Client-Side Custom Forms Guide →](/developer-guides/client-side-custom-forms)
## Best Practices
### Performance Optimization
**Load the embed script asynchronously** to avoid blocking your page load. The provided embed code already handles this automatically.
```html theme={null}
```
### User Experience
* 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
* The widget includes ARIA labels and keyboard navigation
* Ensure sufficient color contrast in custom styling
* Test with screen readers for accessibility compliance
* Pass relevant page/user context to provide better responses
* Use identity verification for personalized experiences
* Clear chat context when users navigate to different sections
### Security Considerations
**Never expose sensitive data** through the embed script. Use [identity verification](/developer-guides/identity-verification) instead of passing raw user data.
## Troubleshooting
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
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
## What's Next?
Secure your chatbot for authenticated users
Integrate Chatbase with your existing backend
Call backend actions from the client side
Add interactive forms and data collection to your chat
# 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.
## Choose Your Integration Path
Perfect for web developers who want to add a chat widget with custom behavior, event handling, and rich user experiences.
Ideal for backend developers building custom chat interfaces, mobile apps, or server-to-server integrations.
## 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.
Get the full implementation guide with examples, advanced features, and best practices →
## 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
Get the full API documentation with examples, authentication, and best practices →
## Common Integration Patterns
**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
**Help users succeed with your product**
* **Embed Script**: Contextual help widget
* **Event Listeners**: Track user interactions
* **Custom Actions**: Feature tutorials, account management
**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
# 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')
}
```
# 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
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.
You can have a fully functional AI Agent live on your website in **under 5 minutes**!
Our [Quick Start guide](/user-guides/quick-start/your-first-agent) walks you through each step.
**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](/api-reference/chat/chat-with-a-chatbot) for custom integrations.
## Features & Capabilities
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.
You can train your AI Agent with various data sources:
**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
**Upload files directly**
* **Supported formats:** PDF, DOC, DOCX, TXT
* **Use cases:** Manuals, FAQs, product docs, policies
**Direct text input**
* Paste content directly into the platform
* Ideal for structured information
**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
**Connect your Notion workspace**
* Sync with your existing knowledge base
* Automatic updates when Notion content changes
* Perfect for workspaces already using Notion
## Pricing & Credits
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:**
* **DeepSeek-R1:** 2 credits ⚡ (Fast & efficient)
* **GPT-4 Turbo:** 10 credits ⚖️ (Balanced performance)
* **GPT-4 & Claude 3 Opus:** 20 credits 🏆 (Premium quality)
* **GPT-4.5:** 30 credits 🚀 (Cutting-edge performance)
* **All other models**: 1 credit 💰 (Most economical)
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.
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**.
**Yes!** You can change your plan anytime:
## Technical Questions
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.
When uploading training data, Chatbase automatically displays the character count.
**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](/developer-guides/custom-domains) guide for more information.
You'll need to configure DNS records to point your domain to Chatbase servers.
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](/user-guides/integrations/webflow) section for setup guides.
## Troubleshooting
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
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 set to "Public"
* Confirm the agent ID matches your AI Agent
**2. Check website integration:**
* Script should be in `` or before closing `` 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.
## Still Need Help?
Can't find the answer you're looking for? We're here to help!
Get personalized help from our support team
# 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.
**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.
Before using Stripe actions, you must first integrate your Stripe account with Chatbase. [Learn how to set up the Stripe integration](/user-guides/integrations/stripe).
**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
***
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"
**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.
### 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."
# 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.
Once connected go to the Actions tab and select the "Calendly Get Slots" Action.
Next select the Event from the dropdown that you want your Agent to use for bookings.
### 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.
### 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."
# 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.
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.
**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.
After you're done editing, you can preview all your settings in the AI agent found on the Action page.
Finally, press enable and your form will be live ready for your agent to serve to users.
# 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.
### 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.
* 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.
* 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.
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 common formats should include JSON.
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.
> **Note:** The maximum response size is 20KB. Anything exceeding that will return an error.
## 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.
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'.
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.
In the Test Response section, we tested the response of the API when we provided active and premium as a subscription upgrade example.
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.
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.
### 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.
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.
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.
In the Test Response section, we tested the response of the API when we provided London as a city example.
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.
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.
# 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:
This field is only showing the name of the action in the dashboard.
Next scroll donw and select the Custom Button.
Now give your Custom Button an Action name.
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.
Button text: This is the text shown on the button provided to the users once asked about a specific topic.
* URL:
This is where to add the URL that the button should route the users to.
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."
# 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:
2. Choose the Slack workspace that you want to be connected with this Action:
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.
4. Click on Save button.
5. Make sure to enable this action to allow us to send a message to your Slack channel.
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"
Once the user mentioned the professional plan, a Slack notification is sent to the channel connected to this action:
# 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.
**Prerequisites Required**: Before using Stripe Actions, you must:
1. [Set up Stripe integration](/user-guides/integrations/stripe) with your Chatbase account
2. Configure [identity verification](/developer-guides/identity-verification) for secure customer authentication
3. Set up [contacts](/user-guides/chatbot/contacts/contacts-overview) with valid `stripe_account` fields for each customer
## 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
**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](/developer-guides/javascript-embed) in your website and test the action.
## Available Stripe Actions
### 1. Get Subscription Information
Retrieve and display customer subscription details including current plan, status, billing cycle, and pricing information.
Answering questions about current subscription status, plan details, renewal dates, and subscription history.
**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
Navigate to **Actions** → **Create Action** and select **Stripe Get Subscription Info**.
**Action Name:** Enter a unique name for the action.
**When to use:** Provide detailed instructions for when the AI should use this action.
Click **Save** and toggle the action to **Enabled** to make it available to your AI agent.
Test the action in the embedded widget to ensure it correctly retrieves subscription data for authenticated users.
### 2. Get Invoice History
Retrieve and display customer invoice history, payment details, and billing records.
Providing access to billing history, payment confirmations, invoice downloads, and payment troubleshooting.
**Common Use Cases:**
* "Show me my recent invoices"
* "Was my payment processed?"
* "Can you provide my billing history?"
#### Setup Instructions
Select **Stripe Get Invoices** from the action creation dialog.
**Action Name:** Enter a unique name for the action.
**When to use:** Provide detailed instructions for when the AI should use this action.
Save the configuration and test with a sample customer request in the embedded widget.
### 3. Manage Subscriptions
Comprehensive subscription management including plan changes, upgrades, downgrades, and cancellations.
Complete subscription lifecycle management, plan changes, adding payment methods and cancellation handling.
**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
Select **Stripe** → **Manage Subscriptions** from the Stripe action options.
**Action Name:** Enter a unique name for the action.
**When to use:** Provide detailed instructions for when the AI should use this action.
Configure which subscription plans and options are available for customers to choose from:
Set up available plans with their behavior.
Configure cancellation policies and refund handling.
Thoroughly test various subscription management scenarios:
Test upgrading from basic to premium plans with proper proration calculations.
Verify downgrades work correctly with appropriate billing adjustments.
Test the complete cancellation process.
All subscription changes should be immediately reflected in both Stripe and the customer experience.
### 4. Change Billing Information
Allow customers to update their billing address and other account information.
Self-service billing updates, address changes and other account information updates.
**Common Use Cases:**
* "I need to update my billing address"
* "Update my billing email address"
* "Update my billing phone number"
#### Setup Instructions
Select **Stripe** → **Change customer information** from the available Stripe actions.
**Action Name:** Enter a unique name for the action.
**When to use:**
Provide detailed instructions for when the AI should use this action.
Test the action with various scenarios to ensure only authenticated users can make changes.
Verify that billing information updates are reflected in both Stripe and the customer's account.
## Troubleshooting
**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
**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
**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
## Best Practices
Always validate user identity before processing any billing-related requests. Never allow unauthenticated access to financial data.
Thoroughly test all actions with various user scenarios, edge cases, and error conditions before going live.
# 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.
#### 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.
#### Include images
This allows the AI agent to provide images as replies to the users elaborating the answer provided.
#### 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.
# 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.
The chat logs can be filtered by the following:
* Date
* Confidence Score
* Source
* Feedback
* Sentiment
* Topic
**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.
### 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.
## 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.
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.
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.
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.
## Topics
This section shows the topics that were included in the conversations and mentioned by the users.
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:
## 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.
## 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.
Unlike anonymous visitors, contacts represent users who are authenticated and identified within your business system.
### The identification process
Upload user data to Chatbase using the [Contacts API](/api-reference/contacts/create-contacts-for-a-chatbot) or manage them through the dashboard.
**Recommended:** Use [JWT identity verification](/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.
When users interact with your agent, use [identity verification](/developer-guides/identity-verification) to securely link them to their contact data.
The `user_id` from your verification must match the `external_id` of a contact for the data to be accessible.
Once linked, your agent can access contact data to provide personalized responses and perform actions on behalf of the user.
## Key benefits
User data is encrypted and access-controlled, ensuring privacy and compliance.
Agents can reference user-specific information to provide tailored responses.
Contact data powers actions, enabling agents to perform user-specific operations such as [Stripe actions](/user-guides/chatbot/actions/stripe-action).
Keep Chatbase contacts in sync with your external systems and databases.
## Next steps
Learn how to get started with contacts.
Implement secure user identification to link sessions with contact data.
# Getting Started
Source: https://chatbase.co/docs/user-guides/chatbot/contacts/getting-started
Learn how to get started with the Contacts API
### Prerequisites
* An active Chatbase subscription
* End user data ready for upload
* Access to implement end user identification on your website
Use the [Contacts API](/developer-guides/api/contacts/add-contacts-to-chatbase) endpoint to upload your end user data,
and assign an `external_id` to each contact. This `external_id` should be used
to identify the end user in future conversations.
This `external_id` should match the `user_id`
you use in your end user identification step. Also,
the data associated with the `external_id` will not
be used if the user\_hash verification fails. So you don't
need to worry about data privacy.
Create custom actions from the dashboard that utilize contact data by referencing fields under the `contact.` key:
Add the identification script to your website and use one of our end user identification methods.
For end user verification implementation details, see our [Identity Verification Guide](/developer-guides/identity-verification).
## Security Considerations
* End user data is only accessible through custom actions that explicitly reference contact fields
* End user verification is required to access contact data
## Best Practices
1. **Data Minimization:** Only upload necessary end user data that will be used in AI Agent interactions
2. **Regular Updates:** Keep contact data current by updating it when end user information changes
3. **Error Handling:** Implement proper error handling for cases where contact data might be unavailable
4. **Testing:** Thoroughly test custom actions that use contact data before deploying to production
## Implementation Details
For more details on the Contacts API, see the [Contacts API](/api-reference/contacts/create-contacts-for-a-chatbot) guide.
# 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.
### GPT-4o Mini
GPT-4o Mini is a lightweight, high-speed version of GPT-4o, designed for rapid, cost-effective customer support interactions while retaining strong multilingual and multimodal capabilities.
**Best Suited For:**
* Fast, high-volume customer support scenarios
* Multilingual and image-based support inquiries
* Scalable deployments where speed and efficiency are critical
* Real-time troubleshooting and quick response needs
**Note:** GPT-4o Mini offers a balance of speed and capability, making it ideal for workspaces needing responsive support without sacrificing quality.
### GPT-4o
GPT-4o (GPT-4 Omni) is an advanced, multimodal model optimized for versatility and accuracy across text, images, and languages.
**Best Suited For:**
* Excellent multilingual support with strong empathetic communication
* Complex troubleshooting involving text and visual inputs
* Fast responses in high-volume, enterprise-level customer support
* Multi-step problem-solving with strong reasoning
### Claude Opus 4.1
Claude Opus 4.1 is Anthropic's latest flagship model, offering enhanced reasoning capabilities and improved performance across complex tasks.
**Best Suited For:**
* Advanced reasoning and analytical support scenarios
* Complex troubleshooting requiring deep understanding
* High-stakes customer support where accuracy and reliability are critical
* Enterprise environments needing sophisticated problem-solving capabilities
**Note:** Claude Opus 4.1 represents the cutting edge in AI reasoning, making it ideal for premium support scenarios where quality is paramount.
### Claude 3.7 Sonnet
Claude 3.7 Sonnet is a model from Anthropic, renowned for its transparent reasoning and deep analytical abilities.
**Best Suited For:**
* Premium support scenarios requiring clear, empathetic, and detailed explanations
* Complex, multi-step technical troubleshooting
* High-quality interactions needing detailed context and reasoning transparency
* Deep domain expertise in enterprise environments
### Claude 3.5 Sonnet
Claude 3.5 Sonnet uniquely combines strong reasoning with rich output capabilities, including visualizations and interactive content.
**Best Suited For:**
* Support interactions enhanced by visual aids or formatted outputs
* Communicating empathetically with enriched user experiences
* Handling multi-step scenarios where detailed, interactive explanations are beneficial
* Efficient performance balanced with sophisticated output
### Grok 4
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
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
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
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
### O3 Mini
**Best Suited For:**
* Rapid, structured technical support and logical troubleshooting
* Scenarios requiring precise adherence to guidelines
**Note:** Benefits from additional prompting to enhance empathetic interactions.
### GPT-4.5
**Best Suited For:**
* Highly specialized, knowledge-intensive scenarios
* Situations needing deep context analysis
**Note:** More resource-intensive; best for specific, detailed interactions.
### Gemini 2.0 Flash
**Best Suited For:**
* Real-time interactive customer engagements
* Multi-step workflows and conversational experiences
* Voice-based support requiring immediate response
**Note:** Ideal for dynamic, fast-paced customer interactions.
### Gemini 2.0 Pro
**Best Suited For:**
* Premium, highly accurate support scenarios
* Regulated industries requiring precise analysis
**Note:** Recommended when accuracy is critical in complex scenarios.
### Command R+
**Best Suited For:**
* Integrating external knowledge bases and taking actions for customers
* Multi-step troubleshooting and complex support interactions
**Note:** Excels at structured, action-oriented customer support.
### Command R
**Best Suited For:**
* Handling high-volume FAQs and scripted troubleshooting
* Cost-effective support agents integrated with knowledge bases
**Note:** Reliable for quickly addressing common inquiries.
### DeepSeek-V3
**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
**Best Suited For:**
* Accurate interactions using detailed documentation
* Conversational search and nuanced, documentation-driven support
**Note:** Strong performance in precise, documentation-based interactions.
## Legacy Models (Not Recommended for New Agents)
* **GPT-4:** Superseded by GPT-4o's enhanced multilingual and multimodal capabilities.
* **GPT-4 Turbo:** Lacks newer model enhancements.
* **Claude 3 Opus:** Replaced by Claude 3.7 Sonnet's superior transparency.
* **Claude 3 Haiku:** Limited in advanced features and complex scenario handling.
* **Gemini 1.5 Pro:** Outperformed by Gemini 2.0's superior reasoning and performance.
# 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.
### 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.
* **GPT-5**: 1 message credits
* **GPT-5 Mini**: 1 message credits
* **GPT-5 Nano**: 1 message credits
* **GPT-OSS-120B**: 1 message credits
* **GPT-OSS-20B**: 1 message credits
* **GPT-4**: 20 message credits
* **GPT-4 Turbo**: 10 message credits
* **GPT-4.5**: 30 message credits
* **GPT-4o**: 1 message credit
* **GPT-4o Mini**: 1 message credit
* **o3**: 10 message credits
* **o3 Mini**: 1 message credit
* **o4 Mini**: 2 message credits
* **GPT-4.1**: 1 message credit
* **GPT-4.1 Mini**: 1 message credit
* **GPT-4.1 Nano**: 1 message credit
* **Claude 4.1 Opus**: 20 message credits
* **Claude 4 Sonnet**: 1 message credit
* **Claude 4 Opus**: 20 message credits
* **Claude 3 Opus**: 20 message credits
* **Claude 3.7 Sonnet**: 1 message credit
* **Claude 3.5 Sonnet**: 1 message credit
* **Claude 3 Haiku**: 1 message credit
* **Gemini 2.0 Pro**: 1 message credit
* **Gemini 2.0 Flash**: 1 message credit
* **Gemini 2.5 Flash**: 1 message credit
* **Gemini 1.5 Pro**: 1 message credit
* **Gemini 1.5 Flash**: 1 message credit
* **Command R**: 1 message credit
* **Command R+**: 1 message credit
* **Command A**: 1 message credit
* **Llama 4 Scout**: 1 message credit
* **Llama 4 Maverick**: 1 message credit
* **DeepSeek-V3**: 1 message credit
* **DeepSeek-R1**: 2 message credits
* **Grok 4**: 10 message credit
* **Grok 3**: 1 message credit
* **Grok 3 mini**: 2 message credits
* **KimiK2**: 1 message credit
## Side bar
### Temperature
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
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.
### 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.
Test your AI Actions thoroughly with various user inputs to ensure they activate at the right moments and provide the expected functionality.
For complete setup instructions and configuration details, see our [Actions Overview guide](/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
Start with a simple, clear description of your agent's purpose, then gradually add specific instructions based on user feedback and common queries.
## Compare Area
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.
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.
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.
5. To change which AI models you are testing, click the filter icon and select a new model from the dropdown.
> **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.
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.
***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.
## 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.
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.
### 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)
#### 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 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
```
### 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.
```
```
### 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.
```
```
### 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.”
```
### 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.
## Chat Interface
This section allows you to adjust the chat interface, where the bubble should appear, the welcome message, and chat icon.
* 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](/developer-guides/custom-initial-messages)
* Suggested messages: The messages that the users can use when contacting the AI agent. This should be the most frequently asked questions by the users.
### Content
* Text 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.
* Regenerate messages: Display a regenerate response button on AI agent messages.
* Footer: Text shown in the button of the chat. You can use this to add a disclaimer or a link to your privacy policy.
* Theme: Light or Dark
### Style
* Display Name: The name of the AI agent appearing to users.
* Profile picture: Picture of the AI agent when providing answers.
* Chat Icon: The icon appearing on the website to display the AI agent.
* User message color.
* Align Chat Bubble Button: Left or Right
* Auto show initial messages pop-ups after: You can set it to negative to disable.
## Security
Here you can change the Visibility settings of your Agent from "private" meaning no one can access your agent except you (your account) or 'public' meaning other people can chat with your agent if you send them the link.
You can also embed it on your website so your website visitors are able to use it.
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 displat 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
## Webhooks
On this page, you can configure a webhook to trigger based on a selected action.
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.
# Sources
Source: https://chatbase.co/docs/user-guides/chatbot/sources
The 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, and integrate with Notion. 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.
## Files
The Files tab within the 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.
### 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.
### 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.
## Text Snippets
The 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.
### 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 sources’ 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 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.
### 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.
### Grouping and Link Management
Once crawling is complete:
* All links from a single domain are grouped under the homepage URL for easy management.
* Click on a homepage group to view all fetched links.
* You can preview the content of each link by clicking on it.
### Editing and Excluding Links
After crawling:
* You can edit the URL of any fetched link.
* You can also exclude specific links from a group if you don't want them used in training.
- You can edit include/exclude paths anytime, recrawl the website, and update your AI agent accordingly.
### 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 checkbox next to 'Link sources'.
## Custom Q\&A Training
The Q\&A Sources 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.
### 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
### 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.
### 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.
## General Notes
* Each AI agent cannot be trained on more than 33 MB.
* 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.
# Bubble
Source: https://chatbase.co/docs/user-guides/integrations/bubble
## Step 1: Set Up Your Chatbase Chatbot
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](/user-guides/quick-start/your-first-agent).
## Step 2: Generate and Copy Your Chatbase Chatbot 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.
2\. Clicking on the bot should take you to the bot's playground page. From there, proceed to the **Connect** tab.
3\. Up next, a new page should come up, click on **Copy Script** to copy the code snippet.
## Step 3: Embed Chatbase Chatbot 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.
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.
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.
7\. You can now preview your Bubble app to test your agent.
**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.
# 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.
2\. On the list of available agents, click on the one you want to integrate into your Framer website.
3\. Once you've clicked on your chosen agent, you'll be directed to the AI Playground page.
4\. On the page, locate and click on the **Connect** tab at the top of the page.
5\. On the connect tab, click on **Copy Script** to copy the embed code.
## 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
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.
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 \ tag"* and click **Save** on the top right corner of the panel.
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)
**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.
# 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.
## Perquisites
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 a agent.
3\. Navigate to **Connect** > **Integrations**.
4\. Click on **Connect** then **I understand**.
5\. Click on **Continue.**
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.
7\. Login to instagram.
8\. Choose the businesses affiliated with you Instagram page. If you have no business select **Opt in all current future businesses.**
9\. Choose the Facebook Page(s) linked to your Instagram.
10\. Select the Instagram page(s) you want to integrate.
11\. Click save.
12\. Your pages should be integrated successfully to see the pages integrated click on **Manage.**
13\. You can add more pages or delete existing ones from the manage page.
## The 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 Instagram dashboard.
#### to 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 Instagram chats.
3\. Click the human takeover icon.
5\. You can click the icon again to restore access to the agent.
## 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 **Activity > Integrations > 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 a 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.
Now this brings an end to the Messenger integration guide, for any further questions please do not hesitate to [contact us](https://www.chatbase.co/help).
# 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.
## Connecting to messenger
1\. First navigate to your dashboard, and pick a agent.
2\. Navigate to **connect** > **Integrations**
3\. Click on Connect 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.
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.
6\. Review the permissions and click save.
7\. click on **done** and wait for the integration to connect, this should take only a few seconds.
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.
## The 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.
#### to 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.
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 **Activity > Integrations > manage.**
2\. Click the **Manage** button to navigate to the dashboard. As shown in the **agent field**, all my pages are connected to the same agent. If I want to connect another agent to an already connected page, click, then simply delete the agent.
3\. Click **connect a new Facebook Page**, and make sure you are on the correct agent. Then click **edit previous settings.**
4\. A list of pages connected will be displayed, if you deleted a 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.
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.
6\. Click the save button.
7\. As shown the new page was added to the dashboard, and is now integrated with the new agent.
Now this brings an end to the Messenger integration guide, for any further questions please do not hesitate to [contact us](https://www.chatbase.co/help).
# Shopify
Source: https://chatbase.co/docs/user-guides/integrations/shopify
## Step 1: Sign Into Chatbase and Configure Your Chatbase Chatbot
To add a Chatbase agent to your Shopify website, sign into your Chatbase account to create and set up a agent. If you don't have a Chatbase account, you can start by creating one for free. If you are not sure how to create a agent, here is a [detailed guide on how to create a agent on Chatbase](/user-guides/quick-start/your-first-agent).
## Step 2: Generate and Copy the Chatbot Embed Code
To embed your agent on your Shopify site, you'll need to first generate an embed code for your agent. To do this:
1\. Head over to your [**Dashboard**](https://www.chatbase.co/dashboard/) page and click on the bot you want to embed on your Shopify website to reveal the bot's Playground page.
2\. On the playground page, click on **Connect** at the top of the page.
3\. Up next, click on **Copy Iframe** to copy the agent embed code.
## Step 3: Sign Into Your Shopify Website and Embed Your Chatbot
To add the embed code to your Shopify website:
1\. Log into your Shopify account and head to your Shopify admin page.
2\. On the left sidebar of the admin page, click on **Online Store** and then click on **Pages** to reveal the list of pages on your store website.
3\. Click on the page you wish to embed the agent. (For this example, we want to embed it in the Contact page)
4\. The page you click on should open on an HTML editor, click the source code icon on the top right corner of the editor.
5\. Paste the embed code on the code editor and click **Save** on the top right corner of the page.
6\. Click the source code icon again to return to the visual editor. A preview of your Chatbase agent should be loaded in the editor.
Your Chatbase agent has now been added to your Shopify website. You can optionally click the **View page** button on the top right corner of the page editor to see how your agent will look on your live page.
> **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.
# 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 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, [create a free Chatbase account](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:** [A step-by-step guide to creating a Chatbase agent in just a few minutes](/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.
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
4\. Up next, you'll be asked to authorize Chatbase to access your Slack account and workspace.
5\. Scroll down and click on **Allow**.
5\. If all goes well, you should get a message saying "**Chatbase has been successfully added to your workspace.**"
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.
## Step 3: Deploy Slack Bot
Once you've launched the Slack workspace that hosts your Chatbase agent, you can start setting up the agent as a Slack bot. 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.
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.
Team members can direct questions to your intelligent bot in any channel or DM that has the bot. 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 bot 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, [create a free Chatbase account](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:** [A step-by-step guide to creating a Chatbase agent in just a few minutes](/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.
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
4\. Up next, you'll be asked to authorize Chatbase to access your Stripe account.
5\. After clicking on **Continue** you will be asked to choose the account you want to connect to.
5\. If all goes well, you should be redirected back to Chatbase with a message saying "**Stripe integration successful.**"
6\. Add Stripe accounts to your customers' contacts. For more information, see [Contacts](/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
## 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.
3\. Navigate to **Actions** > **Integrations**. Click **Connect** on the Sunshine Integration card.
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.
# 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
The Chatbase integration works seamlessly with all frameworks supported by Vercel, including Next.js, React, Vue.js, SvelteKit, and static HTML sites.
## 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
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
You can also access the Chatbase integration directly at [vercel.com/integrations/chatbase](https://vercel.com/integrations/chatbase)
On the Chatbase integration page, click the **Install** button to begin the installation process.
You'll be redirected to the Chatbase configuration wizard.
### Step 2: Configure Your Chatbot
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
You can customize any preset later. This just provides a starting point for your chatbot's behavior.
* 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.
You can change both the personality, AI model, and styles anytime from your Chatbase dashboard.
### Step 3: Choose Your Subscription 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.
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
Your selected plan will only take effect after the invoice is paid. Until then, you'll have access to the free tier features.
Billing is handled securely through Vercel's payment system. You can manage your subscription from the Vercel dashboard.
### Step 4: Name Your Chatbot
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"
Choose a name that clearly describes the chatbot's purpose, especially if you plan to create multiple chatbots for different projects.
### Step 5: Customize in 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.
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
Train your chatbot with your content:
1. Navigate to the **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
The more relevant training data you provide, the better your chatbot will respond to user queries. Learn more in [Adding Sources](/user-guides/chatbot/sources).
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 →](/user-guides/chatbot/actions/actions-overview)
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 →](/user-guides/integrations/zapier)
### Step 6: Connect to Your Vercel Project
Go back to your Vercel dashboard where you initiated the Chatbase installation.
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
You can connect the same chatbot to multiple projects if needed.
Click **Connect** to finalize the connection. Vercel will automatically inject the environment variables into your selected project(s).
Your environment variables are now configured and ready to use!
### Step 7: Redeploy Your Project
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**
Environment variables are injected at **build time**, not runtime. This is why a redeployment is necessary.
### Step 8: Verify Installation
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.
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
If the chatbot responds appropriately to your test questions, your integration is successful!
## 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
Only environment variable changes require redeployment. All chatbot configuration changes are live immediately.
## 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
This is useful if you have multiple frontends (web app, marketing site, documentation) that should use the same chatbot.
### 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.
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.
**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.
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.
**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
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.
#### Canceling Your Subscription
Select the **Free** plan and confirm your cancellation.
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.
**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
You can undo a cancellation before the period end by selecting a paid plan again from the same settings page.
## 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
Removing the integration will immediately stop the chatbot from appearing on your Vercel deployments. Make sure to redeploy after removing environment variables.
## Troubleshooting
**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
**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
**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
**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
## 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 →](/user-guides/quick-start/response-quality)
## Next Steps
Now that your Chatbase chatbot is live on Vercel, explore these features to enhance your implementation:
Upload documents, connect websites, and add Q\&A pairs
Match your brand colors and style
Add lead collection, bookings, and custom workflows
Track conversations and measure performance
Integrate with Slack, CRMs, and 5,000+ apps
Explore API, webhooks, and advanced integrations
## Additional Resources
* [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)
* [Getting Started Guide](/user-guides/quick-start/introduction)
* [Your First Agent](/user-guides/quick-start/your-first-agent)
* [Best Practices](/user-guides/quick-start/best-practices)
* [Response Quality Tips](/user-guides/quick-start/response-quality)
* [JavaScript Embed Options](/developer-guides/javascript-embed)
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
When contacting support, include your Vercel project ID and Chatbase chatbot ID for faster assistance.
# 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.
3. In the Flow editor, click on **Select Trigger**.
4. Select **Webhook** as the trigger then copy the generated Webhook URL.
### 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.
3. Click **Settings** and select **Webhooks**.
4. Select the events you want to trigger, then paste the copied Webhook URL into the **Endpoint** field, then **Create Webhook**.
### Step 3: Set Up an Action to Automate Tasks
1. Go back to the viaSocket Flow Builder and click on **Select Action**.
2. Choose the **Google Docs** action: *Append Text to Document*.
3. Establish a connection and configure your action with the required details.
### Step 4: Test and Publish the Flow
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.
New to Chatbase? Check out [Your First Agent](/user-guides/quick-start/your-first-agent) to get started with the embed script first.
## Step 2: Copy Your Chatbot 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.
3\. On the agent preview page, click on the **Connect** tab.
4\. A new page should come up. Click on **Copy Iframe** to copy the provided HTML code.
## 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**.
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.
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.
8\. Now, scroll down down the list of elements and drag the **Embed** element unto the Div you added on the Webflow canvas.
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**.
If all goes well, you should see a preview of the agent on the live preview of your Webflow website right inside the designer.
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 [step-by-step guide for setting up your Chatbase agent](/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.
2\. On the agent Playground page, click on the **Connect** tab at the top of the page.
3\. Click on **Copy Iframe** to copy the HTML code.
## 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**.
4\. Drag the **Embed Code** element to wherever you want your agent to appear on the page.
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.
7\. Click outside the element and your agent should appear on the page.
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.
## 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)
1\. Navigate to the Chatbot you would like to integrate with WhatsApp.
2\. Navigate to Dashboard > \[Chatbot] > Connect > Integrations.
3\. Click Connect on the WhatsApp integration card.
4\. Log in with your personal Facebook Account.
5\. Click **Get started**
6\. Choose or create a business profile.
7\. Create a WhatsApp business profile or select an existing one.
8\. Fill in the information for the Business profile.
9\. Add a phone number, , it is recommended to have only one associate number in this profile.
10\. Click **Continue**.
11\. Wait a few seconds for information verification.
12\. Click on **Finish**.
13\. (Optional) You can modify your WhatsApp bot styling or delete your phone number by clicking the "I" icon next to WhatsApp or by navigating to the manage WhatsApp page .
14\. (Optional) Navigate to **Profile** and update your WhatsApp settings then click the **Save** button.
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.
Congratulations! You finished integrating your Chatbase agent to WhatsApp, your agent is now ready to reply to all the messages received through your WhatsApp!
# Wix
Source: https://chatbase.co/docs/user-guides/integrations/wix
## Step 1: Set Up Your Chatbase Chatbot
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](/user-guides/quick-start/your-first-agent).
## Step 2: Generate and Copy the Chatbase Chatbot 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.
2\. On the agent preview page, locate and click on the **Connect** tab.
3\. Next, a new page will appear displaying the HTML code snippet for embedding your agent. Copy this code by clicking the "**Copy Script**" button.
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 Chatbot
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.
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.
6\. Scroll down to locate and click on **Embed Code**, followed by **Popular Embeds** and then **Custom Code**.
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.
**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 Chatbot**
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 public](/user-guides/chatbot/settings#security)**. 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](/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**.
* Click **Add New Plugin** at the top of the next page.
* 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**.
**3. Add your Chatbot 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 "Chatbot ID".
**4. Copy and paste your Chatbot ID:**
* Go to your Chatbase account and navigate to your Dashboard.
* Select the agent you want to embed.
* Click on the agent, then click on the "**Settings**" tab. At the top of the settings page, you'll find the Chatbot ID. Copy it.
* Paste the copied Chatbot ID into the text box in your WordPress settings.
**5. Save your changes:**
Click **Save Changes**. Your Chatbase agent should now be live on your WordPress website!
# 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 [step-by-step guide to building a agent with Chatbase](/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 .
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.
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.
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.
3\. On the Zap editor click on **Trigger**.
4\. On the pop-up menu, search for Chatbase on the search bar and click on it.
5\. Next, on the right side of the page, click on the form field labeled **Event** and select **Form Submission**.
6\. Click on **Continue.**
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**.
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.
***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.*
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.**
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.
2\. On the next screen, click on the input field labeled **Event**, and select **Append Text to Document** and then click **Continue.**
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**.
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 provides a quick and easy way to add an intelligent AI-powered agent to your Zendesk website.
In just a few minutes, you can make a Chatbase agent available across your company's Zendesk website. The agent will be able to respond to users' tickets and help the workspace provide round-the-clock automated support.
## Setup Guide
Here's how to integrate a Chatbase agent into your Zendesk website:
### 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, [create a Chatbase account](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:** [A step-by-step guide to creating a Chatbase agent in just a few minutes](/user-guides/quick-start/your-first-agent).
### Step 2: Connect the Zendesk 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 Zendesk.
2\. Click on the **Integrations** tab.
3\. Find the **Zendesk** integration and click on **Connect**.
4\. 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.
### 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.
Select the following options:
* The Zendesk agent that the bot will reply as.
* Determine if tickets should be automatically assigned to the agent.
And then click on **Save**.
3\. The AI Configuration page will pop up. If you click on **Go To AI Settings**, you'll be redirected to the AI Settings page, there you can choose a **different AI Model** or **change the instructions** for the agent.
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)
## 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.
# Best Practices
Source: https://chatbase.co/docs/user-guides/quick-start/best-practices
This page 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.
```
### 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.
```
You can find more detailed information about refining your instruction [here](/user-guides/chatbot/settings#instructions).
## Improve Readability of 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.
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.
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!
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.
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!
> **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:
## 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 
```
Once added, every agent response will display the image, as illustrated in the screenshot below:
## 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 [Sources](https://www.chatbase.co/docs/user-guides/ai-agent/sources).
# 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.
## Why Choose Chatbase?
Train your AI Agent with your own documents, websites, or databases for accurate, relevant responses
Embed anywhere with simple copy-paste code - no technical expertise required
Pre-built actions for Slack, Stripe, Calendly, lead collection, and web search - Plus custom actions for any API integration
Track conversations, monitor performance, and continuously improve your AI Agent
Capture and manage leads automatically through intelligent conversations
Experience our lush integrations across 15+ platforms including WordPress, Shopify, WhatsApp, Slack, Zendesk, and more.
Let's build your first AI agent! The entire process takes less than 10 minutes.
# 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.
![[object Object]](https://www.chatbase.co/_next/image?url=https%3A%2F%2Fcdn.sanity.io%2Fimages%2Fi6kpkyc7%2Fprod-dataset%2F06ebe2568a4065eb18ad9bc261fdcb06a3f7127b-1590x534.webp&w=3840&q=75&dpl=dpl_GXfa6D8Kjn4Aa4uEdVi6Kg5JjumG)
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.
![[object Object]](https://www.chatbase.co/_next/image?url=https%3A%2F%2Fcdn.sanity.io%2Fimages%2Fi6kpkyc7%2Fprod-dataset%2F62adf4a64d125990bc3d3e4b98532a79c825ec78-1459x541.png&w=3840&q=75&dpl=dpl_GXfa6D8Kjn4Aa4uEdVi6Kg5JjumG)
## 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:
![[object Object]](https://www.chatbase.co/_next/image?url=https%3A%2F%2Fcdn.sanity.io%2Fimages%2Fi6kpkyc7%2Fprod-dataset%2Fb721647921ca64a7a4b250965dd3fc081be97b00-1610x1050.webp&w=3840&q=75&dpl=dpl_GXfa6D8Kjn4Aa4uEdVi6Kg5JjumG)
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
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.
## Overview
Here's what we'll accomplish in this guide:
Set up a new AI Agent and train it using your website or documents
Use the Playground to test responses and fine-tune performance using the Compare feature
Add your AI Agent to your website with a simple embed code
**Estimated time:** 5 minutes from start to finish
## 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.
### Choose Your Training Data
Your AI Agent needs information to learn from. You can train it using various data sources:
**Upload your documents**
Train your agent on your documents.
**Best for:** Business documents, manuals, FAQs, product information, etc.
**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
**Crawl your website**
Our crawlers will discover and learn from all your pages.
**Best for:** Your entire website or sitemap
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.
**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
**Connect your Notion workspace**
Connect your Notion workspace to your agent. This is useful for your entire knowledge base.
**Best for:** Teams using Notion
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.
### Review & Start Training
Click **"Create Agent"** to begin the training process.
Training typically takes 2-5 minutes depending on the amount of data. You can proceed to the next step while training completes.
**Character Limits:** Different plans have different character limits for training data. Check your plan if you hit any limits.
## Step 2: Test & Optimize Your AI Agent
### Access the Playground
Once training begins, you'll automatically be taken to the [**Playground**](/user-guides/chatbot/playground) - your testing environment where you can chat with your AI Agent and fine-tune it before making it live.
### Evaluate Response Quality
As you test, look for:
**Accuracy** - Are responses factually correct?
**Relevance** - Does it answer what was asked?
**Completeness** - Are responses comprehensive but concise?
**Tone** - Does it match your brand voice?
### Fine-tune Settings
### Test responses 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**
Based on the comparison, select the model that best fits your specific use case and brand voice.
For detailed model comparisons and advanced testing strategies, check out our [comprehensive model comparison guide](/user-guides/chatbot/playground#compare-area).
Define how your AI Agent should behave and respond to users. These instructions shape your agent's personality, tone, and approach to conversations.
**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.
**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
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
## 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 click on **"Update"** button to change the visibility to public.
**Private vs Public:** Private agents are only accessible to workspace members. Public agents can be embedded on websites and accessed by anyone with the link.
### Choose Your Deployment Method
Chatbase offers multiple deployment methods including chat widget, help page, and integrations with WhatsApp, WordPress, and other platforms.
In this guide, we'll use the **Chat widget** option as it's most common. Click on Manage on chat widget then select Embed.
**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
**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
### Get Your Embed Code
In this guide we'll use the **Chat widget** option.
Copy the provided JavaScript code snippet:
### Add Code to Your Website
Find where you can add JavaScript code to your website. This is usually in the `` section or before the closing `` tag.
**For fast loading:** Place the script just before the closing `` tag to ensure your page content loads first, then the chat widget appears.
**For immediate availability:** Place the script in the `` section to load the chat widget as early as possible, though this may slightly delay your page's initial render.
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.
Save your changes and publish your website updates.
### Verify Installation
Visit your website and look for the chat bubble. Click it to test the integration!
**Success!** Your AI Agent is now live and ready to help your website visitors.
Need more control over your widget? Check out our [Developer Guides](/developer-guides/overview) for more information on JavaScript embed, [widget control options](/developer-guides/control-widget), and advanced features like [client-side custom actions](/developer-guides/client-side-custom-actions) and [event listeners](/developer-guides/chatbot-event-listeners).
### Customize Appearance (Optional)
Want to match your brand? Check out our settings guide for [style](/user-guides/chatbot/settings#chat-interface) and [content](/user-guides/chatbot/settings#content).
* Upload custom chat bubble icon
* Change bubble colors to match your brand
* Customize welcome messages
* Set initial questions users can click
* Auto-open chat after delay
* Collect user feedback
* Regenerate messages
## 🎉 Congratulations!
You've successfully created, trained, tested, and deployed your first AI Agent! Here's what you've accomplished:
✅ Created an intelligent AI Agent trained on your data
✅ Tested and validated response quality
✅ Deployed it live on your website
✅ Made it accessible to your visitors 24/7
### What's Next?
Track conversations and optimize your AI Agent's performance
Add actions like lead capture, appointment booking, and more
Learn proven strategies to maximize your AI Agent's effectiveness
Build custom integrations with our powerful API
**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](/faq/faq) for common questions.
# Manage
Source: https://chatbase.co/docs/user-guides/workspace/manage
Organize your users in Chatbase workspaces for better collaboration and permission control.
### Creating a Team
To create a new workspace, click on the **Create or join workspace** button on the **Select workspace** dropdown menu.
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.
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!
### 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.
### Members
This tab displays all the information about your workspace members, as well as those you've invited but haven't responded yet.
### 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.
### 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.
### Remove workspace member
To remove a member from the workspace
### 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.
### 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."
In the **Pro** plan, you can add an extra workspace member to the dashboard for \$25 per month.
***Note :*** If the button is unclickable, it means you've reached the maximum number of members or invitations. Clear some space to be able to invite new members.
## 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.
### 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.
We have a new pricing that was released on the 20th of January as follows:
**Free Plan:**
* Cost: \$0/month
* Message Credits: 100/month
* AI agents: 1
* Seats: 1
* Characters/AI agent: 400,000
* Embed on Unlimited Websites: Yes
* Limited of 10 links to train on
* API Access: No
**Hobby Plan:**
* Cost: \$40 per month, or \$384 per year
* Message Credits: 2,000/month
* AI agents: 1
* Workspace members: 1
* 5 AI Actions/AI agent
* Characters/AI agent: 11,000,000
* Embed on Unlimited Websites: Yes
* Unlimited links to train on
* API Access: Yes
* Access to Integrations
* Access to the advanced AI models
* Basic analytics
**Standard Plan:**
* Cost: \$150 per month or \$1440 per year
* Message Credits: 12,000/month
* AI agents: 2
* Workspace members: 3
* 10 AI Actions/AI agent
* Characters/AI agent: 11,000,000
* Embed on Unlimited Websites: Yes
* API Access: Yes
**Pro Plan**
* Cost: \$500 per month or \$4800 per year
* Message Credits: 40,000/month
* AI agents: 3
* Workspace members: 5 (\$25 for each extra member)
* 15 AI Actions/AI agent
* Characters/AI agent: 11,000,000
* Embed on Unlimited Websites: Yes
* API Access: Yes
* Advanced analytics
* Remove 'Powered by Chatbase': Yes
**Credit Pricing Updates:**
* Auto-recharge credits: \$14 per 1,000 credits
* Extra credits: \$12 per 1,000 credits
We're also upgrading the Free Tier to include 100 message credits/month (previously 20 credits).
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.
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.
***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:
### Add Ons
This section is responsible for adding extra stuff on top of your current plan. Some add-ons are one buy for the whole workspace like custom domains or remove powered by chatbase. So by clicking enable you will see a prompt similar to this one:
If you are choosing an add-on that can have quantities like extra AI agents, or extra message credits, you will see a prompt similar to this:
#### 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.
The cost is \$14 for each 1000 messages credits.
#### Extra message credits
Get additional 1000 message credits per month, allowing you to keep your AI agent running smoothly without running out of credits.
This costs \$12 per month for 1000 additional message credits.
#### Extra AI agents
You can add extra AI agents to help you scale your service by managing multiple bots simultaneously.
This feature costs \$7 per AI agent each month.
#### 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.
The cost is \$59 per month for custom domains.
#### Remove 'Powered By Chatbase'
Remove the Chatbase branding from the iframe and widget for a cleaner, custom experience.
This feature is available for \$39 per month.
## 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.
### Billing Email
This section shows the email address that will receive automated copies of all invoices for this workspace.
### Tax ID
In this section, you can add a tax ID to be displayed on the invoice if needed.
### 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.
### 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.
## API Keys
On this page, you'll find your Chatbase API keys, which allow you to interact with your bot 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.
# 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.
## 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:
### 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:
## 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.
### 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.
### 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.
### 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.
