Message Types

Overview

Message types define the structure of messages in a thread. Messages use an Anthropic-style content blocks pattern where each message contains an array of content blocks (text, tool calls, tool results, components).

TamboThreadMessage

Represents a single message in a thread.

import type { TamboThreadMessage } from '@tambo-ai/react';

Definition

interface TamboThreadMessage {
  /** Unique message identifier */
  id: string;
  
  /** Message role (user, assistant, or system) */
  role: MessageRole;
  
  /** Content blocks in the message */
  content: Content[];
  
  /** When the message was created (ISO 8601 timestamp) */
  createdAt?: string;
  
  /** Message metadata */
  metadata?: Record<string, unknown>;
  
  /**
   * The id of the parent message, if this message was created during
   * generation of another message (e.g., MCP sampling or elicitation).
   */
  parentMessageId?: string;
  
  /**
   * Reasoning content from the model (transient - only during streaming).
   * Each element is a reasoning "chunk" - models may emit multiple reasoning blocks.
   * This data is not persisted and will not be present in messages loaded from the API.
   */
  reasoning?: string[];
  
  /**
   * Duration of the reasoning phase in milliseconds (for display purposes).
   * Populated when reasoning completes.
   */
  reasoningDurationMS?: number;
}

Fields

string

required

Unique identifier for the message.

id: 'msg_abc123'

role

MessageRole

required

The message role. See MessageRole.

"user" - Message from the user
"assistant" - Message from the AI
"system" - System message (when loading from API)

content

Content[]

required

Array of content blocks. See Content Types.A message can contain multiple content blocks of different types:

Text blocks
Tool use blocks (tool calls)
Tool result blocks (tool responses)
Component blocks (rendered UI)
Resource blocks (attached files/data)

createdAt

string

ISO 8601 timestamp when the message was created. Optional for historical messages loaded from API.

createdAt: '2024-03-15T10:30:00Z'

metadata

Record<string, unknown>

Custom metadata associated with the message.

metadata: {
  sourceType: 'voice',
  language: 'en-US'
}

parentMessageId

string

ID of the parent message if this message was created during generation of another message (e.g., MCP sampling or elicitation).

reasoning

string[]

Reasoning content from the model. Only present during streaming and not persisted to the database.Models may emit multiple reasoning blocks, so this is an array of strings.

reasoning: [
  'Let me think about this step by step...',
  'First, I need to check the weather data...'
]

reasoningDurationMS

number

Duration of the reasoning phase in milliseconds. Populated when reasoning completes.

reasoningDurationMS: 1234

MessageRole

The role/author of a message.

import type { MessageRole } from '@tambo-ai/react';

type MessageRole = "user" | "assistant" | "system";

Values

user

string

Message from the user/human.

assistant

string

Message from the AI assistant.

system

string

System message. Included to accommodate messages loaded from the API.

Content Types

Union type of all content block types.

import type { Content } from '@tambo-ai/react';

type Content =
  | TextContent
  | TamboToolUseContent
  | ToolResultContent
  | TamboComponentContent
  | ResourceContent;

TextContent

A text content block.

import type { TextContent } from '@tambo-ai/react';

interface TextContent {
  type: 'text';
  text: string;
}

type

'text'

required

Discriminator for the content block type.

text

string

required

The text content.

{ type: 'text', text: 'Hello, how can I help you?' }

TamboToolUseContent

A tool call (tool use) content block. Extended from the SDK with computed state properties.

import type { TamboToolUseContent } from '@tambo-ai/react';

interface TamboToolUseContent {
  type: 'tool_use';
  id: string;
  name: string;
  input: Record<string, unknown>;
  
  // Computed properties (populated by useTambo() hook)
  hasCompleted?: boolean;
  statusMessage?: string;
  tamboDisplayProps?: TamboToolDisplayProps;
}

type

'tool_use'

required

Discriminator for the content block type.

string

required

Unique identifier for this tool call.

name

string

required

Name of the tool being called.

input

Record<string, unknown>

required

Tool input parameters with internal _tambo_* properties removed. Consumers see only the actual tool parameters.

hasCompleted

boolean

Whether this tool call has completed (has a matching tool_result). Computed by useTambo().

statusMessage

string

The status message to display, resolved based on tool execution state. Computed by useTambo().

