# How to Access the CloddsBot WebChat UI: Complete Setup and Connection Guide

> Learn how to access the CloddsBot WebChat UI by following this setup and connection guide. Easily connect to your CloddsBot instance for real-time messaging.

- Repository: [AL/CloddsBot](https://github.com/alsk1992/CloddsBot)
- Tags: how-to-guide
- Published: 2026-09-13

---

**Launch the CloddsBot gateway and navigate to `http://localhost:18789/webchat` to access the built-in browser client for real-time messaging.**

CloddsBot includes a native **WebChat UI** that provides immediate browser-based interaction without external messaging platforms. This single-page application connects directly to the bot's gateway via WebSocket, offering a streamlined interface for testing and deployment. This guide explains how to start the gateway, authenticate connections, and send messages using the WebChat interface.

## Starting the Gateway Server

The WebChat UI is served by the CloddsBot gateway process. You must start this server before the browser client becomes accessible.

### Automated Onboarding

Run the interactive setup wizard to launch the gateway automatically:

```bash
npx clodds onboard

```

The wizard configures your environment and starts the gateway on the configured port. Upon completion, it displays the direct URL to open in your browser (typically `http://localhost:18789/webchat`), as documented in [`docs/QUICK_START.md`](https://github.com/alsk1992/CloddsBot/blob/main/docs/QUICK_START.md) at line 20.

### Manual Build and Launch

For development or custom configurations, start the gateway manually:

```bash
npm install
cp .env.example .env          # Configure ANTHROPIC_API_KEY and optional WEBCHAT_TOKEN

npm run build
npm start                     # Binds to port defined in gateway.port (default 18789)

```

The gateway reads its listening port from the configuration key `gateway.port`, defaulting to **18789** when unspecified. If no external channels (Telegram, Discord, etc.) are configured, the CLI prints a reminder that WebChat remains available: *"WebChat at http://localhost:18789/webchat will still work"* (see [`src/index.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/index.ts) lines 53-58).

## Opening the WebChat Interface

Once the gateway is running, access the single-page application at:

```text
http://localhost:18789/webchat

```

The Express server in [`src/gateway/server.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/gateway/server.ts) (lines 44-50) serves static assets under the `/webchat` HTTP path. The page loads a React-based client that immediately establishes a WebSocket connection to the `/chat` endpoint on the same host and port.

## WebSocket Connection and Authentication

The WebChat client communicates via WebSocket to transmit and receive messages in real-time.

### Connection Endpoint

The browser connects to:

```text
ws://localhost:18789/chat

```

All message traffic flows through this endpoint, handled by the `createWebChatChannel` function in [`src/channels/webchat/index.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/channels/webchat/index.ts).

### Token-Based Authentication

If you enabled authentication via `webchat.authToken` in your configuration, the UI supports two authentication methods:

1. **Query string parameter**: Append the token to the URL:

   ```text
   http://localhost:18789/webchat?token=your-secret-token
   ```

2. **WebSocket message**: Send an auth payload after connection:

   ```javascript
   const ws = new WebSocket('ws://localhost:18789/chat');
   
   ws.onopen = () => {
     ws.send(JSON.stringify({
       type: 'auth',
       token: 'your-secret-token',
       userId: 'my-user'
     }));
   };
   ```

The server validates tokens in `createWebChatChannel` (lines 13-22 in [`src/channels/webchat/index.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/channels/webchat/index.ts)) before allowing message processing.

## Sending Messages Programmatically

Once authenticated, the client transmits JSON payloads to trigger bot responses.

### Via WebSocket Client

Send standard message payloads using the WebSocket connection:

```javascript
function sendMessage(text) {
  ws.send(JSON.stringify({
    type: 'message',
    text: text
  }));
}

sendMessage('What markets are trending?');

```

The server converts these into internal `IncomingMessage` objects and routes them through the standard message pipeline.

### Via Browser Console

Access the global API exposed by the WebChat UI for debugging:

```javascript
// In the browser console after page load
window.CloddsWebChat.sendMessage('Analyze current BTC trends');

```

This method wraps the WebSocket communication in a convenient JavaScript interface.

## Legacy Interface Access

For minimal environments or debugging, CloddsBot provides a fallback HTML client at:

```text
http://localhost:18789/webchat/legacy

```

This inline interface, defined in [`src/gateway/server.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/gateway/server.ts) (lines 52-58), offers basic WebSocket connectivity without the full React application overhead.

## Summary

- **Start the gateway** using `clodds onboard` or `npm start` to bind the server to your configured port (default 18789).
- **Access the UI** at `http://localhost:<port>/webchat`, served by Express middleware in [`src/gateway/server.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/gateway/server.ts).
- **Connect via WebSocket** to `/chat` and optionally authenticate using `webchat.authToken` via query parameters or the auth message protocol defined in [`src/channels/webchat/index.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/channels/webchat/index.ts).
- **Send messages** as JSON payloads type `"message"`, which the gateway converts to `IncomingMessage` objects for routing.

## Frequently Asked Questions

### What is the default port for the CloddsBot WebChat UI?

The gateway defaults to port **18789** unless overridden by the `gateway.port` configuration value. The onboarding wizard and CLI reminders explicitly reference `http://localhost:18789/webchat` as the standard access point.

### Does WebChat work without configuring Telegram or Discord?

Yes. The WebChat channel operates independently of external messaging integrations. As noted in [`src/index.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/index.ts) (lines 53-58), the CLI explicitly confirms that the WebChat interface remains functional even when no other channels are configured.

### How do I secure the WebChat interface?

Enable the `webchat.authToken` configuration option. When set, the server validates this token against either the URL query string (`?token=...`) or the `auth` WebSocket message payload within the `createWebChatChannel` handler. Without a valid token, the connection cannot send or receive messages.

### Can I use WebChat for automated testing?

Yes. The repository includes integration tests in [`tests/integration/webchat-auth.test.ts`](https://github.com/alsk1992/CloddsBot/blob/main/tests/integration/webchat-auth.test.ts) that demonstrate automated connection, authentication, and message flow. You can replicate this pattern using the WebSocket client example to programmatically interact with the bot without browser automation.