Feat: Polls

lib/discordrb.rb

@@ -32,7 +32,9 @@ module Discordrb
     server_message_typing: 1 << 11,
     direct_messages: 1 << 12,
     direct_message_reactions: 1 << 13,
-    direct_message_typing: 1 << 14
+    direct_message_typing: 1 << 14,
+    server_message_polls: 1 << 24,
+    direct_message_polls: 1 << 25
   }.freeze
 
   # All available intents

lib/discordrb/api/channel.rb

@@ -75,8 +75,8 @@ def message(token, channel_id, message_id)
   # https://discord.com/developers/docs/resources/channel#create-message
   # @param attachments [Array<File>, nil] Attachments to use with `attachment://` in embeds. See
   #   https://discord.com/developers/docs/resources/channel#create-message-using-attachments-within-embeds
-  def create_message(token, channel_id, message, tts = false, embeds = nil, nonce = nil, attachments = nil, allowed_mentions = nil, message_reference = nil, components = nil)
-    body = { content: message, tts: tts, embeds: embeds, nonce: nonce, allowed_mentions: allowed_mentions, message_reference: message_reference, components: components&.to_a }
+  def create_message(token, channel_id, message, tts = false, embeds = nil, nonce = nil, attachments = nil, allowed_mentions = nil, message_reference = nil, components = nil, poll = nil)
+    body = { content: message, tts: tts, embeds: embeds, nonce: nonce, allowed_mentions: allowed_mentions, message_reference: message_reference, components: components&.to_a, poll: poll }
     body = if attachments
              files = [*0...attachments.size].zip(attachments).to_h
              { **files, payload_json: body.to_json }
@@ -608,4 +608,29 @@ def list_joined_private_archived_threads(token, channel_id, before = nil, limit
       Authorization: token
     )
   end
+
+  # Immediately ends a poll the bot has made.
+  # https://discord.com/developers/docs/resources/poll#end-poll
+  def end_poll(token, channel_id, message_id)
+    Discordrb::API.request(
+      :channels_cid_messages_mid_expire,
+      channel_id,
+      :post,
+      "#{Discordrb::API.api_base}/channels/#{channel_id}/polls/#{message_id}/expire",
+      Authorization: token
+    )
+  end
+
+  # Gets the members that have voted for a specific poll answer.
+  # https://discord.com/developers/docs/resources/poll#end-poll
+  def get_answer_voters(token, channel_id, message_id, answer_id, after, limit)
+    query = URI.encode_www_form({ after: after, limit: limit }.compact)
+    Discordrb::API.request(
+      :channels_cid_messages_mid_answers_aid,
+      channel_id,
+      :get,
+      "#{Discordrb::API.api_base}/channels/#{channel_id}/polls/#{message_id}/answers/#{answer_id}?#{query}",
+      Authorization: token
+    )
+  end
 end

lib/discordrb/api/interaction.rb

@@ -6,8 +6,8 @@ module Discordrb::API::Interaction
 
   # Respond to an interaction.
   # https://discord.com/developers/docs/interactions/slash-commands#create-interaction-response
