#harmony #protocol #api #chat #client


Rust library to work with the Harmony chat protocol

14 releases (7 breaking)

0.8.0 Jan 9, 2022
0.7.0 Nov 29, 2021
0.6.1 Jul 9, 2021
0.5.1 Mar 9, 2021
0.1.0 Dec 21, 2020

#1783 in Web programming

33 downloads per month
Used in ilo-toki

MIT license

2.5K SLoC

GitHub Workflow Status crates.io docs.rs docs.rs MSRV

Rust implementation of the Harmony chat protocol. Currently implements a lightweight client and a client API (powered by hrpc), along with auto generated API via hrpc-build.


  • Latest stable Rust and Cargo.
  • If you are using Nix, nix-shell (or nix develop if you use flakes) should get you covered.
  • Otherwise, you'll need to get protobuf and make sure protoc is in your PATH env variable.
    • If for some reason build.rs fails, make sure to set:
      • PROTOC env variable to your protoc executable
      • and PROTOC_INCLUDE env variable to wherever protobuf include files are located, most likely in /usr/share/include.


  • echo_bot: Showcases a simple message echo bot that operates in a guild. It will repost messages whenever someone else posts a message.
  • message_log: Showcases a simple message log bot that operates in a guild. It will log messages to the console whenever someone posts a message.
  • cmd_bot: A more complex bot that responds to "commands". The commands are:
    • r!ping: responds with "Pong! Took X secs."
    • r!hello: responds with "Hello, username!"
    • r!uptime: responds with "Been running for X secs."
  • Bot run instructions:
    • Run bots with GUILD_INVITE=invite cargo run --example example_name.
    • Make sure the bot has necessary permissions to view channels / send messages etc.

Crate features

  • By default, only a bare-bones common API of all services is generated. You can customize the crate to your needs by enabling feature(s) listed below:
    • Enable the client_native feature for a lightweight client implementation that uses hyper and works on native platforms.
    • Enable the client_web feature for a lightweight client implementation that works on web platforms (WASM).
    • Enable the client_backoff feature to enable request retrying on ratelimited requests.
    • Enable the gen_client feature to generate client service code.
    • Enable the gen_server feature to generate server service code.
    • (Default) Enable the gen_chat feature to generate chat service code.
    • (Default) Enable the gen_auth feature to generate auth service code.
    • (Default) Enable the gen_voice feature to generate voice service code.
    • (Default) Enable the gen_mediaproxy feature to generate media proxy service code.
    • (Default) Enable the gen_harmonytypes feature to generate common Harmony types.
    • (Default) Enable the gen_sync feature to generate sync service code.
    • (Default) Enable the gen_emote feature to generate emote service code.
    • (Default) Enable the gen_profile feature to generate profile service code.
    • (Default) Enable the gen_batch feature to generate batch service code.


Minimum Supported Rust Version: current stable.

Changing MSRV is not considered a semver-breaking change.


~255K SLoC