Webex

Tip: agent-webex is a shortcut for agent-messenger webex.

Quick Start

# 1. Extract token from browser (recommended — messages appear as you)
agent-webex auth extract

# 2. Get workspace snapshot
agent-webex snapshot

# 3. Send a message
agent-webex message send <space-id> "Hello from AI agent!"

Authentication

Browser Token Extraction (Recommended)

Extracts your first-party Webex session token from a Chromium browser where you're logged into web.webex.com. Messages appear as you — no "via agent-messenger" label. Zero-config.

agent-webex auth extract
agent-webex auth extract --browser-profile ~/browser-data
agent-webex auth extract --browser-profile "$HOME/work-profile,$HOME/personal-profile"

This command:

• Scans Chromium browser profiles for Webex localStorage data (LevelDB)
• Extracts the first-party supertoken, device URL, and user ID
• Extracts cached KMS encryption keys for end-to-end encrypted messaging
• Validates the token against the Webex API
• Stores credentials and encryption keys in ~/.config/agent-messenger/
• Supported browsers: Chrome, Chrome Canary, Edge, Arc, Brave, Vivaldi, Chromium
• Supports --browser-profile <path> for agent-browser profiles, custom Chrome user data dirs, or portable browser profiles; repeatable and comma-separated values are accepted
• Auto-extraction runs when no valid token is stored, so manual extraction is rarely needed
• Messages are encrypted client-side (JWE/AES-256-GCM). Encryption keys are cached at extract time; for end-to-end encrypted conversations whose key is not cached, the key is fetched on demand (Mercury + KMS) and persisted for reuse. Non-encrypted conversations send as plaintext.

Email/Password Login

Logs in with a Webex email and password — no browser. Useful for servers and CI/CD that need a real user token (e.g. for the real-time listener, which receives all space messages without an @mention). Run agent-webex auth login with no flags in a terminal to be prompted for your email and then your password (read without echoing); for headless use, pipe the password via stdin to keep it out of shell history.

# Interactive — prompts for email, then password (hidden)
agent-webex auth login

# Headless — provide the email and pipe the password from stdin
printf '%s' "$WEBEX_PASSWORD" | agent-webex auth login --email you@example.com --password-stdin

# Provide the email only — password is prompted securely
agent-webex auth login --email you@example.com

• Discovers the user's Webex region, performs OAuth2 Authorization Code + PKCE against Cisco IdBroker, and stores access/refresh tokens in ~/.config/agent-messenger/
• Produces a KMS-scoped user token (client-side JWE/AES-256-GCM encryption works)
• --idbroker-host <host> overrides region auto-discovery if needed
• Accounts protected by SSO/IdP or MFA are not supported and fail with a clear error

OAuth Device Grant (Fallback)

Uses OAuth Device Grant flow with built-in Integration credentials. No tokens to copy, no developer portal setup needed. Messages show "via agent-messenger".

agent-webex auth oauth

This command:

• Requests a device code from Webex
• Opens your browser to the Webex verification page
• Displays a user code for you to enter
• Polls automatically until you approve
• Stores access and refresh tokens securely in ~/.config/agent-messenger/
• Auto-refreshes expired access tokens (14-day access, 90-day refresh)

How Login Works

1. Run agent-webex auth extract (recommended), agent-webex auth login (email/password), or agent-webex auth oauth (Device Grant)
2. For extraction: CLI reads your browser's Webex session — no prompts needed
3. For email/password: CLI prompts for any missing credentials, then exchanges them for a token
4. For Device Grant: Browser opens, enter the displayed code, CLI stores tokens
5. Access tokens are refreshed automatically

Token Types

Authentication Commands

# Extract token from browser (recommended)
agent-webex auth extract

# Log in with email/password (prompts when flags are omitted)
agent-webex auth login
printf '%s' "$WEBEX_PASSWORD" | agent-webex auth login --email you@example.com --password-stdin

# Log in via OAuth Device Grant (opens browser)
agent-webex auth oauth

# Log in via OAuth with custom Integration credentials
agent-webex auth oauth --client-id <id> --client-secret <secret>

# Log in with a bot token (never expires)
agent-webex auth login --token <bot-token>

# Log in with a PAT (12-hour lifetime)
agent-webex auth login --token <pat>

# Check auth status
agent-webex auth status

# Log out (clear stored credentials)
agent-webex auth logout

Environment Variables

Override the built-in Integration credentials with your own:

Both must be set together. When set, auth oauth uses these instead of the built-in credentials.

Commands

Whoami Command