tamboDisplayProps

TamboToolDisplayProps

Extracted Tambo display properties from the tool input. See TamboToolDisplayProps.

ToolResultContent

A tool result content block (response from a tool call).

import type { ToolResultContent } from '@tambo-ai/react';

interface ToolResultContent {
  type: 'tool_result';
  tool_use_id: string;
  content: string | Array<{ type: string; [key: string]: unknown }>;
  is_error?: boolean;
}

type

'tool_result'

required

Discriminator for the content block type.

tool_use_id

string

required

ID of the tool_use block this result corresponds to.

content

string | Array<...>

required

The tool result content. Can be a string or an array of content parts.

is_error

boolean

Whether this result represents an error.

TamboComponentContent

A component content block. Extended from the SDK with streaming state.

import type { TamboComponentContent } from '@tambo-ai/react';

interface TamboComponentContent {
  type: 'component';
  id: string;
  name: string;
  props?: Record<string, unknown>;
  state?: Record<string, unknown>;
  streamingState?: ComponentStreamingState;
}

type

'component'

required

Discriminator for the content block type.

string

required

Unique identifier for this component instance.

name

string

required

Name of the component to render.

props

Record<string, unknown>

Component props provided by the AI.

state

Record<string, unknown>

Component state (can be updated by AI or client).

streamingState

ComponentStreamingState

Current streaming state of this component’s props. See ComponentStreamingState.

ResourceContent

A resource content block (attached files/data).

import type { ResourceContent } from '@tambo-ai/react';

interface ResourceContent {
  type: 'resource';
  resource: {
    type: string;
    resource: {
      uri: string;
      mimeType?: string;
      text?: string;
      blob?: string;
    };
  };
}

type

'resource'

required

Discriminator for the content block type.

resource

object

required

The resource data including URI, MIME type, and content.

ComponentStreamingState

Streaming state for component content blocks.

import type { ComponentStreamingState } from '@tambo-ai/react';

type ComponentStreamingState = "started" | "streaming" | "done";

Values

started

string

Component block created, awaiting props.

streaming

string

Props are being streamed.

done

string

Props streaming complete. Default for historical messages loaded from API.

TamboToolDisplayProps

Special display properties that can be included in tool input to customize status messages.

import type { TamboToolDisplayProps } from '@tambo-ai/react';

interface TamboToolDisplayProps {
  /** Message shown while the tool is executing */
  _tambo_statusMessage?: string;
  
  /** Message shown after the tool completes */
  _tambo_completionStatusMessage?: string;
}

_tambo_statusMessage

string

Custom message displayed while the tool is executing.

_tambo_statusMessage: 'Fetching weather data...'

_tambo_completionStatusMessage

string

Custom message displayed after the tool completes.

_tambo_completionStatusMessage: 'Weather data retrieved'

Input Message Types

Types for sending messages to the AI.

InputMessage

Standard message format for user input.

import type { InputMessage } from '@tambo-ai/react';

interface InputMessage {
  role: 'user';
  content: string | Array<{ type: string; [key: string]: unknown }>;
}

InitialInputMessage

Message type for initial messages that seed a new thread. Supports system and assistant roles in addition to user.

import type { InitialInputMessage } from '@tambo-ai/react';

interface InitialInputMessage {
  role: 'user' | 'assistant' | 'system';
  content: string | Array<TextContent | ResourceContent>;
}

Initial messages can only contain text and resource blocks, not tool results.

API Response Types

Types returned by the Tambo API for message operations.

MessageListResponse

Response when listing messages in a thread.

import type { MessageListResponse } from '@tambo-ai/react';

MessageGetResponse

Response when fetching a specific message.

import type { MessageGetResponse } from '@tambo-ai/react';

These types are re-exported from @tambo-ai/typescript-sdk. Refer to the SDK documentation for detailed field definitions.

Usage Examples

Rendering Messages

import { useTambo } from '@tambo-ai/react';
import type { TamboThreadMessage, Content } from '@tambo-ai/react';

function MessageList() {
  const { messages } = useTambo();
  
  return (
    <div>
      {messages.map((message: TamboThreadMessage) => (
        <div key={message.id} className={`message-${message.role}`}>
          {message.content.map((block: Content, idx: number) => (
            <ContentBlock key={idx} block={block} />
          ))}
        </div>
      ))}
    </div>
  );
}

