Class: OnyxCord::Webhook

Inherits:
Object
  • Object
show all
Includes:
IDObject
Defined in:
lib/onyxcord/models/webhook.rb

Overview

A webhook on a server channel

Instance Attribute Summary collapse

Attributes included from IDObject

#id

Instance Method Summary collapse

Methods included from IDObject

#==, #creation_time, synthesise

Instance Attribute Details

#avatar ⇒ String

Returns the webhook's avatar id.

Returns:

  • (String) —

    the webhook's avatar id.



25
26
27
 
# File 'lib/onyxcord/models/webhook.rb', line 25

def avatar
  @avatar
end

#channel ⇒ Channel

Returns the channel that the webhook is currently connected to.

Returns:

  • (Channel) —

    the channel that the webhook is currently connected to.



16
17
18
 
# File 'lib/onyxcord/models/webhook.rb', line 16

def channel
  @channel
end

#name ⇒ String

Returns the webhook name.

Returns:

  • (String) —

    the webhook name.



13
14
15
 
# File 'lib/onyxcord/models/webhook.rb', line 13

def name
  @name
end

#owner ⇒ Member, ... (readonly)

Gets the user object of the creator of the webhook. May be limited to username, discriminator, ID and avatar if the bot cannot reach the owner

Returns:

  • (Member, User, nil) —

    the user object of the owner or nil if the webhook was requested using the token.



33
34
35
 
# File 'lib/onyxcord/models/webhook.rb', line 33

def owner
  @owner
end

#server ⇒ Server (readonly)

Returns the server that the webhook is currently connected to.

Returns:

  • (Server) —

    the server that the webhook is currently connected to.



19
20
21
 
# File 'lib/onyxcord/models/webhook.rb', line 19

def server
  @server
end

#token ⇒ String? (readonly)

Returns the webhook's token, if this is an Incoming Webhook.

Returns:

  • (String, nil) —

    the webhook's token, if this is an Incoming Webhook.



22
23
24
 
# File 'lib/onyxcord/models/webhook.rb', line 22

def token
  @token
end

#type ⇒ Integer (readonly)

Returns the webhook's type (1: Incoming, 2: Channel Follower).

Returns:

  • (Integer) —

    the webhook's type (1: Incoming, 2: Channel Follower)



28
29
30
 
# File 'lib/onyxcord/models/webhook.rb', line 28

def type
  @type
end

Instance Method Details

#avatar_url ⇒ String

Utility function to get a webhook's avatar URL.

Returns:

  • (String) —

    the URL to the avatar image



200
201
202
203
204
 
# File 'lib/onyxcord/models/webhook.rb', line 200

def avatar_url
  return REST::User.default_avatar(@id) unless @avatar

  REST::User.avatar_url(@id, @avatar)
end

#delete(reason = nil) ⇒ Object

Deletes the webhook.

Parameters:

  • reason (String) (defaults to: nil) —

    The reason the webhook is being deleted.



96
97
98
99
100
101
102
 
# File 'lib/onyxcord/models/webhook.rb', line 96

def delete(reason = nil)
  if token?
    REST::Webhook.token_delete_webhook(@token, @id, reason)
  else
    REST::Webhook.delete_webhook(@bot.token, @id, reason)
  end
end

#delete_avatar ⇒ Object

Deletes the webhook's avatar.



64
65
66
 
# File 'lib/onyxcord/models/webhook.rb', line 64

def delete_avatar
  update_webhook(avatar: nil)
end

#delete_message(message) ⇒ Object

Delete a message created by this webhook.

Parameters:

Raises:



161
162
163
164
165
 
# File 'lib/onyxcord/models/webhook.rb', line 161

def delete_message(message)
  raise OnyxCord::Errors::UnauthorizedWebhook unless @token

  REST::Webhook.token_delete_message(@token, @id, message.resolve_id)
end

#edit_message(message, content: nil, embeds: nil, allowed_mentions: nil, builder: nil, components: nil, flags: 0, has_components: false, components_v2: false) {|builder| ... } ⇒ Message

Note:

When editing allowed_mentions, it will update visually in the client but not alert the user with a notification.

Edit a message created by this webhook.

Parameters:

  • message (Message, String, Integer) —

    The ID of the message to edit.

  • content (String) (defaults to: nil) —

    The content of the message. May be 2000 characters long at most.

  • embeds (Array<Webhooks::Embed, Hash>) (defaults to: nil) —

    Embeds to be attached to the message.

  • allowed_mentions (AllowedMentions, Hash) (defaults to: nil) —

    Mentions that are allowed to ping in the content.

  • builder (Builder, nil) (defaults to: nil) —

    The builder to start out with, or nil if one should be created anew.

  • components (View, Array<Hash>) (defaults to: nil) —

    Interaction components to associate with this message.

Yields:

  • (builder) —

    Gives the builder to the block to add additional steps, or to do the entire building process.

Yield Parameters:

  • builder (Webhooks::Builder) —

    The builder given as a parameter which is used as the initial step to start from.

Returns:

  • (Message) —

    The updated message.

Raises:



178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
 
# File 'lib/onyxcord/models/webhook.rb', line 178

