Registry / communication / webex-node-bot-framework

webex-node-bot-framework

JSON →
library2.5.1jsnpmunverified

The webex-node-bot-framework is a Node.js framework designed to simplify the development of bots for Cisco Webex messaging. Currently stable at version 2.5.1, it provides an abstraction layer over the complex Webex For Developers APIs, streamlining tasks such as event registration and REST API calls. Unlike its inspiration, node-flint, this framework is built upon the actively supported webex-jssdk, ensuring compatibility with new Webex features. Developers migrating from node-flint should note that it is not backward compatible, requiring changes. The framework primarily focuses on enabling developers to implement bot interaction logic through 'handlers' for various message and membership events. It features recent enhancements in version 2.5.0, introducing `trigger.command` and `trigger.prompt` for more precise message parsing, and earlier updates in Version 2 for bot access restrictions. The project operates with community support, encouraging contributions and providing detailed migration guides and quickstart blogs for new users.

npm install webex-node-bot-framework
INSTALL
IMPORT
SIG · WEBEX-NODE-BOT-FRA
W
webex-node-bot-framework
communicationjavascriptv2.5.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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
musl
node 18226 runs
build_error
glibc
node 18226 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.
fix
Review 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.
fix
Consult 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.
fix
Use 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.
fix
Instruct 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.
fix
Set 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.
fix
Ensure `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`.
fix
Consult 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.
Upgrade
Version history
2.5.1latest on npm
Audit
Dependencies
webex-jssdkrequiredCore dependency; the framework is built on this SDK to interact with Webex APIs.
Agent activity
35 hits · last 30 days
node
30
OpenAI (training)
1
Resources
webex-node-bot-framework — npm install webex-node-bot-framework · libregistry