racket-cord: Racket discord library

8.1

top ← prev up next →

racket-cord: Racket discord library

1 Example

Example usage of the library:

(require racket-cord)

(define bot-token (getenv "BOT_TOKEN"))

(define myclient (make-client bot-token #:auto-shard #t))

(on-event
  'message-create myclient
  (lambda (client message)
    (unless (string=? (user-id (message-author message))
                      (user-id (client-user client)))
      (cond
        [(string-prefix? (message-content message) "!echo ")
         (http:create-message client (message-channel-id message)
                              (string-trim (message-content message) "!echo " #:right? #f))]))))

(define dr (make-log-receiver discord-logger 'debug))

(thread
  (thunk
    (let loop ()
      (let ([v (sync dr)])
        (printf "[~a] ~a\n" (vector-ref v 0)
                (vector-ref v 1)))
      (loop))))

(start-client myclient)

2 Client

procedure
(make-client token
[ #:intents intents
#:token-type token-type
#:auto-shard auto-shard
#:shard-count shard-count]) → client?
  token : string?
  intents : (listof integer?) = null
  token-type : (or/c 'bot 'bearer 'client) = 'bot
  auto-shard : boolean? = #f
  shard-count : integer? = 1

Constructs a client with the passed token.

#:auto-shard: If #t, ask Discord what the number of shards should be. Only applies if #:token-type is 'bot.

#:shard-count: If #:auto-shard is #f, the number of shards to use.

procedure
(start-client client) → void?
client : client?

Starts a client and begins handling events.
This function blocks until the client is stopped through stop-client.

procedure
(start-client-no-wait client) → void?
client : client?

Same as start-client but does not block the calling thread.

procedure
(stop-client client) → void?
client : client?

Stops a client

procedure
(update-status client
guild-id
[ #:since since
#:activities activities
#:status status
#:afk afk]) → void?
  client : client?
  guild-id : integer?
  since : (or/c integer? #f) = #f
  activities : (listof hash?) = null
   status : (or/c "online" "dnd" "idle" "invisible" "offline")
= "online"
  afk : boolean? = #f

Updates the client’s status.

struct
(struct client ( shards
user
guilds
private-channels
events
http-client
token
running)
    #:mutable
    #:transparent)
  shards : list?
  user : user?
  guilds : (hash/c string? guild?)
  private-channels : (hash/c string? dm-channel?)
  events : (hash/c symbol? procedure?)
  http-client : http:http-client?
  token : string?
  running : semaphore?

Stores the state of the client.

3 Data Models

Note that these have rotted significantly at the time of writing. Please see the source for precise details. Not all data models are fully specified or working.

struct
(struct guild ( shard-id
id
name
icon
splash
owner-id
region
afk-channel-id
afk-timeout
embed-enabled
embed-channel-id
verification-level
default-message-notifications
explicit-content-filter
roles
emojis
features
mfa-level
application-id
widget-enabled
widget-channel-id
joined-at
large
member-count
voice-states
members
channels
presences))
  shard-id : integer?
  id : string?
  name : string?
  icon : string?
  splash : string?
  owner-id : string?
  region : string?
  afk-channel-id : string?
  afk-timeout : integer?
  embed-enabled : boolean?
  embed-channel-id : string?
  verification-level : integer?
  default-message-notifications : integer?
  explicit-content-filter : integer?
  roles : (hash/c string? role?)
  emojis : (hash/c string? emoji?)
  features : (listof string?)
  mfa-level : integer?
  application-id : string?
  widget-enabled : boolean?
  widget-channel-id : string?
  joined-at : string?
  large : boolean?
  member-count : integer?
  voice-states : jsexpr?
  members : (hash/c string? member?)
  channels : (hash/c string? guild-channel?)
  presences : (listof jsexpr?)

struct
(struct guild-channel ( id
type
guild-id
position
permission-overwrites
name
topic
nsfw
last-message-id
bitrate
user-limit
parent-id))
  id : string?
  type : integer?
  guild-id : string?
  position : integer?
  permission-overwrites : (listof jsexpr?)
  name : string?
  topic : string?
  nsfw : boolean?
  last-message-id : string?
  bitrate : integer?
  user-limit : integer?
  parent-id : string?

An object representing a guild text channel or a guild voice channel. Fields that only exist for voice channels will be null for a text channel, and vice-versa.

struct
(struct dm-channel ( id
type
name
last-message-id
icon
recipients
owner-id
application-id))
  id : string?
  type : integer?
  name : string?
  last-message-id : string?
  icon : string?
  recipients : string?
  owner-id : string?
  application-id : string?

struct
(struct user (id username discriminator avatar bot mfa-enabled))
  id : string?
  username : string?
  discriminator : string?
  avatar : string?
  bot : boolean?
  mfa-enabled : boolean?

struct
(struct member (user nick roles joined-at deaf mute status game))
  user : user?
  nick : (or/c string? null?)
  roles : (listof string?)
  joined-at : string?
  deaf : boolean?
  mute : boolean?
  status : (or/c string? null?)
  game : (or/c game? null?)

struct
(struct message ( id
channel-id
author
content
timestamp
edited-timestamp
tts
mention-everyone
mentions
mention-roles
attachments
embeds
reactions
pinned
type))
  id : string?
  channel-id : string?
  author : (or/c user? null?)
  content : string?
  timestamp : string?
  edited-timestamp : (or/c string? null?)
  tts : boolean?
  mention-everyone : boolean?
  mentions : (listof user?)
  mention-roles : (listof role?)
  attachments : jsexpr?
  embeds : jsexpr?
  reactions : jsexpr?
  pinned : boolean?
  type : integer?

struct
(struct role ( id
name
color
hoist
position
permissions
managed
mentionable))
  id : string?
  name : string?
  color : integer?
  hoist : boolean?
  position : integer?
  permissions : integer?
  managed : boolean?
  mentionable : boolean?

struct
(struct emoji (id name roles user require-colons managed))
  id : string?
  name : string?
  roles : (listof string?)
  user : (or/c user? null?)
  require-colons : boolean?
  managed : boolean?

struct
(struct game (name type url))
  name : string?
  type : integer?
  url : string?

struct
(struct invite (code guild-id channel-id))
  code : string?
  guild-id : string?
  channel-id : string?

struct
(struct webhook (id guild-id channel-id user name avatar token))
  id : string?
  guild-id : (or/c string? null?)
  channel-id : string?
  user : (or/c user?)
  name : (or/c string? null?)
  avatar : (or/c string? null?)
  token : string?

4 Events

procedure
(on-event evt client callback) → void?
  evt : symbol?
  client : client?
  callback : procedure?

Subscribe to callbacks for the given gateway event identified by evt.

The Racket symbol name evt corresponding to a given Discord gateway event is derived as follows:

Lowercase the event name
Replace underscores with dashes
Convert to symbol

For example, the Discord gateway event MESSAGE_CREATE would be identified as the Racket symbol 'message-create.

The exact type for callback depends on the specific event, see Event Callback Signatures for more information.

Example:

(on-event 'message-create
(lambda (client message)
(println (message-content message))))

Each event has a raw counterpart, identified by prepending raw- to the Racket symbolic name. For example, the raw event symbol for MESSAGE_CREATE would be 'raw-message-create.

Raw events contain the raw data as provided by the Discord gateway. In contrast, the regular events are unmarshalled into structural representations by the library.

As of the time of writing, the regular events have bitrotted quite a bit and will need some work to fix. If you must receive many events reliably, using raw events is recommended.

Raw events will also allow you to immediately react to new features added by Discord without having to wait for the library to update.

In contrast to regular events, all raw event callbacks have the same type:

procedure
(raw-callback ws-client client data) → void?
  ws-client : ws-client?
  client : client?
  data : jsexpr?

where data is the raw d payload received from the Discord gateway.

4.1 Event Callback Signatures

Below are the expected callback signatures for event handlers.

Note that some of these are no longer accurate and the authors are working on fixing them.

procedure
(channel-create client channel) → void?
  client : client?
  channel : (or/c dm-channel? guild-channel?)
procedure
(channel-delete client channel) → void?
  client : client?
  channel : (or/c dm-channel? guild-channel?)
procedure
(channel-update client
old-channel
new-channel) → void?
  client : client?
  old-channel : (or/c dm-channel? guild-channel?)
  new-channel : (or/c dm-channel? guild-channel?)
procedure
(guild-create client guild) → void?
  client : client?
  guild : guild?
procedure
(guild-delete client guild) → void?
  client : client?
  guild : guild?
procedure
(guild-update client old-guild new-guild) → void?
  client : client?
  old-guild : guild?
  new-guild : guild?
procedure
(guild-ban-add client user guild) → void?
  client : client?
  user : user?
  guild : guild?
procedure
(guild-ban-remove client user guild) → void?
  client : client?
  user : user?
  guild : guild?
procedure
(guild-emojis-update client guild emojis) → void?
  client : client?
  guild : guild?
  emojis : (listof emoji?)
procedure
(guild-member-add client member) → void?
  client : client?
  member : member?
procedure
(guild-member-remove client member) → void?
  client : client?
  member : member?
procedure
(guild-member-update client
old-member
new-member) → void?
  client : client?
  old-member : member?
  new-member : member?
procedure
(presence-update client
old-member
new-member) → void?
  client : client?
  old-member : member?
  new-member : member?
procedure
(message-create client message) → void?
  client : client?
  message : message?
procedure
(message-delete client message-id) → void?
  client : client?
  message-id : string?
procedure
(message-reaction-add client
user-id
channel-id
message-id
emoji) → void?
  client : client?
  user-id : string?
  channel-id : string?
  message-id : string?
  emoji : emoji?
procedure
(message-reaction-remove client
user-id
channel-id
message-id
emoji) → void?
  client : client?
  user-id : string?
  channel-id : string?
  message-id : string?
  emoji : emoji?
procedure
(message-reaction-remove-all client
channel-id
message-id) → void?
  client : client?
  channel-id : string?
  message-id : string?
procedure
(typing-start client channel-id user-id) → void?
  client : client?
  channel-id : string?
  user-id : string?

5 Miscellaneous functions

procedure
(get-channels client) → (listof guild-channel?)
client : client?

procedure
(get-channel client id) → (or/c guild-channel? null?)
client : client?
id : string?

Get a channel by id. Returns null on failure.

procedure
(get-guild client id) → (or/c guild? null?)
client : client?
id : string?

Get a guild by id. Returns null on failure.

procedure
(get-member client member-id guild-id) → (or/c member? null?)
  client : client?
  member-id : string?
  guild-id : string?

Get a member of a guild by id. Returns null on failure.

6 HTTP

HTTP requests are defined here. Ratelimiting is handled for you by the library. Requests that fail raise a exn:fail:network:http:discord? exception.

procedure
(http:get-channel client channel-id)
→ (or/c dm-channel? guild-channel?)
client : client?
channel-id : string?

Request a channel.

procedure
(http:modify-channel client channel-id data)
→ (or/c dm-channel? guid-channel?)
  client : client?
  channel-id : string?
  data : hash?

data should be a hashmap that conforms to Modify Channel.

procedure
(http:delete-channel client channel-id) → jsexpr?
client : client?
channel-id : string?

procedure
(http:get-channel-messages client
channel-id
params ...) → (listof message?)
  client : client?
  channel-id : string?
  params : (cons/c string? string?)

params provided should be cons cells of '(k . v) conforming to Get Channel Message.

procedure
(http:get-channel-message client
channel-id
message-id) → message?
  client : client?
  channel-id : string?
  message-id : string?

procedure
(http:create-message client
[ content
#:embed embed
#:tts tts
#:file file]) → message?
  client : client?
  content : string? = ""
  embed : jsexpr? = null
  tts : boolean? = #f
  file : attachment? = #f

procedure
(http:edit-message client
channel-id
message-id
[ #:content content
#:embed embed]) → message?
  client : client?
  channel-id : string?
  message-id : string?
  content : (or/c string? null?) = null
  embed : jsexpr? = null

procedure
(http:delete-message client
channel-id
message-id) → jsexpr?
  client : client?
  channel-id : string?
  message-id : string?

procedure
(http:create-reaction client
channel-id
message-id
emoji) → jsexpr?
  client : client?
  channel-id : string?
  message-id : string?
  emoji : string?

procedure
(http:delete-own-reaction client
channel-id
message-id
emoji) → jsexpr?
  client : client?
  channel-id : string?
  message-id : string?
  emoji : string?

procedure
(http:delete-user-reaction client
channel-id
message-id
emoji
user-id) → jsexpr?
  client : client?
  channel-id : string?
  message-id : string?
  emoji : string?
  user-id : string?

procedure
(http:get-reactions client
channel-id
message-id
emoji
params ...) → (listof user?)
  client : client?
  channel-id : string?
  message-id : string?
  emoji : string?
  params : (cons string? string?)

params provided should be cons cells of '(k . v) conforming to Get Reactions.

procedure
(http:delete-all-reactions client
channel-id
message-id) → jsexpr?
  client : client?
  channel-id : string?
  message-id : string?

procedure
(http:bulk-delete-messages client
channel-id
ids ...) → jsexpr?
  client : client?
  channel-id : string?
  ids : string?

procedure
(http:edit-channel-permissions client
channel-id
overwrite-id
allow
deny
type) → jsexpr?
  client : client?
  channel-id : string?
  overwrite-id : string?
  allow : integer?
  deny : integer?
  type : string?

procedure
(http:get-channel-invites client
channel-id) → jsexpr?
client : client?
channel-id : string?

procedure
(http:create-channel-invite client
channel-id
[ age
uses
temporary
unique]) → invite?
  client : client?
  channel-id : string?
  age : integer? = 86400
  uses : integer? = 0
  temporary : boolean? = #f
  unique : boolean = #f

procedure
(http:delete-channel-permission client
channel-id
overwrite-id) → jsexpr?
  client : client?
  channel-id : string?
  overwrite-id : string?

procedure
(http:trigger-typing-indicator client
channel-id) → jsexpr?
client : client?
channel-id : string?

procedure
(http:get-pinned-messages client
channel-id) → (listof message?)
client : client?
channel-id : string?

procedure
(http:add-pinned-channel-message client
channel-id
message-id) → jsexpr?
  client : client?
  channel-id : string?
  message-id : string?

procedure
(http:delete-pinned-channel-message client
channel-id
message-id) → jsexpr?
  client : client?
  channel-id : string?
  message-id : string?

procedure
(http:group-dm-add-recipient client
channel-id
user-id
access-token
nick) → jsexpr?
  client : client?
  channel-id : string?
  user-id : string?
  access-token : string?
  nick : string?

procedure
(http:group-dm-remove-recipient client
channel-id
user-id) → jsexpr?
  client : client?
  channel-id : string?
  user-id : string?

procedure
(http:list-guild-emoji client guild-id) → (listof emoji?)
client : client?
guild-id : string?

procedure
(http:get-guild-emoji client
guild-id
emoji-id) → emoji?
  client : client?
  guild-id : string?
  emoji-id : string?

procedure
(http:create-guild-emoji client
guild-id
name
image
image-type
roles) → emoji?
  client : client?
  guild-id : string?
  name : string?
  image : bytes?
  image-type : string?
  roles : (listof string?)

procedure
(http:modify-guild-emoji client
guild-id
emoji-id
name
roles) → emoji?
  client : client?
  guild-id : string?
  emoji-id : string?
  name : string?
  roles : (listof string?)

procedure
(http:delete-guild-emoji client
guild-id
emoji-id) → jsexpr?
  client : client?
  guild-id : string?
  emoji-id : string?

procedure
(http:get-guild client guild-id) → guild?
client : client?
guild-id : string?

procedure
(http:modify-guild client guild-id data) → guild?
  client : client?
  guild-id : string?
  data : hash?

data should be a hashmap that conforms to Modify Guild.

procedure
(http:delete-guild client guild-id) → jsexpr?
client : client?
guild-id : string?

procedure
(http:get-guild-channels client guild-id)
→ (listof guild-channel?)
client : client?
guild-id : string?

procedure
(http:create-guild-channel client
guild-id
data) → guild-channel?
  client : client?
  guild-id : string?
  data : hash?

data should be a hashmap that conforms to Create Guild Channel.

procedure
(http:modify-guild-channel-permissions client
guild-id
data)
→ (racket data)
  client : client?
  guild-id : string?
  data : hash?

should be a hashmap that conforms to Modify Guild Channel Positions.

procedure
(http:get-guild-member client
guild-id
user-id) → member?
  client : client?
  guild-id : string?
  user-id : string?

procedure
(http:list-guild-members client
guild-id
[ #:limit limit
#:after after]) → (listof member?)
  client : client?
  guild-id : string?
  limit : integer? = 1
  after : integer? = 0

procedure
(http:add-guild-member client
guild-id
user-id
data) → member?
  client : client?
  guild-id : string?
  user-id : string?
  data : hash?

data should be a hashmap that conforms to Add Guild Member.

procedure
(http:modify-guild-member client
guild-id
user-id
data) → jsexpr?
  client : client?
  guild-id : string?
  user-id : string?
  data : hash?

data should be a hashmap that conforms to Modify Guild Member.

procedure
(http:modify-user-nick client guild-id nick) → jsexpr?
  client : client?
  guild-id : string?
  nick : string?

procedure
(http:add-guild-member-rols client
guild-id
user-id
role-id) → jsexpr?
  client : client?
  guild-id : string?
  user-id : string?
  role-id : string?

procedure
(http:remove-guild-member-role client
guild-id
user-id
role-id) → jsexpr?
  client : client?
  guild-id : string?
  user-id : string?
  role-id : string?

procedure
(http:remove-guild-member client
guild-id
user-id) → jsexpr?
  client : client?
  guild-id : string?
  user-id : string?

procedure
(http:get-guild-bans client guild-id) → jsexpr?
client : client?
guild-id : string?

procedure
(http:create-guild-ban client
guild-id
user-id
[ days]) → jsexpr?
  client : client?
  guild-id : string?
  user-id : string?
  days : integer? = 1

procedure
(http:remove-guild-ban client
guild-id
user-id) → jsexpr?
  client : client?
  guild-id : string?
  user-id : string?

procedure
(http:get-guild-roles client guild-id) → (listof role?)
client : client?
guild-id : string?

procedure
(http:create-guild-role client
guild-id
data) → role?
  client : client?
  guild-id : string?
  data : hash?

data should be a hashmap that conforms to Create Guild Role.

procedure
(http:modify-guild-role-positions client
guild-id
data) → (listof role?)
  client : client?
  guild-id : string?
  data : hash?

data should be a hashmap that conforms to Modify Guild Role Positions.

procedure
(http:modify-guild-role client
guild-id
role-id
data) → role?
  client : client?
  guild-id : string?
  role-id : string?
  data : hash?

data should be a hashmap that conforms to Modify Guild Role.

procedure
(http:delete-guild-role client
guild-id
role-id) → jsexpr?
  client : client?
  guild-id : string?
  role-id : string?

procedure
(http:get-guild-prune-count client
guild-id
days) → integer?
  client : client?
  guild-id : string?
  days : integer?

procedure
(http:begin-guild-prune client
guild-id
days) → integer?
  client : client?
  guild-id : string?
  days : integer?

procedure
(http:get-guild-invites client guild-id) → (listof invite?)
client : client?
guild-id : string?

procedure
(http:get-guild-integrations client
guild-id) → jsexpr?
client : client?
guild-id : string?

procedure
(http:create-guild-integration client
guild-id
type
id) → jsexpr?
  client : client?
  guild-id : string?
  type : string?
  id : string?

procedure
(http:modify-guild-integration client
guild-id
integration-id
data) → jsexpr?
  client : client?
  guild-id : string?
  integration-id : string?
  data : hash?

data should be a hashmap that conforms to Modify Guild Integration.

procedure
(http:delete-guild-integration client
guild-id
integration-id) → jsexpr?
  client : client?
  guild-id : string?
  integration-id : string?

procedure
(http:sync-guild-integrations client
guild-id
integration-id) → jsexpr?
  client : client?
  guild-id : string?
  integration-id : string?

procedure
(http:get-guild-embed client guild-id) → jsexpr?
client : client?
guild-id : string?

procedure
(http:modify-guild-embed client
guild-id
data) → jsexpr?
  client : client?
  guild-id : string?
  data : hash?

data should be a hashmap that conforms to Modify Guild Embed.

procedure
(http:get-current-user client) → user?
client : client

procedure
(http:get-user client user-id) → user?
client : client?
user-id : string?

procedure
(http:modify-current-user client
[ #:username username
#:avatar avatar
#:avatar-type avatar-type]) → user?
  client : client?
  username : string? = null
  avatar : bytes? = null
  avatar-type : string? = ""

procedure
(http:get-current-user-guilds client
[ #:before before
#:after after
#:limit limit])
→ (listof guild?)
  client : client?
  before : integer? = null
  after : integer? = null
  limit : integer? = null

procedure
(http:leave-guild client guild-id) → jsexpr?
client : client?
guild-id : string?

procedure
(http:get-user-dms client) → (listof dm-channel?)
client : client?

procedure
(http:create-dm client recipient-id) → dm-channel?
client : client?
recipient-id : string?

procedure
(http:create-group-dm client data) → dm-channel?
client : client?
data : hash?

data should be a hashmap that conforms to Create Group DM.

procedure
(http:create-webhook client
channel-id
name
avatar
avatar-type) → jsexpr?
  client : client?
  channel-id : string?
  name : string?
  avatar : bytes?
  avatar-type : string?

procedure
(http:get-channel-webhooks client
channel-id) → jsexpr?
client : client?
channel-id : string?

procedure
(http:get-guild-webhooks client guild-id) → jsexpr?
client : client?
guild-id : string?

procedure
(http:get-webhook client webhook-id) → jsexpr?
client : client?
webhook-id : string?

procedure
(http:get-webhook-with-token client
webhook-id
webhook-token) → jsexpr?
  client : client?
  webhook-id : string?
  webhook-token : string?

procedure
(http:modify-webhook client
webhook-id
[ #:name name
#:avatar avatar
#:avatar-type avatar-type
#:channel-id channel-id]) → jsexpr?
  client : client?
  webhook-id : string?
  name : string? = null
  avatar : bytes? = null
  avatar-type : string? = ""
  channel-id : string? = null

procedure
(http:modify-webhook-with-token client
webhook-id
token
[ #:name name
#:avatar avatar
#:avatar-type avatar-type
#:channel-id channel-id])
→ jsexpr?
  client : client?
  webhook-id : string?
  token : string?
  name : string? = null
  avatar : bytes = null
  avatar-type : string = ""
  channel-id : string? = null

procedure
(http:delete-webhook client webhook-id) → jsexpr?
client : client?
webhook-id : string?

procedure
(http:delete-webhook-with-token client
webhook-id
webhook-token) → jsexpr?
  client : client?
  webhook-id : string?
  webhook-token : string?

procedure
(http:execute-webhook client
webhook-id
webhook-token
data
[ #:wait wait]) → jsexpr?
  client : client?
  webhook-id : string?
  webhook-token : string?
  data : hash?
  wait : boolean? = #f

data should be a hashmap that conforms to Execute Webhook.

7 Exceptions

struct
(struct http:exn:fail:network:http:discord ( message
continuation-marks
http-code
discord-code
reason)
    #:transparent)
  message : string?
  continuation-marks : continuation-mark-set?
  http-code : number?
  discord-code : number?
  reason : string?

Raised when a http error code is retrieved from discord.

8 Additional

value
discord-logger : logger?

Logger of discord events in the library.

struct
(struct http:http-client (requester global-lock ratelimits))
  requester : requester?
  global-lock : semaphore?
  ratelimits : (hash/c string? semaphore?)

Internal http client of the library, holds ratelimiting state.

top ← prev up next →

1	Example
2	Client
3	Data Models
4	Events
5	Miscellaneous functions
6	HTTP
7	Exceptions
8	Additional