OpenClaw RingCentral Channel

RingCentral Team Messaging channel plugin for OpenClaw.

Overview

Use this plugin when you want an OpenClaw agent to receive and send RingCentral Team Messaging conversations through a RingCentral Bot Add-in.

It supports:

• Direct messages with pairing, allowlist, open, or disabled policy.
• RingCentral Team and Everyone chats as channel surfaces.
• RingCentral Group conversations as group DMs, disabled by default and enabled only by explicit allowlist.
• Threaded replies, mention gates, per-chat user allowlists, and per-chat system prompts.
• Inbound file/image attachment download into OpenClaw managed media storage.
• Shared OpenClaw message actions for send/read/edit/delete/channel-info.
• Optional ringcentral_get_recent_messages, Adaptive Card, note, and calendar event tools.

RingCentral Team chats are topic-oriented chats, while Group conversations are member-set conversations. See the RingCentral Team Messaging Teams documentation for the platform model this plugin follows.

Human Install

1. Install The Plugin

Install through the OpenClaw plugin manager:

openclaw plugins install npm:openclaw-ringcentral
openclaw plugins enable ringcentral
openclaw gateway restart

Use npm install openclaw-ringcentral only for package inspection or local plugin development. Normal OpenClaw installs should go through the plugin manager so OpenClaw can register the channel, tool contracts, and hook metadata.

2. Create A RingCentral Bot

Create a RingCentral Bot Add-in app with Team Messaging and WebSocket Subscriptions permissions, then copy the bot static token.

Optional owner credentials are only needed for owner-backed operations such as recent message history and Home-confirmed note/calendar writes. If you need those flows, create a JWT REST API app for the owner user with Team Messaging, WebSocket Subscriptions, Read Accounts, and Read Messages permissions.

3. Configure The Channel

Minimal bot-only config:

{
  "channels": {
    "ringcentral": {
      "enabled": true,
      "botToken": "your-bot-static-token"
    }
  }
}

The same bot token can also be supplied as RC_BOT_TOKEN.

4. Route RingCentral To An Agent

Use a dedicated agent for RingCentral traffic. This keeps RingCentral conversation state separate from webchat/TUI debugging and avoids global coding tool profiles hiding optional ringcentral_* tools.