-  def create_interaction_response(interaction_token, interaction_id, type, content = nil, tts = nil, embeds = nil, allowed_mentions = nil, flags = nil, components = nil)
-    data = { tts: tts, content: content, embeds: embeds, allowed_mentions: allowed_mentions, flags: flags, components: components }.compact
+  def create_interaction_response(interaction_token, interaction_id, type, content = nil, tts = nil, embeds = nil, allowed_mentions = nil, flags = nil, components = nil, poll = nil)
+    data = { tts: tts, content: content, embeds: embeds, allowed_mentions: allowed_mentions, flags: flags, components: components, poll: poll }.compact
 
     Discordrb::API.request(
       :interactions_iid_token_callback,
@@ -42,8 +42,8 @@ def get_original_interaction_response(interaction_token, application_id)
 
   # Edit the original response to an interaction.
   # https://discord.com/developers/docs/interactions/slash-commands#edit-original-interaction-response
-  def edit_original_interaction_response(interaction_token, application_id, content = nil, embeds = nil, allowed_mentions = nil, components = nil)
-    Discordrb::API::Webhook.token_edit_message(interaction_token, application_id, '@original', content, embeds, allowed_mentions, components)
+  def edit_original_interaction_response(interaction_token, application_id, content = nil, embeds = nil, allowed_mentions = nil, components = nil, poll = nil)
+    Discordrb::API::Webhook.token_edit_message(interaction_token, application_id, '@original', content, embeds, allowed_mentions, components, poll)
   end
 
   # Delete the original response to an interaction.

lib/discordrb/api/webhook.rb

@@ -29,8 +29,8 @@ def token_webhook(webhook_token, webhook_id)
 
   # Execute a webhook via token.
   # https://discord.com/developers/docs/resources/webhook#execute-webhook
-  def token_execute_webhook(webhook_token, webhook_id, wait = false, content = nil, username = nil, avatar_url = nil, tts = nil, file = nil, embeds = nil, allowed_mentions = nil, flags = nil, components = nil)
-    body = { content: content, username: username, avatar_url: avatar_url, tts: tts, embeds: embeds&.map(&:to_hash),  allowed_mentions: allowed_mentions, flags: flags, components: components }
+  def token_execute_webhook(webhook_token, webhook_id, wait = false, content = nil, username = nil, avatar_url = nil, tts = nil, file = nil, embeds = nil, allowed_mentions = nil, flags = nil, components = nil, poll = nil)
+    body = { content: content, username: username, avatar_url: avatar_url, tts: tts, embeds: embeds&.map(&:to_hash),  allowed_mentions: allowed_mentions, flags: flags, components: components, poll: poll }
     body = if file
              { file: file, payload_json: body.to_json }
            else
@@ -116,13 +116,13 @@ def token_get_message(webhook_token, webhook_id, message_id)
 
   # Edit a webhook message via webhook token
   # https://discord.com/developers/docs/resources/webhook#edit-webhook-message
-  def token_edit_message(webhook_token, webhook_id, message_id, content = nil, embeds = nil, allowed_mentions = nil, components = nil)
+  def token_edit_message(webhook_token, webhook_id, message_id, content = nil, embeds = nil, allowed_mentions = nil, components = nil, poll = nil)
     Discordrb::API.request(
       :webhooks_wid_messages,
       webhook_id,
       :patch,
       "#{Discordrb::API.api_base}/webhooks/#{webhook_id}/#{webhook_token}/messages/#{message_id}",
-      { content: content, embeds: embeds, allowed_mentions: allowed_mentions, components: components }.to_json,
+      { content: content, embeds: embeds, allowed_mentions: allowed_mentions, components: components, poll: poll }.to_json,
       content_type: :json
     )
   end

lib/discordrb/bot.rb

@@ -20,6 +20,7 @@
 require 'discordrb/events/invites'
 require 'discordrb/events/interactions'
 require 'discordrb/events/threads'
+require 'discordrb/events/polls'
 
 require 'discordrb/api'
 require 'discordrb/api/channel'
@@ -401,15 +402,16 @@ def delete_invite(code)
     # @param allowed_mentions [Hash, Discordrb::AllowedMentions, false, nil] Mentions that are allowed to ping on this message. `false` disables all pings
     # @param message_reference [Message, String, Integer, nil] The message, or message ID, to reply to if any.
     # @param components [View, Array<Hash>] Interaction components to associate with this message.
+    # @param poll [Hash] A poll request object to include. If you just need to send a poll refer to Channel#send_poll.
     # @return [Message] The message that was sent.
-    def send_message(channel, content, tts = false, embeds = nil, attachments = nil, allowed_mentions = nil, message_reference = nil, components = nil)
+    def send_message(channel, content, tts = false, embeds = nil, attachments = nil, allowed_mentions = nil, message_reference = nil, components = nil, poll = nil)
       channel = channel.resolve_id
       debug("Sending message to #{channel} with content '#{content}'")
       allowed_mentions = { parse: [] } if allowed_mentions == false
       message_reference = { message_id: message_reference.id } if message_reference.respond_to?(:id)
       embeds = (embeds.instance_of?(Array) ? embeds.map(&:to_hash) : [embeds&.to_hash]).compact
 
-      response = API::Channel.create_message(token, channel, content, tts, embeds, nil, attachments, allowed_mentions&.to_hash, message_reference, components)
+      response = API::Channel.create_message(token, channel, content, tts, embeds, nil, attachments, allowed_mentions&.to_hash, message_reference, components, poll)
       Message.new(JSON.parse(response), self)
     end
 
@@ -424,11 +426,12 @@ def send_message(channel, content, tts = false, embeds = nil, attachments = nil,
     # @param allowed_mentions [Hash, Discordrb::AllowedMentions, false, nil] Mentions that are allowed to ping on this message. `false` disables all pings
     # @param message_reference [Message, String, Integer, nil] The message, or message ID, to reply to if any.
     # @param components [View, Array<Hash>] Interaction components to associate with this message.
-    def send_temporary_message(channel, content, timeout, tts = false, embeds = nil, attachments = nil, allowed_mentions = nil, message_reference = nil, components = nil)
+    # @param poll [Hash] A poll request object to include. If you just need to send a poll refer to Channel#send_poll.
+    def send_temporary_message(channel, content, timeout, tts = false, embeds = nil, attachments = nil, allowed_mentions = nil, message_reference = nil, components = nil, poll = nil)
       Thread.new do
         Thread.current[:discordrb_name] = "#{@current_thread}-temp-msg"
 
-        message = send_message(channel, content, tts, embeds, attachments, allowed_mentions, message_reference, components)
+        message = send_message(channel, content, tts, embeds, attachments, allowed_mentions, message_reference, components, poll)
         sleep(timeout)
         message.delete
       end
@@ -1638,6 +1641,14 @@ def handle_dispatch(type, data)
 
         event = ThreadMembersUpdateEvent.new(data, self)
         raise_event(event)
+
+      when :MESSAGE_POLL_VOTE_ADD
+        event = PollVoteAddEvent.new(data, self)
+        raise_event(event)
+
+      when :MESSAGE_POLL_VOTE_REMOVE
+        event = PollVoteRemoveEvent.new(data, self)
+        raise_event(event)
       else
         # another event that we don't support yet
         debug "Event #{type} has been received but is unsupported. Raising UnknownEvent"

lib/discordrb/container.rb

@@ -635,6 +635,32 @@ def channel_select(attributes = {}, &block)
       register_event(ChannelSelectEvent, attributes, block)
     end
 
+    # This **event** is raised whenever a user votes for a poll.
+    # @param attributes [Hash] The event's attributes.
+    # @option attributes [String, Integer, User] :user A user to match against.
+    # @option attributes [String, Integer, Channel] :channel A channel to match against.
+    # @option attributes [String, Integer, Message] :message A message to match against.
+    # @option attributes [String, Integer] :answer_id Custom_id of an answer to match against.
+    # @yield The block is executed when the event is raised.
+    # @yieldparam event [PollVoteAddEvent] The event that was raised.
+    # @return [PollVoteAddEventHandler] The event handler that was registered.
+    def poll_vote_add(attributes = {}, &block)
+      register_event(PollVoteAddEvent, attributes, block)
+    end
+
+    # This **event** is raised whenever a user removes a vote for a poll.
+    # @param attributes [Hash] The event's attributes.
+    # @option attributes [String, Integer, User] :user_id A user to match against.
+    # @option attributes [String, Integer, Channel] :channel_id A channel to match against.
+    # @option attributes [String, Integer, Message] :message_id A message to match against.
+    # @option attributes [String, Integer] :answer_id Custom_id of an answer to match against.
+    # @yield The block is executed when the event is raised.
+    # @yieldparam event [PollVoteRemoveEvent] The event that was raised.
+    # @return [PollVoteRemoveEventHandler] The event handler that was registered.
+    def poll_vote_remove(attributes = {}, &block)
+      register_event(PollVoteRemoveEvent, attributes, block)
+    end
+
     # This **event** is raised for every dispatch received over the gateway, whether supported by discordrb or not.
     # @param attributes [Hash] The event's attributes.
     # @option attributes [String, Symbol, Regexp] :type Matches the event type of the dispatch.

lib/discordrb/data.rb

@@ -40,3 +40,4 @@
 require 'discordrb/data/audit_logs'
 require 'discordrb/data/interaction'
 require 'discordrb/data/component'
+require 'discordrb/data/poll'

lib/discordrb/data/channel.rb

@@ -428,9 +428,10 @@ def slowmode?
     # @param allowed_mentions [Hash, Discordrb::AllowedMentions, false, nil] Mentions that are allowed to ping on this message. `false` disables all pings
     # @param message_reference [Message, String, Integer, nil] The message, or message ID, to reply to if any.
     # @param components [View, Array<Hash>] Interaction components to associate with this message.
+    # @param poll [Hash] A poll request object to include. If you just need to send a poll refer to Channel#send_poll.
     # @return [Message] the message that was sent.
-    def send_message(content, tts = false, embed = nil, attachments = nil, allowed_mentions = nil, message_reference = nil, components = nil)
-      @bot.send_message(@id, content, tts, embed, attachments, allowed_mentions, message_reference, components)
+    def send_message(content, tts = false, embed = nil, attachments = nil, allowed_mentions = nil, message_reference = nil, components = nil, poll = nil)
+      @bot.send_message(@id, content, tts, embed, attachments, allowed_mentions, message_reference, components, poll)
     end
 
     alias_method :send, :send_message
@@ -444,8 +445,9 @@ def send_message(content, tts = false, embed = nil, attachments = nil, allowed_m
     # @param allowed_mentions [Hash, Discordrb::AllowedMentions, false, nil] Mentions that are allowed to ping on this message. `false` disables all pings
     # @param message_reference [Message, String, Integer, nil] The message, or message ID, to reply to if any.
     # @param components [View, Array<Hash>] Interaction components to associate with this message.
-    def send_temporary_message(content, timeout, tts = false, embed = nil, attachments = nil, allowed_mentions = nil, message_reference = nil, components = nil)
-      @bot.send_temporary_message(@id, content, timeout, tts, embed, attachments, allowed_mentions, message_reference, components)
+    # @param poll [Hash] A poll request object to include. If you just need to send a poll refer to Channel#send_poll.
+    def send_temporary_message(content, timeout, tts = false, embed = nil, attachments = nil, allowed_mentions = nil, message_reference = nil, components = nil, poll = nil)
+      @bot.send_temporary_message(@id, content, timeout, tts, embed, attachments, allowed_mentions, message_reference, components, poll)
     end
 
     # Convenience method to send a message with an embed.
@@ -461,16 +463,44 @@ def send_temporary_message(content, timeout, tts = false, embed = nil, attachmen
     # @param allowed_mentions [Hash, Discordrb::AllowedMentions, false, nil] Mentions that are allowed to ping on this message. `false` disables all pings
     # @param message_reference [Message, String, Integer, nil] The message, or message ID, to reply to if any.
     # @param components [View, Array<Hash>] Interaction components to associate with this message.
+    # @param poll [Hash] A poll request object to include. If you just need to send a poll refer to Channel#send_poll.
     # @yield [embed] Yields the embed to allow for easy building inside a block.
     # @yieldparam embed [Discordrb::Webhooks::Embed] The embed from the parameters, or a new one.
     # @return [Message] The resulting message.
-    def send_embed(message = '', embed = nil, attachments = nil, tts = false, allowed_mentions = nil, message_reference = nil, components = nil)
+    def send_embed(message = '', embed = nil, attachments = nil, tts = false, allowed_mentions = nil, message_reference = nil, components = nil, poll = nil)
       embed ||= Discordrb::Webhooks::Embed.new
       view = Discordrb::Webhooks::View.new
 
       yield(embed, view) if block_given?
 
-      send_message(message, tts, embed, attachments, allowed_mentions, message_reference, components || view.to_a)
+      send_message(message, tts, embed, attachments, allowed_mentions, message_reference, components || view.to_a, poll)
+    end
+
+    # Convenience method to send a message with a poll.
+    # @example Send a message with a poll
+    #   channel.send_poll do |poll|
+    #     poll.question = 'Cops?'
+    #     poll.duration = 56
+    #     poll.add_answer(name: 'Hell Yea', emoji: nil)
+    #     poll.add_answer(name: 'Hell Na', emoji: nil)
+    #   end
+    # @param message [String] The message that should be sent along with the embed. If this is the empty string, only the embed will be shown.
+    # @param embed [Discordrb::Webhooks::Embed, nil] The embed to start the building process with, or nil if one should be created anew.
+    # @param attachments [Array<File>] Files that can be referenced in embeds via `attachment://file.png`
+    # @param tts [true, false] Whether or not this message should be sent using Discord text-to-speech.
+    # @param allowed_mentions [Hash, Discordrb::AllowedMentions, false, nil] Mentions that are allowed to ping on this message. `false` disables all pings
+    # @param message_reference [Message, String, Integer, nil] The message, or message ID, to reply to if any.
+    # @param components [View, Array<Hash>] Interaction components to associate with this message.
+    # @param poll [Hash] A poll request object to include with this message.
+    # @yieldparam poll [Discordrb::Poll::Builder] The poll from the parameters, or a new one.
+    # @return [Message] The resulting message.
+    def send_poll(message = '', embed = nil, attachments = nil, tts = false, allowed_mentions = nil, message_reference = nil, components = nil, poll = nil)
+      view = Discordrb::Webhooks::View.new
+      builder ||= Discordrb::Poll::Builder.new
+
+      yield(builder, view) if block_given?
+
+      send_message(message, tts, embed, attachments, allowed_mentions, message_reference, components || view.to_a, poll || builder.to_hash)
     end
 
     # Sends multiple messages to a channel