def edit_message(message, content: nil, embeds: nil, allowed_mentions: nil, builder: nil, components: nil, flags: 0, has_components: false, components_v2: false)
  raise OnyxCord::Errors::UnauthorizedWebhook unless @token

  params = { allowed_mentions: allowed_mentions }.compact

  builder ||= Webhooks::Builder.new
  view ||= Webhooks::View.new

  yield(builder, view) if block_given?

  data = builder.to_json_hash.merge(params.compact)
  components ||= view
  flags = OnyxCord::MessageComponents.apply_v2_flag(flags, components, force: has_components || components_v2)

  edit_content = content == OnyxCord::MessagePayload::KEEP || !content.nil? ? content : data[:content]
  edit_embeds = embeds == OnyxCord::MessagePayload::KEEP || !embeds.nil? ? embeds : data[:embeds]
  resp = REST::Webhook.token_edit_message(@token, @id, message.resolve_id, edit_content, edit_embeds, data[:allowed_mentions], components.to_a, nil, flags)
  Message.new(OnyxCord::Internal::JSON.parse(resp), @bot)
end

#execute(content: nil, username: nil, avatar_url: nil, tts: nil, file: nil, embeds: nil, allowed_mentions: nil, wait: true, builder: nil, components: nil, flags: 0, has_components: false, components_v2: false) {|builder| ... } ⇒ Message?

Note:

This is only available to webhooks with publically exposed tokens. This excludes channel follow webhooks and webhooks retrieved via the audit log.

Execute a webhook.

Examples:

Execute the webhook with kwargs

client.execute(
  content: 'Testing',
  username: 'onyxcord',
  embeds: [
    { timestamp: Time.now.iso8601, title: 'testing', image: { url: 'https://i.imgur.com/PcMltU7.jpg' } }
  ])

Execute the webhook with an already existing builder

builder = OnyxCord::Webhooks::Builder.new # ...
client.execute(builder)

Execute the webhook by building a new message

client.execute do |builder|
  builder.content = 'Testing'
  builder.username = 'onyxcord'
  builder.add_embed do |embed|
    embed.timestamp = Time.now
    embed.title = 'Testing'
    embed.image = OnyxCord::Webhooks::EmbedImage.new(url: 'https://i.imgur.com/PcMltU7.jpg')
  end
end

Parameters:

  • content (String) (defaults to: nil) —

    The content of the message. May be 2000 characters long at most.

  • username (String) (defaults to: nil) —

    The username the webhook will display as. If this is not set, the default username set in the webhook's settings.

  • avatar_url (String) (defaults to: nil) —

    The URL of an image file to be used as an avatar. If this is not set, the default avatar from the webhook's

  • tts (true, false) (defaults to: nil) —

    Whether this message should use TTS or not. By default, it doesn't.

  • file (File) (defaults to: nil) —

    File to be sent together with the message. Mutually exclusive with embeds; a webhook message can contain either a file to be sent or embeds.

  • embeds (Array<Webhooks::Embed, Hash>) (defaults to: nil) —

    Embeds to attach to this message.

  • allowed_mentions (AllowedMentions, Hash) (defaults to: nil) —

    Mentions that are allowed to ping in the content.

  • wait (true, false) (defaults to: true) —

    Whether Discord should wait for the message to be successfully received by clients, or whether it should return immediately after sending the message. If true a Message object will be returned.

Yields:

  • (builder) —

    Gives the builder to the block to add additional steps, or to do the entire building process.

Yield Parameters:

  • builder (Builder) —

    The builder given as a parameter which is used as the initial step to start from.

Returns:

  • (Message, nil) —

    If wait is true, a Message will be returned. Otherwise this method will return nil.

Raises:



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/onyxcord/models/webhook.rb', line 140

def execute(content: nil, username: nil, avatar_url: nil, tts: nil, file: nil, embeds: nil, allowed_mentions: nil, wait: true, builder: nil, components: nil, flags: 0, has_components: false, components_v2: false)
  raise OnyxCord::Errors::UnauthorizedWebhook unless @token

  params = { content: content, username: username, avatar_url: avatar_url, tts: tts, file: file, embeds: embeds, allowed_mentions: allowed_mentions }

  builder ||= Webhooks::Builder.new
  view = Webhooks::View.new

  yield(builder, view) if block_given?

  data = builder.to_json_hash.merge(params.compact)
  components ||= view
  flags = OnyxCord::MessageComponents.apply_v2_flag(flags, components, force: has_components || components_v2)

  resp = REST::Webhook.token_execute_webhook(@token, @id, wait, data[:content], data[:username], data[:avatar_url], data[:tts], data[:file], data[:embeds], data[:allowed_mentions], flags, components.to_a)

  Message.new(OnyxCord::Internal::JSON.parse(resp), @bot) if wait
end

#inspect ⇒ Object

The inspect method is overwritten to give more useful output.



207
208
209
 
# File 'lib/onyxcord/models/webhook.rb', line 207

def inspect
  "<Webhook name=#{@name} id=#{@id}>"
end

#token? ⇒ true, false

Utility function to know if the webhook was requested through a webhook token, rather than auth.

Returns:

  • (true, false) —

    whether the webhook was requested by token or not.



213
214
215
 
# File 'lib/onyxcord/models/webhook.rb', line 213

def token?
  @owner.nil?
end

#update(data) ⇒ Object

Updates the webhook if you need to edit more than 1 attribute.

Parameters:

  • data (Hash) —

    the data to update.

Options Hash (data):

  • :avatar (String, #read, nil) —

    The new avatar, in base64-encoded JPG format, or nil to delete the avatar.

  • :channel (Channel, String, Integer) —

    The channel the webhook should use.

  • :name (String) —

    The webhook's new name.

  • :reason (String) —

    The reason for the webhook changes.



86
87
88
89
90
91
92
 
# File 'lib/onyxcord/models/webhook.rb', line 86

def update(data)
  # Only pass a value for avatar if the key is defined as sending nil will delete the
  data[:avatar] = avatarise(data[:avatar]) if data.key?(:avatar)
  data[:channel_id] = data[:channel]&.resolve_id
  data.delete(:channel)
  update_webhook(**data)
end