# Initial Messages
URL: /concepts/message-threads/initial-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

```tsx
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:

```tsx
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:

1. **Custom Instructions**: Set via the project settings dashboard, applied to all threads in the project
2. **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

```tsx
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

```tsx
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
  },
];
```