discord-haskell: Write bots for Discord in Haskell

[ library, mit, network, program ] [ Propose Tags ]
Versions [RSS] 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, 1.8.2, 1.8.3, 1.8.4, 1.8.5, 1.8.6, 1.8.7, 1.8.8, 1.8.9, 1.9.0, 1.9.1, 1.9.2, 1.10.0, 1.11.0, 1.12.0, 1.12.1, 1.12.2, 1.12.3, 1.12.4, 1.12.5, 1.13.0, 1.14.0, 1.15.0, 1.15.1, 1.15.2, 1.15.3, 1.15.4, 1.15.5, 1.15.6, 1.16.0, 1.16.1
Change log changelog.md
Dependencies aeson, async, base (>=4 && <5), base64-bytestring, bytestring, containers, data-default, discord-haskell, emoji (==0.1.0.2), http-client, iso8601-time, JuicyPixels, MonadRandom, mtl, req, safe-exceptions, text, time, unliftio, unordered-containers, vector, websockets, wuss [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 2021-11-14T05:53:51Z
Distributions NixOS:1.16.1
Reverse Dependencies 2 direct, 0 indirect [details]
Executables ping-pong
Downloads 17904 total (215 in the last 30 days)
Rating 2.5 (votes: 6) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2021-11-14 [all 1 reports]

Readme for discord-haskell-1.9.1

[back to package description]

discord-haskell Build Status Hackage version

Build that discord bot in Haskell! Also checkout the calamity haskell discord library for a more advanced interface than discord-haskell.

This is an example bot that replies "pong" to messages that start with "ping".

{-# LANGUAGE OverloadedStrings #-}  -- allows "string literals" to be Text

import Control.Monad (when, void)
import Data.Text (isPrefixOf, toLower, Text)
import qualified Data.Text.IO as TIO

import UnliftIO.Concurrent

import Discord
import Discord.Types
import qualified Discord.Requests as R

-- | Replies "pong" to every message that starts with "ping"
pingpongExample :: IO ()
pingpongExample = do userFacingError <- runDiscord $ def
                                            { discordToken = "Bot ZZZZZZZZZZZZZZZZZZZ"
                                            , discordOnEvent = eventHandler }
                     TIO.putStrLn userFacingError

eventHandler :: Event -> DiscordHandler ()
eventHandler event = case event of
       MessageCreate m -> when (not (fromBot m) && isPing m) $ do
               void $ restCall (R.CreateReaction (messageChannel m, messageId m) "eyes")
               threadDelay (2 * 10^6)
               void $ restCall (R.CreateMessage (messageChannel m) "Pong!")
       _ -> return ()

fromBot :: Message -> Bool
fromBot = userIsBot . messageAuthor

isPing :: Message -> Bool
isPing = ("ping" `isPrefixOf`) . toLower . messageText
-- ping-pong.cabal

executable haskell-bot
  main-is:             src/Main.hs
  default-language:    Haskell2010
  ghc-options:         -threaded
  build-depends:       base
                     , text
                     , unliftio
                     , discord-haskell

Biggest TODOs

  • APIv9
  • rewrite eventloop issue 70
  • Event type includes roles and other cached info
  • higher level bot interface? easier to add state and stuff

Installing

discord-haskell is on hosted on hackage at https://hackage.haskell.org/package/discord-haskell,

In stack.yaml

extra-deps:
- emoji-0.1.0.2
- discord-haskell-VERSION

In project.cabal

executable haskell-bot
  main-is:             src/Main.hs
  default-language:    Haskell2010
  ghc-options:         -threaded
  build-depends:       base
                     , text
                     , discord-haskell

For a more complete example with various options go to Installing the Library wiki page

Also take a look at Creating your first Bot for some help setting up your bot token

Emoji

For single character Emoji you can use the unicode name ("eyes", "fire", etc).

For multi-character Emoji you must use the discord format. Type \:emoji: into a discord chat and paste that into the Text

For example :thumbsup::skin-tone-3: is "👍\127997". A custom emoji will look like <name:id_number> or name:id_number.

See examples/ping-pong.hs for a CreateReaction request in use.

Embeds

Embeds are special messages with boarders and images. Example embed created by discord-haskell

The Embed record (and sub-records) store embed data received from Discord.

The CreateEmbed record stores data when we want to create an embed.

CreateEmbed has a Default instance, so you only need to specify the fields you use:

_ <- restCall (R.CreateMessageEmbed <channel_id> "Pong!" $
        def { createEmbedTitle = "Pong Embed"
            , createEmbedImage = Just $ CreateEmbedImageUpload <bytestring>
            , createEmbedThumbnail = Just $ CreateEmbedImageUrl
                    "https://avatars2.githubusercontent.com/u/37496339"
            })

Uploading a file each time is slow, prefer uploading images to a hosting site like imgur.com, and then referencing them.

Limitations

The following features are not implemented:

  • Voice & Audio
  • Authenticating with a user token

Debugging

Always print the userFacingError Text returned from runDiscord. I use this to record errors that cannot be recovered from.

If something else 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.

Assign a handler to the discordOnLog :: Text -> IO () to print info as it happens. Remember to remove sensitive information before posting.

Getting Help

Official discord docs

For a list of rest requests, gateway events, and gateway sendables go to the official discord documentation

The rest requests line up very closely. The documentation lists Get Channel and discord-haskell has GetChannel :: ChannelId -> ChannelRequest Channel. Same for gateway Events.

Examples

The examples were crafted to display a variety of use cases. Read them with care.

Open an Issue

For deeper questions about how the library functions, feel free to open an issue.

Discord server

Coming sometime!