{
  "agents": {
    "defaults": {
      "model": "your-default-model"
    },
    "list": [
      { "id": "main", "default": true },
      {
        "id": "ringcentral-bot",
        "tools": {
          "profile": null
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "ringcentral-bot",
      "match": {
        "channel": "ringcentral"
      }
    }
  ]
}

Set tools.allow only for optional tools you want the RingCentral agent to use.

AI-Assisted Install

When installing this plugin for a user, use this checklist:

1. Inspect the existing OpenClaw config for channels.ringcentral, existing agents, and existing bindings.
2. Install and enable the plugin through OpenClaw's plugin manager, not by manually editing package files.
3. Ask for or provision the RingCentral bot static token, then set channels.ringcentral.botToken or RC_BOT_TOKEN.
4. Write canonical config under channels.ringcentral. Do not add legacy fields such as allowedChannels, allowedUserEmails, or groups.
5. Prefer stable RingCentral person IDs for DM allowlists and explicit chat IDs for Team/Group allowlists.
6. Add a dedicated ringcentral-bot agent and channel binding unless the user already has a clear RingCentral-specific agent.
7. Enable optional ringcentral_* tools only when requested. Keep tools.profile: null on the RingCentral agent if the user's global profile would hide channel tools.
8. For artifact tools in RingCentral Teams or Group DMs, ensure the target chat is explicitly allowlisted with teams.<chatId>.allow=true or dm.groupChannels.<chatId>.allow=true.
9. Restart the OpenClaw gateway and verify the bot can receive one admitted message and send one reply.

Example AI-generated config patch:

{
  "channels": {
    "ringcentral": {
      "enabled": true,
      "botToken": "your-bot-static-token",
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist",
      "teams": {
        "123456789": {
          "allow": true,
          "requireMention": true
        }
      }
    }
  },
  "agents": {
    "list": [
      {
        "id": "ringcentral-bot",
        "tools": {
          "profile": null
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "ringcentral-bot",
      "match": {
        "channel": "ringcentral"
      }
    }
  ]
}

Configuration Recipes

Bot-Only Default

This is enough for paired DMs and bot-authenticated sends:

{
  "channels": {
    "ringcentral": {
      "enabled": true,
      "botToken": "your-bot-static-token"
    }
  }
}

DM Allowlist

{
  "channels": {
    "ringcentral": {
      "enabled": true,
      "botToken": "your-bot-static-token",
      "dmPolicy": "allowlist",
      "allowFrom": ["sender-person-id"]
    }
  }
}

dmPolicy defaults to pairing. dmPolicy: "open" requires allowFrom: ["*"]. allowFrom matches stable RingCentral person IDs by default. Email matching is disabled unless dangerouslyAllowEmailMatching: true is set.

Team Allowlist

{
  "channels": {
    "ringcentral": {
      "enabled": true,
      "botToken": "your-bot-static-token",
      "groupPolicy": "allowlist",
      "teams": {
        "*": {
          "requireMention": true
        },
        "123456789": {
          "allow": true,
          "requireMention": true,
          "users": ["sender-person-id"],
          "systemPrompt": "Answer as the RingCentral support bot."
        }
      }
    }
  }
}

teams."*" is only a default entry. It can provide settings such as requireMention, but it does not allow every Team and does not authorize the artifact bot-token path.

Group DM Allowlist

RingCentral Group conversations are ignored by default. Enable only explicit group DMs:

{
  "channels": {
    "ringcentral": {
      "enabled": true,
      "botToken": "your-bot-static-token",
      "dm": {
        "groupEnabled": true,
        "groupChannels": {
          "987654321": {
            "allow": true,
            "requireMention": false,
            "users": ["sender-person-id"]
          }
        }
      }
    }
  }
}

Threads And Replies

{
  "channels": {
    "ringcentral": {
      "replyToMode": "first",
      "threadRequireMention": false,
      "noThreadChannels": ["123456789"]
    }
  }
}

replyToMode can be off, first, or all. When threadRequireMention=false, replies inside a thread where the bot already participated can activate the bot without a new mention.

Attachments And Processing Placeholder

{
  "channels": {
    "ringcentral": {
      "attachments": {
        "enabled": true,
        "maxCount": 5,
        "maxBytes": 5242880
      },
      "processingPlaceholder": {
        "enabled": true,
        "initialText": "Working...",
        "delayedText": "Still working...",
        "editDelaySeconds": 2
      }
    }
  }
}

Artifact Tools

Enable only the artifact tools your RingCentral agent should use:

{
  "tools": {
    "allow": [
      "ringcentral_create_adaptive_card",
      "ringcentral_create_note",
      "ringcentral_create_calendar_event"
    ]
  }
}

Artifact target resolution order is:

1. Explicit chat_id, chatId, or target.
2. Current RingCentral Team/Group chat injected by the plugin's before_tool_call hook.
3. homeChannel or RC_HOME_CHANNEL.

If the resolved chat is explicitly allowlisted with teams.<chatId>.allow=true or dm.groupChannels.<chatId>.allow=true, Adaptive Card, note, and calendar event artifact tools use the bot token directly. Bot token failures are returned directly and do not fall back to owner credentials.

For object-ID tools such as ringcentral_get_note, ringcentral_update_note, ringcentral_get_calendar_event, and ringcentral_delete_adaptive_card, chat_id is only the authorization context. The RingCentral API still operates on the object ID.

When OpenClaw supplies agent-scoped config to a channel tool, artifact tools fall back to the plugin runtime's full OpenClaw config before reading RC_TEAMS or RC_GROUP_DM_CHANNELS. Normal JSON config under channels.ringcentral therefore remains authoritative for artifact allowlists.

Owner Credentials And Home Confirmation

{
  "channels": {
    "ringcentral": {
      "enabled": true,
      "botToken": "your-bot-static-token",
      "homeChannel": "home-chat-id",
      "homeChannelName": "RingCentral Home",
      "ownerCredentials": {
        "clientId": "owner-app-client-id",
        "clientSecret": "owner-app-client-secret",
        "jwt": "owner-jwt-token"
      }
    }
  },
  "tools": {
    "allow": ["ringcentral_get_recent_messages"]
  }
}

homeChannel is the default chat for history/artifact tools when neither an explicit target nor a current RingCentral Team/Group target is available. For non-allowlisted targets, owner-backed note and calendar writes keep the Home confirmation flow through ringcentral_confirm_artifact_action. Owner-backed reads outside Home are rejected. Adaptive Card tools are bot-token tools and require Home or an allowlisted target.

credentials is still accepted as a deprecated alias for ownerCredentials, but new configs should use ownerCredentials.

Targets And Tools

Canonical Targets

Legacy ringcentral:*, rc:*, and bare numeric targets are rejected with a migration error.

Shared Message Actions

The shared OpenClaw message tool exposes these RingCentral actions when the channel is configured:

Optional RingCentral Tools

Reference

Environment Variables

Use RC_* variables only. Existing RINGCENTRAL_* variables are intentionally ignored.

Key Options

Legacy Migration Errors

These old access-control fields are rejected:

The corresponding legacy env vars (RC_ALLOWED_USER_EMAILS, RC_ALLOW_ALL_USERS, RC_ALLOWED_CHANNELS, RC_IGNORED_CHANNELS, and RC_FREE_RESPONSE_CHANNELS) are rejected with migration guidance.

Local Verification

git diff --check
node -e 'JSON.parse(require("fs").readFileSync("openclaw.plugin.json","utf8"))'
pnpm test src/artifact-tools.test.ts --run
pnpm typecheck
pnpm build

License

MIT