Open Chat Widget

https://docs.openchatwidget.com
Admin
Open Chat Widget is a ChatGPT-like AI chat widget for websites that supports custom agents built...
Tokens:3,802
Snippets:61
Trust Score:2.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies

Source: https://docs.openchatwidget.com/example-basic-react-express-app

Navigate to the example directory and install project dependencies using npm.

```bash
cd /Users/matt8p/Desktop/openchatwidget/examples/basic-react-express-app
npm install
```

--------------------------------

### Install Dependencies

Source: https://docs.openchatwidget.com/example-nextjs-landing-page

Install project dependencies using npm. Navigate to the example directory first.

```bash
cd /Users/matt8p/Desktop/openchatwidget/examples/nextjs-landing-page
npm install
```

--------------------------------

### Install Dependencies

Source: https://docs.openchatwidget.com/example-nextjs-portfolio-chat

Install project dependencies using pnpm. Navigate to the example directory first.

```bash
cd /Users/matt8p/Desktop/openchatwidget/examples/nextjs-portfolio-chat
pnpm install
```

--------------------------------

### Start Development Server

Source: https://docs.openchatwidget.com/example-nextjs-portfolio-chat

Run the Next.js development server.

```bash
pnpm dev
```

--------------------------------

### Start Development Server

Source: https://docs.openchatwidget.com/example-nextjs-landing-page

Start the Next.js development server to run the application.

```bash
npm run dev
```

--------------------------------

### Install OpenChatWidget SDK

Source: https://docs.openchatwidget.com/installation

Install the SDK package using npm. This is the first step to integrate the widget into your project.

```bash
npm i @openchatwidget/sdk
```

--------------------------------

### Configure Environment Variables

Source: https://docs.openchatwidget.com/example-nextjs-landing-page

Copy the example environment file and set your OpenRouter API key.

```bash
cp .env.example .env.local
```

```env
OPENROUTER_API_KEY=your_key_here
```

--------------------------------

### Install MCP SDK

Source: https://docs.openchatwidget.com/agent-with-mcp

Install the `@mcpjam/sdk` package using npm. This package provides the necessary tools to connect your agent to an MCP server.

```bash
npm i @mcpjam/sdk
```

--------------------------------

### Configure Environment Variables

Source: https://docs.openchatwidget.com/example-basic-react-express-app

Copy the example environment file and set your OpenAI API key.

```bash
cp .env.example .env
```

```env
OPENAI_API_KEY=your_key_here
```

--------------------------------

### Express Agent Server Setup

Source: https://docs.openchatwidget.com/create-an-agent

Set up an Express server to expose a streaming API endpoint for your AI agent. This snippet uses the Vercel AI SDK to create a streamText agent and pipe the stream to the response.

```typescript
import "dotenv/config";
import cors from "cors";
import express from "express";
import {
  convertToModelMessages,
  createOpenAI,
  streamText,
  type UIMessage,
} from "@openchatwidget/sdk";

const app = express();

app.use(cors());
app.use(express.json());

app.post("/api/chat", async (request, response) => {
  const { messages } = request.body as { messages: UIMessage[] };

  const openai = createOpenAI({
    apiKey: process.env.OPENAI_API_KEY,
  });

  const result = streamText({
    model: openai("gpt-4o-mini"),
    system: "You are the Open Chat Widget example assistant. Keep answers concise and useful.",
    messages: await convertToModelMessages(messages),
  });

  result.pipeUIMessageStreamToResponse(response);
});

app.listen(8787, () => {
  console.log("Express agent listening on http://localhost:8787");
});
```

--------------------------------

### Configure Environment Variables

Source: https://docs.openchatwidget.com/example-nextjs-portfolio-chat

Set up your OpenRouter API key in the environment variables.

```env
OPENROUTER_API_KEY=your_key_here
```

--------------------------------

### Build Agent with MCP Client Manager

Source: https://docs.openchatwidget.com/agent-with-mcp

Connect to an MCP server, fetch AI SDK-compatible tools, and integrate them into the `/api/chat` handler using `MCPClientManager` and `streamText`. Ensure to disconnect servers on completion or error.

