Module: Discordrb::API

Defined in:
lib/discordrb/api.rb

Overview

List of methods representing endpoints in Discord's API

Constant Summary collapse

APIBASE =

The base URL of the Discord REST API.

'https://discordapp.com/api'

Class Method Summary collapse

Class Method Details

.acknowledge_message(token, channel_id, message_id) ⇒ Object

Acknowledge that a message has been received The last acknowledged message will be sent in the ready packet, so this is an easy way to catch up on messages



263
264
265
266
267
268
269
270
 
# File 'lib/discordrb/api.rb', line 263

def acknowledge_message(token, channel_id, message_id)
  request(
    :post,
    "#{APIBASE}/channels/#{channel_id}/messages/#{message_id}/ack",
    nil,
    Authorization: token
  )
end

.ban_user(token, server_id, user_id, message_days) ⇒ Object

Ban a user from a server and delete their messages from the last message_days days



51
52
53
54
55
56
57
 
# File 'lib/discordrb/api.rb', line 51

def ban_user(token, server_id, user_id, message_days)
  request(
    :put,
    "#{APIBASE}/guilds/#{server_id}/bans/#{user_id}?delete-message-days=#{message_days}",
    Authorization: token
  )
end

.bans(token, server_id) ⇒ Object

Get a server's banned users



78
79
80
81
82
83
84
 
# File 'lib/discordrb/api.rb', line 78

def bans(token, server_id)
  request(
    :get,
    "#{APIBASE}/guilds/#{server_id}/bans",
    Authorization: token
  )
end

.channel(token, channel_id) ⇒ Object

Get a channel's data



140
141
142
143
144
145
146
 
# File 'lib/discordrb/api.rb', line 140

def channel(token, channel_id)
  request(
    :get,
    "#{APIBASE}/channels/#{channel_id}",
    Authorization: token
  )
end

.channel_log(token, channel_id, amount, before = nil, after = nil) ⇒ Object

Get a list of messages from a channel's history



388
389
390
391
392
393
394
 
# File 'lib/discordrb/api.rb', line 388

def channel_log(token, channel_id, amount, before = nil, after = nil)
  request(
    :get,
    "#{APIBASE}/channels/#{channel_id}/messages?limit=#{amount}#{"&before=#{before}" if before}#{"&after=#{after}" if after}",
    Authorization: token
  )
end

.create_channel(token, server_id, name, type) ⇒ Object

Create a channel



149
150
151
152
153
154
155
156
157
 
# File 'lib/discordrb/api.rb', line 149

def create_channel(token, server_id, name, type)
  request(
    :post,
    "#{APIBASE}/guilds/#{server_id}/channels",
    { 'name' => name, 'type' => type }.to_json,
    Authorization: token,
    content_type: :json
  )
end

.create_invite(token, channel_id, max_age = 0, max_uses = 0, temporary = false, xkcd = false) ⇒ Object

Create an instant invite from a server or a channel id



210
211
212
213
214
215
216
217
218
 
# File 'lib/discordrb/api.rb', line 210

def create_invite(token, channel_id, max_age = 0, max_uses = 0, temporary = false, xkcd = false)
  request(
    :post,
    "#{APIBASE}/channels/#{channel_id}/invites",
    { 'max_age' => max_age, 'max_uses' => max_uses, 'temporary' => temporary, 'xkcdpass' => xkcd }.to_json,
    Authorization: token,
    content_type: :json
  )
end

.create_private(token, bot_user_id, user_id) ⇒ Object

Create a private channel



199
200
201
202
203
204
205
206
207
 
# File 'lib/discordrb/api.rb', line 199

def create_private(token, bot_user_id, user_id)
  request(
    :post,
    "#{APIBASE}/users/#{bot_user_id}/channels",
    { 'recipient_id' => user_id }.to_json,
    Authorization: token,
    content_type: :json
  )
end

.create_role(token, server_id) ⇒ Object

Create a role (parameters such as name and colour will have to be set by update_role afterwards)



283
284
285
286
287
288
289
290
 
