Channels
Ym Openclaw
By OpenClaw channel plugin for Yandex Messenger (Я.360 для бизнеса)
Install
npm install
pnpmConfiguration Example
{
"plugins": {
"allow": ["openclaw-channel-yandex-messenger"],
"entries": {
"yandex-messenger": {
"enabled": true
}
}
},
"channels": {
"yandex-messenger": {
"token": "${secret:yandex.token}",
"allowFrom": ["[email protected]", "[email protected]"],
"pollIntervalMs": 25000,
"dmSecurity": "allowlist",
"groups": {
"*": { "enabled": true, "requireMention": true }
}
}
}
}README
# openclaw-channel-yandex-messenger
Bring AI agents into [Yandex Messenger](https://360.yandex.ru/business/) (Я.360 для бизнеса) chats. This [OpenClaw](https://openclaw.dev) channel plugin lets your gateway-managed agent talk to colleagues through a Y.M bot — handling direct messages, group conversations, file exchange, inline button keyboards, voice transcripts, and bot-initiated group creation for workflows like contract approvals.
**At a glance:**
- Direct messages and group chats, with per-group mention policy
- Inbound and outbound images and documents (PDF and friends)
- Inline buttons via OpenClaw `presentation` — server-action callbacks and open-URL links
- Bot creates groups and manages members (`channel-create`, `addParticipant`, `removeParticipant`)
- Group voice messages admitted by display-name detection in Y.M's auto-transcript
- Allowlist DM security with per-user logins
- Long-polling delivery — no webhooks, no public endpoint required
Single OAuth token from the Y.M Bot API admin panel. TypeScript, 350+ unit tests, runs on Node 22+. Single account in v1; multi-account is a clean future extension.
---
## Status
MVP + media + group support + inline buttons + group management + voice-name detection are complete and passing CI.
**Supported in current version:**
- Direct messages (DM) — text, images, documents
- Group / supergroup chats — with per-group mention policy (see "Group chat configuration" below)
- Long-polling delivery
- Inline buttons (`SuggestButtons`) — server-action callbacks and open-URL links via OpenClaw `presentation`
- Group management — bot creates new chats and manages members (`channel-create`, `addParticipant`, `removeParticipant`)
- Voice messages in groups — Y.M auto-transcribes and we admit the voice via implicit "voice-name mention" when the bot's display name or login appears in the transcript
**Not yet implemented:**
- Webhook delivery
- Multi-account support (single `channels.yandex-messenger` section only)
- `SendMessageDirective` and `SetElementsStateDirective` (the two unused Y.M button directives)
- After-click message editing (Y.M API has no `editMessage` endpoint)
- Voice file download (we read the auto-transcript only — `voice.file.id` is not yet pulled into the OpenClaw media buffer; if `was_recognized: false` the message is empty)
**Unverified / best-effort:**
- Caption character ceiling (mirrors text ceiling, but not confirmed against Yandex docs)
- File size ceiling (the Bot API has one, but the exact value is unconfirmed)
- Yandex Messenger API edge cases in groups with many members
---
## Requirements
| Requirement | Version |
|---|---|
| Node.js | >= 22 |
| OpenClaw | >= 2026.2.19 |
| pnpm | >= 9 |
| Yandex 360 для бизнеса | OAuth token from admin panel |
---
## Install
### Option 1 — link mode (dev / local checkout)
```bash
git clone https://github.com/kukushulhu/ym-openclaw.git
cd ym-openclaw
pnpm install
pnpm build
# From your OpenClaw config directory:
openclaw plugins install /absolute/path/to/ym_openclaw
```
### Option 2 — pack and install local archive
```bash
cd ym_openclaw
pnpm build
pnpm pack
# Produces: openclaw-channel-yandex-messenger-0.1.0.tgz
openclaw plugins install ./openclaw-channel-yandex-messenger-0.1.0.tgz
```
### Option 3 — npm (once published)
```bash
openclaw plugins install openclaw-channel-yandex-messenger
```
After installing, restart the gateway:
```bash
openclaw gateway restart
```
---
## Configuration
Add the following to your `openclaw.json`:
```json
{
"plugins": {
"allow": ["openclaw-channel-yandex-messenger"],
"entries": {
"yandex-messenger": {
"enabled": true
}
}
},
"channels": {
"yandex-messenger": {
"token": "${secret:yandex.token}",
"allowFrom": ["[email protected]", "[email protected]"],
"pollIntervalMs": 25000,
"dmSecurity": "allowlist",
"groups": {
"*": { "enabled": true, "requireMention": true }
}
}
}
}
```
**`dmSecurity` values:**
- `"allowlist"` (default) — only logins in `allowFrom` may DM the bot
- `"anyone"` — any Yandex user may DM the bot (use with caution)
**Set the token secret:**
```bash
openclaw secrets set yandex.token
# Paste your OAuth token at the prompt; it will not echo.
```
The token is issued from the Yandex 360 для бизнеса admin panel under
Bot API settings. It must include the `ya.360biz.botapi` scope.
---
## Group chat configuration
The `groups` config block controls bot behaviour in Yandex Messenger group chats.
It uses a Telegram-style wildcard + per-group-override pattern:
```json
"groups": {
"*": { "enabled": true, "requireMention": true },
"0/0/<group-uuid>": { "enabled": true, "requireMention": false }
}
```
**Wildcard `"*"` (default policy):**
Applies to every group chat not explicitly listed. Recommended default: `enabled: true, requireMention: true`.
**Per-group override:**
Add an entry keyed by the group's `chat.id` (the `0/0/<uuid>` form) to override the default for that specific group.
**`requireMention: true` (default):**
The bot only responds when it is @-mentioned by name, when someone replies directly to a bot message, when an inline button is clicked, or when a voice message's transcript contains the bot's display name (or login) — see "Voice messages" below. Plain group messages are ignored.
**`requireMention: false`:**
The bot responds to every message in that group, no mention required. Use with care in busy groups.
**`enabled: false`:**
Disables the bot entirely in that group (all messages ignored).
**Discovering a group's `chat.id`:**
Add the bot to the group, then look in your gateway logs for a line like:
```
[yandex-messenger] observed chat: id=0/0/<uuid>, type=group
```
This INFO log fires once per unique chat, on first observation. Copy the `id` value and use it as the per-group override key in your config.
---
## Inline buttons
The plugin maps OpenClaw's `presentation` system (the same channel-agnostic mechanism the Telegram plugin uses) to Y.M's `SuggestButtons`. The agent attaches an inline keyboard to a reply by emitting a `presentation.buttons` block; the plugin converts it to the wire format. Clicks come back as agent turns.
### Sending buttons (agent-side)
The agent emits a `payload.presentation` like:
```ts
{
blocks: [
{ type: "text", text: "Согласовать договор?" },
{
type: "buttons",
buttons: [
{ label: "✅ Согласовать", value: "approve_dg_50" },
{ label: "❌ Отклонить", value: "reject_dg_50" },
{ label: "📄 Открыть", url: "https://docs.example.com/dg-50" }
]
}
]
}
```
- Buttons with `value` produce a server-action callback (the bot is notified on click).
- Buttons with `url` open the URL in the user's browser; the bot is **not** notified.
- Per-button `style` (success/danger/...) is ignored — Y.M API has no styling on buttons.
### Receiving clicks (agent-side)
A click on a `value`-button generates a fresh agent turn with:
- `body = "<value>"` (e.g. `"approve_dg_50"`) — readable as a normal user message.
- `extraContext.buttonPress = { name, payload, elementId, senderLogin }` — structured copy for tools that want it.
Use `senderLogin` to enforce business rules (e.g. "only the contract owner can approve"); the plugin admits all clicks and leaves the policy decision to the agent.
### Limitations
- Layout is `false` (single-line wrap). 2D matrices not supported in v1.
- `persist: true` always — the keyboard stays visible after subsequent messages until the user clicks. (Y.M's default of `false` would vanish the buttons the moment the agent's natural follow-up message arrives, killing the UX before the user can react.)
- Only `ServerActionDirective` and `OpenUriDirective` are implemented. `SendMessageDirective` and `SetElementsStateDirective` are deferred until a real use case surfaces.
- After-click message editing is not supported (Y.M API has no `editMessage`). The agent should send a fresh follow-up message instead (e.g., "Принято от Алисы — дальше передаю юристам.").
---
## Voice messages
Yandex Messenger auto-transcribes group voice notes and delivers the transcript in the message's `text` field (alongside a `voice` object with `file.id`, `duration`, and `was_recognized`). DM voices are not currently exposed by Y.M (the mic button is hidden in DMs).
**Why a special detection path:** Y.M's UI does not let users attach an `@`-mention to a voice message. In a group with `requireMention: true`, that means a voice would be rejected even when the user clearly addressed the bot. We compensate by scanning the transcript for the bot's display name (e.g. "Юстас") or login as a case-insensitive substring; a hit is treated as an implicit `voice_name_mention` that admits the message through the policy.
**What the agent sees:** the regular `body` is the auto-transcript text. No `voice` field is exposed on the agent side in v1; the voice file itself is not downloaded into the OpenClaw media buffer (deferred — see "Not yet implemented").
**Tuning:** the bot's `display_name` is observed from `chat_members_update.new[]` events (when the bot is added to a chat) and persisted to disk so it survives gateway restarts. If your on-disk identity file (at `~/.openclaw/state/yandex-messenger/<accountId>.identity.json`) was written by an earlier build that didn't capture `display_name`, the cache will upgrade itself in place the next time a `chat_members_update` for the bot arrives — typically when the bot is added to or removed from any chat. Until then the detector falls back to matching the bot's full login, which rarely appears in natural speech.
**Caveats:**
- If `was_recognized: false` (Y.M failed to transcribe), `text` is empty and the message is silently dropped.
- Voice file download (raw audio) is not implemented — see "Not yet implemented".
---
## Group management
The bot can create new Y.M group chats and manage their participants on beh
... (truncated)
channels
Comments
Sign in to leave a comment