telegramAPI 1.0.1 → 1.0.2b

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 62d780796896bb0d1b9860090ebe8947dda0ff8f
-  data.tar.gz: 54302fa7ce896108350e4d45692a8cdeecc77f95
+  metadata.gz: 89e16e0cd37195648280e189febf1a7c5b250527
+  data.tar.gz: d478828f86e3181ba3e43337ee7a12fa90ceeace
 SHA512:
-  metadata.gz: 1473f06f0b80dc0cd31cb65a11a7316e0de55c452c73e8734a8f2a12d33772154dec0c78897a66e3ec5d07555cc9636bd13e316f40ea68d2ff099e31d1b17aeb
-  data.tar.gz: 78d0480e5b74a6686cf2a6d03982f5004ef4671e71d20de8319ed71dcb11c4d9f6e54f143fda85129417cd05c67ee88cddde86b0ac37161136f76f58f3ecd175
+  metadata.gz: 9700f259459eb019acaf2cce1ccaddb47782818140fafcb111caf6b877240502a7774df2232ffd54b84dbe25d048eb37a0ebfd34641df3e3d461144a9c816d6c
+  data.tar.gz: d657f246416f0aaa84af591e170c18b68a352695e35ca2034c6d1d578c146e4bc9ddea063f40bd133da8a1b692fefc9251257c5c4d85e6c286e9f3591204d07f

data/README.md

