discord-haskell: Write bots for Discord in Haskell

[ library, mit, network, program ] [ Propose Tags ]

Functions and data types to write discord bots. Official discord docs https://discordapp.com/developers/docs/reference.

See the project readme for quickstart notes https://github.com/aquarial/discord-haskell#discord-haskell

[Skip to Readme]
Versions [faq] 0.5.0, 0.5.1, 0.6.0, 0.7.0, 0.7.1, 0.8.0, 0.8.1, 0.8.2, 0.8.3, 0.8.4, 1.0.0, 1.1.0, 1.1.1, 1.1.2, 1.1.3, 1.2.0, 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.5.2, 1.6.0, 1.6.1, 1.7.0, 1.8.0, 1.8.1
Change log changelog.md
Dependencies aeson (>= && <1.5), async (>=2.2.1 && <2.3), base (==4.*), base64-bytestring (>= && <1.1), bytestring (>= && <0.11), containers (>= && <0.7), data-default (>= && <0.8), http-client (>= && <0.6), iso8601-time (>=0.1.5 && <0.2), JuicyPixels (>= && <3.4), MonadRandom (>= && <0.6), req (>=1.1.0 && <1.3), safe-exceptions (>= && <0.2), text (>= && <1.3), time (>= && <1.9), unordered-containers (>= && <0.3), vector (>= && <0.13), websockets (>= && <0.13), wuss (>=1.1.10 && <1.2) [details]
License MIT
Copyright 2019 Karl
Author Karl
Maintainer ksfish5@gmail.com
Category Network
Home page https://github.com/aquarial/discord-haskell
Bug tracker https://github.com/aquarial/discord-haskell/issues
Source repo head: git clone https://github.com/aquarial/discord-haskell.git
Uploaded by Aquarial at 2019-06-22T17:14:05Z
Distributions NixOS:1.8.1
Downloads 8411 total (66 in the last 30 days)
Rating 2.25 (votes: 4) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs not available [build log]
All reported builds failed as of 2019-06-22 [all 3 reports]


  • Discord
    • Discord.Gateway
      • Discord.Gateway.Cache
      • Discord.Gateway.EventLoop
    • Discord.Rest
      • Discord.Rest.Channel
      • Discord.Rest.Emoji
      • Discord.Rest.Guild
      • Discord.Rest.HTTP
      • Discord.Rest.Invite
      • Discord.Rest.Prelude
      • Discord.Rest.User
    • Discord.Types
      • Discord.Types.Channel
      • Discord.Types.Events
      • Discord.Types.Gateway
      • Discord.Types.Guild
      • Discord.Types.Prelude


Maintainer's Corner

For package maintainers and hackage trustees

Readme for discord-haskell-0.8.4

[back to package description]

discord-haskell Build Status

Please refer to Getting Started and Notes when relevant. A few minutes of reading can save you hours of debugging.

Recent change: master branch has the potentially broken, most recent commits, stable has the most recent working version. Pull requests are automatically made against master and it's nice to merge pull requests to test them.

Getting Started

1 Create an application at the Developer Portal: https://discordapp.com/developers/applications.

2 Add a 'Bot User' using the settings pane on the left. Take note of CLIENT ID on this page.

3 Use the BOT PERMISSIONS tab to compute a Permissions Int to use for step 3

3 Invite the bot to a server filling in the <information> below. Client ID and Permissions come from previous steps. https://discordapp.com/oauth2/authorize?client_id=<CLIENT_ID>&scope=bot&permissions=<PERMISSIONS>

4 To send CreateMessage events with restCall, you must connect to the gateway at least once. Try running examples/gateway.hs with your token to satisfy this. This is a Discord requirement.

5 Look at the examples to get an idea of how the library is used. examples/gateway.hs, examples/rest.hs, examples/cache.hs, and examples/ping-pong.hs

6 Understand what's available to the bot. Rest API calls can modify Channels, Emoji, Guilds, etc. Most endpoints are covered with very similar names. List Guild Emojis becomes ListGuildEmojis. You can use :info in ghci on type constructors to explore the ADTs.

Gateway Events provide the other source of info, using nextEvent and sendCommand. Use :info to explore Event and GatewaySendable ADTs.

7 Add this library to your dependencies. discord-haskell is on hackage, open an issue if the dependencies are too strict and you can't add it to your project.. You can also use the github repo.

# in stack.yaml (if using stack)
resolver: lts-12.10
- git: git@github.com:aquarial/discord-haskell.git
  commit: <most recent stable commit>
  extra-dep: true

# in project.cabal
  build-depends:       base
                     , discord-haskell


loginRest allows restCall. loginRestGateway allows restCall, nextEvent, sendCommand, and readCache. Use loginRest if you don't need the gateway.

Use Control.Exception.finally with stopDiscord to safely kill background threads when running examples in ghci (otherwise exit ghci and reopen to kill threads).

The examples will work on the stable branch. The master branch has the most recent (potentially) breaking changes.

To get the format to use for Emoji, type \:emoji: into a discord chat. You should copy-paste that into the request. This can be a bit finicky. The equivalent of :thumbsup::skin-tone-3: is "👍\127997" for example, and a custom emoji will look like <name:id_number> or name:id_number.


If something goes wrong with the library please open an issue. It is helpful, but not always necessary, to attach a log of what's going on when the library crashes.

Use loginRestGatewayWithLog :: Auth -> String -> IO (stuff) to write the events to a file. Remember to remove sensitive information before posting.


This library was originally forked from discord.hs. After rewriting the gateway/rest loops and extending the types I think it makes more sense to present this library as separate from the source. The APIs are not compatible.


In roughly the order I'm working on them:

  • Finish REST request ADT. Search for -- todo pattern
  • Add data types for permissions and presences
  • Update channel types (fill out guildcategory)
  • Modify cache with Events
  • Add gateway ToJSON for events
  • Update comments on ADT types