Back to Details

hermes-bale-messenger

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bale Platform Adapter for Hermes

适用于Hermes的Bale平台适配器

Adds Bale (بله) messenger support to Hermes Gateway as a platform plugin. Your AI agent can send/receive messages, voice notes, images, and documents through Bale via the Bot API.
作为平台插件为Hermes Gateway添加Bale（بله）即时通讯工具支持。你的AI agent可通过Bot API在Bale上发送/接收消息、语音笔记、图片和文档。

Quick Install

快速安装

bash
cd ~/.hermes/plugins/platforms/
git clone https://github.com/mah92/hermes-bale-messenger-plugin.git bale
hermes plugins enable hermes-bale-messenger
Then add your bot token to 
~/.hermes/.env
:
env
BALE_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
BALE_ALLOWED_CHATS=123456789,987654321
Restart the gateway and you're done.
bash
cd ~/.hermes/plugins/platforms/
git clone https://github.com/mah92/hermes-bale-messenger-plugin.git bale
hermes plugins enable hermes-bale-messenger
然后将你的机器人令牌添加至
~/.hermes/.env
文件：
env
BALE_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
BALE_ALLOWED_CHATS=123456789,987654321
重启网关即可完成配置。

Files

文件说明

FilePurpose
plugin.yaml
Platform manifest — env vars, metadata
__init__.py
Package entry — re-exports 
register()
adapter.py
Full 
BasePlatformAdapter
implementation
文件用途
plugin.yaml
平台清单——环境变量、元数据
__init__.py
包入口——重新导出
register()
方法
adapter.py
BasePlatformAdapter
完整实现

Features

功能特性

  • Text messages (send & receive)
  • Voice messages — send via TTS, receive voice/audio as downloadable files
  • Images — send by URL (with download fallback) or local file upload
  • Documents — upload and send
  • Typing indicators (
    sendChatAction
    )
  • Group chat support with optional @mention gate
  • User/chat allowlisting
  • Cron delivery support
  • 文本消息（发送与接收）
  • 语音消息——通过TTS发送，接收的语音/音频可作为可下载文件获取
  • 图片——通过URL发送（支持下载回退）或本地文件上传
  • 文档——上传并发送
  • 输入状态提示（
    sendChatAction
    ）
  • 群聊支持，可选@提及限制
  • 用户/聊天白名单
  • 定时发送支持

Configuration

配置说明

All via 
~/.hermes/.env
:
VariableRequiredDefaultDescription
BALE_BOT_TOKEN
✅—Bot token from @BotFather
BALE_ALLOWED_CHATS
—allComma-separated chat IDs
BALE_ALLOWED_USERS
—allComma-separated user IDs
BALE_ALLOW_ALL_USERS
—falseSet "true" for open access
BALE_HOME_CHANNEL
——Default chat for cron delivery
BALE_REQUIRE_MENTION
—falseRequire @mention in groups
BALE_MAX_VOICE_DURATION
—30000Max voice/audio duration (milliseconds) for STT. 0 = no limit
所有配置均通过
~/.hermes/.env
文件设置：
变量名是否必填默认值描述
BALE_BOT_TOKEN
✅—从@BotFather获取的机器人令牌
BALE_ALLOWED_CHATS
—全部逗号分隔的聊天ID列表
BALE_ALLOWED_USERS
—全部逗号分隔的用户ID列表
BALE_ALLOW_ALL_USERS
—false设置为"true"则开放所有访问权限
BALE_HOME_CHANNEL
——定时发送的默认聊天渠道
BALE_REQUIRE_MENTION
—false群聊中要求@提及机器人
BALE_MAX_VOICE_DURATION
—30000用于语音转文本（STT）的最大语音/音频时长（毫秒）。0表示无限制

How It Works

工作原理

The adapter uses Bale's Bot API (Telegram-compatible) with long-polling. No gRPC, no user account — just HTTP calls to 
tapi.bale.ai
.
Bale Server ←→ HTTP Long Poll ←→ Hermes Gateway ←→ AI Agent
该适配器使用Bale的Bot API（兼容Telegram）和长轮询机制。无需gRPC，无需用户账户——仅需向
tapi.bale.ai
发起HTTP请求。
Bale Server ←→ HTTP Long Poll ←→ Hermes Gateway ←→ AI Agent

Common Pitfalls

常见问题

  1. Bot blocked by user: User must 
    /start
    the bot before it can DM them.
  2. Bot-to-bot blocked: Bale (like Telegram) blocks bots from seeing each other's messages, even in groups. Use a user account bridge for bot-to-bot.
  3. Group privacy: The bot must be an admin to see all group messages, otherwise it only sees 
    /command
    and replies.
  4. Voice messages arrive empty? Transcription needs an STT provider. The 
    hermes-persian-stt
    skill in this repo provides Persian STT, or set 
    stt.provider
    in 
    ~/.hermes/config.yaml
    .
  5. TTS voice not delivered? Set 
    voice_compatible: true
    on your TTS provider in config.yaml. The adapter now overrides 
    send_voice
    to upload directly via Bale's 
    sendVoice
    API (retries 3×). Without this, Hermes emits 
    MEDIA:
    tags which Bale cannot render.
  6. Cache after edits: Always 
    find ~/.hermes/plugins/platforms/bale -name __pycache__ -exec rm -rf {} +
    after editing adapter files.
  7. Webhook blocks polling: If you previously used webhook mode, call 
    deleteWebhook
    before switching to polling — 
    curl -s "https://tapi.bale.ai/bot$BALE_BOT_TOKEN/deleteWebhook"
    . Otherwise 
    getUpdates
    returns nothing.
  8. 401 Unauthorized: Token expired or regenerated from @BotFather. Get a new token and update 
    BALE_BOT_TOKEN
    in 
    ~/.hermes/.env
    .
  1. 机器人被用户屏蔽： 用户必须先向机器人发送
    /start
    指令，机器人才可向其发送私信。
  2. 机器人之间无法交互： Bale（类似Telegram）禁止机器人查看其他机器人的消息，即使在群聊中也是如此。如需机器人之间交互，请使用用户账户桥接。
  3. 群聊隐私设置： 机器人必须是群管理员才能查看所有群消息，否则仅能查看
    /command
    指令和回复消息。
  4. 语音消息为空？ 语音转文本需要STT服务提供商。本仓库中的
    hermes-persian-stt
    skill提供波斯语STT服务，或在
    ~/.hermes/config.yaml
    中设置
    stt.provider
    。
  5. TTS语音未送达？ 在config.yaml中为你的TTS服务提供商设置
    voice_compatible: true
    。适配器现在会重写
    send_voice
    方法，直接通过Bale的
    sendVoice
    API上传（重试3次）。如果不设置此项，Hermes会生成Bale无法识别的
    MEDIA:
    标签。
  6. 编辑后的缓存问题： 编辑适配器文件后，请务必执行
    find ~/.hermes/plugins/platforms/bale -name __pycache__ -exec rm -rf {} +
    清除缓存。
  7. Webhook阻塞轮询： 如果之前使用过Webhook模式，请在切换到轮询模式前调用
    deleteWebhook
    ——执行
    curl -s "https://tapi.bale.ai/bot$BALE_BOT_TOKEN/deleteWebhook"
    。否则
    getUpdates
    将返回空结果。
  8. 401未授权： 令牌过期或已在@BotFather处重新生成。获取新令牌并更新
    ~/.hermes/.env
    中的
    BALE_BOT_TOKEN
    。