@bitbasti/chat-adapter-webex

Community Webex adapter for Chat SDK.

Installation

Usage

import { Chat } from "chat";import { createWebexAdapter } from "@bitbasti/chat-adapter-webex";const bot = new Chat({  userName: "mybot",  adapters: {    webex: createWebexAdapter({      botToken: process.env.WEBEX_BOT_TOKEN!,      webhookSecret: process.env.WEBEX_WEBHOOK_SECRET,    }),  },});bot.onNewMention(async (thread, message) => {  await thread.post(`Hello from Webex! You said: ${message.text}`);});

import { Chat } from "chat";import { createWebexAdapter } from "@bitbasti/chat-adapter-webex";const bot = new Chat({  userName: "mybot",  adapters: {    webex: createWebexAdapter({      botToken: process.env.WEBEX_BOT_TOKEN!,      webhookSecret: process.env.WEBEX_WEBHOOK_SECRET,    }),  },});bot.onNewMention(async (thread, message) => {  await thread.post(`Hello from Webex! You said: ${message.text}`);});

Environment variables

Variable	Required	Description
`WEBEX_BOT_TOKEN`	Yes	Bot access token from the Webex Developer Portal
`WEBEX_WEBHOOK_SECRET`	Recommended	Shared secret for webhook signature verification
`WEBEX_BASE_URL`	No	Override the Webex API base URL (default: `https://webexapis.com/v1`)
`WEBEX_BOT_USERNAME`	No	Override the bot display name

Configuration

Option	Type	Default	Description
`botToken`	`string`	`WEBEX_BOT_TOKEN`	Bot access token
`webhookSecret`	`string`	`WEBEX_WEBHOOK_SECRET`	Shared secret for verifying webhook signatures
`baseUrl`	`string`	`"https://webexapis.com/v1"`	Webex API base URL
`userName`	`string`	`"webex-bot"`	Bot display name (overridden by the bot's Webex profile on initialization)
`botUserId`	`string`	Auto-detected via `/people/me`	Webex person ID of the bot (skips the `/people/me` call if provided)
`logger`	`Logger`	`ConsoleLogger`	Custom logger instance

Platform setup

Go to the Webex Developer Portal and sign in.
Navigate to My Webex Apps → Create a New App → Create a Bot.
Fill in the bot name, username, and icon, then click Add Bot.
Copy the Bot Access Token — this is your WEBEX_BOT_TOKEN. Store it securely; it is only shown once.
Create a webhook pointing to your server:
- Target URL: https://your-domain.com/api/webhooks/webex
- Resource: messages | Event: created
- Resource: attachmentActions | Event: created
- Secret: a random string — this is your WEBEX_WEBHOOK_SECRET
Add the bot to a Webex space and mention it to verify the integration.

See the Webex Webhooks Guide for details on webhook registration.

Features

Mentions and DMs
Rich text (bold, italic, code, links) via Markdown
Adaptive Cards (buttons, selects, radio selects, fields, sections)
Modals (form cards with submit/close actions)
File uploads (single file per message)
Thread support (parentId-based threading)
Webhook signature verification (HMAC-SHA1)

Limitations

Reactions are not supported by Webex bot tokens — addReaction / removeReaction throw NotImplementedError
Typing indicators are not available in the Webex Messaging API
Only one file upload per message is supported
Cards and file uploads cannot be combined in the same message

License

MIT