```typescript
import { MCPClientManager } from "@mcpjam/sdk";
import {
  convertWidgetMessagesToModelMessages,
  createOpenAI,
  stepCountIs,
  streamText,
  type UIMessage,
} from "@openchatwidget/sdk";

app.post("/api/chat", async (request, response) => {
  const { messages } = request.body as { messages: UIMessage[] };

  const openai = createOpenAI({
    apiKey: process.env.OPENAI_API_KEY,
  });

  const manager = new MCPClientManager();
  await manager.connectToServer("workspace", {
    url: "https://mcp.notion.com/mcp",
    requestInit: {
      headers: {
        Authorization: `Bearer ${process.env.NOTION_TOKEN}`,
      },
    },
  });

  const mcpTools = await manager.getToolsForAiSdk(["workspace"]);

  const result = streamText({
    model: openai("gpt-4o-mini"),
    system: "Use MCP tools when needed.",
    messages: await convertWidgetMessagesToModelMessages(messages),
    stopWhen: stepCountIs(10),
    tools: { ...mcpTools },
    onFinish: async () => {
      await manager.disconnectAllServers();
    },
    onAbort: async () => {
      await manager.disconnectAllServers();
    },
    onError: async () => {
      await manager.disconnectAllServers();
    },
  });

  result.pipeUIMessageStreamToResponse(response);
});
```

--------------------------------

### Streaming Reasoning Summaries with AI SDK

Source: https://docs.openchatwidget.com/features/reasoning

This snippet demonstrates how to stream reasoning summaries alongside the assistant response using the AI SDK. Ensure your backend streams AI SDK `reasoning` parts for the widget to display the reasoning block. The `sendReasoning: true` option is crucial for enabling this feature in the UI.

```typescript
const result = streamText({
  model: openai("gpt-5-mini"),
  messages: await convertToModelMessages(messages),
  providerOptions: {
    openai: {
      reasoningEffort: "medium",
      reasoningSummary: "detailed",
    },
  },
});

result.pipeUIMessageStreamToResponse(response, {
  sendReasoning: true,
});
```

--------------------------------

### Connect Widget to Agent URL

Source: https://docs.openchatwidget.com/create-an-agent

Connect the Open Chat Widget to your AI agent by providing the streaming URL endpoint in the `url` prop of the `<OpenChatWidget />` component.

```tsx
<OpenChatWidget url="http://localhost:8787/api/chat" />
```

--------------------------------

### Add Web Search to API Chat Handler

Source: https://docs.openchatwidget.com/agent-with-web-search

Integrate web search directly into your `/api/chat` streaming handler by registering the `tools.web_search` option. This enables the model to access current information from the internet.

```typescript
import {
  convertWidgetMessagesToModelMessages,
  createOpenAI,
  stepCountIs,
  streamText,
  type UIMessage,
} from "@openchatwidget/sdk";

app.post("/api/chat", async (request, response) => {
  const { messages } = request.body as { messages: UIMessage[] };

  const openai = createOpenAI({
    apiKey: process.env.OPENAI_API_KEY,
  });

  const result = streamText({
    model: openai("gpt-5-mini"),
    system:
      "You are an assistant. Use web_search for current events or up-to-date information.",
    messages: await convertWidgetMessagesToModelMessages(messages),
    stopWhen: stepCountIs(5),
    tools: {
      web_search: openai.tools.webSearch({
        externalWebAccess: true,
        searchContextSize: "medium",
      }),
    },
  });

  result.pipeUIMessageStreamToResponse(response);
});
```

--------------------------------

### Embed Widget in React App

Source: https://docs.openchatwidget.com/installation

Embed the OpenChatWidget component in your React application. Mount it in your main app layout for site-wide visibility. Ensure you replace '<YOUR_AGENT_STREAMING_ENDPOINT>' with your actual agent's streaming endpoint URL.

```tsx
import { OpenChatWidget } from "@openchatwidget/sdk";

export default function MySite() {
  return (
    <>
      ...
      <OpenChatWidget url="<YOUR_AGENT_STREAMING_ENDPOINT>" />
    </>
  );
}
```

--------------------------------

### Disabling Reasoning UI in Open Chat Widget

Source: https://docs.openchatwidget.com/features/reasoning

To disable the reasoning UI in the Open Chat Widget, pass the `disableReasoning` prop to the root component. This action only affects the widget's display and does not alter your backend's contract.

```tsx
<OpenChatWidget
  url="http://localhost:8787/api/chat"
  disableReasoning
/>
```
Tokens:
Raw