# File 'lib/discordrb/api.rb', line 283

def create_role(token, server_id)
  request(
    :post,
    "#{APIBASE}/guilds/#{server_id}/roles",
    nil,
    Authorization: token
  )
end

.create_server(token, name, region = :london) ⇒ Object

Create a server



107
108
109
110
111
112
113
114
115
 
# File 'lib/discordrb/api.rb', line 107

def create_server(token, name, region = :london)
  request(
    :post,
    "#{APIBASE}/guilds",
    { 'name' => name, 'region' => region.to_s }.to_json,
    Authorization: token,
    content_type: :json
  )
end

.delete_channel(token, channel_id) ⇒ Object

Delete a channel



171
172
173
174
175
176
177
 
# File 'lib/discordrb/api.rb', line 171

def delete_channel(token, channel_id)
  request(
    :delete,
    "#{APIBASE}/channels/#{channel_id}",
    Authorization: token
  )
end

.delete_invite(token, code) ⇒ Object

Delete an invite by code



221
222
223
224
225
226
227
 
# File 'lib/discordrb/api.rb', line 221

def delete_invite(token, code)
  request(
    :delete,
    "#{APIBASE}/invites/#{code}",
    Authorization: token
  )
end

.delete_message(token, channel_id, message_id) ⇒ Object

Delete a message



241
242
243
244
245
246
247
 
# File 'lib/discordrb/api.rb', line 241

def delete_message(token, channel_id, message_id)
  request(
    :delete,
    "#{APIBASE}/channels/#{channel_id}/messages/#{message_id}",
    Authorization: token
  )
end

.delete_role(token, server_id, role_id) ⇒ Object

Delete a role



307
308
309
310
311
312
313
 
# File 'lib/discordrb/api.rb', line 307

def delete_role(token, server_id, role_id)
  request(
    :delete,
    "#{APIBASE}/guilds/#{server_id}/roles/#{role_id}",
    Authorization: token
  )
end

.delete_server(token, server_id) ⇒ Object Also known as: leave_server

Delete a server



129
130
131
132
133
134
135
 
# File 'lib/discordrb/api.rb', line 129

def delete_server(token, server_id)
  request(
    :delete,
    "#{APIBASE}/guilds/#{server_id}",
    Authorization: token
  )
end

.edit_message(token, channel_id, message_id, message, mentions = []) ⇒ Object

Edit a message



250
251
252
253
254
255
256
257
258
 
# File 'lib/discordrb/api.rb', line 250

def edit_message(token, channel_id, message_id, message, mentions = [])
  request(
    :patch,
    "#{APIBASE}/channels/#{channel_id}/messages/#{message_id}",
    { 'content' => message, 'mentions' => mentions }.to_json,
    Authorization: token,
    content_type: :json
  )
end

.gateway(token) ⇒ Object

Get the gateway to be used



349
350
351
352
353
354
355
 
# File 'lib/discordrb/api.rb', line 349

def gateway(token)
  request(
    :get,
    "#{APIBASE}/gateway",
    Authorization: token
  )
end

.join_server(token, invite_code) ⇒ Object

Join a server using an invite



180
181
182
183
184
185
186
187
 
# File 'lib/discordrb/api.rb', line 180

def join_server(token, invite_code)
  request(
    :post,
    "#{APIBASE}/invite/#{invite_code}",
    nil,
    Authorization: token
  )
end

.kick_user(token, server_id, user_id) ⇒ Object

Kick a user from a server



69
70
71
72
73
74
75
 
# File 'lib/discordrb/api.rb', line 69

def kick_user(token, server_id, user_id)
  request(
    :delete,
    "#{APIBASE}/guilds/#{server_id}/members/#{user_id}",
    Authorization: token
  )
end

.login(email, password) ⇒ Object

Login to the server



87
88
89
90
91
92
93
94
 
# File 'lib/discordrb/api.rb', line 87

def (email, password)
  request(
    :post,
    "#{APIBASE}/auth/login",
    email: email,
    password: password
  )
end

.logout(token) ⇒ Object

