Custom Initial Messages

Prerequisites

A website with the Chatbase embed script already installed and working. New to Chatbase? Check out 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:

// 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:

// 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

Initial messages can be set two ways — through the runtime options API or the dedicated setInitialMessages method. Both write the same setting, and the last call wins whichever method made it.

setOptions()

The runtime options API accepts initial messages alongside the widget’s other overridable options:

window.chatbase.setOptions({
  initialMessages: ["Hi!", "How can I help you today?"],
});

string[]

Array of non-empty strings containing the messages to display in sequenceRequirements:

Must be an array of non-empty strings
Total character count limited to 1000 characters — oversize input is rejected with a console.error, never truncated

setInitialMessages()

Set the messages displayed when the agent first loads:

string[]

required

Array containing the messages to display in sequenceRequirements:

Must be an array of strings
Total character count limited to 1000 characters — input over the limit is truncated

Clearing custom initial messages

To remove your custom initial messages and return to the agent’s configured ones, clear the override through resetOptions:

window.chatbase.resetOptions({ initialMessages: true });

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

Message Content

Write effective initial messages

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

Personalization Strategy

Use user data thoughtfully

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

Timing and Performance

Optimize when messages are set

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

Getting Started

JavaScript Embed Features

API v1 Reference

Advanced Integration

Widgets

Custom Initial Messages

Prerequisites

Setting Up Custom Initial Messages

Personalized Messages

Dynamic Content Examples

Method Reference

setOptions()

setInitialMessages()

Clearing custom initial messages

Best Practices

​Prerequisites

​Setting Up Custom Initial Messages

​Personalized Messages

​Dynamic Content Examples

​Method Reference

​setOptions()

​setInitialMessages()

​Clearing custom initial messages

​Best Practices

Prerequisites

Setting Up Custom Initial Messages

Personalized Messages

Dynamic Content Examples

Method Reference

setOptions()

setInitialMessages()

Clearing custom initial messages

Best Practices