@@ -0,0 +1,72 @@
+# TelegramAPI
+
+This is a simple and lightweight Ruby API for Telegram Bots.
+
+With this tiny library you can create awesome Telegram Bot!
+
+## Installation
+
+```
+sudo gem install telegramAPI
+```
+
+## Use
+
+Import the library in your script with:
+
+```ruby
+require 'telegramAPI'
+```
+
+Obtain a token, if you haven't yet, talking with [@BotFather](https://telegram.me/botfather)
+
+## Getting Started
+
+To test your access token, you can use the *getMe* method
+```ruby
+require 'telegramAPI'
+
+token = "******"
+api = TelegramAPI.new token
+bot = api.getMe
+puts "I'm bot #{bot.first_name} with id #{bot.id}"
+puts "But you can call me @#{bot.username}"
+```
+
+## Documentation
+
+The complete documentation can be found at [www.rubydoc.info](http://www.rubydoc.info/gems/telegramAPI/)
+
+
+## Examples
+
+### Echo Server
+
+```ruby
+token = "******"
+api = TelegramAPI.new token
+while true do
+  # Get last messages if there are, or wait 180 seconds for new messages
+  u=api.getUpdates {timeout=>180}
+  u.each do |m|
+    api.sendMessage(m.message.chat.id, m.message.text)
+  end
+end
+```
+
+### Send Media
+
+```ruby
+api.sendSticker m.message.chat.id, sticker_id
+
+api.sendPhoto m.message.chat.id, "/home/path-of-image/image.jpg"
+
+api.sendDocument m.message.chat.id, "/home/path-of-document/doc.gif"
+
+api.sendAudio m.message.chat.id, "/home/path-of-audio/audio.opus"
+
+api.sendVideo m.message.chat.id, "/home/path-of-video/video.mp4"
+
+api.sendLocation m.message.chat.id, 45.462781, 9.177732
+```
+**Note:** According to Telegram, each audio must be encoded in **Ogg OPUS**, and each video must be encoded in **mp4**.

data/lib/telegramAPI.rb

@@ -3,17 +3,25 @@ require 'json'
 require 'net/http'
 require 'net/https'
 require 'uri'
-require 'rest-client' # sudo gem install rest-client
+require 'rest-client'
 require 'telegramObjects'
 
+# This library provides an easy way to access to the Telegram Bot API
+# Author:: Benedetto Nespoli
+# License:: MIT
+
 class TelegramAPI
   @@core = "https://api.telegram.org/bot"
 
-  def initialize t
-    @token = t
+  # Create a new instance of TelegramAPI
+  #
+  # @param token [String] the access token, obtained thanks to {https://telegram.me/botfather @BotFather} on Telegram.
+  def initialize token
+    @token = token
     @last_update = 0
   end
 
+  private
   def query api, params={}
     p=[]
     params_s=""
@@ -23,12 +31,18 @@ class TelegramAPI
 
     JSON.parse(open(@@core+@token+"/"+api+params_s).read)
   end
+  public
 
+  # Provide information about the bot itself
+  # @return [User] Information about the bot
   def getMe
     User.new self.query("getMe")
   end
 
-  def getUpdates options={}
+  # Get last updates, including last received messages
+  # @param options [Hash<String, String>] Optional settings
+  # @return [Array<Update>] List of all updates
+  def getUpdates options={"timeout"=>0, "limit"=>100}
     r=self.query "getUpdates", {"offset"=>@last_update.to_s}.merge(options)
     if r['ok']!=true then return nil end
     up=ArrayOf.new(r['result'],Update).to_a
@@ -36,52 +50,95 @@ class TelegramAPI
     return up
   end
 
+  # Send a message to the user with id +to+, with the text +text+
+  # @param to [Integer] chat_id to which send the message. Usually message.chat.id
+  # @param text [String] The text to send
+  # @param options (see #getUpdates)
+  # @return [Message] Message with the Photo sent
   def sendMessage to, text, options={}
-    Message.new self.query("sendMessage", {"chat_id"=>to.to_s, "text"=>URI::encode(text)}.merge(options))
+    if options.has_key?"reply_markup" then
+      options["reply_markup"]=options["reply_markup"].to_json
+    end
+    Message.new self.query("sendMessage", {"chat_id"=>to.to_s, "text"=>URI::encode(text)}.merge(options))["result"]
   end
 
+  # Send a message as forwarded
+  # @param to (see #sendMessage)
+  # @param from [Integer] chat_id of the original message.
+  # @param msg [Integer] The message_id of the original message
+  # @return (see #sendPhoto)
   def forwardMessage to, from, msg
-    Message.new self.query("forwardMessage", {"chat_id"=>to, "from_chat_id"=>from, "message_id"=>msg})
+    Message.new self.query("forwardMessage", {"chat_id"=>to, "from_chat_id"=>from, "message_id"=>msg})["result"]
   end
 
+  # Send a local file containing a photo
+  # @param to (see #sendMessage)
+  # @param path [String] The path of the file to send
+  # @param options (see #sendMessage)
+  # @return (see #sendMessage)
   def sendPhoto to, path, options={}
     Message.new JSON.parse(RestClient.post(@@core+@token+"/sendPhoto", {:photo=>File.new(path,'rb'), :chat_id=>to.to_s}.merge(options)).body)["result"]
   end
 
-  # Max size: 50MB
-  # Format: Ogg OPUS. On ubuntu: avconv -i input.ext -acodec libopus output.ogg
+  # Send an audio file in Ogg OPUS format of max 50MB
+  # @param (see #sendPhoto)
+  # @return (see #sendPhoto)
   def sendAudio to, path, options={}
-    RestClient.post @@core+@token+"/sendAudio", {:audio=>File.new(path, 'rb'), :chat_id=>to.to_s}.merge(options)
+    Message.new JSON.parse(RestClient.post(@@core+@token+"/sendAudio", {:audio=>File.new(path, 'rb'), :chat_id=>to.to_s}.merge(options)).body)["result"]
   end
 
+  # Send a general document (file, image, audio)
+  # @param (see #sendPhoto)
+  # @return (see #sendPhoto)
   def sendDocument to, path, options={}
-    RestClient.post @@core+@token+"/sendDocument", {:document=>File.new(path,'rb'), :chat_id=>to.to_s}.merge(options)
+    Message.new JSON.parse(RestClient.post(@@core+@token+"/sendDocument", {:document=>File.new(path,'rb'), :chat_id=>to.to_s}.merge(options)).body)["result"]
   end
 
+  # Send a Sticker from File
+  # @param (see #sendPhoto)
+  # @return (see #sendSticker)
   def sendStickerFromFile to, path, options={}
-    RestClient.post @@core+@token+"/sendStiker", {:sticker=>File.new(path,'rb'), :chat_id=>to.to_s}.merge(options)
+    Message.new JSON.parse(RestClient.post(@@core+@token+"/sendStiker", {:sticker=>File.new(path,'rb'), :chat_id=>to.to_s}.merge(options)).body)["result"]
   end
 
+  # Send a Sticker through its ID
+  # @param to (see #sendPhoto)
+  # @param id [Integer] the ID of the sticker to send
+  # @param options (see #sendPhoto)
+  # @return (see #sendPhoto)
   def sendSticker to, id, options={}
-    RestClient.post @@core+@token+"/sendSticker", {:sticker=>id, :chat_id=>to.to_s}.merge(options)
+    Message.new JSON.parse(RestClient.post(@@core+@token+"/sendSticker", {:sticker=>id, :chat_id=>to.to_s}.merge(options)).body)["result"]
   end
 
-  # Max size: 50MB
-  # Fromat: mp4
+  # Send a video file in mp4 format of max 50MB
+  # @param (see #sendPhoto)
+  # @return (see #sendPhoto)
   def sendVideo to, path, options={}
-    RestClient.post @@core+@token+"/sendVideo", {:video=>File.new(path,'rb'), :chat_id=>to.to_s}.merge(options)
+    Message.new JSON.parse(RestClient.post(@@core+@token+"/sendVideo", {:video=>File.new(path,'rb'), :chat_id=>to.to_s}.merge(options)).body)["result"]
   end
   
+  # Send a location
+  # @param to (see #sendPhoto)
+  # @param lat [Float] Latitude
+  # @param long [Float] Longitude
+  # @param options (see #sendPhoto)
+  # @return (see #sendPhoto)
   def sendLocation to, lat, long, options={}
-    self.query "sendLocation", {"chat_id"=>to, "latitude"=>lat, "longitude"=>long}.merge(options)
+    Message.new self.query("sendLocation", {"chat_id"=>to, "latitude"=>lat, "longitude"=>long}.merge(options))["result"]
   end
 
-  # act is one between: typing, upload_photo, record_video, record_audio, upload_audio, upload_document, find_location
+  # Send a Chat Action
+  # @param to (see #sendPhoto)
+  # @param act [String] One of: typing, upload_photo, record_video, record_audio, upload_audio, upload_document, find_location
   def sendChatAction to, act
     self.query "sendChatAction", {"chat_id"=>to, "action"=>act}
   end
 
+  # Get a list of user profile photos, in up to 4 sizes each
+  # @param id [Integer] ID user whom getting the photos
+  # @param options (see #sendPhoto)
+  # @return [UserProfilePhotos]
   def getUserProfilePhotos id, options={}
-    self.query "getUserProfilePhotos", {"user_id"=>id}.merge(options)
+    UserProfilePhotos.new self.query("getUserProfilePhotos", {"user_id"=>id}.merge(options))["result"]
   end
 end

data/lib/telegramObjects.rb

@@ -7,6 +7,7 @@ class Update
   end
 end
 
+# Object describing a Bot or User
 class User
   attr_accessor :id, :first_name, :last_name, :username
   def initialize json
@@ -18,6 +19,7 @@ class User
   end
 end
 
+# Object describing a Chat Group
 class GroupChat
   attr_accessor :id, :title
   def initialize json
@@ -43,6 +45,7 @@ class ArrayOf
   end
 end
 
+# Object describing a Message
 class Message
   attr_accessor :message_id, :from, :date, :chat, :forward_from, :forward_date,
     :reply_to_message, :text, :audio, :document, :photo, :sticker, :video,
@@ -75,6 +78,7 @@ class Message
   end
 end
 
+# Object Describing a Photo or Sticker
 class PhotoSize
   attr_accessor :file_id, :width, :height, :file_size
   def initialize json
@@ -156,6 +160,7 @@ class Location
   end
 end
 
+# Object describing a list of photos in up to 4 sizes each
 class UserProfilePhotos
   attr_accessor :total_count, :photos
   def initialize json
@@ -177,6 +182,10 @@ class ReplyKeyboardMarkup
     @one_time_keyboard = json["one_time_keyboard"]
     @selective = json["selective"]
   end
+
+  def to_json
+    "{\"keyboard\":" + @keyboard.to_json  + ", \"resize_keyboard\":" + (!@resize_keyboard ? "false" : "true") + ", \"one_time_keyboard\":" + (!@one_time_keyboard ? "false" : "true") + ", \"selective\":" + (!@selective ? "false" : "true") + "}"
+  end
 end
 
 class ReplyKeyboardHide
@@ -186,6 +195,10 @@ class ReplyKeyboardHide
     @hide_keyboard = json["hide_keyboard"]
     @selective = json["selective"]
   end
+
+  def to_json
+    "{\"hide_keyboard\":true, \"selective\":"+(!@selective ? "false" : "true")+"}"
+  end
 end
 
 class ForceReply
@@ -195,4 +208,8 @@ class ForceReply
     @force_reply = json["force_reply"]
     @selective = json["selective"]
   end
+
+  def to_json
+    "{\"force_reply\":true, \"selective\":"+(!@selective ? "false" : "true")+"}"
+  end
 end

metadata

@@ -1,24 +1,39 @@
 --- !ruby/object:Gem::Specification
 name: telegramAPI
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2b
 platform: ruby
 authors:
 - Benedetto Nespoli
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-03 00:00:00.000000000 Z
-dependencies: []
-description: A lightweight Ruby API for Telegram-Bots
+date: 2015-07-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A lightweight Ruby API for Telegram Bots
 email: benedetto.nespoli@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - lib/telegramAPI.rb
 - lib/telegramObjects.rb
-homepage: http://rubygems.org/gems/telegramAPI
+homepage: https://github.com/bennesp/telegramAPI
 licenses:
 - MIT
 metadata: {}
@@ -33,13 +48,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
-summary: Telegram api for Bots
+summary: Telegram API for Bots
 test_files: []
+has_rdoc: