# TypeScript Types
URL: /api-reference/typescript-types

The `@tambo-ai/react` package exports TypeScript types and interfaces to help you build type-safe AI applications.

## TamboTool

The `TamboTool` interface defines the structure for registering tools with Tambo.

```typescript
interface TamboTool {
  name: string;
  description: string;
  tool: (...args: any[]) => any;
  toolSchema: z.ZodFunction | JSONSchemaLite;
  transformToContent?: (
    result: any,
  ) => Promise<ChatCompletionContentPart[]> | ChatCompletionContentPart[];
}
```

### Properties

#### name

The unique identifier for the tool. This is how Tambo references the tool internally.

```typescript
name: string;
```

#### description

A clear description of what the tool does. This helps the AI understand when to use the tool.

```typescript
description: string;
```

#### tool

The function that implements the tool's logic. Can be synchronous or asynchronous.

```typescript
tool: (...args: any[]) => any;
```

#### toolSchema

A Zod function schema that defines the tool's parameters and return type. Can also be a JSON Schema object.

```typescript
toolSchema: z.ZodFunction | JSONSchemaLite;
```

**Example:**

```typescript
toolSchema: z.function()
  .args(z.string().describe("The city name"))
  .returns(z.object({ temperature: z.number(), condition: z.string() }));
```

#### transformToContent (optional)

A function that transforms the tool's return value into an array of content parts. Use this when your tool needs to return rich content like images or audio.

```typescript
transformToContent?: (result: any) => Promise<ChatCompletionContentPart[]> | ChatCompletionContentPart[];
```

By default, tool responses are stringified and wrapped in a text content part. The `transformToContent` function allows you to return rich content including images, audio, or mixed media.

**Example:**

```typescript
transformToContent: (result) => [
  { type: "text", text: result.description },
  { type: "image_url", image_url: { url: result.imageUrl } },
];
```

[Learn more about returning rich content from tools](/concepts/tools/adding-tools#returning-rich-content).

## TamboComponent

The `TamboComponent` interface defines the structure for registering React components with Tambo.

```typescript
interface TamboComponent {
  name: string;
  description: string;
  component: ComponentType<any>;
  propsSchema?: z.ZodTypeAny | JSONSchema7;
  propsDefinition?: any;
  loadingComponent?: ComponentType<any>;
  associatedTools?: TamboTool[];
}
```

### Properties

#### name

The unique identifier for the component.

```typescript
name: string;
```

#### description

A clear description of what the component displays or does. This helps the AI understand when to use the component.

```typescript
description: string;
```

#### component

The React component to render.

```typescript
component: ComponentType<any>;
```

#### propsSchema (recommended)

A Zod schema that defines the component's props.

```typescript
propsSchema?: z.ZodTypeAny | JSONSchema7;
```

#### propsDefinition (deprecated)

A JSON object defining the component's props. Use `propsSchema` instead.

```typescript
propsDefinition?: any;
```

#### loadingComponent (optional)

A component to display while the main component is loading.

```typescript
loadingComponent?: ComponentType<any>;
```

#### associatedTools (optional)

An array of tools that are associated with this component.

```typescript
associatedTools?: TamboTool[];
```

## ChatCompletionContentPart

Content parts that can be sent to or received from the AI.

```typescript
interface ChatCompletionContentPart {
  type: "text" | "image_url" | "input_audio";
  text?: string;
  image_url?: { url: string; detail?: "auto" | "high" | "low" };
  input_audio?: { data: string; format: "wav" | "mp3" };
}
```

This type is used in the `transformToContent` function to define rich content responses.

## TamboThreadMessage

A message in a Tambo thread.

```typescript
interface TamboThreadMessage {
  id: string;
  role: "user" | "assistant" | "system" | "tool";
  content: ChatCompletionContentPart[];
  createdAt: string;
  renderedComponent?: React.ReactNode;
  component?: {
    componentName: string;
    props: any;
  };
  actionType?: string;
  error?: string;
}
```

## TamboThread

A Tambo conversation thread.

```typescript
interface TamboThread {
  id: string;
  messages: TamboThreadMessage[];
  contextKey?: string;
  createdAt: string;
  updatedAt: string;
}
```

## GenerationStage

The current stage of AI response generation.

```typescript
enum GenerationStage {
  IDLE = "IDLE",
  CHOOSING_COMPONENT = "CHOOSING_COMPONENT",
  FETCHING_CONTEXT = "FETCHING_CONTEXT",
  HYDRATING_COMPONENT = "HYDRATING_COMPONENT",
  STREAMING_RESPONSE = "STREAMING_RESPONSE",
  COMPLETE = "COMPLETE",
  ERROR = "ERROR",
}
```

## ContextAttachment

Represents a context attachment that appears as a badge above the message input.

```typescript
interface ContextAttachment {
  id: string;
  name: string;
  icon?: React.ReactNode;
  metadata?: Record<string, unknown>;
}
```

### Properties

#### id

Unique identifier for the attachment. Auto-generated when adding a context attachment.

```typescript
id: string;
```

#### name

Display name shown in the badge.

```typescript
name: string;
```

#### icon

Optional icon to display in the badge.

```typescript
icon?: React.ReactNode;
```

#### metadata

Additional data passed to the AI as context.

```typescript
metadata?: Record<string, unknown>;
```

## ContextAttachmentState

The state interface returned by the `useTamboContextAttachment` hook.

```typescript
interface ContextAttachmentState {
  attachments: ContextAttachment[];
  addContextAttachment: (context: Omit<ContextAttachment, "id">) => void;
  removeContextAttachment: (id: string) => void;
  clearContextAttachments: () => void;
  customSuggestions: Suggestion[] | null;
  setCustomSuggestions: (suggestions: Suggestion[] | null) => void;
}
```

### Properties

#### attachments

Array of active context attachments currently displayed as badges.

```typescript
attachments: ContextAttachment[];
```

#### addContextAttachment

Function to add a new context attachment. The `id` is automatically generated.

```typescript
addContextAttachment: (context: Omit<ContextAttachment, "id">) => void;
```

#### removeContextAttachment

Function to remove a specific context attachment by its ID.

```typescript
removeContextAttachment: (id: string) => void;
```

#### clearContextAttachments

Function to remove all active context attachments.

```typescript
clearContextAttachments: () => void;
```

#### customSuggestions

Current custom suggestions that override auto-generated ones. Returns `null` if using auto-generated suggestions.

```typescript
customSuggestions: Suggestion[] | null;
```

#### setCustomSuggestions

Function to set custom suggestions or clear them by passing `null`.

```typescript
setCustomSuggestions: (suggestions: Suggestion[] | null) => void;
```

## ContextHelperData

Data structure returned by a context helper function.

```typescript
type ContextHelperData = Record<string, unknown>;
```

This type represents the data sent to the AI when a context attachment is active. You can customize this structure using the `getContextHelperData` prop on `TamboProvider`.