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'.freeze

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



299
300
301
302
303
304
305
306
 
# File 'lib/discordrb/api.rb', line 299

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

.avatar_url(user_id, avatar_id) ⇒ Object

Make an avatar URL from the user and avatar IDs



50
51
52
 
# File 'lib/discordrb/api.rb', line 50

def avatar_url(user_id, avatar_id)
  "#{APIBASE}/users/#{user_id}/avatars/#{avatar_id}.jpg"
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



55
56
57
58
59
60
61
62
 
# File 'lib/discordrb/api.rb', line 55

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

.bans(token, server_id) ⇒ Object

Get a server's banned users



94
95
96
97
98
99
100
 
# File 'lib/discordrb/api.rb', line 94

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

.bot_name ⇒ Object 



11
12
13
 
# File 'lib/discordrb/api.rb', line 11

def bot_name
  @bot_name
end

.bot_name=(value) ⇒ Object 



15
16
17
 
# File 'lib/discordrb/api.rb', line 15

def bot_name=(value)
  @bot_name = value
end

.channel(token, channel_id) ⇒ Object

Get a channel's data



167
168
169
170
171
172
173
 
# File 'lib/discordrb/api.rb', line 167

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



424
425
426
427
428
429
430
 
# File 'lib/discordrb/api.rb', line 424

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



185
186
187
188
189
190
191
192
193
 
# File 'lib/discordrb/api.rb', line 185

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



246
247
248
249
250
251
252
253
254
 
# File 'lib/discordrb/api.rb', line 246

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



235
236
237
238
239
240
241
242
243
 
# File 'lib/discordrb/api.rb', line 235

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)



319
320
321
322
323
324
325
326
 
# File 'lib/discordrb/api.rb', line 319

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



123
124
125
126
127
128
129
130
131
 
# File 'lib/discordrb/api.rb', line 123

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



207
208
209
210
211
212
213
 
# File 'lib/discordrb/api.rb', line 207

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



257
258
259
260
261
262
263
 
# File 'lib/discordrb/api.rb', line 257

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

.delete_message(token, channel_id, message_id) ⇒ Object

Delete a message



277
278
279
280
281
282
283
 
# File 'lib/discordrb/api.rb', line 277

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



343
344
345
346
347
348
349
 
# File 'lib/discordrb/api.rb', line 343

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



156
157
158
159
160
161
162
 
# File 'lib/discordrb/api.rb', line 156

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



286
287
288
289
290
291
292
293
294
 
# File 'lib/discordrb/api.rb', line 286

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



385
386
387
388
389
390
391
 
# File 'lib/discordrb/api.rb', line 385

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

.join_server(token, invite_code) ⇒ Object

Join a server using an invite



216
217
218
219
220
221
222
223
 
# File 'lib/discordrb/api.rb', line 216

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



74
75
76
77
78
79
80
 
# File 'lib/discordrb/api.rb', line 74

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



103
104
105
106
107
108
109
110
 
# File 'lib/discordrb/api.rb', line 103

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

.logout(token) ⇒ Object

Logout from the server



113
114
115
116
117
118
119
120
 
# File 'lib/discordrb/api.rb', line 113

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

.member(token, server_id, user_id) ⇒ Object

Get a member's data



176
177
178
179
180
181
182
 
# File 'lib/discordrb/api.rb', line 176

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

.move_user(token, server_id, user_id, channel_id) ⇒ Object

Move a user to a different voice channel



83
84
85
86
87
88
89
90
91
 
# File 'lib/discordrb/api.rb', line 83

def move_user(token, server_id, user_id, channel_id)
  request(
    :patch,
    "#{APIBASE}/guilds/#{server_id}/members/#{user_id}",
    { channel_id: channel_id }.to_json,
    Authorization: token,
    content_type: :json
  )
end

.raw_request(type, attributes) ⇒ Object 



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

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



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

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



226
227
228
229
230
231
232
 
# File 'lib/discordrb/api.rb', line 226

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



309
310
311
312
313
314
315
316
 
# File 'lib/discordrb/api.rb', line 309

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



266
267
268
269
270
271
272
273
274
 
# File 'lib/discordrb/api.rb', line 266

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)



394
395
396
397
398
399
400
401
 
# File 'lib/discordrb/api.rb', line 394

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

.transfer_ownership(token, server_id, user_id) ⇒ Object

Transfer server ownership



145
146
147
148
149
150
151
152
153
 
# File 'lib/discordrb/api.rb', line 145

def transfer_ownership(token, server_id, user_id)
  request(
    :patch,
    "#{APIBASE}/guilds/#{server_id}",
    { owner_id: user_id }.to_json,
    Authorization: token,
    content_type: :json
  )
end

.unban_user(token, server_id, user_id) ⇒ Object

Unban a user from a server



65
66
67
68
69
70
71
 
# File 'lib/discordrb/api.rb', line 65

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



196
197
198
199
200
201
202
203
204
 
# File 'lib/discordrb/api.rb', line 196

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)



332
333
334
335
336
337
338
339
340
 
# File 'lib/discordrb/api.rb', line 332

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



374
375
376
377
378
379
380
381
382
 
# File 'lib/discordrb/api.rb', line 374

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



134
135
136
137
138
139
140
141
142
 
# File 'lib/discordrb/api.rb', line 134

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



413
414
415
416
417
418
419
420
421
 
# File 'lib/discordrb/api.rb', line 413

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



363
364
365
366
367
368
369
370
371
 
# File 'lib/discordrb/api.rb', line 363

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



352
353
354
355
356
357
358
359
360
 
# File 'lib/discordrb/api.rb', line 352

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



404
405
406
407
408
409
410
 
# File 'lib/discordrb/api.rb', line 404

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.



20
21
22
23
24
25
26
 
# File 'lib/discordrb/api.rb', line 20

def user_agent
  # This particular string is required by the Discord devs.
  required = "DiscordBot (https://github.com/meew0/discordrb, v#{Discordrb::VERSION})"
  @bot_name ||= ''

  "rest-client/#{RestClient::VERSION} #{RUBY_ENGINE}/#{RUBY_VERSION}p#{RUBY_PATCHLEVEL} discordrb/#{Discordrb::VERSION} #{required} #{@bot_name}"
end