Tambo AI Documentation

Set up conversation state when creating new threads with system instructions, context, or welcome messages

The Initial Messages feature allows you to set up a "conversation state" when creating new threads in Tambo. This is useful for providing system instructions, context, or welcome messages that should be present at the start of every new conversation.

React SDK Usage

Basic Example

import { TamboProvider, TamboThreadMessage } from "@tambo-ai/react";

const initialMessages: TamboThreadMessage[] = [
  {
    id: "system-message",
    role: "system",
    content: [
      {
        type: "text",
        text: "You are a helpful assistant specialized in customer support.",
      },
    ],
    createdAt: new Date().toISOString(),
    componentState: {},
  },
  {
    id: "welcome-message",
    role: "assistant",
    content: [{ type: "text", text: "Hello! How can I help you today?" }],
    createdAt: new Date().toISOString(),
    componentState: {},
  },
];

function App() {
  return (
    <TamboProvider
      tamboUrl="https://api.tambo.ai"
      apiKey="your-api-key"
      initialMessages={initialMessages}
    >
      <YourChatComponent />
    </TamboProvider>
  );
}

With Components

You can also include components in initial messages:

const initialMessagesWithComponent: TamboThreadMessage[] = [
  {
    id: "system-message",
    role: "system",
    content: [{ type: "text", text: "You are a helpful assistant." }],
    createdAt: new Date().toISOString(),
    componentState: {},
  },
  {
    id: "welcome-component",
    role: "assistant",
    content: [{ type: "text", text: "Welcome! Here's a quick overview:" }],
    createdAt: new Date().toISOString(),
    componentState: {},
    component: {
      componentName: "WelcomeCard",
      props: {
        title: "Welcome to Support",
        description: "I can help you with your questions.",
      },
    },
  },
];

Behavior

New Threads

Initial messages are included when creating a new thread (placeholder thread)
They are sent to the AI model as part of the conversation context
They appear in the thread's message history

Existing Threads

Initial messages are not added to existing threads
Only applies when threadId is undefined (new thread creation)

Validation

The API validates initial messages to ensure:

Each message has valid content and role
Roles are one of: system, user, assistant
Text content parts have the required text property
Content arrays are not empty

Interaction with Custom Instructions

Initial messages work alongside the "custom instructions" feature:

Custom Instructions: Set via the project settings dashboard, applied to all threads in the project
Initial Messages: Set programmatically via the SDK/API, applied per thread creation

Both are sent to the AI model, with custom instructions typically processed first, followed by initial messages, then the conversation history.

Error Handling

Invalid initial messages will cause the thread creation to fail with a descriptive error:

Initial message at index 0 must have content
Initial message at index 1 has invalid role "invalid-role". Allowed roles are: system, user, assistant
Initial message at index 2, content part 0 with type 'text' must have text property

Examples

Customer Support Bot

const supportMessages: TamboThreadMessage[] = [
  {
    role: "system",
    content: [
      {
        type: "text",
        text: "You are a customer support agent for TechCorp. Be helpful, professional, and always ask for the customer's order number if they have an issue.",
      },
    ],
    // ... other required fields
  },
  {
    role: "assistant",
    content: [
      {
        type: "text",
        text: "Hi! I'm here to help with any questions about your TechCorp products. What can I assist you with today?",
      },
    ],
    // ... other required fields
  },
];

Educational Assistant

const educationMessages: TamboThreadMessage[] = [
  {
    role: "system",
    content: [
      {
        type: "text",
        text: "You are an educational assistant. Always encourage learning, ask clarifying questions, and provide step-by-step explanations.",
      },
    ],
    // ... other required fields
  },
  {
    role: "assistant",
    content: [
      {
        type: "text",
        text: "Welcome to your learning session! What topic would you like to explore today?",
      },
    ],
    // ... other required fields
  },
];

Initial Messages

On this page