Rendering Content Blocks

import type { Content } from '@tambo-ai/react';

function ContentBlock({ block }: { block: Content }) {
  switch (block.type) {
    case 'text':
      return <p>{block.text}</p>;
      
    case 'component':
      return <ComponentRenderer content={block} />;
      
    case 'tool_use':
      return (
        <div className="tool-call">
          Calling tool: {block.name}
          {block.statusMessage && <span>{block.statusMessage}</span>}
        </div>
      );
      
    case 'tool_result':
      return (
        <div className="tool-result">
          {typeof block.content === 'string' ? block.content : JSON.stringify(block.content)}
        </div>
      );
      
    default:
      return null;
  }
}

Handling Reasoning

import type { TamboThreadMessage } from '@tambo-ai/react';

function MessageWithReasoning({ message }: { message: TamboThreadMessage }) {
  return (
    <div>
      {message.reasoning && message.reasoning.length > 0 && (
        <div className="reasoning">
          <h4>Reasoning:</h4>
          {message.reasoning.map((chunk, idx) => (
            <p key={idx}>{chunk}</p>
          ))}
          {message.reasoningDurationMS && (
            <span className="duration">
              Took {message.reasoningDurationMS}ms
            </span>
          )}
        </div>
      )}
      
      {/* Render content blocks */}
      {message.content.map((block, idx) => (
        <ContentBlock key={idx} block={block} />
      ))}
    </div>
  );
}

Sending Messages

import { useTamboThreadInput } from '@tambo-ai/react';
import type { InputMessage } from '@tambo-ai/react';

function ChatInput() {
  const { value, setValue, submit } = useTamboThreadInput();
  
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    
    await submit({
      message: value,
      metadata: {
        source: 'chat-input',
        timestamp: Date.now()
      }
    });
  };
  
  return (
    <form onSubmit={handleSubmit}>
      <input
        value={value}
        onChange={(e) => setValue(e.target.value)}
        placeholder="Type a message..."
      />
      <button type="submit">Send</button>
    </form>
  );
}

Type Imports

import type {
  TamboThreadMessage,
  MessageRole,
  Content,
  TextContent,
  TamboToolUseContent,
  ToolResultContent,
  TamboComponentContent,
  ResourceContent,
  ComponentStreamingState,
  TamboToolDisplayProps,
  InputMessage,
  InitialInputMessage,
  MessageListResponse,
  MessageGetResponse,
} from '@tambo-ai/react';

React SDK

Client

CLI

Types

Overview

TamboThreadMessage

Definition

Fields

MessageRole

Values

Content Types

TextContent

TamboToolUseContent

ToolResultContent

TamboComponentContent

ResourceContent

ComponentStreamingState

Values

TamboToolDisplayProps

Input Message Types

InputMessage

InitialInputMessage

API Response Types

MessageListResponse

MessageGetResponse

Usage Examples

Rendering Messages

Rendering Content Blocks

Handling Reasoning

Sending Messages

Type Imports

See Also

Build docs developers (and LLMs) love

React SDK

Client

CLI

Types

​Overview

​TamboThreadMessage

​Definition

​Fields

​MessageRole

​Values

​Content Types

​TextContent

​TamboToolUseContent

​ToolResultContent

​TamboComponentContent

​ResourceContent

​ComponentStreamingState

​Values

​TamboToolDisplayProps

​Input Message Types

​InputMessage

​InitialInputMessage

​API Response Types

​MessageListResponse

​MessageGetResponse

​Usage Examples

​Rendering Messages

​Rendering Content Blocks

​Handling Reasoning

​Sending Messages

​Type Imports

​See Also

Build docs developers (and LLMs) love

Overview

TamboThreadMessage

Definition

Fields

MessageRole

Values

Content Types

TextContent

TamboToolUseContent

ToolResultContent

TamboComponentContent

ResourceContent

ComponentStreamingState

Values

TamboToolDisplayProps

Input Message Types

InputMessage

InitialInputMessage

API Response Types

MessageListResponse

MessageGetResponse

Usage Examples

Rendering Messages

Rendering Content Blocks

Handling Reasoning

Sending Messages

Type Imports

See Also