telegrammer 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d3618d92e021d648b116dc847bc1d92abe78fb07
-  data.tar.gz: eb1ac18503e71ba969677914c5a55a5f77ff79df
+  metadata.gz: 01192345cd31357f67504923fbd3cb1933e99b4e
+  data.tar.gz: a06447a0d0bde6d7d0f9cf03a09e0b51faba93a4
 SHA512:
-  metadata.gz: 5cb7e077fa9cc0c2ed3822de1ccbfd4685ed014db036fec6d7828363f0678d1cb8b05cde5a9c167c9c103a22f3d540c3a209b149b5d8b5b6ce4b94ebbe9e48fc
-  data.tar.gz: dc30eebd1849f0daeec50783653d1ddb731885f0fa43081deac9f28580829067f8f9ac06b085ac9f26a2c6d4c71af7d0a4e615ad0212dffc5bd92834e03d062f
+  metadata.gz: d8d582a1eb2c96034917e98133a7b8eae71ef67dc6e63582fdaefbd5500cf9b1637fd097760f5b2907b0b0a566f11484decad6f9e801d7710dd5929ac607445a
+  data.tar.gz: d3e478e64f1bca7af8eae29785abcb9fe04df2dd8f482e6f1e03e11a20b0b3c74663d63e87f378939a033cc0c3bc50a0155219e1fc1ff3b21d618c67ae53b475

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+v0.1.0
+======
+
+* Fixing coercion in Telegrammer::DataTypes::Channel.
+* Fixed some Telegram data types.
+* Better error handling when Telegram API servers are down.
+* Improved documentation.
+
 v0.0.3
 ======
 

data/README.md

