Zoom

Name: Zoom
Rating: 3.5 (1 reviews)
Author: agent-plex

By agent-plex 👁 1 views ▲ 0 votes

Zoom Team Chat channel plugin for OpenClaw — WebSocket mode, no public URL required 🦞

GitHub

Install

npm install @plexlabs/openclaw-zoom

Configuration Example

{
  "channels": {
    "zoom": {
      "clientId": "your_zoom_client_id",
      "clientSecret": "your_zoom_client_secret",
      "botJid": "[email protected]",
      "subscriptionId": "your_subscription_id",
      "dmPolicy": "open",
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["allowed_channel_jid"]
    }
  }
}

README

# @plexlabs/openclaw-zoom

**Zoom Team Chat channel plugin for OpenClaw** — WebSocket mode, no public URL required.

This is the **first Zoom Team Chat plugin** for the OpenClaw ecosystem, enabling AI agents to send and receive messages via Zoom Team Chat using WebSocket delivery.

Built with ⚡ by [Plex Labs](https://plexlabs.ai)

---

## Features

- ✅ **WebSocket-based** — No webhooks, no public URL needed
- ✅ **Works behind NAT** — Perfect for local development and private networks
- ✅ **Auto-reconnect** — Exponential backoff on connection failures
- ✅ **Proactive token refresh** — Refreshes OAuth tokens before expiry
- ✅ **Security policies** — DM and group allowlists
- ✅ **Markdown support** — Send formatted messages
- ✅ **TypeScript** — Fully typed for better DX

---

## Prerequisites

- **OpenClaw** >= 2026.3.0
- **Node.js** >= 18.0.0
- **Zoom account** with Team Chat enabled
- **Zoom App** created on marketplace.zoom.us

### Zoom Plan Requirements

Zoom Team Chat is available on:
- Zoom Pro, Business, or Enterprise plans
- Team Chat must be enabled in your account settings

---

## Installation

```bash
npm install @plexlabs/openclaw-zoom
```

---

## Setup

### 1. Create a Zoom App

1. Go to [Zoom Marketplace](https://marketplace.zoom.us/)
2. Click **Develop** → **Build App**
3. Choose **Team Chat App**
4. Fill in basic information:
   - **App Name**: OpenClaw Bot (or your preferred name)
   - **Description**: AI-powered chatbot for Zoom Team Chat
   - **Company Name**: Your company/organization

### 2. Configure App Scopes

Navigate to **Scopes** and add:
- `imchat:bot` — Required for sending/receiving messages

### 3. Enable Features

Go to **Features** → **Team Chat**:
- Enable **Chatbot**
- Note down the **Bot JID** (looks like `[email protected]`)

### 4. Set Up Event Subscriptions

1. Go to **Features** → **Event Subscriptions**
2. Select **Use WebSocket**
3. Copy the **Subscription ID**
4. Subscribe to event types:
   - `chat_message.sent` — Receive messages sent to the bot

### 5. Get Credentials

Navigate to **App Credentials**:
- Copy **Client ID**
- Copy **Client Secret**

### 6. Activate the App

1. Go to **Activation**
2. Install the app to your Zoom account
3. Authorize the requested permissions

---

## Configuration

Add the Zoom configuration to your `openclaw.json`:

```json
{
  "channels": {
    "zoom": {
      "clientId": "your_zoom_client_id",
      "clientSecret": "your_zoom_client_secret",
      "botJid": "[email protected]",
      "subscriptionId": "your_subscription_id",
      "dmPolicy": "open",
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["allowed_channel_jid"]
    }
  }
}
```

### Configuration Options

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `clientId` | string | ✅ | Zoom App Client ID |
| `clientSecret` | string | ✅ | Zoom App Client Secret |
| `botJid` | string | ✅ | Bot JID from Features page |
| `subscriptionId` | string | ✅ | Event Subscription ID |
| `dmPolicy` | string | ❌ | DM security: `open`, `allowlist`, `pairing` (default: `open`) |
| `allowFrom` | string[] | ❌ | Allowed user JIDs for DMs (when `dmPolicy: "allowlist"`) |
| `groupPolicy` | string | ❌ | Group security: `open`, `allowlist` (default: `open`) |
| `groupAllowFrom` | string[] | ❌ | Allowed channel JIDs for groups |

### Security Policies

**DM Policy** (`dmPolicy`):
- `open` — Accept DMs from anyone
- `allowlist` — Only accept DMs from users in `allowFrom` list
- `pairing` — Require device pairing (not yet implemented)

**Group Policy** (`groupPolicy`):
- `open` — Respond in all channels where the bot is added
- `allowlist` — Only respond in channels listed in `groupAllowFrom`

---

## Usage

### Starting OpenClaw

Once configured, start OpenClaw:

```bash
openclaw gateway start
```

The Zoom plugin will:
1. Fetch an OAuth token using client credentials
2. Connect to Zoom WebSocket
3. Start receiving messages
4. Send heartbeats every 30 seconds
5. Auto-reconnect on disconnection
6. Proactively refresh tokens before expiry

### Sending Messages

Messages sent from OpenClaw to Zoom will be delivered via the REST API with markdown support.

### Finding JIDs

To find user or channel JIDs for allowlists:
- User JIDs are typically visible in message payloads
- You can enable temporary `open` policy and check logs for JIDs
- Zoom support: [Chatbot Development Guide](https://developers.zoom.us/docs/team-chat-apps/chatbots/)

---

## Architecture

### WebSocket Connection

```
┌─────────────┐         OAuth Token          ┌─────────────┐
│             │ ◄─────────────────────────── │             │
│  OpenClaw   │                               │    Zoom     │
│             │ ──────────────────────────► │             │
└─────────────┘    WebSocket (wss://)         └─────────────┘
       │                                             │
       │          Inbound: bot_notification          │
       │ ◄───────────────────────────────────────── │
       │                                             │
       │          Outbound: REST API                 │
       │ ──────────────────────────────────────────► │
       │         POST /v2/im/chat/messages           │
```

### Components

- **`ZoomClient`** — OAuth token management and REST API calls
- **`ZoomWebSocketManager`** — WebSocket connection, heartbeat, reconnection
- **`zoomChannelPlugin`** — OpenClaw channel adapter (config, security, outbound)

### Token Lifecycle

1. Fetch token with `grant_type=client_credentials`
2. Token expires in 60 minutes
3. **Proactive refresh** at 55 minutes
4. Token used for WebSocket connection and API calls

### Reconnection Strategy

- Initial backoff: 1 second
- Exponential backoff: doubles each attempt
- Max backoff: 60 seconds
- Resets on successful connection

---

## Development

### Build

```bash
npm run build
```

### Watch Mode

```bash
npm run watch
```

### Testing

```bash
npm test
```

---

## Troubleshooting

### WebSocket Won't Connect

**Symptom**: `[Zoom WS] Connection failed`

**Solutions**:
1. Verify `subscriptionId` is correct
2. Check that OAuth token is valid (`clientId` and `clientSecret`)
3. Ensure event subscriptions are enabled in Zoom App settings
4. Check network firewall allows WebSocket connections to `wss://ws.zoom.us`

### Token Refresh Failures

**Symptom**: `Zoom OAuth failed: 401`

**Solutions**:
1. Verify `clientId` and `clientSecret` are correct
2. Ensure app is activated in Zoom Marketplace
3. Check app hasn't been deauthorized

### Messages Not Received

**Symptom**: Bot doesn't respond to messages

**Solutions**:
1. Check `dmPolicy` and `groupPolicy` settings
2. Verify sender's JID is in `allowFrom` (if using `allowlist`)
3. Ensure bot is added to the channel (for group messages)
4. Check OpenClaw logs for errors

### Messages Not Sent

**Symptom**: `Send failed`

**Solutions**:
1. Verify `botJid` is correct
2. Check recipient JID format (should be `[email protected]` or channel JID)
3. Ensure bot has `imchat:bot` scope
4. Check Zoom API rate limits

---

## Limitations

- **Single account only** — Multi-account support not yet implemented
- **No threading** — Zoom Team Chat doesn't expose thread/reply IDs via API
- **No reactions** — Not supported by Zoom API
- **No message editing/deletion** — Not supported by current Zoom API
- **No attachments** — Not yet implemented (Zoom supports it)

---

## Roadmap

- [ ] Pairing policy implementation
- [ ] Multi-account support
- [ ] Attachment support (images, files)
- [ ] Rich message formatting (cards, buttons)
- [ ] Slash commands
- [ ] Interactive setup wizard
- [ ] Rate limit handling with backoff

---

## Contributing

Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Submit a pull request

---

## License

MIT — see [LICENSE](./LICENSE)

---

## Credits

Built by **Plex Labs** — [plexlabs.ai](https://plexlabs.ai)

Part of the [OpenClaw](https://github.com/openclaw/openclaw) ecosystem.

---

## Support

- **Issues**: [GitHub Issues](https://github.com/agent-plex/openclaw-zoom/issues)
- **Discussions**: [GitHub Discussions](https://github.com/agent-plex/openclaw-zoom/discussions)
- **Zoom Docs**: [Team Chat Apps](https://developers.zoom.us/docs/team-chat-apps/)
- **OpenClaw Docs**: [openclaw.dev](https://openclaw.dev)

---

**Made with ⚡ by Plex Labs**

channels