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



289
290
291
292
293
294
295
296
 
# File 'lib/discordrb/api.rb', line 289

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
 
# 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}",
    Authorization: token
  )
end

.bans(token, server_id) ⇒ Object

Get a server's banned users



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

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



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

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



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

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



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

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



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

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



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

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)



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

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



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

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



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

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



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

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

.delete_message(token, channel_id, message_id) ⇒ Object

Delete a message



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

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



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

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



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

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



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

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



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

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

.join_server(token, invite_code) ⇒ Object

Join a server using an invite



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

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



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

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



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

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

.logout(token) ⇒ Object

Logout from the server



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

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

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

Move a user to a different voice channel



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

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



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

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



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

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



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

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)



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

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



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

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



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

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



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

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)



322
323
324
325
326
327
328
329
330
 
# File 'lib/discordrb/api.rb', line 322

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



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

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



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

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



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

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



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

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



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

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



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

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