> ## Documentation Index
> Fetch the complete documentation index at: https://docs.illa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Building a chat flow

> Step-by-step guide to integrate ILLA SDK in your app

This guide walks you through creating a complete chat flow with the ILLA SDK.

## Using the ILLA SDK (recommended)

The simplest way to build a chat flow is with the `IllaSDK` class.

### 1) Initialize the SDK

```ts theme={null}
import { IllaSDK } from '@illalabs/sdk'

const sdk = new IllaSDK({
  apiKey: process.env.ILLA_API_KEY!
})
```

### 2) Start a conversation

```ts theme={null}
const result = await sdk.sendMessage(
  'What can I do on Base?',
  { userContext: { address: '0xYourAddress' } }
)

// Save the chatId to continue the conversation
const chatId = result.chatId

if (!result.response.isError) {
  console.log('Assistant:', result.response.data.text)
}
```

### 3) Continue the conversation

```ts theme={null}
const followUp = await sdk.sendMessage(
  'Swap 0.1 ETH to USDC',
  { chatId }
)

if (!followUp.response.isError && followUp.response.data.pendingTools) {
  // Handle tool execution - see Handling Tool Execution guide
  console.log('Tools to execute:', followUp.response.data.pendingTools)
}
```

### 4) Retrieve message history

```ts theme={null}
const messages = await sdk.getMessages(chatId)
console.log('Conversation history:', messages)
```

### 5) Multiple chats

```ts theme={null}
// Track multiple conversations
const chatIds = sdk.chatIds
console.log('Active chats:', chatIds)

// Send messages to different chats
await sdk.sendMessage('Hello', { chatId: chatIds[0] })
await sdk.sendMessage('Hi there', { chatId: chatIds[1] })
```

## Advanced: Using Chat class

For more control, you can use the lower-level `Chat` class directly.

### 1) Initialize the components

```ts theme={null}
import {
  Chat,
  ContextManager,
  CoreApiProvider,
  InMemoryCache,
} from '@illalabs/sdk'

const provider = new CoreApiProvider({
  headers: { 'x-api-key': process.env.ILLA_API_KEY! },
})

const context = new ContextManager(new InMemoryCache())

const chat = new Chat({
  coreApiProvider: provider,
  contextManager: context,
  userContext: { address: '0xYourAddress' },
  // optional:
  // id: 'my-chat-id',
  // defaultRole: 'user',
})
```

### 2) Send messages

```ts theme={null}
import { Prompt } from '@illalabs/sdk'

const first = await chat.sendMessage(
  new Prompt({ text: 'What can I do on Base?' })
)

// Inspect returned shape
if (!first.response.isError) {
  console.log('Assistant:', first.response.data.text)
}

// Follow-up
const second = await chat.sendMessage(
  new Prompt({ text: 'Swap 0.1 ETH to USDC' })
)

// Handle potential tool execution
if (!second.response.isError && second.response.data.pendingTools) {
  console.log('Tools to execute:', second.response.data.pendingTools)
}
```

### 3) Persisted context

The chat automatically persists message history using the `ContextManager`. You can snapshot or restore it as needed.

```ts theme={null}
const snapshot = await chat.getContext()
// ... store snapshot ...
await chat.setContext(snapshot)
```

### 4) Long‑running actions (optional)

If your prompts can trigger on-chain actions, add an `AsyncToolChecker` and use `chat.awaitAction` or subscribe for progress.

See: [Awaiting actions & polling](/sdk/guides/awaiting-actions-and-polling)