@@ -1,5 +1,6 @@
 [![Gem Version](https://badge.fury.io/rb/telegrammer.svg)](http://badge.fury.io/rb/telegrammer)
 [![Code Climate](https://codeclimate.com/github/mayoral/telegrammer/badges/gpa.svg)](https://codeclimate.com/github/mayoral/telegrammer)
+[![Inline docs](http://inch-ci.org/github/mayoral/telegrammer.svg?branch=master)](http://inch-ci.org/github/mayoral/telegrammer)
 
 # Telegrammer
 
@@ -22,15 +23,13 @@ And then execute:
 First you'll need to register your bot and get an API token. To do that you have to talk with the [@BotFather](https://telegram.me/botfather).
 Learn more about this [here](https://core.telegram.org/bots).
 
-All current actions are supported by the gem. Here's an example for each action:
+After getting your token, you can do things like this:
 
 ```ruby
 require 'telegrammer'
 
 bot = Telegrammer::Bot.new('[YOUR TELEGRAM TOKEN]')
 
-# GET UPDATES
-# https://core.telegram.org/bots/api/#getupdates
 bot.get_updates do |message|
   puts "In chat #{message.chat.id}, @#{message.from.username} said: #{message.text}"
   bot.send_message(chat_id: message.chat.id, text: "You said: #{message.text}")
@@ -38,90 +37,13 @@ bot.get_updates do |message|
   # Here you can also process message text to detect user commands
   # To learn more about commands, see https://core.telegram.org/bots#commands
 end
-
-# SEND MESSAGES
-# https://core.telegram.org/bots/api/#sendmessage
-bot.send_message(chat_id: 123456789, text: "This is a text")
-
-# https://core.telegram.org/bots/api/#replykeyboardmarkup
-reply_markup = Telegrammer::DataTypes::ReplyKeyboardMarkup.new(
-  keyboard: [
-    ["Option 1.1", "Option 1.2"],
-    ["Option 2"],
-    ["Option 3.1", "Option 3.2", "Option 3.3"]
-  ],
-  resize_keyboard: false
-)
-
-# This message will activate a custom keyboard...
-bot.send_message(
-  chat_id: 1460713,
-  text: "Select an option",
-  reply_markup: reply_markup
-)
-
-# https://core.telegram.org/bots/api/#replykeyboardhide
-reply_markup = Telegrammer::DataTypes::ReplyKeyboardHide.new(
-  hide_keyboard: true
-)
-
-# And this message will disable it
-bot.send_message(
-  chat_id: 1460713,
-  text: "Thanks",
-  reply_markup: reply_markup
-)
-
-# FORWARDING A MESSAGE
-# https://core.telegram.org/bots/api/#forwardmessage
-bot.forward_message(chat_id: 123456789, from_chat_id: 987654321, message_id: 111222333)
-
-# SENDING PHOTOS
-# https://core.telegram.org/bots/api/#sendphoto
-image_file = File.open("foo.jpg")
-bot.send_document(chat_id: 123456789, document: image_file)
-
-# SENDING AUDIO FILES
-# https://core.telegram.org/bots/api/#sendaudio
-audio_file = File.open("foo.ogg")
-bot.send_audio(chat_id: 123456789, audio: audio_file)
-
-# SENDING DOCUMENTS
-# https://core.telegram.org/bots/api/#senddocument
-my_secret_file = File.open("secret.txt")
-bot.send_document(chat_id: 123456789, document: my_secret_file)
-
-# SENDING STICKERS
-# https://core.telegram.org/bots/api/#sendsticker
-sticker_image_file = File.open("sticker.jpg")
-bot.send_sticker(chat_id: 123456789, sticker: sticker_image_file)
-
-# SENDING VIDEOS
-# https://core.telegram.org/bots/api/#sendvideo
-video_file = File.open("foo.mp4")
-bot.send_audio(chat_id: 123456789, video: video_file)
-
-# SENDING DOCUMENTS
-# https://core.telegram.org/bots/api/#senddocument
-file = File.open("foo.ogg")
-bot.send_audio(chat_id: 123456789, audio: file)
-
-# SENDING LOCATIONS
-# https://core.telegram.org/bots/api/#sendlocation
-bot.send_location(chat_id: 123456789, latitude: 38.775539, longitude: -4.829988)
-
-# SENDING CHAT ACTIONS
-# https://core.telegram.org/bots/api/#sendchataction
-bot.send_chat_action(chat_id: 123456789, action: "typing")
-
-# GETTING USER PROFILE PHOTOS
-# https://core.telegram.org/bots/api/#getuserprofilephotos
-bot.get_user_profile_photos(user_id: 123456789)
 ```
 
+This gem currently supports all operations exposed by the Telegram's Bot API. All the classes and methods are documented with examples, so please [check the documentation](http://www.rubydoc.info/gems/telegrammer/Telegrammer/Bot). Also you can [check the the wiki](https://github.com/mayoral/telegrammer/wiki), where you'll find more info about topics like [setting webhooks for your bot](https://github.com/mayoral/telegrammer/wiki/Using-webhooks).
+
 ## Contributing
 
-1. Fork it ( https://github.com/mayoral/telegrammer/fork )
+1. Fork it: https://github.com/mayoral/telegrammer/fork
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/lib/telegrammer.rb

@@ -28,22 +28,32 @@ require "telegrammer/api_response"
 
 module Telegrammer
   module Errors
+    # Error returned when a required param is missing
     class MissingParamsError < StandardError
       def initialize(parameter, action)
         super("Missing parameter #{parameter} for action #{action}")
       end
     end
 
+    # Error returned when a param type is invalid
     class InvalidParamTypeError < StandardError
       def initialize(parameter, current_type, allowed_types)
         super("Invalid parameter type: #{parameter}: #{current_type}. Allowed types: #{allowed_types.each {|type| type.class.to_s }.join(",")}.")
       end
     end
 
+    # Error returned when something goes bad with your request to the Telegram API
     class BadRequestError < StandardError
       def initialize(error_code, message)
         super("Bad request. Error code: #{error_code} - Message: #{message}")
       end
     end
+
+    # Error returned when Telegram API Service is unavailable
+    class ServiceUnavailableError < StandardError
+      def initialize(status_code)
+        super("Telegram API Service unavailable (HTTP error code #{status_code})")
+      end
+    end
   end
 end

data/lib/telegrammer/api_response.rb

@@ -5,15 +5,19 @@ module Telegrammer
     attr_reader :success
 
     def initialize(response)
-      @body = response.response_body
-      data = MultiJson.load(@body)
+      if response.code < 500
+        @body = response.response_body
 
-      @success = data["ok"]
+        data = MultiJson.load(@body)
+        @success = data["ok"]
 
-      if @success
-        @result = data["result"]
+        if @success
+          @result = data["result"]
+        else
+          raise Telegrammer::Errors::BadRequestError.new(data["error_code"], data["description"])
+        end
       else
-        raise Telegrammer::Errors::BadRequestError.new(data["error_code"], data["description"])
+        raise Telegrammer::Errors::ServiceUnavailableError.new(response.code)
       end
     end
 

data/lib/telegrammer/bot.rb

@@ -1,9 +1,19 @@
 module Telegrammer
+  # Wrapper for the Telegram's Bots API
   class Bot
     API_ENDPOINT = 'https://api.telegram.org'
 
     attr_reader :me
 
+    # Returns a new instance of Telegrammer::Bot
+    #
+    # @param [String] api_token API Token
+    #
+    # @example
+    #     bot = Telegrammer::Bot.new('[YOUR TELEGRAM TOKEN]')
+    #
+    # @raise [Telegrammer::Errors::BadRequestError] if something goes wrong obtaining data about your bot
+    # @raise [Telegrammer::Errors::ServiceUnavailableError] if Telegram servers are down
     def initialize(api_token)
       @api_token = api_token
       @offset = 0
@@ -12,6 +22,21 @@ module Telegrammer
       @me = get_me
     end
 
+    # Get incoming updates using long polling
+    #
+    # @example
+    #     bot = Telegrammer::Bot.new('[YOUR TELEGRAM TOKEN]')
+    #
+    #     bot.get_updates do |message|
+    #       puts "In chat #{message.chat.id}, @#{message.from.username} said: #{message.text}"
+    #       bot.send_message(chat_id: message.chat.id, text: "You said: #{message.text}")
+    #
+    #       # Here you can also process message text to detect user commands
+    #       # To learn more about commands, see https://core.telegram.org/bots#commands
+    #     end
+    #
+    # @raise [Telegrammer::Errors::BadRequestError] if something goes wrong in the Telegram API servers with the params received by the operation
+    # @raise [Telegrammer::Errors::ServiceUnavailableError] if Telegram servers are down
     def get_updates(&block)
       loop do
         response = api_request("getUpdates", {offset: @offset, timeout: @timeout}, nil)
@@ -24,19 +49,65 @@ module Telegrammer
       end
     end
 
+    # Set a webhook where Telegram will send the messages received by your bot.
+    #
+    # @param [String] url
+    #
+    # @example
+    #     bot = Telegrammer::Bot.new('[YOUR TELEGRAM TOKEN]')
+    #
+    #     # Set up a webhook
+    #     bot.set_webhook("http://www.example.com/my/action")
+    #
+    #     # Delete a webhook
+    #     bot.set_webhook("")
+    #
+    # @raise [Telegrammer::Errors::BadRequestError] if something goes wrong in the Telegram API servers with the params received by the operation
+    # @raise [Telegrammer::Errors::ServiceUnavailableError] if Telegram servers are down
+    #
+    # @see https://github.com/mayoral/telegrammer/wiki/Using-webhooks
+    # @return [Telegrammer::ApiResponse] Response from the API.
     def set_webhook(url)
-      response = api_request("setWebhook", {url: url}, nil)
-
-      Telegrammer::DataTypes::Update.new(response.result)
+      api_request("setWebhook", {url: url}, nil)
     end
 
-
+    # Returns basic information about the bot in form of a User object. Used for testing your bot's auth token.
+    #
+    # @example
+    #     bot = Telegrammer::Bot.new('[YOUR TELEGRAM TOKEN]')
+    #     bot_user = bot.get_me
+    #
+    # @raise [Telegrammer::Errors::BadRequestError] if something goes wrong in the Telegram API servers with the params received by the operation
+    # @raise [Telegrammer::Errors::ServiceUnavailableError] if Telegram servers are down
+    #
+    # @return [Telegrammer::DataTypes::User] User object with info about the bot
     def get_me
       response = api_request("getMe", nil, nil)
 
       Telegrammer::DataTypes::User.new(response.result)
     end
 
+    # Send text messages to a user or group chat.
+    #
+    # @param [Hash] params hash of paramers to send to the sendMessage API operation.
+    # @option params [Integer] :chat_id Required. Unique identifier for the message recipient — User or GroupChat id.
+    # @option params [String] :text Required. Text of the message to be sent
+    # @option params [Boolean] :disable_web_page_preview Optional. Disables link previews for links in this message
+    # @option params [Integer] :reply_to_message_id Optional. If the message is a reply, ID of the original message
+    # @option params [Telegrammer::DataTypes::ReplyKeyboardMarkup,Telegrammer::DataTypes::ReplyKeyboardHide,Telegrammer::DataTypes::ForceReply] :reply_markup Optional. Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to hide keyboard or to force a reply from the user.
+    #
+    # @example
+    #     bot = Telegrammer::Bot.new('[YOUR TELEGRAM TOKEN]')
+    #
+    #     bot.send_message(
+    #       chat_id: 123456789,
+    #       text: "Hello World!"
+    #     )
+    #
+    # @raise [Telegrammer::Errors::BadRequestError] if something goes wrong in the Telegram API servers with the params received by the operation
+    # @raise [Telegrammer::Errors::ServiceUnavailableError] if Telegram servers are down
+    #
+    # @return [Telegrammer::DataTypes::Message] Message object sent to the user or group chat
     def send_message(params)
       params_validation = {
         chat_id: { required: true, class: [Fixnum] },
@@ -55,6 +126,26 @@ module Telegrammer
       Telegrammer::DataTypes::Message.new(response.result)
     end
 
+    # Forward message to a user or group chat.
+    #
+    # @param [Hash] params hash of paramers to send to the forwardMessage API operation.
+    # @option params [Integer] :chat_id Required. Unique identifier for the message recipient — User or GroupChat id.
+    # @option params [Integer] :from_chat_id Required. Unique identifier for the chat where the original message was sent.
+    # @option params [Integer] :message_id Required. Message id to be forwarded.
+    #
+    # @example
+    #     bot = Telegrammer::Bot.new('[YOUR TELEGRAM TOKEN]')
+    #
+    #     bot.forward_message(
+    #       chat_id: 123456789,
+    #       from_chat_id: 987654321
+    #       message_id: 111222333
+    #     )
+    #
+    # @raise [Telegrammer::Errors::BadRequestError] if something goes wrong in the Telegram API servers with the params received by the operation
+    # @raise [Telegrammer::Errors::ServiceUnavailableError] if Telegram servers are down
+    #
+    # @return [Telegrammer::DataTypes::Message] Message object sent to the user or group chat
     def forward_message(params)
       params_validation = {
         chat_id: { required: true, class: [Fixnum] },
@@ -67,6 +158,25 @@ module Telegrammer
       Telegrammer::DataTypes::Message.new(response.result)
     end
 
+    # Sends a photo to a user or group chat.
+    #
+    # @param [Hash] params hash of paramers to send to the sendPhoto API operation.
+    # @option params [Integer] :chat_id Required. Unique identifier for the message recipient — User or GroupChat id.
+    # @option params [File,String] :photo Required.
+    # @option params [String] :caption Optional.
+    # @option params [Integer] :reply_to_message_id Optional. If the message is a reply, ID of the original message
+    # @option params [Telegrammer::DataTypes::ReplyKeyboardMarkup,Telegrammer::DataTypes::ReplyKeyboardHide,Telegrammer::DataTypes::ForceReply] :reply_markup Optional. Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to hide keyboard or to force a reply from the user.
+    #
+    # @example
+    #     bot = Telegrammer::Bot.new('[YOUR TELEGRAM TOKEN]')
+    #     image_file = File.open("foo.jpg")
+    #     bot.send_photo(chat_id: 123456789, photo: image_file)
+    #
+    # @raise [Telegrammer::Errors::BadRequestError] if something goes wrong in the Telegram API servers with the params received by the operation
+    # @raise [Telegrammer::Errors::ServiceUnavailableError] if Telegram servers are down
+    #
+    # @see #send_document
+    # @return [Telegrammer::DataTypes::Message] Message object sent to the user or group chat
     def send_photo(params)
       params_validation = {
         chat_id: { required: true, class: [Fixnum] },
@@ -85,6 +195,26 @@ module Telegrammer
       Telegrammer::DataTypes::Message.new(response.result)
     end
 
+    # Sends audio file to a user or group chat.
+    #
+    # At this moment, Telegram only allows Ogg files encoded with the OPUS codec. If you need to send another file format, you must use #send_document.
+    #
+    # @param [Hash] params hash of paramers to send to the sendAudio API operation.
+    # @option params [Integer] :chat_id Required. Unique identifier for the message recipient — User or GroupChat id.
+    # @option params [File,String] audio Required. Audio file to send. You can either pass a file_id as String to resend an audio that is already on the Telegram servers, or upload a new audio file using multipart/form-data
+    # @option params [Integer] :reply_to_message_id Optional. If the message is a reply, ID of the original message
+    # @option params [Telegrammer::DataTypes::ReplyKeyboardMarkup,Telegrammer::DataTypes::ReplyKeyboardHide,Telegrammer::DataTypes::ForceReply] :reply_markup Optional. Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to hide keyboard or to force a reply from the user.
+    #
+    # @example
+    #     bot = Telegrammer::Bot.new('[YOUR TELEGRAM TOKEN]')
+    #     audio_file = File.open("foo.ogg")
+    #     bot.send_audio(chat_id: 123456789, audio: audio_file)
+    #
+    # @raise [Telegrammer::Errors::BadRequestError] if something goes wrong in the Telegram API servers with the params received by the operation
+    # @raise [Telegrammer::Errors::ServiceUnavailableError] if Telegram servers are down
+    #
+    # @see #send_document
+    # @return [Telegrammer::DataTypes::Message] Message object sent to the user or group chat
     def send_audio(params)
       params_validation = {
         chat_id: { required: true, class: [Fixnum] },
@@ -102,10 +232,28 @@ module Telegrammer
       Telegrammer::DataTypes::Message.new(response.result)
     end
 
+    # Sends a document to a user or group chat.
+    #
+    # @param [Hash] params hash of paramers to send to the sendDocument API operation.
+    # @option params [Integer] :chat_id Required. Unique identifier for the message recipient — User or GroupChat id.
+    # @option params [File,String] :document Required. File to send. You can either pass a file_id as String to resend a file that is already on the Telegram servers, or upload a new file using multipart/form-data.
+    # @option params [Integer] :reply_to_message_id Optional. If the message is a reply, ID of the original message
+    # @option params [Telegrammer::DataTypes::ReplyKeyboardMarkup,Telegrammer::DataTypes::ReplyKeyboardHide,Telegrammer::DataTypes::ForceReply] :reply_markup Optional. Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to hide keyboard or to force a reply from the user.
+    #
+    # @example
+    #     bot = Telegrammer::Bot.new('[YOUR TELEGRAM TOKEN]')
+    #     my_secret_file = File.open("secrets.doc")
+    #     bot.send_document(chat_id: 123456789, document: my_secret_file)
+    #
+    # @raise [Telegrammer::Errors::BadRequestError] if something goes wrong in the Telegram API servers with the params received by the operation
+    # @raise [Telegrammer::Errors::ServiceUnavailableError] if Telegram servers are down
+    #
+    # @return [Telegrammer::DataTypes::Message] Message object sent to the user or group chat
     def send_document(params)
       params_validation = {
         chat_id: { required: true, class: [Fixnum] },
         document: { required: false, class: [File, String] },
+        reply_to_message_id: { required: false, class: [String] },
         reply_markup: { required: false, class: [
           Telegrammer::DataTypes::ReplyKeyboardMarkup,
           Telegrammer::DataTypes::ReplyKeyboardHide,
@@ -118,10 +266,29 @@ module Telegrammer
       Telegrammer::DataTypes::Message.new(response.result)
     end
 
+    # Send WebP images as stickers.
+    #
+    # @param [Hash] params hash of paramers to send to the sendSticker API operation.
+    # @option params [Integer] :chat_id Required. Unique identifier for the message recipient — User or GroupChat id.
+    # @option params [File,String] :sticker Required. Sticker to send. You can either pass a file_id as String to resend a file that is already on the Telegram servers, or upload a new file using multipart/form-data.
+    # @option params [Integer] :reply_to_message_id Optional. If the message is a reply, ID of the original message
+    # @option params [Telegrammer::DataTypes::ReplyKeyboardMarkup,Telegrammer::DataTypes::ReplyKeyboardHide,Telegrammer::DataTypes::ForceReply] :reply_markup Optional. Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to hide keyboard or to force a reply from the user.
+    #
+    # @example
+    #     bot = Telegrammer::Bot.new('[YOUR TELEGRAM TOKEN]')
+    #     sticker_file = File.open("my-sticker.webp")
+    #     bot.send_sticker(chat_id: 123456789, sticker: sticker_file)
+    #
+    # @raise [Telegrammer::Errors::BadRequestError] if something goes wrong in the Telegram API servers with the params received by the operation
+    # @raise [Telegrammer::Errors::ServiceUnavailableError] if Telegram servers are down
+    #
+    # @see #send_document
+    # @return [Telegrammer::DataTypes::Message] Message object sent to the user or group chat
     def send_sticker(params)
       params_validation = {
         chat_id: { required: true, class: [Fixnum] },
         sticker: { required: true, class: [File, String] },
+        reply_to_message_id: { required: false, class: [String] },
         reply_markup: { required: false, class: [
           Telegrammer::DataTypes::ReplyKeyboardMarkup,
           Telegrammer::DataTypes::ReplyKeyboardHide,
@@ -134,10 +301,31 @@ module Telegrammer
       Telegrammer::DataTypes::Message.new(response.result)
     end
 
+    # Sends a video file to a user or group chat.
+    #
+    # At this moment, Telegram only support mp4 videos. If you need to send other formats you must use #send_document.
+    #
+    # @param [Hash] params hash of paramers to send to the sendVideo API operation.
+    # @option params [Integer] :chat_id Required. Unique identifier for the message recipient — User or GroupChat id.
+    # @option params [File,String] :video Video to send. You can either pass a file_id as String to resend a video that is already on the Telegram servers, or upload a new video file.
+    # @option params [Integer] :reply_to_message_id Optional. If the message is a reply, ID of the original message
+    # @option params [Telegrammer::DataTypes::ReplyKeyboardMarkup,Telegrammer::DataTypes::ReplyKeyboardHide,Telegrammer::DataTypes::ForceReply] :reply_markup Optional. Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to hide keyboard or to force a reply from the user.
+    #
+    # @example
+    #     bot = Telegrammer::Bot.new('[YOUR TELEGRAM TOKEN]')
+    #     my_video = File.open("foo.mp4")
+    #     bot.send_video(chat_id: 123456789, video: my_video)
+    #
+    # @raise [Telegrammer::Errors::BadRequestError] if something goes wrong in the Telegram API servers with the params received by the operation
+    # @raise [Telegrammer::Errors::ServiceUnavailableError] if Telegram servers are down
+    #
+    # @see #send_document
+    # @return [Telegrammer::DataTypes::Message] Message object sent to the user or group chat
     def send_video(params)
       params_validation = {
         chat_id: { required: true, class: [Fixnum] },
         video: { required: true, class: [File, String] },
+        reply_to_message_id: { required: false, class: [String] },
         reply_markup: { required: false, class: [
           Telegrammer::DataTypes::ReplyKeyboardMarkup,
           Telegrammer::DataTypes::ReplyKeyboardHide,
@@ -150,11 +338,29 @@ module Telegrammer
       Telegrammer::DataTypes::Message.new(response.result)
     end
 
+    # Sends point on the map to a user or group chat.
+    #
+    # @param [Hash] params hash of paramers to send to the sendAudio API operation.
+    # @option params [Integer] :chat_id Required. Unique identifier for the message recipient — User or GroupChat id.
+    # @option params [Float] :latitude Required. Latitude of location.
+    # @option params [Float] :longitude Required. Longitude of location.
+    # @option params [Integer] :reply_to_message_id Optional. If the message is a reply, ID of the original message.
+    # @option params [Telegrammer::DataTypes::ReplyKeyboardMarkup,Telegrammer::DataTypes::ReplyKeyboardHide,Telegrammer::DataTypes::ForceReply] :reply_markup Optional. Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to hide keyboard or to force a reply from the user.
+    #
+    # @example
+    #     bot = Telegrammer::Bot.new('[YOUR TELEGRAM TOKEN]')
+    #     bot.send_location(chat_id: 123456789, latitude: 38.775539, longitude: -4.829988)
+    #
+    # @raise [Telegrammer::Errors::BadRequestError] if something goes wrong in the Telegram API servers with the params received by the operation
+    # @raise [Telegrammer::Errors::ServiceUnavailableError] if Telegram servers are down
+    #
+    # @return [Telegrammer::DataTypes::Message] Message object sent to the user or group chat
     def send_location(params)
       params_validation = {
         chat_id: { required: true, class: [Fixnum] },
         latitude: { required: true, class: [Float] },
         longitude: { required: true, class: [Float] },
+        reply_to_message_id: { required: false, class: [String] },
         reply_markup: { required: false, class: [
           Telegrammer::DataTypes::ReplyKeyboardMarkup,
           Telegrammer::DataTypes::ReplyKeyboardHide,
@@ -167,18 +373,46 @@ module Telegrammer
       Telegrammer::DataTypes::Message.new(response.result)
     end
 
-    # bot.send_chat_action(chat_id: "1460713", action: "typing")
+    # Sends a status action to a user or group chat.
+    #
+    # Used when you need to tell the user that something is happening on the bot's side. The status is set for 5 seconds or less (when a message arrives from your bot, Telegram clients clear its typing status).
+    #
+    # @param [Hash] params hash of paramers to send to the sendChatAction API operation.
+    # @option params [Integer] :chat_id Required. Unique identifier for the message recipient — User or GroupChat id.
+    # @option params [String] :action Required. Type of action to broadcast. Choose one, depending on what the user is about to receive: "typing" for text messages, "upload_photo" for photos, "record_video" or "upload_video" for videos, "record_audio" or "upload_audio" for audio files, "upload_document" for general files, "find_location" for location data.
+    #
+    # @example
+    #     bot = Telegrammer::Bot.new('[YOUR TELEGRAM TOKEN]')
+    #     bot.send_chat_action(chat_id: 123456789, action: "typing")
+    #
+    # @raise [Telegrammer::Errors::BadRequestError]
+    # @raise [Telegrammer::Errors::ServiceUnavailableError] if Telegram servers are down
+    #
+    # @return [Telegrammer::ApiResponse] Response from the API.
     def send_chat_action(params)
       params_validation = {
         chat_id: { required: true, class: [Fixnum] },
         action: { required: true, class: [String] }
       }
 
-      response = api_request("sendChatAction", params, params_validation)
-
-      response.result
+      api_request("sendChatAction", params, params_validation)
     end
 
+    # Get a list of profile pictures for a user.
+    #
+    # @param [Hash] params hash of paramers to send to the sendChatAction API operation.
+    # @option params [Integer] :chat_id Required. Unique identifier of the target user.
+    # @option params [Integer] :offset Optional. Sequential number of the first photo to be returned. By default, all photos are returned.
+    # @option params [Integer] :limit Optional. Limits the number of photos to be retrieved. Values between 1—100 are accepted. Defaults to 100.
+    #
+    # @example
+    #     bot = Telegrammer::Bot.new('[YOUR TELEGRAM TOKEN]')
+    #     bot.get_user_profile_photos(user_id: 123456789)
+    #
+    # @raise [Telegrammer::Errors::BadRequestError]
+    # @raise [Telegrammer::Errors::ServiceUnavailableError] if Telegram servers are down
+    #
+    # @return [Telegrammer::DataTypes::UserProfilePhotos] Message object sent to the user or group chat
     def get_user_profile_photos(params)
       params_validation = {
         user_id: { required: true, class: [Fixnum] },

data/lib/telegrammer/data_types/audio.rb

@@ -1,6 +1,15 @@
 module Telegrammer
   module DataTypes
+    # Telegram Audio data type
+    #
+    # @attr [String] file_id Unique identifier for this file
+    # @attr [Integer] duration Duration of the audio in seconds as defined by sender
+    # @attr [String] mime_type MIME type of the file as defined by sender
+    # @attr [Integer] file_size File size
+    #
+    # See more at https://core.telegram.org/bots/api#audio
     class Audio < Telegrammer::DataTypes::Base
+      # Unique identifier
       attribute :file_id, String
       attribute :duration, Integer
       attribute :mime_type, String

data/lib/telegrammer/data_types/channel.rb

@@ -1,8 +1,8 @@
 module Telegrammer
   module DataTypes
-    class Channel < Telegrammer::DataTypes::Base
-      attribute :id, Integer
-
+    # Custom attribute class to handle chat attribute in Telegrammer::DataTypes::Message
+    class Channel < Virtus::Attribute
+      # Transforms a channel into a User object or GroupChat object
       def coerce(value)
         value.respond_to?(:first_name) ? User.new(value) : GroupChat.new(value)
       end

data/lib/telegrammer/data_types/contact.rb

@@ -1,5 +1,13 @@
 module Telegrammer
   module DataTypes
+    # Telegram Contact data type
+    #
+    # @attr [String] phone_number Contact's phone number
+    # @attr [String] first_name Contact's first name
+    # @attr [String] last_name Optional. Contact's last name
+    # @attr [String] user_id Optional. Contact's user identifier in Telegram
+    #
+    # See more at https://core.telegram.org/bots/api#contact
     class Contact < Telegrammer::DataTypes::Base
       attribute :phone_number, String
       attribute :first_name, String

data/lib/telegrammer/data_types/document.rb

@@ -1,5 +1,14 @@
 module Telegrammer
   module DataTypes
+    # Telegram Document data type
+    #
+    # @attr [String] file_id Unique file identifier
+    # @attr [Telegrammer::DataTypes::PhotoSize] thumb Document thumbnail as defined by sender
+    # @attr [String] file_name Optional. Original filename as defined by sender
+    # @attr [String] mime_type Optional. MIME type of the file as defined by sender
+    # @attr [String] file_size Optional. File size
+    #
+    # See more at https://core.telegram.org/bots/api#document
     class Document < Telegrammer::DataTypes::Base
       attribute :file_id, String
       attribute :thumb, PhotoSize

data/lib/telegrammer/data_types/force_reply.rb

@@ -1,5 +1,11 @@
 module Telegrammer
   module DataTypes
+    # Telegram ForceReply data type
+    #
+    # @attr [Boolean] force_reply Shows reply interface to the user, as if they manually selected the bot‘s message and tapped ’Reply'
+    # @attr [Boolean] selective Optional. Use this parameter if you want to force reply from specific users only. Targets: 1) users that are @mentioned in the text of the Message object; 2) if the bot's message is a reply (has reply_to_message_id), sender of the original message.
+    #
+    # See more at https://core.telegram.org/bots/api#forcereply
     class ForceReply < Telegrammer::DataTypes::Base
       attribute :force_reply, Boolean, default: true
       attribute :selective, Boolean, default: false

data/lib/telegrammer/data_types/group_chat.rb

@@ -1,5 +1,11 @@
 module Telegrammer
   module DataTypes
+    # Telegram GroupChat data type
+    #
+    # @attr [Integer] id Unique identifier for this group chat
+    # @attr [String] title Group name
+    #
+    # See more at https://core.telegram.org/bots/api#groupchat
     class GroupChat < Telegrammer::DataTypes::Base
       attribute :id, Integer
       attribute :title, String

data/lib/telegrammer/data_types/location.rb

@@ -1,8 +1,14 @@
 module Telegrammer
   module DataTypes
+    # Telegram Location data type
+    #
+    # @attr [Float] latitude Latitude as defined by sender
+    # @attr [Float] longitude Longitude as defined by sender
+    #
+    # See more at https://core.telegram.org/bots/api#location
     class Location < Telegrammer::DataTypes::Base
-      attribute :longitude, Float
       attribute :latitude, Float
+      attribute :longitude, Float
     end
   end
 end

data/lib/telegrammer/data_types/message.rb

@@ -1,12 +1,37 @@
 module Telegrammer
   module DataTypes
+    # Telegram Message data type
+    #
+    # @attr [Integer] message_id Unique message identifier
+    # @attr [Telegrammer::DataTypes::User] from Sender
+    # @attr [DateTime] date Date the message was sent
+    # @attr [Telegrammer::DataTypes::Channel] chat Conversation the message belongs to — user in case of a private message, GroupChat in case of a group
+    # @attr [Telegrammer::DataTypes::User] forward_from Optional. For forwarded messages, sender of the original message
+    # @attr [DateTime] forward_date Optional. For forwarded messages, date the original message was sent
+    # @attr [Telegrammer::DataTypes::Message] reply_to_message Optional. For replies, the original message. Note that the Message object in this field will not contain further reply_to_message fields even if it itself is a reply.
+    # @attr [String] text Optional. For text messages, the actual UTF-8 text of the message
+    # @attr [Telegrammer::DataTypes::Audio] audio Optional. Message is an audio file, information about the file
+    # @attr [Telegrammer::DataTypes::Document] document Optional. Message is a general file, information about the file
+    # @attr [Telegrammer::DataTypes::PhotoSize] photo Optional. Message is a photo, available sizes of the photo
+    # @attr [Telegrammer::DataTypes::Sticker] sticker Optional. Message is a sticker, information about the sticker
+    # @attr [Telegrammer::DataTypes::Video] video Optional. Message is a video, information about the video
+    # @attr [Telegrammer::DataTypes::Contact] contact Optional. Message is a shared contact, information about the contact
+    # @attr [Telegrammer::DataTypes::Location] location Optional. Message is a shared location, information about the location
+    # @attr [Telegrammer::DataTypes::User] new_chat_participant Optional. A new member was added to the group, information about them (this member may be bot itself)
+    # @attr [Telegrammer::DataTypes::User] left_chat_participant Optional. A member was removed from the group, information about them (this member may be bot itself)
+    # @attr [String] new_chat_title Optional. A group title was changed to this value
+    # @attr [Telegrammer::DataTypes::PhotoSize] new_chat_photo Optional. A group photo was change to this value
+    # @attr [Boolean] delete_chat_photo Optional. Informs that the group photo was deleted
+    # @attr [Boolean] group_chat_created Optional. Informs that the group has been created
+    #
+    # See more at https://core.telegram.org/bots/api#message
     class Message < Telegrammer::DataTypes::Base
       attribute :message_id, Integer
       attribute :from, User
       attribute :date, DateTime
       attribute :chat, Channel
       attribute :forward_from, User
-      attribute :forward_date, Integer
+      attribute :forward_date, DateTime
       attribute :reply_to_message, Message
       attribute :text, String
       attribute :audio, Audio
@@ -19,7 +44,7 @@ module Telegrammer
       attribute :new_chat_participant, User
       attribute :left_chat_participant, User
       attribute :new_chat_title, String
-      attribute :new_chat_photo, String
+      attribute :new_chat_photo, Array[PhotoSize]
       attribute :delete_chat_photo, Boolean
       attribute :group_chat_created, Boolean
     end

data/lib/telegrammer/data_types/photo_size.rb

@@ -1,5 +1,13 @@
 module Telegrammer
   module DataTypes
+    # Telegram PhotoSize data type
+    #
+    # @attr [String] file_id Unique identifier for this file
+    # @attr [Integer] width Photo width
+    # @attr [Integer] height Photo height
+    # @attr [Integer] file_size Optional. File size
+    #
+    # See more at https://core.telegram.org/bots/api#photosize
     class PhotoSize < Telegrammer::DataTypes::Base
       attribute :file_id, String
       attribute :width, Integer

data/lib/telegrammer/data_types/reply_keyboard_hide.rb

@@ -1,5 +1,11 @@
 module Telegrammer
   module DataTypes
+    # Telegram ReplyKeyboardHide data type
+    #
+    # @attr [Boolean] hide_keyboard Requests clients to hide the custom keyboard
+    # @attr [Boolean] selective Optional. Use this parameter if you want to hide keyboard for specific users only. Targets: 1) users that are @mentioned in the text of the Message object; 2) if the bot's message is a reply (has reply_to_message_id), sender of the original message.
+    #
+    # See more at https://core.telegram.org/bots/api#replykeyboardhide
     class ReplyKeyboardHide < Telegrammer::DataTypes::Base
       attribute :hide_keyboard, Boolean, default: true
       attribute :selective, Boolean, default: false

data/lib/telegrammer/data_types/reply_keyboard_markup.rb

@@ -1,5 +1,15 @@
 module Telegrammer
   module DataTypes
+    # Telegram ReplyKeyboardMarkup data type.
+    #
+    # This object represents a custom keyboard with reply options (see Introduction to bots for details and examples).
+    #
+    # @attr [Array] keyboard Array of button rows, each represented by an Array of Strings
+    # @attr [Boolean] resize_keyboard Optional. Requests clients to resize the keyboard vertically for optimal fit. Defaults to false.
+    # @attr [Boolean] one_time_keyboard Optional. Requests clients to hide the keyboard as soon as it's been used. Defaults to false.
+    # @attr [Boolean] selective Optional. Use this parameter if you want to hide keyboard for specific users only. Targets: 1) users that are @mentioned in the text of the Message object; 2) if the bot's message is a reply (has reply_to_message_id), sender of the original message.
+    #
+    # See more at https://core.telegram.org/bots/api#replykeyboardmarkup
     class ReplyKeyboardMarkup < Telegrammer::DataTypes::Base
       attribute :keyboard, Array[Array[String]]
       attribute :resize_keyboard, Boolean, default: false

data/lib/telegrammer/data_types/sticker.rb

@@ -1,5 +1,14 @@
 module Telegrammer
   module DataTypes
+    # Telegram Sticker data type.
+    #
+    # @attr [String] file_id Unique identifier for this file
+    # @attr [Integer] width Sticker width
+    # @attr [Integer] height Sticker height
+    # @attr [Telegrammer::DataTypes::PhotoSize] thumb Sticker thumbnail in .webp or .jpg format
+    # @attr [Integer] file_id Optional. File size
+    #
+    # See more at https://core.telegram.org/bots/api#sticker
     class Sticker < Telegrammer::DataTypes::Base
       attribute :file_id, String
       attribute :width, Integer

data/lib/telegrammer/data_types/update.rb

@@ -1,5 +1,11 @@
 module Telegrammer
   module DataTypes
+    # Telegram Update data type.
+    #
+    # @attr [Integer] update_id The update‘s unique identifier. Update identifiers start from a certain positive number and increase sequentially.
+    # @attr [Telegrammer::DataTypes::Message] message Optional. New incoming message of any kind - text, photo, sticker, etc.
+    #
+    # See more at https://core.telegram.org/bots/api#update
     class Update < Telegrammer::DataTypes::Base
       attribute :update_id, Integer
       attribute :message, Message

data/lib/telegrammer/data_types/user.rb

@@ -1,5 +1,13 @@
 module Telegrammer
   module DataTypes
+    # Telegram User data type.
+    #
+    # @attr [Integer] id Unique identifier for this user or bot
+    # @attr [String] first_name User‘s or bot’s first name
+    # @attr [String] last_name Optional. User‘s or bot’s last name
+    # @attr [String] username Optional. User‘s or bot’s username
+    #
+    # See more at https://core.telegram.org/bots/api#user
     class User < Telegrammer::DataTypes::Base
       attribute :id, Integer
       attribute :first_name, String

data/lib/telegrammer/data_types/user_profile_photos.rb

@@ -1,9 +1,13 @@
 module Telegrammer
   module DataTypes
+    # Telegram UserProfilePhotos data type.
+    #
+    # @attr [Integer] total_count Total number of profile pictures the target user has
+    # @attr [Telegrammer::DataTypes::PhotoSize] photos Requested profile pictures (in up to 4 sizes each)
+    #
+    # See more at https://core.telegram.org/bots/api#userprofilephotos
     class UserProfilePhotos < Telegrammer::DataTypes::Base
-      attribute :id, Integer
-      attribute :first_name, String
-      attribute :last_name, String
+      attribute :total_count, Integer
       attribute :photos, Array[PhotoSize]
     end
   end

data/lib/telegrammer/data_types/video.rb

@@ -1,5 +1,17 @@
 module Telegrammer
   module DataTypes
+    # Telegram Video data type
+    #
+    # @attr [String] file_id Unique file identifier
+    # @attr [Integer] width Video width as defined by sender
+    # @attr [Integer] height Video height as defined by sender
+    # @attr [Integer] duration Duration of the video in seconds as defined by sender
+    # @attr [Telegrammer::DataTypes::PhotoSize] thumb Video thumbnail
+    # @attr [String] mime_type Optional. Mime type of a file as defined by sender
+    # @attr [String] file_size Optional. File size
+    # @attr [String] caption Optional. Text description of the video (usually empty)
+    #
+    # See more at https://core.telegram.org/bots/api#video
     class Video < Telegrammer::DataTypes::Base
       attribute :file_id, String
       attribute :width, Integer

data/lib/telegrammer/version.rb

@@ -1,3 +1,3 @@
 module Telegrammer
-  VERSION = "0.0.3"
+  VERSION = "0.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: telegrammer
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
 platform: ruby
 authors:
 - Luis Mayoral
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-06-26 00:00:00.000000000 Z
+date: 2015-06-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: typhoeus