# Show current authenticated user
agent-webex whoami
agent-webex whoami --pretty

Output includes the authenticated user's identity information.

Space Commands

Webex organizes conversations into "spaces" (group spaces and direct messages).

# List spaces
agent-webex space list
agent-webex space list --type group
agent-webex space list --type direct
agent-webex space list --limit 20

# Get space info
agent-webex space info <space-id>

Message Commands

# Send a message
agent-webex message send <space-id> <text>
agent-webex message send abc123 "Hello world"

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

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

# List messages in a space
agent-webex message list <space-id>
agent-webex message list abc123 --limit 50

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

# Edit a message
agent-webex message edit <message-id> <space-id> <text>
agent-webex message edit msg123 abc123 "Updated text" --markdown

# Delete a message
agent-webex message delete <message-id>
agent-webex message delete <message-id> --force

# Send a typing indicator ("…is typing")
agent-webex message typing <space-id>
# Clear the typing indicator
agent-webex message typing <space-id> --stop

Typing indicators require an extracted (browser) or password token — bot and OAuth tokens are not supported. The indicator is ephemeral and auto-expires after a few seconds.

Member Commands

# List members of a space
agent-webex member list <space-id>
agent-webex member list abc123 --limit 100

File Commands

# Upload a local file to a space
agent-webex file upload <space-id> <path>
agent-webex file upload abc123 ./report.pdf --text "Latest report"
agent-webex file upload abc123 ./image.png --text "**Done**" --markdown

# Download a file attachment by content URL or ID
agent-webex file download <content-url-or-id>
agent-webex file download <content-url-or-id> ./out.pdf

Snapshot Command

Get workspace overview for AI agents (brief by default):

# Brief snapshot (default) — fast, minimal output
agent-webex snapshot

# Full snapshot — includes type and lastActivity
agent-webex snapshot --full

Default returns brief JSON with:

• Spaces (id, ref, title) — only spaces you're a member of
• Hint for next commands

With --full, returns:

• Spaces (id, ref, title, type, lastActivity)

For messages or members, use message list <space-id> or member list <space-id>.

Global Options

All commands support these options:

--pretty      # Pretty-print JSON output (default is compact JSON)

Key Differences: Webex vs Slack vs Discord vs Teams

Troubleshooting

"Not authenticated"

No credentials stored. Log in first:

agent-webex auth login

Token Expired (401 Unauthorized)

If using Device Grant: Tokens auto-refresh. If you still get 401s, the refresh token may have expired (after 90 days). Re-run:

agent-webex auth oauth

If using a PAT: Generate a new one at https://developer.webex.com/docs/getting-started

If using a bot token: Bot tokens don't expire. Double-check the full token was copied correctly.

"Device authorization timed out"

You didn't approve the request in the browser before the code expired. Run auth oauth again:

agent-webex auth oauth

"Device authorization failed"

Possible causes:

• Network connectivity issues
• Custom client ID is invalid or revoked
• Webex API is temporarily unavailable

Rate Limiting (429 Too Many Requests)

Webex allows roughly 600 API calls per minute. Wait a few seconds and retry:

# Add delays between operations in scripts
sleep 1

Space or Message Not Found

Webex uses opaque Base64-encoded IDs. You can't guess them. Always get IDs from space list or snapshot first:

agent-webex space list --pretty

agent-webex: command not found

The npm package is agent-messenger, not agent-webex:

npm install -g agent-messenger

AI Agent Integration

See skills/agent-webex/ for:

• Complete skill documentation
• Common patterns and runnable templates

Example: AI Agent Workflow

#!/bin/bash
# Example: Daily standup automation

# 1. Check auth
if ! agent-webex auth status | jq -e '.authenticated' > /dev/null 2>&1; then
  echo "Not authenticated. Run 'agent-webex auth login' first."
  exit 1
fi

# 2. Get workspace context
agent-webex snapshot > /tmp/webex-context.json

# 3. Send standup reminder
agent-webex message send $STANDUP_SPACE "Good morning! Time for standup."

Send and Track Pattern

#!/bin/bash
# Send a message, then update it later

SPACE_ID="Y2lzY29zcGFyazovL..."

# Send initial status
RESULT=$(agent-webex message send "$SPACE_ID" "Deploying v2.1.0...")
MSG_ID=$(echo "$RESULT" | jq -r '.id')

# ... do work ...
sleep 5

# Update the message with final status
agent-webex message edit "$MSG_ID" "$SPACE_ID" "Deployed v2.1.0 successfully!"