hermes-ringcentral 2026.6.7__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- hermes_ringcentral-2026.6.7/PKG-INFO +202 -0
- hermes_ringcentral-2026.6.7/README.md +188 -0
- hermes_ringcentral-2026.6.7/hermes_ringcentral.egg-info/PKG-INFO +202 -0
- hermes_ringcentral-2026.6.7/hermes_ringcentral.egg-info/SOURCES.txt +13 -0
- hermes_ringcentral-2026.6.7/hermes_ringcentral.egg-info/dependency_links.txt +1 -0
- hermes_ringcentral-2026.6.7/hermes_ringcentral.egg-info/entry_points.txt +2 -0
- hermes_ringcentral-2026.6.7/hermes_ringcentral.egg-info/requires.txt +6 -0
- hermes_ringcentral-2026.6.7/hermes_ringcentral.egg-info/top_level.txt +1 -0
- hermes_ringcentral-2026.6.7/pyproject.toml +32 -0
- hermes_ringcentral-2026.6.7/ringcentral/__init__.py +5 -0
- hermes_ringcentral-2026.6.7/ringcentral/adapter.py +4347 -0
- hermes_ringcentral-2026.6.7/ringcentral/rc_client.py +804 -0
- hermes_ringcentral-2026.6.7/ringcentral/rc_ws.py +371 -0
- hermes_ringcentral-2026.6.7/setup.cfg +4 -0
- hermes_ringcentral-2026.6.7/tests/test_ringcentral.py +3343 -0
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: hermes-ringcentral
|
|
3
|
+
Version: 2026.6.7
|
|
4
|
+
Summary: RingCentral Team Messaging gateway adapter for Hermes Agent
|
|
5
|
+
Author: Nous Research
|
|
6
|
+
License: MIT
|
|
7
|
+
Requires-Python: >=3.11
|
|
8
|
+
Description-Content-Type: text/markdown
|
|
9
|
+
Requires-Dist: aiohttp>=3.9.0
|
|
10
|
+
Requires-Dist: websockets>=12.0
|
|
11
|
+
Provides-Extra: dev
|
|
12
|
+
Requires-Dist: pytest>=7.0; extra == "dev"
|
|
13
|
+
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
|
|
14
|
+
|
|
15
|
+
# Hermes RingCentral Plugin
|
|
16
|
+
|
|
17
|
+
RingCentral Team Messaging support for Hermes Agent. This plugin lets a Hermes
|
|
18
|
+
agent talk through a RingCentral bot, reply in threads, read owner-visible chat
|
|
19
|
+
history when explicitly requested by the owner, and deliver scheduled
|
|
20
|
+
notifications into RingCentral.
|
|
21
|
+
|
|
22
|
+
[中文说明](README.zh-CN.md)
|
|
23
|
+
|
|
24
|
+
## Quick Start
|
|
25
|
+
|
|
26
|
+
Install with the Hermes plugin manager:
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
hermes plugins install ringclaw/hermes-ringcentral --enable
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The installer prompts for `RC_BOT_TOKEN` and saves it to `~/.hermes/.env`. If
|
|
33
|
+
the plugin is already installed but disabled, enable it with:
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
hermes plugins enable ringcentral-platform
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Restart the gateway after installing or changing credentials:
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
hermes gateway restart
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
For first-time gateway setup, `hermes gateway start` is also fine.
|
|
46
|
+
|
|
47
|
+
## RingCentral App Setup
|
|
48
|
+
|
|
49
|
+
Create a RingCentral bot app in the RingCentral developer portal:
|
|
50
|
+
|
|
51
|
+
1. Sign in at <https://developers.ringcentral.com/>.
|
|
52
|
+
2. Create an app with the **Bot** platform type.
|
|
53
|
+
3. Grant at least these permissions:
|
|
54
|
+
- `TeamMessaging` for reading and writing team messages
|
|
55
|
+
- `ReadAccounts` for resolving the bot extension
|
|
56
|
+
- `WebSocketsSubscription` for live message events
|
|
57
|
+
4. Install or publish the bot to the target RingCentral account.
|
|
58
|
+
5. Copy the bot JWT and use it as `RC_BOT_TOKEN`.
|
|
59
|
+
|
|
60
|
+
For owner-only history summaries or fallback sends, also configure a user JWT
|
|
61
|
+
app for the owner account and set all three `RC_USER_*` variables.
|
|
62
|
+
|
|
63
|
+
## Configuration
|
|
64
|
+
|
|
65
|
+
Minimum:
|
|
66
|
+
|
|
67
|
+
```sh
|
|
68
|
+
export RC_BOT_TOKEN="<bot JWT>"
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Common optional settings:
|
|
72
|
+
|
|
73
|
+
```sh
|
|
74
|
+
# Production is the default. Use devtest for sandbox accounts.
|
|
75
|
+
export RC_SERVER_URL="https://platform.ringcentral.com"
|
|
76
|
+
|
|
77
|
+
# Owner mode: enables owner-only history reads and fallback sends.
|
|
78
|
+
export RC_USER_CLIENT_ID="<owner app client id>"
|
|
79
|
+
export RC_USER_CLIENT_SECRET="<owner app client secret>"
|
|
80
|
+
export RC_USER_JWT_TOKEN="<owner JWT>"
|
|
81
|
+
export RC_HISTORY_MESSAGE_LIMIT=250
|
|
82
|
+
|
|
83
|
+
# User access control. If owner mode is configured and this is unset,
|
|
84
|
+
# the plugin auto-seeds the owner email as the only allowed user.
|
|
85
|
+
export RC_ALLOWED_USER_EMAILS="owner@example.com,teammate@example.com"
|
|
86
|
+
export RC_ALLOW_ALL_USERS=false
|
|
87
|
+
|
|
88
|
+
# Group/team channel controls.
|
|
89
|
+
export RC_ALLOWED_CHANNELS="g-abc123,g-def456"
|
|
90
|
+
export RC_IGNORED_CHANNELS="g-muted"
|
|
91
|
+
export RC_REQUIRE_MENTION=true
|
|
92
|
+
export RC_FREE_RESPONSE_CHANNELS="g-abc123"
|
|
93
|
+
export RC_THREAD_REQUIRE_MENTION=false
|
|
94
|
+
|
|
95
|
+
# Threading and delivery.
|
|
96
|
+
export RC_REPLY_TO_MODE=first
|
|
97
|
+
export RC_NO_THREAD_CHANNELS="g-announcements"
|
|
98
|
+
export RC_PROCESSING_EMOJI_ENABLED=true
|
|
99
|
+
export RC_PROCESSING_EMOJI_EDIT_DELAY_SECONDS=5
|
|
100
|
+
export RC_HOME_CHANNEL="g-abc123"
|
|
101
|
+
export RC_HOME_CHANNEL_NAME="Hermes Updates"
|
|
102
|
+
|
|
103
|
+
# Inbound attachments are downloaded only after message admission succeeds.
|
|
104
|
+
export RC_ATTACHMENT_DOWNLOAD_ENABLED=true
|
|
105
|
+
export RC_ATTACHMENT_MAX_COUNT=5
|
|
106
|
+
export RC_ATTACHMENT_MAX_BYTES=5242880
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Put persistent values in `~/.hermes/.env` if you do not want to export them in
|
|
110
|
+
your shell each time.
|
|
111
|
+
|
|
112
|
+
## How To Use
|
|
113
|
+
|
|
114
|
+
### Direct messages
|
|
115
|
+
|
|
116
|
+
DM the RingCentral bot and talk to Hermes normally:
|
|
117
|
+
|
|
118
|
+
```text
|
|
119
|
+
Can you draft a deployment update for the team?
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Only the configured owner or users in `RC_ALLOWED_USER_EMAILS` can trigger the
|
|
123
|
+
bot. Unauthorized DMs are ignored.
|
|
124
|
+
|
|
125
|
+
### Group and team chats
|
|
126
|
+
|
|
127
|
+
Mention the bot in a group/team chat:
|
|
128
|
+
|
|
129
|
+
```text
|
|
130
|
+
@Hermes summarize the decision in this thread
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
By default, group messages require a bot mention. You can allow selected
|
|
134
|
+
channels to trigger without mentions by setting `RC_FREE_RESPONSE_CHANNELS`, or
|
|
135
|
+
disable mention requirements globally with `RC_REQUIRE_MENTION=false`.
|
|
136
|
+
|
|
137
|
+
### Owner history summaries
|
|
138
|
+
|
|
139
|
+
From the owner-bot DM, ask Hermes for a group or DM summary in natural language:
|
|
140
|
+
|
|
141
|
+
```text
|
|
142
|
+
Summarize Project Team since yesterday.
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
```text
|
|
146
|
+
总结我和 Alice Wang 今天的聊天
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
Hermes may call the `ringcentral_get_recent_messages` tool to fetch recent
|
|
150
|
+
source messages visible to the owner. The plugin returns structured history;
|
|
151
|
+
Hermes Agent decides the intent, target, time window, and final summary. Other
|
|
152
|
+
users cannot use this tool to read history.
|
|
153
|
+
|
|
154
|
+
### Cron and notifications
|
|
155
|
+
|
|
156
|
+
Set `RC_HOME_CHANNEL` to route Hermes cron jobs and notifications into
|
|
157
|
+
RingCentral:
|
|
158
|
+
|
|
159
|
+
```text
|
|
160
|
+
Create a daily 9am reminder and deliver it to RingCentral.
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
## Feature Highlights
|
|
164
|
+
|
|
165
|
+
- **Hermes-native plugin install** via `hermes plugins install`.
|
|
166
|
+
- **Bot-first messaging** for normal conversations, with optional owner fallback
|
|
167
|
+
when the bot is not in a target chat.
|
|
168
|
+
- **Owner-only chat history tool** for group and direct-message summaries,
|
|
169
|
+
with intent and summarization handled by Hermes Agent.
|
|
170
|
+
- **Thread replies** using RingCentral Team Messaging `parentPostId` /
|
|
171
|
+
`threadId` where supported.
|
|
172
|
+
- **Waiting emoji in threads**: Hermes posts `👀`, edits it to `⏳` after a
|
|
173
|
+
short delay, then deletes it when the final reply is delivered.
|
|
174
|
+
- **Discord-style controls** for allowed users, allowed channels, ignored
|
|
175
|
+
channels, mention requirements, free-response channels, and thread follow-up
|
|
176
|
+
behavior.
|
|
177
|
+
- **Attachment handling** for inbound images, audio, and documents so Hermes
|
|
178
|
+
tools can work with downloaded files.
|
|
179
|
+
- **Cron delivery** through `RC_HOME_CHANNEL`, including out-of-process cron
|
|
180
|
+
sender support.
|
|
181
|
+
- **Webhook text fallback** for integration posts where the modern Team
|
|
182
|
+
Messaging posts API returns empty text.
|
|
183
|
+
|
|
184
|
+
## Troubleshooting
|
|
185
|
+
|
|
186
|
+
| Symptom | Likely cause | Fix |
|
|
187
|
+
| --- | --- | --- |
|
|
188
|
+
| Plugin does not load | Installed but not enabled | Run `hermes plugins enable ringcentral-platform` and restart the gateway |
|
|
189
|
+
| Gateway logs `RC_BOT_TOKEN not configured` | Missing bot JWT | Set `RC_BOT_TOKEN` in `~/.hermes/.env` |
|
|
190
|
+
| Gateway logs `RingCentral rejected bot token` | Bad or expired JWT | Re-issue the bot JWT in the RingCentral developer portal |
|
|
191
|
+
| Owner history request says credentials are missing | `RC_USER_*` is incomplete | Set `RC_USER_CLIENT_ID`, `RC_USER_CLIENT_SECRET`, and `RC_USER_JWT_TOKEN` |
|
|
192
|
+
| Bot does not reply in a group | No mention, blocked user, or blocked channel | Mention the bot and check `RC_ALLOWED_USER_EMAILS`, `RC_ALLOWED_CHANNELS`, and `RC_IGNORED_CHANNELS` |
|
|
193
|
+
| Replies are not threaded in a chat | RingCentral UI/API behavior or channel disabled threads | Check `RC_REPLY_TO_MODE` and `RC_NO_THREAD_CHANNELS` |
|
|
194
|
+
|
|
195
|
+
## Development
|
|
196
|
+
|
|
197
|
+
Run the RingCentral test suite with Hermes Agent on `PYTHONPATH`:
|
|
198
|
+
|
|
199
|
+
```sh
|
|
200
|
+
PYTHONPATH=/root/workspace/github/NousResearch/hermes-agent \
|
|
201
|
+
uv run --with PyYAML --extra dev pytest -q tests/test_ringcentral.py
|
|
202
|
+
```
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
# Hermes RingCentral Plugin
|
|
2
|
+
|
|
3
|
+
RingCentral Team Messaging support for Hermes Agent. This plugin lets a Hermes
|
|
4
|
+
agent talk through a RingCentral bot, reply in threads, read owner-visible chat
|
|
5
|
+
history when explicitly requested by the owner, and deliver scheduled
|
|
6
|
+
notifications into RingCentral.
|
|
7
|
+
|
|
8
|
+
[中文说明](README.zh-CN.md)
|
|
9
|
+
|
|
10
|
+
## Quick Start
|
|
11
|
+
|
|
12
|
+
Install with the Hermes plugin manager:
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
hermes plugins install ringclaw/hermes-ringcentral --enable
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
The installer prompts for `RC_BOT_TOKEN` and saves it to `~/.hermes/.env`. If
|
|
19
|
+
the plugin is already installed but disabled, enable it with:
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
hermes plugins enable ringcentral-platform
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Restart the gateway after installing or changing credentials:
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
hermes gateway restart
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
For first-time gateway setup, `hermes gateway start` is also fine.
|
|
32
|
+
|
|
33
|
+
## RingCentral App Setup
|
|
34
|
+
|
|
35
|
+
Create a RingCentral bot app in the RingCentral developer portal:
|
|
36
|
+
|
|
37
|
+
1. Sign in at <https://developers.ringcentral.com/>.
|
|
38
|
+
2. Create an app with the **Bot** platform type.
|
|
39
|
+
3. Grant at least these permissions:
|
|
40
|
+
- `TeamMessaging` for reading and writing team messages
|
|
41
|
+
- `ReadAccounts` for resolving the bot extension
|
|
42
|
+
- `WebSocketsSubscription` for live message events
|
|
43
|
+
4. Install or publish the bot to the target RingCentral account.
|
|
44
|
+
5. Copy the bot JWT and use it as `RC_BOT_TOKEN`.
|
|
45
|
+
|
|
46
|
+
For owner-only history summaries or fallback sends, also configure a user JWT
|
|
47
|
+
app for the owner account and set all three `RC_USER_*` variables.
|
|
48
|
+
|
|
49
|
+
## Configuration
|
|
50
|
+
|
|
51
|
+
Minimum:
|
|
52
|
+
|
|
53
|
+
```sh
|
|
54
|
+
export RC_BOT_TOKEN="<bot JWT>"
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Common optional settings:
|
|
58
|
+
|
|
59
|
+
```sh
|
|
60
|
+
# Production is the default. Use devtest for sandbox accounts.
|
|
61
|
+
export RC_SERVER_URL="https://platform.ringcentral.com"
|
|
62
|
+
|
|
63
|
+
# Owner mode: enables owner-only history reads and fallback sends.
|
|
64
|
+
export RC_USER_CLIENT_ID="<owner app client id>"
|
|
65
|
+
export RC_USER_CLIENT_SECRET="<owner app client secret>"
|
|
66
|
+
export RC_USER_JWT_TOKEN="<owner JWT>"
|
|
67
|
+
export RC_HISTORY_MESSAGE_LIMIT=250
|
|
68
|
+
|
|
69
|
+
# User access control. If owner mode is configured and this is unset,
|
|
70
|
+
# the plugin auto-seeds the owner email as the only allowed user.
|
|
71
|
+
export RC_ALLOWED_USER_EMAILS="owner@example.com,teammate@example.com"
|
|
72
|
+
export RC_ALLOW_ALL_USERS=false
|
|
73
|
+
|
|
74
|
+
# Group/team channel controls.
|
|
75
|
+
export RC_ALLOWED_CHANNELS="g-abc123,g-def456"
|
|
76
|
+
export RC_IGNORED_CHANNELS="g-muted"
|
|
77
|
+
export RC_REQUIRE_MENTION=true
|
|
78
|
+
export RC_FREE_RESPONSE_CHANNELS="g-abc123"
|
|
79
|
+
export RC_THREAD_REQUIRE_MENTION=false
|
|
80
|
+
|
|
81
|
+
# Threading and delivery.
|
|
82
|
+
export RC_REPLY_TO_MODE=first
|
|
83
|
+
export RC_NO_THREAD_CHANNELS="g-announcements"
|
|
84
|
+
export RC_PROCESSING_EMOJI_ENABLED=true
|
|
85
|
+
export RC_PROCESSING_EMOJI_EDIT_DELAY_SECONDS=5
|
|
86
|
+
export RC_HOME_CHANNEL="g-abc123"
|
|
87
|
+
export RC_HOME_CHANNEL_NAME="Hermes Updates"
|
|
88
|
+
|
|
89
|
+
# Inbound attachments are downloaded only after message admission succeeds.
|
|
90
|
+
export RC_ATTACHMENT_DOWNLOAD_ENABLED=true
|
|
91
|
+
export RC_ATTACHMENT_MAX_COUNT=5
|
|
92
|
+
export RC_ATTACHMENT_MAX_BYTES=5242880
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Put persistent values in `~/.hermes/.env` if you do not want to export them in
|
|
96
|
+
your shell each time.
|
|
97
|
+
|
|
98
|
+
## How To Use
|
|
99
|
+
|
|
100
|
+
### Direct messages
|
|
101
|
+
|
|
102
|
+
DM the RingCentral bot and talk to Hermes normally:
|
|
103
|
+
|
|
104
|
+
```text
|
|
105
|
+
Can you draft a deployment update for the team?
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Only the configured owner or users in `RC_ALLOWED_USER_EMAILS` can trigger the
|
|
109
|
+
bot. Unauthorized DMs are ignored.
|
|
110
|
+
|
|
111
|
+
### Group and team chats
|
|
112
|
+
|
|
113
|
+
Mention the bot in a group/team chat:
|
|
114
|
+
|
|
115
|
+
```text
|
|
116
|
+
@Hermes summarize the decision in this thread
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
By default, group messages require a bot mention. You can allow selected
|
|
120
|
+
channels to trigger without mentions by setting `RC_FREE_RESPONSE_CHANNELS`, or
|
|
121
|
+
disable mention requirements globally with `RC_REQUIRE_MENTION=false`.
|
|
122
|
+
|
|
123
|
+
### Owner history summaries
|
|
124
|
+
|
|
125
|
+
From the owner-bot DM, ask Hermes for a group or DM summary in natural language:
|
|
126
|
+
|
|
127
|
+
```text
|
|
128
|
+
Summarize Project Team since yesterday.
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
```text
|
|
132
|
+
总结我和 Alice Wang 今天的聊天
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Hermes may call the `ringcentral_get_recent_messages` tool to fetch recent
|
|
136
|
+
source messages visible to the owner. The plugin returns structured history;
|
|
137
|
+
Hermes Agent decides the intent, target, time window, and final summary. Other
|
|
138
|
+
users cannot use this tool to read history.
|
|
139
|
+
|
|
140
|
+
### Cron and notifications
|
|
141
|
+
|
|
142
|
+
Set `RC_HOME_CHANNEL` to route Hermes cron jobs and notifications into
|
|
143
|
+
RingCentral:
|
|
144
|
+
|
|
145
|
+
```text
|
|
146
|
+
Create a daily 9am reminder and deliver it to RingCentral.
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
## Feature Highlights
|
|
150
|
+
|
|
151
|
+
- **Hermes-native plugin install** via `hermes plugins install`.
|
|
152
|
+
- **Bot-first messaging** for normal conversations, with optional owner fallback
|
|
153
|
+
when the bot is not in a target chat.
|
|
154
|
+
- **Owner-only chat history tool** for group and direct-message summaries,
|
|
155
|
+
with intent and summarization handled by Hermes Agent.
|
|
156
|
+
- **Thread replies** using RingCentral Team Messaging `parentPostId` /
|
|
157
|
+
`threadId` where supported.
|
|
158
|
+
- **Waiting emoji in threads**: Hermes posts `👀`, edits it to `⏳` after a
|
|
159
|
+
short delay, then deletes it when the final reply is delivered.
|
|
160
|
+
- **Discord-style controls** for allowed users, allowed channels, ignored
|
|
161
|
+
channels, mention requirements, free-response channels, and thread follow-up
|
|
162
|
+
behavior.
|
|
163
|
+
- **Attachment handling** for inbound images, audio, and documents so Hermes
|
|
164
|
+
tools can work with downloaded files.
|
|
165
|
+
- **Cron delivery** through `RC_HOME_CHANNEL`, including out-of-process cron
|
|
166
|
+
sender support.
|
|
167
|
+
- **Webhook text fallback** for integration posts where the modern Team
|
|
168
|
+
Messaging posts API returns empty text.
|
|
169
|
+
|
|
170
|
+
## Troubleshooting
|
|
171
|
+
|
|
172
|
+
| Symptom | Likely cause | Fix |
|
|
173
|
+
| --- | --- | --- |
|
|
174
|
+
| Plugin does not load | Installed but not enabled | Run `hermes plugins enable ringcentral-platform` and restart the gateway |
|
|
175
|
+
| Gateway logs `RC_BOT_TOKEN not configured` | Missing bot JWT | Set `RC_BOT_TOKEN` in `~/.hermes/.env` |
|
|
176
|
+
| Gateway logs `RingCentral rejected bot token` | Bad or expired JWT | Re-issue the bot JWT in the RingCentral developer portal |
|
|
177
|
+
| Owner history request says credentials are missing | `RC_USER_*` is incomplete | Set `RC_USER_CLIENT_ID`, `RC_USER_CLIENT_SECRET`, and `RC_USER_JWT_TOKEN` |
|
|
178
|
+
| Bot does not reply in a group | No mention, blocked user, or blocked channel | Mention the bot and check `RC_ALLOWED_USER_EMAILS`, `RC_ALLOWED_CHANNELS`, and `RC_IGNORED_CHANNELS` |
|
|
179
|
+
| Replies are not threaded in a chat | RingCentral UI/API behavior or channel disabled threads | Check `RC_REPLY_TO_MODE` and `RC_NO_THREAD_CHANNELS` |
|
|
180
|
+
|
|
181
|
+
## Development
|
|
182
|
+
|
|
183
|
+
Run the RingCentral test suite with Hermes Agent on `PYTHONPATH`:
|
|
184
|
+
|
|
185
|
+
```sh
|
|
186
|
+
PYTHONPATH=/root/workspace/github/NousResearch/hermes-agent \
|
|
187
|
+
uv run --with PyYAML --extra dev pytest -q tests/test_ringcentral.py
|
|
188
|
+
```
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: hermes-ringcentral
|
|
3
|
+
Version: 2026.6.7
|
|
4
|
+
Summary: RingCentral Team Messaging gateway adapter for Hermes Agent
|
|
5
|
+
Author: Nous Research
|
|
6
|
+
License: MIT
|
|
7
|
+
Requires-Python: >=3.11
|
|
8
|
+
Description-Content-Type: text/markdown
|
|
9
|
+
Requires-Dist: aiohttp>=3.9.0
|
|
10
|
+
Requires-Dist: websockets>=12.0
|
|
11
|
+
Provides-Extra: dev
|
|
12
|
+
Requires-Dist: pytest>=7.0; extra == "dev"
|
|
13
|
+
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
|
|
14
|
+
|
|
15
|
+
# Hermes RingCentral Plugin
|
|
16
|
+
|
|
17
|
+
RingCentral Team Messaging support for Hermes Agent. This plugin lets a Hermes
|
|
18
|
+
agent talk through a RingCentral bot, reply in threads, read owner-visible chat
|
|
19
|
+
history when explicitly requested by the owner, and deliver scheduled
|
|
20
|
+
notifications into RingCentral.
|
|
21
|
+
|
|
22
|
+
[中文说明](README.zh-CN.md)
|
|
23
|
+
|
|
24
|
+
## Quick Start
|
|
25
|
+
|
|
26
|
+
Install with the Hermes plugin manager:
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
hermes plugins install ringclaw/hermes-ringcentral --enable
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The installer prompts for `RC_BOT_TOKEN` and saves it to `~/.hermes/.env`. If
|
|
33
|
+
the plugin is already installed but disabled, enable it with:
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
hermes plugins enable ringcentral-platform
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Restart the gateway after installing or changing credentials:
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
hermes gateway restart
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
For first-time gateway setup, `hermes gateway start` is also fine.
|
|
46
|
+
|
|
47
|
+
## RingCentral App Setup
|
|
48
|
+
|
|
49
|
+
Create a RingCentral bot app in the RingCentral developer portal:
|
|
50
|
+
|
|
51
|
+
1. Sign in at <https://developers.ringcentral.com/>.
|
|
52
|
+
2. Create an app with the **Bot** platform type.
|
|
53
|
+
3. Grant at least these permissions:
|
|
54
|
+
- `TeamMessaging` for reading and writing team messages
|
|
55
|
+
- `ReadAccounts` for resolving the bot extension
|
|
56
|
+
- `WebSocketsSubscription` for live message events
|
|
57
|
+
4. Install or publish the bot to the target RingCentral account.
|
|
58
|
+
5. Copy the bot JWT and use it as `RC_BOT_TOKEN`.
|
|
59
|
+
|
|
60
|
+
For owner-only history summaries or fallback sends, also configure a user JWT
|
|
61
|
+
app for the owner account and set all three `RC_USER_*` variables.
|
|
62
|
+
|
|
63
|
+
## Configuration
|
|
64
|
+
|
|
65
|
+
Minimum:
|
|
66
|
+
|
|
67
|
+
```sh
|
|
68
|
+
export RC_BOT_TOKEN="<bot JWT>"
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Common optional settings:
|
|
72
|
+
|
|
73
|
+
```sh
|
|
74
|
+
# Production is the default. Use devtest for sandbox accounts.
|
|
75
|
+
export RC_SERVER_URL="https://platform.ringcentral.com"
|
|
76
|
+
|
|
77
|
+
# Owner mode: enables owner-only history reads and fallback sends.
|
|
78
|
+
export RC_USER_CLIENT_ID="<owner app client id>"
|
|
79
|
+
export RC_USER_CLIENT_SECRET="<owner app client secret>"
|
|
80
|
+
export RC_USER_JWT_TOKEN="<owner JWT>"
|
|
81
|
+
export RC_HISTORY_MESSAGE_LIMIT=250
|
|
82
|
+
|
|
83
|
+
# User access control. If owner mode is configured and this is unset,
|
|
84
|
+
# the plugin auto-seeds the owner email as the only allowed user.
|
|
85
|
+
export RC_ALLOWED_USER_EMAILS="owner@example.com,teammate@example.com"
|
|
86
|
+
export RC_ALLOW_ALL_USERS=false
|
|
87
|
+
|
|
88
|
+
# Group/team channel controls.
|
|
89
|
+
export RC_ALLOWED_CHANNELS="g-abc123,g-def456"
|
|
90
|
+
export RC_IGNORED_CHANNELS="g-muted"
|
|
91
|
+
export RC_REQUIRE_MENTION=true
|
|
92
|
+
export RC_FREE_RESPONSE_CHANNELS="g-abc123"
|
|
93
|
+
export RC_THREAD_REQUIRE_MENTION=false
|
|
94
|
+
|
|
95
|
+
# Threading and delivery.
|
|
96
|
+
export RC_REPLY_TO_MODE=first
|
|
97
|
+
export RC_NO_THREAD_CHANNELS="g-announcements"
|
|
98
|
+
export RC_PROCESSING_EMOJI_ENABLED=true
|
|
99
|
+
export RC_PROCESSING_EMOJI_EDIT_DELAY_SECONDS=5
|
|
100
|
+
export RC_HOME_CHANNEL="g-abc123"
|
|
101
|
+
export RC_HOME_CHANNEL_NAME="Hermes Updates"
|
|
102
|
+
|
|
103
|
+
# Inbound attachments are downloaded only after message admission succeeds.
|
|
104
|
+
export RC_ATTACHMENT_DOWNLOAD_ENABLED=true
|
|
105
|
+
export RC_ATTACHMENT_MAX_COUNT=5
|
|
106
|
+
export RC_ATTACHMENT_MAX_BYTES=5242880
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Put persistent values in `~/.hermes/.env` if you do not want to export them in
|
|
110
|
+
your shell each time.
|
|
111
|
+
|
|
112
|
+
## How To Use
|
|
113
|
+
|
|
114
|
+
### Direct messages
|
|
115
|
+
|
|
116
|
+
DM the RingCentral bot and talk to Hermes normally:
|
|
117
|
+
|
|
118
|
+
```text
|
|
119
|
+
Can you draft a deployment update for the team?
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Only the configured owner or users in `RC_ALLOWED_USER_EMAILS` can trigger the
|
|
123
|
+
bot. Unauthorized DMs are ignored.
|
|
124
|
+
|
|
125
|
+
### Group and team chats
|
|
126
|
+
|
|
127
|
+
Mention the bot in a group/team chat:
|
|
128
|
+
|
|
129
|
+
```text
|
|
130
|
+
@Hermes summarize the decision in this thread
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
By default, group messages require a bot mention. You can allow selected
|
|
134
|
+
channels to trigger without mentions by setting `RC_FREE_RESPONSE_CHANNELS`, or
|
|
135
|
+
disable mention requirements globally with `RC_REQUIRE_MENTION=false`.
|
|
136
|
+
|
|
137
|
+
### Owner history summaries
|
|
138
|
+
|
|
139
|
+
From the owner-bot DM, ask Hermes for a group or DM summary in natural language:
|
|
140
|
+
|
|
141
|
+
```text
|
|
142
|
+
Summarize Project Team since yesterday.
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
```text
|
|
146
|
+
总结我和 Alice Wang 今天的聊天
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
Hermes may call the `ringcentral_get_recent_messages` tool to fetch recent
|
|
150
|
+
source messages visible to the owner. The plugin returns structured history;
|
|
151
|
+
Hermes Agent decides the intent, target, time window, and final summary. Other
|
|
152
|
+
users cannot use this tool to read history.
|
|
153
|
+
|
|
154
|
+
### Cron and notifications
|
|
155
|
+
|
|
156
|
+
Set `RC_HOME_CHANNEL` to route Hermes cron jobs and notifications into
|
|
157
|
+
RingCentral:
|
|
158
|
+
|
|
159
|
+
```text
|
|
160
|
+
Create a daily 9am reminder and deliver it to RingCentral.
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
## Feature Highlights
|
|
164
|
+
|
|
165
|
+
- **Hermes-native plugin install** via `hermes plugins install`.
|
|
166
|
+
- **Bot-first messaging** for normal conversations, with optional owner fallback
|
|
167
|
+
when the bot is not in a target chat.
|
|
168
|
+
- **Owner-only chat history tool** for group and direct-message summaries,
|
|
169
|
+
with intent and summarization handled by Hermes Agent.
|
|
170
|
+
- **Thread replies** using RingCentral Team Messaging `parentPostId` /
|
|
171
|
+
`threadId` where supported.
|
|
172
|
+
- **Waiting emoji in threads**: Hermes posts `👀`, edits it to `⏳` after a
|
|
173
|
+
short delay, then deletes it when the final reply is delivered.
|
|
174
|
+
- **Discord-style controls** for allowed users, allowed channels, ignored
|
|
175
|
+
channels, mention requirements, free-response channels, and thread follow-up
|
|
176
|
+
behavior.
|
|
177
|
+
- **Attachment handling** for inbound images, audio, and documents so Hermes
|
|
178
|
+
tools can work with downloaded files.
|
|
179
|
+
- **Cron delivery** through `RC_HOME_CHANNEL`, including out-of-process cron
|
|
180
|
+
sender support.
|
|
181
|
+
- **Webhook text fallback** for integration posts where the modern Team
|
|
182
|
+
Messaging posts API returns empty text.
|
|
183
|
+
|
|
184
|
+
## Troubleshooting
|
|
185
|
+
|
|
186
|
+
| Symptom | Likely cause | Fix |
|
|
187
|
+
| --- | --- | --- |
|
|
188
|
+
| Plugin does not load | Installed but not enabled | Run `hermes plugins enable ringcentral-platform` and restart the gateway |
|
|
189
|
+
| Gateway logs `RC_BOT_TOKEN not configured` | Missing bot JWT | Set `RC_BOT_TOKEN` in `~/.hermes/.env` |
|
|
190
|
+
| Gateway logs `RingCentral rejected bot token` | Bad or expired JWT | Re-issue the bot JWT in the RingCentral developer portal |
|
|
191
|
+
| Owner history request says credentials are missing | `RC_USER_*` is incomplete | Set `RC_USER_CLIENT_ID`, `RC_USER_CLIENT_SECRET`, and `RC_USER_JWT_TOKEN` |
|
|
192
|
+
| Bot does not reply in a group | No mention, blocked user, or blocked channel | Mention the bot and check `RC_ALLOWED_USER_EMAILS`, `RC_ALLOWED_CHANNELS`, and `RC_IGNORED_CHANNELS` |
|
|
193
|
+
| Replies are not threaded in a chat | RingCentral UI/API behavior or channel disabled threads | Check `RC_REPLY_TO_MODE` and `RC_NO_THREAD_CHANNELS` |
|
|
194
|
+
|
|
195
|
+
## Development
|
|
196
|
+
|
|
197
|
+
Run the RingCentral test suite with Hermes Agent on `PYTHONPATH`:
|
|
198
|
+
|
|
199
|
+
```sh
|
|
200
|
+
PYTHONPATH=/root/workspace/github/NousResearch/hermes-agent \
|
|
201
|
+
uv run --with PyYAML --extra dev pytest -q tests/test_ringcentral.py
|
|
202
|
+
```
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
README.md
|
|
2
|
+
pyproject.toml
|
|
3
|
+
hermes_ringcentral.egg-info/PKG-INFO
|
|
4
|
+
hermes_ringcentral.egg-info/SOURCES.txt
|
|
5
|
+
hermes_ringcentral.egg-info/dependency_links.txt
|
|
6
|
+
hermes_ringcentral.egg-info/entry_points.txt
|
|
7
|
+
hermes_ringcentral.egg-info/requires.txt
|
|
8
|
+
hermes_ringcentral.egg-info/top_level.txt
|
|
9
|
+
ringcentral/__init__.py
|
|
10
|
+
ringcentral/adapter.py
|
|
11
|
+
ringcentral/rc_client.py
|
|
12
|
+
ringcentral/rc_ws.py
|
|
13
|
+
tests/test_ringcentral.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
ringcentral
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "hermes-ringcentral"
|
|
7
|
+
version = "2026.6.7"
|
|
8
|
+
description = "RingCentral Team Messaging gateway adapter for Hermes Agent"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = {text = "MIT"}
|
|
11
|
+
requires-python = ">=3.11"
|
|
12
|
+
authors = [{name = "Nous Research"}]
|
|
13
|
+
dependencies = [
|
|
14
|
+
"aiohttp>=3.9.0",
|
|
15
|
+
"websockets>=12.0",
|
|
16
|
+
]
|
|
17
|
+
|
|
18
|
+
[project.optional-dependencies]
|
|
19
|
+
dev = [
|
|
20
|
+
"pytest>=7.0",
|
|
21
|
+
"pytest-asyncio>=0.21",
|
|
22
|
+
]
|
|
23
|
+
|
|
24
|
+
[project.entry-points]
|
|
25
|
+
"hermes_agent.plugins" = {ringcentral = "ringcentral:register"}
|
|
26
|
+
|
|
27
|
+
[tool.setuptools.packages.find]
|
|
28
|
+
include = ["ringcentral*"]
|
|
29
|
+
|
|
30
|
+
[tool.pytest.ini_options]
|
|
31
|
+
testpaths = ["tests"]
|
|
32
|
+
asyncio_mode = "auto"
|