Skip to main content

​
Basic Chat

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

ParameterTypeRequiredDescription
bot_idstringYesBot ID to chat with
messagestringYesUser message
modelstringNoOverride bot’s model
provider_keystringNoUse your own API key (BYOK)
provider_hoststringNoRequired for Ollama (e.g., http://localhost:11434)
instructionstringNoOverride bot’s instruction
source_idsarrayNoSpecific training sources to use
max_reply_tokensnumberNoOverride max tokens
chat_idstringNoChat ID to maintain conversation context
streambooleanNoStream response (default: false)
memorybooleanNoUse agent’s training data (default: true)
reasoning_modestringNoauto, standard, agent

​
Response

{
  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: 
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

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: 
const result = await client.chat({
  bot_id: 'bot_abc123',
  message: 'Hello',
  model: 'llama3.1',
  provider_host: 'http://localhost:11434'
});
Use provider_host instead of provider_key for Ollama.

​
Limit Response Length

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: 
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: 
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: 
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: 
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: 
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. 
// 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

ParameterTypeRequiredDescription
chat_modestringNo'ask', 'edit', or 'plan' (default: 'ask')
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.
Edit mode requires the agent’s Workspace setting to be enabled. If workspace is disabled, edit requests are treated as normal ask mode.

​
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. 
// 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

ParameterTypeRequiredDescription
chat_modestringNo'ask', 'edit', or 'plan' (default: 'ask')
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.
Plan mode requires the agent’s Workspace setting to be enabled. If workspace is disabled, plan requests are treated as normal ask mode.

​
Error Handling

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

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

Training Data

Add knowledge to improve responses

API Reference

Complete API documentation