Webex Node Bot Framework

Common errors

• WEBEX_BOT_TOKEN environment variable is not set.

  cause 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.

  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.
  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.

  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`.
  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.

Warnings

• breaking 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.
  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.
• breaking Version 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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install webex-node-bot-framework npm
• yarn add webex-node-bot-framework yarn
• pnpm add webex-node-bot-framework pnpm

Imports

• Framework
  wrong:

  const Framework = require('webex-node-bot-framework');

  correct:

  import Framework from '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`.

Quickstart

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);
  });
});