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

# Chat API

> Send messages and receive AI responses

## Basic Chat

```javascript theme={null}
const result = await client.chat({
  bot_id: 'bot_abc123',
  message: 'Hello! How can you help me?'
});

if (result.err) {
  console.error('Error:', result.err);
} else {
  console.log('Bot response:', result.response);
}
```

### Parameters

| Parameter          | Type    | Required | Description                                          |
| ------------------ | ------- | -------- | ---------------------------------------------------- |
| `bot_id`           | string  | Yes      | Bot ID to chat with                                  |
| `message`          | string  | Yes      | User message                                         |
| `model`            | string  | No       | Override bot's model                                 |
| `provider_key`     | string  | No       | Use your own API key (BYOK)                          |
| `provider_host`    | string  | No       | Required for Ollama (e.g., `http://localhost:11434`) |
| `instruction`      | string  | No       | Override bot's instruction                           |
| `source_ids`       | array   | No       | Specific training sources to use                     |
| `max_reply_tokens` | number  | No       | Override max tokens                                  |
| `chat_id`          | string  | No       | Chat ID to maintain conversation context             |
| `stream`           | boolean | No       | Stream response (default: `false`)                   |
| `memory`           | boolean | No       | Use agent's training data (default: `true`)          |
| `reasoning_mode`   | string  | No       | `auto`, `standard`, `agent`                          |

### Response

```javascript theme={null}
{
  err: null,
  response: 'I can help you with customer support, product information, and answering your questions!'
}
```

## Chat with Conversation Context

Use `chat_id` to maintain conversation context:

```javascript theme={null}
const chatId = 'chat_user_123';

// First message
const msg1 = await client.chat({
  bot_id: 'bot_abc123',
  message: 'My name is John',
  chat_id: chatId
});

// Second message (bot remembers context)
const msg2 = await client.chat({
  bot_id: 'bot_abc123',
  message: 'What is my name?',
  chat_id: chatId
});

console.log(msg2.response); // "Your name is John"
```

## Override Model Per Request

```javascript theme={null}
const result = await client.chat({
  bot_id: 'bot_abc123',
  message: 'Complex question requiring deep thinking',
  model: 'o1', // Use reasoning model for this request
  reasoning_mode: 'agent' // Autonomous multi-step with tools (up to 10x credit)
});
```

### Reasoning Modes

* **auto** - Automatically selects best approach
* **standard** - Quick answers (1x credit)
* **agent** - Autonomous multi-step reasoning with tool use (up to 10x)

## Use Local Ollama Models

For self-hosted models:

```javascript theme={null}
const result = await client.chat({
  bot_id: 'bot_abc123',
  message: 'Hello',
  model: 'llama3.1',
  provider_host: 'http://localhost:11434'
});
```

<Info>
  Use `provider_host` instead of `provider_key` for Ollama.
</Info>

## Limit Response Length

```javascript theme={null}
const result = await client.chat({
  bot_id: 'bot_abc123',
  message: 'Give me a brief summary',
  max_reply_tokens: 200 // Short response
});
```

## Use Your Own API Key (BYOK)

Bring your own API key for any provider:

```javascript theme={null}
const result = await client.chat({
  bot_id: 'bot_abc123',
  message: 'Hello',
  model: 'gpt-5',
  provider_key: 'sk-your-openai-key' // Use your OpenAI key
});
```

## Override Instructions

Override the bot's instruction per request:

```javascript theme={null}
const result = await client.chat({
  bot_id: 'bot_abc123',
  message: 'Tell me a joke',
  instruction: 'You are a comedian who tells funny jokes.'
});
```

## Use Specific Training Sources

Target specific training sources by ID:

```javascript theme={null}
const result = await client.chat({
  bot_id: 'bot_abc123',
  message: 'What is our refund policy?',
  source_ids: ['source_123', 'source_456'] // Only use these sources
});
```

## Disable Training Data

Skip the agent's training data for a specific request:

```javascript theme={null}
const result = await client.chat({
  bot_id: 'bot_abc123',
  message: 'Hello',
  memory: false // Don't use agent's training data
});
```

## Stream Responses

Stream responses in real-time by setting `stream: true`:

```javascript theme={null}
const result = await client.chat({
  bot_id: 'bot_abc123',
  message: 'Write a long story',
  stream: true
});

if (result.err) {
  console.error('Error:', result.err);
} else {
  // Handle streaming response
  for await (const chunk of result.response) {
    process.stdout.write(chunk);
  }
}
```

