#kupas/imrelay

#Supported platforms

#Build & test

moon check --target native
moon build  --target native
moon test   --target native        # 131 tests

#Run

IMRELAY_CONFIG=gateway.toml moon run example/main --target native

GET  /                        landing page / health check
GET  /health                  {"ok":true,"platforms":N}
POST /<platform>              inbound webhook for that platform (per table above)

#Configuration

#gateway.toml

[gateway]
name = "my-gateway"            # optional
host = "0.0.0.0"               # listen address
port = 8080                    # listen port
public_url = "https://chat.example.com/"   # optional, used for webhook hints
allowed_users = ["alice"]      # optional global allow-list
allow_all_users = true         # optional; default false

[platforms.telegram]
token = "123:abc"
home_channel = "-100123"
home_channel_name = "Ops"
home_channel_thread = "42"
allowed_users = ["alice"]

[platforms.telegram.extra]     # platform-specific options (see below)
parse_mode = "MarkdownV2"
api_base = "https://tg.local"  # optional self-hosted Bot API
polling = true                 # telegram also long-polls by default

#Environment variables

#How it works

1. Inbound — a webhook server on <host>:<port> routes POST /<platform> to the matching adapter's parser, which normalizes the payload into a MessageEvent. Webhook requests are authenticated first (see the table above); handshakes are answered before that: Slack/Feishu challenge, WhatsApp hub.challenge, WeCom echostr. Telegram and WeChat additionally long-poll, and Matrix polls /sync (each in its own background task).
2. Authorization — every event must pass allowed_users: the platform or gateway allowlist must contain the user id (or *), unless allow_all_users = true. With no allowlist configured the gate is closed (the gateway logs who was dropped, and warns at startup). A home_channel (with optional thread/name) marks where notifications go.
3. Session — each (platform, chat_id) gets a Session with bounded history (Gateway::new(cfg, handler, max_history=24)). The agent callback async (MessageEvent, Session) -> String receives both.
4. Commands — inbound text starting with / is intercepted first: /help, /reset, /new, /status, /platforms are answered locally; unknown commands still reach the agent.
5. Send — a reply is delivered through the platform adapter: chunked at Platform::max_message_length, trimmed to truncate limits, retried on transient failures with backoff honoring server retry_after (Telegram FloodWait etc.), and suppressed when the handler returns a silence token ([silent], no reply, empty).
6. Errors — every failure is a typed SendResult with SendErrorKind (TooLong/BadFormat/Forbidden/NotFound/RateLimited/Transient/Unknown) via classify_send_error, mirroring Hermes' SEND_ERROR_KINDS.

#Library quick tour

// Normalize a raw webhook body (any platform).
let events : Array[MessageEvent] = @imrelay.parse_inbound(@imrelay.Telegram, raw)

// Build the gateway with a history-aware agent.
let gw = @imrelay.Gateway::new(cfg, async (ev, session) => "echo: \{ev.text}")
gw.run()

// Classify send failures the way Hermes does.
let kind = @imrelay.classify_send_error("Bad Request: chat not found") // NotFound
assert_true(@imrelay.is_chat_level_not_found("chat not found"))

// Chunk a long reply at a platform's limit, preferring paragraph breaks.
let chunks = @imrelay.chunk_text(long_reply, @imrelay.Platform::max_message_length(p))

#Testing

moon test --target native

#Platform notes

• BlueBubbles (iMessage) — built in as a first-class adapter: it talks directly to the REST API of your own BlueBubbles server ({server_url}/api/v1, GET /ping, POST /message/text, POST /chat/query, password-authenticated), and receives inbound messages from that server's new-message webhook ({"type":"new-message","data":…}). You only need to run a BlueBubbles server on your Mac — the same way Signal needs your own signal-cli HTTP daemon and Telegram can use a self-hosted Bot API base. Messages use chats[].guid as the chat id.
• WeChat — via Tencent's official iLink Bot API (base_url default https://ilinkai.weixin.qq.com, long-polled): you scan a QR to bind a bot identity, and only direct messages are reliably delivered — iLink bots typically cannot join regular group chats. Media uploads (encrypted CDN) and the QR setup wizard are not ported; the adapter covers text send, typing and long-poll receive.
• WhatsApp: Cloud Business API over Graph (graph.facebook.com), with hub verification for webhook subscriptions.
• DingTalk / WeCom / Feishu: keys/secret pairs for the official app APIs; DingTalk and WeCom also support static inbound-robot webhooks. WeCom callback mode additionally implements the official WXBizMsgCrypt msg_signature + AES-256-CBC verification and decryption (callback_token
  • encoding_aes_key), plus the GET echostr handshake.