Logout from the server



97
98
99
100
101
102
103
104
 
# File 'lib/discordrb/api.rb', line 97

def logout(token)
  request(
    :post,
    "#{APIBASE}/auth/logout",
    nil,
    Authorization: token
  )
end

.raw_request(type, attributes) ⇒ Object 



29
30
31
 
# File 'lib/discordrb/api.rb', line 29

def raw_request(type, attributes)
  RestClient.send(type, *attributes)
end

.request(type, *attributes) ⇒ Object

Make an API request. Utility function to implement message queueing in the future



35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/discordrb/api.rb', line 35

def request(type, *attributes)
  # Add a custom user agent
  attributes.last[:user_agent] = user_agent if attributes.last.is_a? Hash
  response = raw_request(type, attributes)

  while response.code == 429
    wait_seconds = response[:retry_after].to_i / 1000.0
    LOGGER.debug("WARNING: Discord rate limiting will cause a delay of #{wait_seconds} seconds for the request: #{type} #{attributes}")
    sleep wait_seconds / 1000.0
    response = raw_request(type, attributes)
  end

  response
end

.resolve_invite(token, invite_code) ⇒ Object

Resolve an invite



190
191
192
193
194
195
196
 
# File 'lib/discordrb/api.rb', line 190

def resolve_invite(token, invite_code)
  request(
    :get,
    "#{APIBASE}/invite/#{invite_code}",
    Authorization: token
  )
end

.send_file(token, channel_id, file) ⇒ Object

Send a file as a message to a channel



273
274
275
276
277
278
279
280
 
# File 'lib/discordrb/api.rb', line 273

def send_file(token, channel_id, file)
  request(
    :post,
    "#{APIBASE}/channels/#{channel_id}/messages",
    { file: file },
    Authorization: token
  )
end

.send_message(token, channel_id, message, mentions = [], tts = false) ⇒ Object

Send a message to a channel



230
231
232
233
234
235
236
237
238
 
# File 'lib/discordrb/api.rb', line 230

def send_message(token, channel_id, message, mentions = [], tts = false)
  request(
    :post,
    "#{APIBASE}/channels/#{channel_id}/messages",
    { 'content' => message, 'mentions' => mentions, tts => tts }.to_json,
    Authorization: token,
    content_type: :json
  )
end

.start_typing(token, channel_id) ⇒ Object

Start typing (needs to be resent every 5 seconds to keep up the typing)



358
359
360
361
362
363
364
365
 
# File 'lib/discordrb/api.rb', line 358

def start_typing(token, channel_id)
  request(
    :post,
    "#{APIBASE}/channels/#{channel_id}/typing",
    nil,
    Authorization: token
  )
end

.unban_user(token, server_id, user_id) ⇒ Object

Unban a user from a server



60
61
62
63
64
65
66
 
# File 'lib/discordrb/api.rb', line 60

def unban_user(token, server_id, user_id)
  request(
    :delete,
    "#{APIBASE}/guilds/#{server_id}/bans/#{user_id}",
    Authorization: token
  )
end

.update_channel(token, channel_id, name, topic, position = 0) ⇒ Object

Update a channel's data



160
161
162
163
164
165
166
167
168
 
# File 'lib/discordrb/api.rb', line 160

def update_channel(token, channel_id, name, topic, position = 0)
  request(
    :patch,
    "#{APIBASE}/channels/#{channel_id}",
    { 'name' => name, 'position' => position, 'topic' => topic }.to_json,
    Authorization: token,
    content_type: :json
  )
end

.update_role(token, server_id, role_id, name, colour, hoist = false, packed_permissions = 36_953_089) ⇒ Object

