timbot-ws

library2026.5.20jsnpmunverified

OpenClaw Tencent Cloud IM intelligent bot channel plugin via WebSocket SDK, version 2026.5.20. This plugin enables real-time chatbot functionality without requiring a public IP address, using WebSocket long connections instead of webhooks. It supports Multi-Agent mode via Worker threads and streaming messages with text_modify and custom_modify modes (but not TIMStreamElem). The package ships TypeScript types and is actively maintained by Tencent RTC. Key differentiators: zero-config deployment, private network support, and dm policies (open/allowlist/pairing/disabled).

messaging

npm install timbot-ws

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TIMBOT-WS

timbot-ws

messagingjavascriptv2026.5.20

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import TimbotWs from 'timbot-ws'

✗ const TimbotWs = require('timbot-ws')

ESM-only package; CommonJS require() is not supported.

type TimbotWsOptions

✓ import type { TimbotWsOptions } from 'timbot-ws'

✗ import { TimbotWsOptions } from 'timbot-ws'

Use 'import type' for type-only imports to avoid runtime errors in TypeScript.

TimbotWsConfig

✓ import { TimbotWsConfig } from 'timbot-ws'

✗ import type { TimbotWsConfig } from 'timbot-ws'

TimbotWsConfig is a runtime class, not a type; import as value.

Installs and configures timbot-ws with basic options including streaming mode and welcome text.

import { getOpenClaw } from 'openclaw'; import TimbotWs from 'timbot-ws'; const app = getOpenClaw(); app.useChannel('timbot-ws', { sdkAppId: 123456789, userId: 'bot_001', userSig: process.env.USER_SIG ?? 'your_user_sig_here', enabled: true, welcomeText: 'Hello! I am your bot.', typingText: 'Thinking...', streamingMode: 'text_modify', fallbackPolicy: 'strict', }); app.start();

Debug

Known issues

breakingstreamingMode 'tim_stream' is not supported

fix

Use 'off', 'text_modify', or 'custom_modify' instead.

affects: >=2026.5.20

deprecatedTop-level sdkAppId is deprecated; use accounts map for multi-account setups

fix

Migrate to accounts object with account-level config.

affects: >=2026.5.20

gotchaUserSig must be pre-generated and set; expires after configured duration

fix

Generate a long-lived UserSig (e.g., 10 years) via Tencent Cloud console.

affects: >=2026.5.20

gotchatypingDelayMs default 1000 may cause message ordering issues with very fast responses

fix

Set to 0 if responses are expected within the same second.

affects: >=2026.5.20

gotchadm.policy 'pairing' requires both parties to initiate; single-user interactions may fail

fix

Use 'open' or 'allowlist' for simple bot-user interactions.

affects: >=2026.5.20

Errors

Common errors & fixes

Error: Cannot find module 'timbot-ws'

Package not installed via openclaw plugins install

fix

Run `openclaw plugins install timbot-ws` in your project root.

TypeError: TimbotWs is not a constructor

Using CommonJS require on an ESM-only module

fix

Switch to ES module syntax: import TimbotWs from 'timbot-ws';

Error: Invalid sdkAppId

sdkAppId is not a number or missing

fix

Ensure sdkAppId is a positive integer (e.g., 123456789).

Error: UserSig expired

UserSig token has expired

fix

Generate a new UserSig with a longer validity (e.g., 315360000 seconds).

Upgrade

Version history

2026.5.20latest on npm

Audit

Dependencies

openclawrequiredpeer dependency; timbot-ws is an OpenClaw plugin

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Tencent-RTC/TIMBot-WS ↗

packagetimbot-ws ↗

homepagehttps://github.com/Tencent-RTC/TIMBot-WS#readme ↗