Skip to content
Minimalist Discord library for Crystal. (Still WIP, but usable)
Branch: master
Clone or download
Pull request Compare This branch is 30 commits ahead of meew0:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Add initial Circle CI config Jun 13, 2019
examples Implement middleware system Jun 13, 2019
src Add support for guild_subscriptions in IDENTIFY Jul 12, 2019
.gitignore Add the new docs folder to .gitignore Jan 7, 2018
LICENSE Initial commit Sep 2, 2016 Update Jun 13, 2019
shard.yml Release 0.4.0 Jun 23, 2018



(The "cr" stands for "creative name".)

discordcr is a minimalist Discord API library for Crystal, designed to be a complement to discordrb for users who want more control and performance and who care less about ease-of-use.

discordcr isn't designed for beginners to the Discord API - while experience with making bots isn't required, it's certainly recommended. If you feel overwhelmed by the complex documentation, try discordrb first and then check back.

Unlike many other libs which handle a lot of stuff, like caching or resolving, themselves automatically, discordcr requires the user to do such things manually. It also doesn't provide any advanced abstractions for REST calls; the methods perform the HTTP request with the given data but nothing else. This means that the user has full control over them, but also full responsibility. discordcr does not support user accounts; it may work but likely doesn't.

Fork status

This is a fork from meew0/discordcr. I've started maintaining my own fork since I've been in need of additional library support for things such as new Discord features and utilities.

Please feel free to use this fork and report any issues - I will address any that come up as soon as I can.

If you have issues or bug reports, please ask in the #crystal-discordcr channel first if you can. Especially if its just a feature request.

Feel free to contact me directly as well - z64#1337.

In the future, the changes to this fork may be ported upstream. I will also merge upstream PRs here that I have approved.


Add this to your application's shard.yml:

    github: z64/discordcr


An example bot can be found here. More examples will come in the future.

A short overview of library structure: the Client class includes the REST module, which handles the REST parts of Discord's API; the Client itself handles the gateway, i. e. the interactive parts such as receiving messages. It is possible to use only the REST parts by never calling the #run method on a Client, which is what does the actual gateway connection.

The example linked above has an example of an event (on_message_create) that is called through the gateway, and of a REST call (client.create_message). Other gateway events and REST calls work much in the same way - see the documentation for what specific events and REST calls do.

Caching is done using a separate Cache class that needs to be added into clients manually:

client = # ...
cache =
client.cache = cache

Resolution requests for objects can now be done on the cache object instead of directly over REST, this ensures that if an object is needed more than once there will still only be one request to Discord. (There may even be no request at all, if the requested data has already been obtained over the gateway.) An example of how to use the cache once it has been instantiated:

# Get the username of the user with ID 66237334693085184
user = cache.resolve_user(66237334693085184_u64)
user = cache.resolve_user(66237334693085184_u64) # won't do a request to Discord
puts user.username

Apart from this, API documentation is also available, at


  1. Fork it (
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

CircleCI is used for continuous integration. You can run tests locally in Docker using the following commands if you want:

$ circleci local execute --job specs
$ circleci local execute --job format
$ circleci local execute --job examples

See .circleci/config.yml for more details.


  • meew0 - creator, maintainer
  • RX14 - Crystal expert, maintainer
  • z64 - maintainer
You can’t perform that action at this time.