Webex Room ID Fetcher

A command-line tool to quickly find Webex room/space IDs by name using the Webex API. Perfect for automating workflows that need to interact with specific Webex spaces.

Features

• OAuth Authentication: Secure authentication with Webex using OAuth 2.0 flow
• Flexible Search: Find rooms by exact or partial name matching
• Self-Contained Script: Uses UV with PEP-723 inline metadata for portable execution
• Token Caching: Automatically handles and caches authentication tokens
• Rich CLI: Beautiful command-line interface with colored output and progress indicators
• Multiple Commands: Find rooms, list all rooms, or re-authenticate
• Runs Anywhere: Execute from any directory via shell aliases or direct path

Prerequisites

• Python 3.13 or higher
• UV dependency management system
• A Webex account

Installation

First, clone this repository:

git clone <repository-url>
cd webex-room-id-fetcher

Then, install dependencies using UV:

uv sync

Note: The script uses PEP-723 inline metadata, so it can also run independently without the project setup. Dependencies will be automatically managed by UV when the script is executed.

Then, set up Webex OAuth credentials:

• Go to Webex Developer Portal
• Click "Create a New App" → "Create an Integration"
• Fill in the details:
  • Integration Name: Your app name (e.g., "Room ID Fetcher")
  • Description: Brief description of your tool
  • Redirect URI: http://localhost:6001/callback
  • Scopes: spark:rooms_read
• Copy the Client ID and Client Secret
• Create a .env file in the project root:

# Webex OAuth Configuration
WEBEX_CLIENT_ID=your_client_id_here
WEBEX_CLIENT_SECRET=your_client_secret_here

# Optional: Set default maximum rooms to display (default: 100)
WEBEX_MAX_ROOMS=50

Then, make the script executable:

chmod +x main.py

Usage

First Run - Authentication

On first use, authenticate with Webex:

./main.py auth

This will open your browser for Webex authentication. After authorizing, tokens will be cached for future use.

Find a Room ID

# Find room by partial name (case-insensitive)
./main.py find "Project Alpha"

# Find room by exact name (case-sensitive)
./main.py find "Project Alpha Team" --exact

# Find room and list all rooms if no match found
./main.py find "Alpha" --list

List All Rooms

# List up to 100 rooms (default), sorted by most recent activity
./main.py list-rooms

# Limit to specific number of rooms
./main.py list-rooms --max-rooms 10

# Use environment variable to set default limit
export WEBEX_MAX_ROOMS=20
./main.py list-rooms

Re-authenticate

./main.py auth

Examples

# Find a room named "Marketing Team"
$ ./main.py find "Marketing Team"
⠋ Fetching rooms...
✓ Fetched 45 rooms
✓ Found room: Marketing Team
Y2lzY29zcGFyazovL3VzL1JPT00vYWJjZGVmZ2g=

# Find rooms containing "dev" (shows multiple matches)
$ ./main.py find "dev"
Found 3 matching rooms:
Development Team: Y2lzY29zcGFyazovL3VzL1JPT00vZGV2dGVhbQ==
DevOps: Y2lzY29zcGFyazovL3VzL1JPT00vZGV2b3Bz
Mobile Dev: Y2lzY29zcGFyazovL3VzL1JPT00vbW9iaWxlZGV2

# List rooms (sorted by recent activity, limited to 100 by default)
$ ./main.py list-rooms
⠋ Fetching rooms...
✓ Fetched 15 rooms
⠤ Sorting by activity...
Found 15 rooms (sorted by recent activity):

Engineering: Y2lzY29zcGFyazovL3VzL1JPT00vZW5naW5lZXJpbmc= (2024-01-15 14:30)
Marketing Team: Y2lzY29zcGFyazovL3VzL1JPT00vbWFya2V0aW5n (2024-01-14 09:15)
...

# List only 5 most recent rooms
$ ./main.py list-rooms --max-rooms 5
Showing 5 of 15 rooms (sorted by recent activity):
...

Integration with Shell Aliases

Add to your .zshrc or .bashrc:

alias webex-room-id="/path/to/webex-room-id-fetcher/main.py find"
alias webex-rooms="/path/to/webex-room-id-fetcher/main.py list-rooms"

Then use from anywhere:

# These work from any directory thanks to PEP-723 inline metadata
webex-room-id "My Room Name"
webex-rooms --max-rooms 10

Command Reference

find <room_name>

Find a Webex room ID by name.

Arguments:

• room_name: Name or partial name of the room to find

Options:

• --exact, -e: Require exact name match (case-sensitive)
• --list, -l: List all rooms if no match found

list-rooms [OPTIONS]

List Webex rooms you're a member of, sorted by most recent activity.

Options:

• --max-rooms INTEGER: Maximum number of rooms to display (default: 100). Can also be set via WEBEX_MAX_ROOMS environment variable.

auth

Authenticate with Webex or re-authenticate if already authenticated.

Troubleshooting

Authentication Issues

If you get authentication errors:

1. Run ./main.py auth to re-authenticate
2. Check that your Client ID and Client Secret are correct
3. Ensure the redirect URI in your Webex integration is exactly: http://localhost:6001/callback

Room Not Found

If a room isn't found:

• Try partial matching without --exact
• Use --list to see all available rooms
• Check that you're a member of the room you're searching for

Permission Issues

Make sure the script is executable:

chmod +x main.py

Technical Details

• Authentication: Uses OAuth 2.0 authorization code flow
• Token Storage: Tokens are cached in ~/.webex_tokens.json
• Dependencies: Self-contained using PEP-723 inline metadata with UV
• Portability: Script runs from any directory without project setup
• API: Uses the official Webex Python SDK

Security Notes

• Tokens are stored locally in your home directory
• The .env file and token file are ignored by git
• OAuth flow uses localhost redirect for security