/agent-webexbot

name: agent-webexbot
description: Interact with Cisco Webex using bot tokens - send messages, reply in threads, upload and download files, look up people, read spaces, manage memberships, stream real-time events
version: 2.36.0
allowed-tools: Bash(agent-webexbot:*)
metadata:
  openclaw:
    requires:
      bins:
        - agent-webexbot
    install:
      - kind: node
        package: agent-messenger
        bins: [agent-webexbot]

Agent WebexBot

A TypeScript CLI tool that enables AI agents and humans to interact with Cisco Webex using **bot tokens** (created at [developer.webex.com](https://developer.webex.com/my-apps/new/bot)). Unlike `agent-webex` which authenticates as a real user account via browser extraction or OAuth, `agent-webexbot` uses the Webex REST API with a permanent bot identity — designed for server-side and CI/CD integrations.

Key Concepts

Before diving in, a few things about Webex Bot integration:

• **Bot tokens** — Created at developer.webex.com → My Webex Apps → Create a Bot. The token is shown once at creation time. Bot tokens never expire.
• **Bot ≠ User** — Messages appear from the bot's identity, not yours. The bot can only interact with spaces it has been added to.
• **Space IDs** — Webex uses opaque Base64-encoded IDs. You can't guess them. Always get IDs from `space list` first.
• **Real-time events** — Available via the `listen` command and the SDK's `WebexBotListener`. Uses the Mercury WebSocket protocol — no public URL required, works behind firewalls.
• **Loop prevention** — The listener filters the bot's own messages by default (`ignoreSelfMessages` is `true`), preventing echo loops.

Quick Start

# Set your bot token (validates against Webex)
agent-webexbot auth set YOUR_BOT_TOKEN

# Verify authentication
agent-webexbot whoami

# Send a message
agent-webexbot message send <space-id> "Hello from the bot!"

# Stream real-time events
agent-webexbot listen

Authentication

Bot Token Setup

`agent-webexbot` uses bot tokens which you create at [developer.webex.com](https://developer.webex.com/my-apps/new/bot):

# Set bot token (validates against Webex API before saving)
agent-webexbot auth set YOUR_BOT_TOKEN

# Set with a custom bot identifier
agent-webexbot auth set YOUR_BOT_TOKEN --bot deploy

# Check auth status
agent-webexbot auth status

# Clear all credentials
agent-webexbot auth clear

Multi-Bot Support

# List all configured bots
agent-webexbot auth list

# Switch active bot
agent-webexbot auth use <bot-id>

# Remove a bot
agent-webexbot auth remove <bot-id>

# Use a specific bot for a single command
agent-webexbot --bot deploy message send <space-id> "Deploy succeeded"

Memory

The agent maintains a `~/.config/agent-messenger/MEMORY.md` file as persistent memory across sessions. This is agent-managed — the CLI does not read or write this file. Use the `Read` and `Write` tools to manage your memory file.

What to Store

• Space IDs with titles (e.g. `Y2lzY29zcGFyazovL...` → "Engineering")
• Bot identifiers and their purposes
• User-given aliases ("the alerts bot", "the team space")

What NOT to Store

Never store bot tokens, credentials, or any sensitive data. Never store full message content (just IDs and space context).

Format / Example

# Agent Messenger Memory

## Webex Bots

- `deploy` — Deploy Bot (active)
- `alert` — Alert Bot

## Spaces (Deploy Bot)

- `Y2lzY29zcGFyazovL...` — Engineering (group)
- `Y2lzY29zcGFyazovL...` — #ci-alerts (group)

## Aliases

- "engineering" → `Y2lzY29zcGFyazovL...`
- "alerts" → `Y2lzY29zcGFyazovL...`

Commands

Auth Commands

# Set bot token
agent-webexbot auth set <token>
agent-webexbot auth set <token> --bot deploy

# Check auth status
agent-webexbot auth status
agent-webexbot auth status --bot deploy

# Clear all credentials
agent-webexbot auth clear

# List stored bots
agent-webexbot auth list

# Switch active bot
agent-webexbot auth use <bot-id>

# Remove a stored bot
agent-webexbot auth remove <bot-id>

Whoami Command

# Show current authenticated bot
agent-webexbot whoami
agent-webexbot whoami --pretty

Space Commands

# List spaces the bot is a member of
agent-webexbot space list
agent-webexbot space list --type group
agent-webexbot space list --type direct
agent-webexbot space list --max 20

# Get space details
agent-webexbot space info <space-id>

Message Commands

# Send a message to a space
agent-webexbot message send <space-id> <text>
agent-webexbot message send <space-id> "Hello world"

# Send a markdown message
agent-webexbot message send <space-id> "**Bold** and _italic_" --markdown

# Reply within a thread (parent message ID)
agent-webexbot message send <space-id> "Threaded reply" --parent <message-id>
agent-webexbot message reply <space-id> <parent-message-id> "Threaded reply"

# List replies in a thread
agent-webexbot message replies <space-id> <parent-message-id>
agent-webexbot message replies <space-id> <parent-message-id> --max 20

# Send a direct message by email
agent-webexbot message dm alice@example.com "Hey, quick question"
agent-webexbot message dm alice@example.com "**Build failed**" --markdown

# List messages in a space
# In group spaces, Webex only returns messages that mention the bot.
# Direct-space history is returned normally.
agent-webexbot message list <space-id>
agent-webexbot message list <space-id> --max 50

# Get a specific message
agent-webexbot message get <message-id>

# Edit a message (bot's own messages only)
agent-webexbot message edit <message-id> <space-id> "Updated text"
agent-webexbot message edit <message-id> <space-id> "**Updated**" --markdown

# Delete a message
agent-webexbot message delete <message-id>

Member Commands

# List members of a space
agent-webexbot member list <space-id>
agent-webexbot member list <space-id> --max 100

User Commands

Search the Webex people directo