Registry /
communication / webex-node-bot-framework
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Framework
✓ import Framework from 'webex-node-bot-framework';
✗ const Framework = require('webex-node-bot-framework');
The primary class/constructor for the bot framework. CommonJS `require` is shown in older examples, but ESM import is preferred in modern Node.js.
Bot
✓ import { Bot } from 'webex-node-bot-framework';
The 'bot' object is passed to handler functions (e.g., `framework.hears`). It represents the bot's instance in a specific space and provides methods like `bot.say()`.
Trigger
✓ import { Trigger } from 'webex-node-bot-framework';
The 'trigger' object is passed to handler functions, providing details about the incoming message or event, including `trigger.person`, `trigger.message`, and newer `trigger.command`, `trigger.prompt`.
Sets up a basic Webex bot that listens for 'echo' commands and responds by echoing the user's input. This demonstrates framework initialization, event handling, and basic messaging with Express for webhooks.
import Framework from 'webex-node-bot-framework';
import express from 'express';
// Ensure you have WEBEX_BOT_TOKEN and WEBEX_WEBHOOK_URL set in your environment
const WEBEX_BOT_TOKEN = process.env.WEBEX_BOT_TOKEN ?? '';
const WEBEX_WEBHOOK_URL = process.env.WEBEX_WEBHOOK_URL ?? ''; // e.g., ngrok URL or public domain
const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : 8080;
if (!WEBEX_BOT_TOKEN) {
console.error('WEBEX_BOT_TOKEN environment variable is not set.');
process.exit(1);
}
const config = {
token: WEBEX_BOT_TOKEN,
webhookUrl: WEBEX_WEBHOOK_URL,
port: PORT,
// Optional: Set to true if running behind a proxy like ngrok, or if using websockets
// if webhookUrl is empty, it defaults to websocket mode.
// This example assumes webhookUrl is provided and requires express
};
const app = express();
const framework = new Framework(config);
// Initialize framework and bind to Express app for webhooks
framework.listen(app, () => {
console.log(`Framework listening on port ${PORT}`);
});
// Log when the framework is initialized and ready
framework.on('initialized', () => {
console.log('Framework initialized successfully!');
});
// Log when a new bot instance is spawned in a room
framework.on('spawn', (bot, id, addedBy) => {
if (addedBy) {
bot.say('Hello! I am a simple echo bot. Mention me with "echo [your message]"');
} else {
console.log(`Bot already in space: ${bot.room.title}`);
}
});
// Example: Respond to 'echo' command
framework.hears('echo', (bot, trigger) => {
const messageToEcho = trigger.prompt || 'Nothing to echo!';
bot.say('markdown', `_You said_: ${messageToEcho}`);
}, '**echo [message]** - I will echo back your message.');
// Graceful shutdown
process.on('SIGINT', () => {
console.log('Stopping bot framework...');
framework.stop().then(() => {
console.log('Bot framework stopped.');
process.exit(0);
});
});
Debug
Known issues
breakingMigration from the `node-flint` framework is not backward compatible due to a rewrite based on `webex-jssdk` and changes in data handling and API call minimization strategies.fixReview the migration guide (`./docs/migrate-from-node-flint.md`) and refactor bot logic, particularly around accessing Webex object details and utilizing bot functions, as some have been removed or simplified.
affects: >=2.0.0
breakingVersion 2 introduced new configuration options (`guideEmails`, `restrictedToEmailDomains`) for restricting bot access. Existing configurations might need updates to align with these new parameters.fixConsult the `Membership-Rules README` (as mentioned in the original README) to understand and implement the new configuration parameters if access restriction is desired or if previous custom implementations are no longer compatible.
affects: >=2.0.0
gotchaFor webhook-based bots, your `webhookUrl` must be publicly accessible. During local development, this often requires tools like `ngrok` or similar tunneling services. Failure to do so will prevent Webex from sending events to your bot.fixUse a tunneling service like ngrok (`ngrok http <your-port>`) to expose your local development server to the internet, or deploy to a publicly accessible server. Alternatively, remove `webhookUrl` from the config to use WebSocket mode for local development, which does not require a public URL.
affects: All versions using webhooks
gotchaIn group spaces, the bot must be at-mentioned (`@YourBotName`) for `framework.hears()` handlers to be triggered. Messages not explicitly mentioning the bot are generally ignored unless configured otherwise.fixInstruct users to explicitly mention the bot in group conversations. Ensure your `framework.hears()` patterns account for the bot's mention in the message.
affects: All versions
Errors
Common errors & fixes
WEBEX_BOT_TOKEN environment variable is not set.
The bot's access token is missing, which is essential for authentication with Webex APIs.
fixSet the `WEBEX_BOT_TOKEN` environment variable with a valid bot access token obtained from the Webex for Developers portal.
Error: Webhook registration failed: The ngrok tunnel is not publicly accessible.
The configured `webhookUrl` (e.g., an ngrok URL) is either invalid, expired, or the ngrok process is not running, preventing Webex from registering a valid webhook endpoint.
fixEnsure `ngrok` is running and correctly tunneling to your bot's configured port, and that the `WEBEX_WEBHOOK_URL` environment variable is updated with the current ngrok public URL. Restart your bot application after updating.
BadRequest: Currently moving room under another team is not supported in Developer API.
Attempting to perform an API operation, such as `bot.roomRename`, that is not supported by the current version of the Webex Developer API or the underlying `webex-jssdk`.
fixConsult the Webex for Developers API documentation for the specific endpoint (`/v1/rooms`) to ensure the operation is supported and to understand any current limitations. If the operation is critical, consider alternative approaches or check for updates to the Webex SDK or framework.
Audit
Dependencies
webex-jssdkrequiredCore dependency; the framework is built on this SDK to interact with Webex APIs.