Update a role Permissions are the Discord defaults; allowed: invite creation, reading/sending messages, sending TTS messages, embedding links, sending files, reading the history, mentioning everybody, connecting to voice, speaking and voice activity (push-to-talk isn't mandatory)



296
297
298
299
300
301
302
303
304
 
# File 'lib/discordrb/api.rb', line 296

def update_role(token, server_id, role_id, name, colour, hoist = false, packed_permissions = 36_953_089)
  request(
    :patch,
    "#{APIBASE}/guilds/#{server_id}/roles/#{role_id}",
    { 'color' => colour, 'name' => name, 'hoist' => hoist, 'permissions' => packed_permissions }.to_json,
    Authorization: token,
    content_type: :json
  )
end

.update_role_overrides(token, channel_id, role_id, allow, deny) ⇒ Object

Update a role's permission overrides in a channel



338
339
340
341
342
343
344
345
346
 
# File 'lib/discordrb/api.rb', line 338

def update_role_overrides(token, channel_id, role_id, allow, deny)
  request(
    :put,
    "#{APIBASE}/channels/#{channel_id}/permissions/#{role_id}",
    { 'type' => 'role', 'id' => role_id, 'allow' => allow, 'deny' => deny }.to_json,
    Authorization: token,
    content_type: :json
  )
end

.update_server(token, server_id, name, region, icon, afk_channel_id, afk_timeout) ⇒ Object

Update a server



118
119
120
121
122
123
124
125
126
 
# File 'lib/discordrb/api.rb', line 118

def update_server(token, server_id, name, region, icon, afk_channel_id, afk_timeout)
  request(
    :patch,
    "#{APIBASE}/guilds/#{server_id}",
    { 'name' => name, 'region' => region, 'icon' => icon, 'afk_channel_id' => afk_channel_id, 'afk_timeout' => afk_timeout }.to_json,
    Authorization: token,
    content_type: :json
  )
end

.update_user(token, email, password, new_username, avatar, new_password = nil) ⇒ Object

Update user data



377
378
379
380
381
382
383
384
385
 
# File 'lib/discordrb/api.rb', line 377

def update_user(token, email, password, new_username, avatar, new_password = nil)
  request(
    :patch,
    "#{APIBASE}/users/@me",
    { 'avatar' => avatar, 'email' => email, 'new_password' => new_password, 'password' => password, 'username' => new_username }.to_json,
    Authorization: token,
    content_type: :json
  )
end

.update_user_overrides(token, channel_id, user_id, allow, deny) ⇒ Object

Update a user's permission overrides in a channel



327
328
329
330
331
332
333
334
335
 
# File 'lib/discordrb/api.rb', line 327

def update_user_overrides(token, channel_id, user_id, allow, deny)
  request(
    :put,
    "#{APIBASE}/channels/#{channel_id}/permissions/#{user_id}",
    { 'type' => 'member', 'id' => user_id, 'allow' => allow, 'deny' => deny }.to_json,
    Authorization: token,
    content_type: :json
  )
end

.update_user_roles(token, server_id, user_id, roles) ⇒ Object

Update a user's roles



316
317
318
319
320
321
322
323
324
 
# File 'lib/discordrb/api.rb', line 316

def update_user_roles(token, server_id, user_id, roles)
  request(
    :patch,
    "#{APIBASE}/guilds/#{server_id}/members/#{user_id}",
    { 'roles' => roles }.to_json,
    Authorization: token,
    content_type: :json
  )
end

.user(token, user_id) ⇒ Object

Get user data



368
369
370
371
372
373
374
 
# File 'lib/discordrb/api.rb', line 368

def user(token, user_id)
  request(
    :get,
    "#{APIBASE}/users/#{user_id}",
    Authorization: token
  )
end

.user_agent ⇒ Object

Generate a user agent identifying this requester as discordrb.



12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
 
# File 'lib/discordrb/api.rb', line 12

def user_agent
  libraries = [
    # rest-client
    "rest-client/#{RestClient::VERSION}",

    # ruby
    "#{RUBY_ENGINE}/#{RUBY_VERSION}p#{RUBY_PATCHLEVEL}",

    # discordrb
    "discordrb/#{Discordrb::VERSION}"
  ]

  # Required by Discord devs
  required = "DiscordBot (https://github.com/meew0/discordrb, v#{Discordrb::VERSION})"
  "#{libraries.join(' ')} #{required}"
end