## Edit Chat Mode

Edit mode routes your request through the agent reasoning pipeline, where the agent uses the built-in `edit` tool to make targeted code changes in your workspace files.

```javascript theme={null}
// Send an edit request — the agent finds and edits the relevant file
const result = await client.chat({
  bot_id: 'bot_abc123',
  message: 'Add email validation to the login form',
  chat_id: chatId,
  chat_mode: 'edit'
});

console.log(result.response); // Agent's summary of changes made
```

### Edit Mode Parameters

| Parameter   | Type   | Required | Description                                       |
| ----------- | ------ | -------- | ------------------------------------------------- |
| `chat_mode` | string | No       | `'ask'`, `'edit'`, or `'plan'` (default: `'ask'`) |

<Info>
  Edit mode forces agent reasoning — the AI analyzes your request, identifies the target file in the workspace, and applies precise string replacements using the built-in `edit` tool. The agent can chain multiple edits in a single turn. No `reference_message_id` is needed.
</Info>

<Warning>
  Edit mode requires the agent's **Workspace** setting to be enabled. If workspace is disabled, `edit` requests are treated as normal `ask` mode.
</Warning>

## Plan Chat Mode

Plan mode enables a conversational "plan-then-execute" workflow — the AI proposes a step-by-step plan before executing any tools, giving you the opportunity to review, modify, or approve.

```javascript theme={null}
// Step 1: Request a plan
const plan = await client.chat({
  bot_id: 'bot_abc123',
  message: 'Find a professional studio background image and update the page',
  chat_id: chatId,
  chat_mode: 'plan'
});

console.log(plan.response); // AI proposes a step-by-step plan

// Step 2: Approve the plan to execute it
const result = await client.chat({
  bot_id: 'bot_abc123',
  message: 'Looks good, go ahead',
  chat_id: chatId,
  chat_mode: 'plan'
});

console.log(result.response); // Executed result

// Or modify the plan instead
const revised = await client.chat({
  bot_id: 'bot_abc123',
  message: 'Actually, search for a darker background instead',
  chat_id: chatId,
  chat_mode: 'plan'
});

console.log(revised.response); // Revised plan
```

### Plan Mode Parameters

| Parameter   | Type   | Required | Description                                       |
| ----------- | ------ | -------- | ------------------------------------------------- |
| `chat_mode` | string | No       | `'ask'`, `'edit'`, or `'plan'` (default: `'ask'`) |

<Info>
  Plan mode classifies each message as one of three intents: **approve** (execute the proposed plan), **modify** (revise the plan), or **new** (generate a fresh plan). The AI is aware of all available tools (built-in and connected integrations) when generating plans. If no tools are needed, it bypasses planning and returns a direct answer. Plan generation costs 2 credits; execution costs are additional based on the tools used.
</Info>

<Warning>
  Plan mode requires the agent's **Workspace** setting to be enabled. If workspace is disabled, `plan` requests are treated as normal `ask` mode.
</Warning>

## Error Handling

```javascript theme={null}
const result = await client.chat({
  bot_id: 'bot_abc123',
  message: 'Hello'
});

if (result.err) {
  if (result.err.includes('Rate limit')) {
    console.log('Rate limited, retry later');
  } else if (result.err.includes('Bot not found')) {
    console.log('Bot does not exist');
  } else {
    console.error('Unknown error:', result.err);
  }
} else {
  console.log('Success:', result.response);
}
```

## Complete Example

```javascript theme={null}
import { BoostGPT } from 'boostgpt';

const client = new BoostGPT({
  project_id: process.env.BOOSTGPT_PROJECT_ID,
  key: process.env.BOOSTGPT_API_KEY
});

async function chat() {
  const chatId = `chat_${Date.now()}`;

  // Start conversation
  const response1 = await client.chat({
    bot_id: 'bot_abc123',
    message: 'What services do you offer?',
    chat_id: chatId
  });

  if (response1.err) {
    console.error('Error:', response1.err);
    return;
  }

  console.log('Bot:', response1.response);

  // Follow-up question (remembers context)
  const response2 = await client.chat({
    bot_id: 'bot_abc123',
    message: 'How much does it cost?',
    chat_id: chatId
  });

  console.log('Bot:', response2.response);
}

chat();
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Training Data" icon="book" href="/sdk/core/training-data">
    Add knowledge to improve responses
  </Card>

  <Card title="API Reference" icon="code" href="/sdk/core/api-reference">
    Complete API documentation
  </Card>
</CardGroup>