{"id":15286,"library":"webex-node-bot-framework","title":"Webex Node Bot Framework","description":"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.","status":"active","version":"2.5.1","language":"javascript","source_language":"en","source_url":"https://github.com/webex/webex-node-bot-framework","tags":["javascript","bot","bot framework","webex","webex teams","cisco"],"install":[{"cmd":"npm install webex-node-bot-framework","lang":"bash","label":"npm"},{"cmd":"yarn add webex-node-bot-framework","lang":"bash","label":"yarn"},{"cmd":"pnpm add webex-node-bot-framework","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency; the framework is built on this SDK to interact with Webex APIs.","package":"webex-jssdk","optional":false}],"imports":[{"note":"The primary class/constructor for the bot framework. CommonJS `require` is shown in older examples, but ESM import is preferred in modern Node.js.","wrong":"const Framework = require('webex-node-bot-framework');","symbol":"Framework","correct":"import Framework from 'webex-node-bot-framework';"},{"note":"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()`.","symbol":"Bot","correct":"import { Bot } from 'webex-node-bot-framework';"},{"note":"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`.","symbol":"Trigger","correct":"import { Trigger } from 'webex-node-bot-framework';"}],"quickstart":{"code":"import Framework from 'webex-node-bot-framework';\nimport express from 'express';\n\n// Ensure you have WEBEX_BOT_TOKEN and WEBEX_WEBHOOK_URL set in your environment\nconst WEBEX_BOT_TOKEN = process.env.WEBEX_BOT_TOKEN ?? '';\nconst WEBEX_WEBHOOK_URL = process.env.WEBEX_WEBHOOK_URL ?? ''; // e.g., ngrok URL or public domain\nconst PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : 8080;\n\nif (!WEBEX_BOT_TOKEN) {\n  console.error('WEBEX_BOT_TOKEN environment variable is not set.');\n  process.exit(1);\n}\n\nconst config = {\n  token: WEBEX_BOT_TOKEN,\n  webhookUrl: WEBEX_WEBHOOK_URL,\n  port: PORT,\n  // Optional: Set to true if running behind a proxy like ngrok, or if using websockets\n  // if webhookUrl is empty, it defaults to websocket mode.\n  // This example assumes webhookUrl is provided and requires express\n};\n\nconst app = express();\nconst framework = new Framework(config);\n\n// Initialize framework and bind to Express app for webhooks\nframework.listen(app, () => {\n  console.log(`Framework listening on port ${PORT}`);\n});\n\n// Log when the framework is initialized and ready\nframework.on('initialized', () => {\n  console.log('Framework initialized successfully!');\n});\n\n// Log when a new bot instance is spawned in a room\nframework.on('spawn', (bot, id, addedBy) => {\n  if (addedBy) {\n    bot.say('Hello! I am a simple echo bot. Mention me with \"echo [your message]\"');\n  } else {\n    console.log(`Bot already in space: ${bot.room.title}`);\n  }\n});\n\n// Example: Respond to 'echo' command\nframework.hears('echo', (bot, trigger) => {\n  const messageToEcho = trigger.prompt || 'Nothing to echo!';\n  bot.say('markdown', `_You said_: ${messageToEcho}`);\n}, '**echo [message]** - I will echo back your message.');\n\n// Graceful shutdown\nprocess.on('SIGINT', () => {\n  console.log('Stopping bot framework...');\n  framework.stop().then(() => {\n    console.log('Bot framework stopped.');\n    process.exit(0);\n  });\n});\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Migration 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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"Version 2 introduced new configuration options (`guideEmails`, `restrictedToEmailDomains`) for restricting bot access. Existing configurations might need updates to align with these new parameters.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"For 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.","severity":"gotcha","affected_versions":"All versions using webhooks"},{"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.","message":"In 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Set the `WEBEX_BOT_TOKEN` environment variable with a valid bot access token obtained from the Webex for Developers portal.","cause":"The bot's access token is missing, which is essential for authentication with Webex APIs.","error":"WEBEX_BOT_TOKEN environment variable is not set."},{"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.","cause":"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.","error":"Error: Webhook registration failed: The ngrok tunnel is not publicly accessible."},{"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.","cause":"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`.","error":"BadRequest: Currently moving room under another team is not supported in Developer API."}],"ecosystem":"npm"}