telerivet 1.1.7 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 22a61e5e23fb3d4e4126c4f8aa914acc10ff7291
-  data.tar.gz: 8d3cdcb11da481a2ba69f6fd7588919540b708f8
+  metadata.gz: 956df92c7601623b5f4cca141712a7f4efa82074
+  data.tar.gz: b6fb090b8d492b7ea8a68ee394793dbfc5f6c890
 SHA512:
-  metadata.gz: d4bada308cb913d0bc9890515d4c48d6cb0f6ca55f28feb5e2cf2e12d9aaf9634f01edcdc78feb78f417f3eb06e977fb51c43d5aaeed051f12972c3385a69d0a
-  data.tar.gz: 3aeecae3a783a50e6498ef7dd8a223cc943d583fd711ec15c4f6fd9fe551669355d117a812c326ac59eddd6836e59e309a5d34d97f2511be87635bfb10e317a9
+  metadata.gz: dead19b8d3452ea46c0a3bc819899e59fc6a726df88cf023277031e58ff72f34c3a5b46a17c415afb699a07376a2f41f50833c9e3edc6a19f86464de9fc2c952
+  data.tar.gz: 3132ac8c08c783f6ba7d48cd06416967818bb416292341b472902e45f3bc19280b23d8e39639b7314d805c6dd41436ad89fd5794da242f8d000e4c9b04aa180c

data/lib/telerivet.rb

@@ -5,11 +5,11 @@ require_relative 'telerivet/apicursor'
 
 module Telerivet
 
-class API    
+class API
     attr_reader :num_requests
 
-    @@client_version = '1.1.7'
-    
+    @@client_version = '1.2.1'
+
     #
     # Initializes a client handle to the Telerivet REST API.
     # 
@@ -30,20 +30,20 @@ class API
     end
 
     public
-    
+
     def do_request(method, path, params = nil)
-        
+
         has_post_data = (method == 'POST' || method == 'PUT')
 
         url = @api_url + path
-        
+
         if !has_post_data and params != nil && params.length > 0
             url += '?' + URI.encode_www_form(get_url_params(params))
         end
-        
+
         uri = URI(url)
-        
-        if @session == nil            
+
+        if @session == nil
             @session = Net::HTTP.start(uri.host, uri.port,
               :use_ssl => @api_url.start_with?("https://"),
               :ca_file => File.dirname(__FILE__) + '/cacert.pem',
@@ -51,39 +51,43 @@ class API
               :open_timeout => 20,
             )
         end
-                
-        cls = get_request_class(method)        
+
+        cls = get_request_class(method)
         request = cls.new(uri.request_uri)
 
         request['User-Agent'] = "Telerivet Ruby Client/#{@@client_version} Ruby/#{RUBY_VERSION} OS/#{RUBY_PLATFORM}"
         request.basic_auth(@api_key, "")
 
         if has_post_data
-            request.set_content_type("application/json")           
+            request.set_content_type("application/json")
             if params != nil
-                request.body = JSON.dump(params)            
+                request.body = JSON.dump(params)
             end
         end
-            
+
         @num_requests += 1
 
-        response = @session.request(request)       
-        
-        res = JSON.parse(response.body)
-        
+        response = @session.request(request)
+
+        begin
+            res = JSON.parse(response.body)
+        rescue
+            raise IOError, "Unexpected response from Telerivet API (HTTP #{response.code}): #{response.body}"
+        end
+
         if res.has_key?("error")
             error = res['error']
             error_code = error['code']
-            
+
             if error_code == 'invalid_param'
                 raise InvalidParameterException, error['message'] #, error['code'], error['param'])
             elsif error_code == 'not_found'
                 raise NotFoundException, error['message'] #, error['code']);
             else
-                raise APIException, error['message'] #, error['code'])               
+                raise APIException, error['message'] #, error['code'])
             end
         else
-            return res    
+            return res
         end
     end
 
@@ -160,35 +164,34 @@ class API
         ""
     end
  
-        
     def cursor(item_cls, path, options)
         APICursor.new(self, item_cls, path, options)
     end
-    
+
     private
-    
+
     def encode_params_rec(param_name, value, res)
         return if value == nil
-        
+
         if value.kind_of?(Array)
-            value.each_index { |i| encode_params_rec("#{param_name}[#{i}]", value[i], res) }            
+            value.each_index { |i| encode_params_rec("#{param_name}[#{i}]", value[i], res) }
         elsif value.kind_of?(Hash)
-            value.each { |k,v| encode_params_rec("#{param_name}[#{k}]", v, res) }            
+            value.each { |k,v| encode_params_rec("#{param_name}[#{k}]", v, res) }
         elsif !!value == value
             res[param_name] = value ? 1 : 0
         else
             res[param_name] = value
         end
     end
-            
+
     def get_url_params(params)
         res = {}
         if params != nil
             params.each { |key,value| encode_params_rec(key, value, res) }
         end
-        return res    
+        return res
     end
-    
+
     def get_request_class(method)
         case method
         when 'GET' then return Net::HTTP::Get
@@ -198,7 +201,7 @@ class API
         else return nil
         end
     end
-    
+
 end
 
 class APIException < Exception

data/lib/telerivet/broadcast.rb

@@ -0,0 +1,275 @@
+
+module Telerivet
+
+#
+# Fields:
+# 
+#   - id (string, max 34 characters)
+#       * ID of the broadcast
+#       * Read-only
+#   
+#   - recipients (array of objects)
+#       * List of recipients. Each recipient is an object with a string `type` property, which
+#           may be `"phone_number"`, `"group"`, or `"filter"`.
+#           
+#           If the type is `"phone_number"`, the `phone_number` property will
+#           be set to the recipient's phone number.
+#           
+#           If the type is `"group"`, the `group_id` property will be set to
+#           the ID of the group, and the `group_name` property will be set to the name of the
+#           group.
+#           
+#           If the type is `"filter"`, the `filter_type` property (string) and
+#           `filter_params` property (object) describe the filter used to send the broadcast. (API
+#           clients should not rely on a particular value or format of the `filter_type` or
+#           `filter_params` properties, as they may change without notice.)
+#       * Read-only
+#   
+#   - recipients_str
+#       * A string with a human readable description of the first few recipients (possibly
+#           truncated)
+#       * Read-only
+#   
+#   - time_created (UNIX timestamp)
+#       * Time the broadcast was sent in Telerivet
+#       * Read-only
+#   
+#   - last_message_time (UNIX timestamp)
+#       * Time the most recent message was queued to send in this broadcast
+#       * Read-only
+#   
+#   - last_send_time (UNIX timestamp)
+#       * Time the most recent message was sent (or failed to send) in this broadcast, or null
+#           if no messages have been sent yet
+#       * Read-only
+#   
+#   - status_counts (Hash)
+#       * An object whose keys are the possible status codes (`"queued"`, `"sent"`,
+#           `"failed"`, `"failed_queued"`, `"delivered"`, `"not_delivered"`, and `"cancelled"`),
+#           and whose values are the number of messages in the broadcast currently in that status.
+#       * Read-only
+#   
+#   - message_count (int)
+#       * The total number of messages created for this broadcast. For large broadcasts, the
+#           messages may not be created immediately after the broadcast is sent. The
+#           `message_count` includes messages in any status, including messages that are still
+#           queued.
+#       * Read-only
+#   
+#   - estimated_count (int)
+#       * The estimated number of messages in this broadcast when it is complete. The
+#           `estimated_count` is calculated at the time the broadcast is sent. When the broadcast
+#           is completed, the `estimated_count` may differ from `message_count` if there are any
+#           blocked contacts among the recipients (blocked contacts are included in
+#           `estimated_count` but not in `message_count`), if any contacts don't have phone
+#           numbers, or if the group membership changed while the broadcast was being sent.
+#       * Read-only
+#   
+#   - message_type
+#       * Type of message sent from this broadcast
+#       * Allowed values: sms, mms, ussd, call
+#       * Read-only
+#   
+#   - content (string)
+#       * The text content of the message (null for USSD messages and calls)
+#       * Read-only
+#   
+#   - audio_url
+#       * For voice calls, the URL of an MP3 file to play when the contact answers the call
+#       * Read-only
+#   
+#   - tts_lang
+#       * For voice calls, the language of the text-to-speech voice
+#       * Allowed values: en-US, en-GB, en-GB-WLS, en-AU, en-IN, da-DK, nl-NL, fr-FR, fr-CA,
+#           de-DE, is-IS, it-IT, pl-PL, pt-BR, pt-PT, ru-RU, es-ES, es-US, sv-SE
+#       * Read-only
+#   
+#   - tts_voice
+#       * For voice calls, the text-to-speech voice
+#       * Allowed values: female, male
+#       * Read-only
+#   
+#   - is_template (bool)
+#       * Set to true if Telerivet will render variables like [[contact.name]] in the message
+#           content, false otherwise
+#       * Read-only
+#   
+#   - status
+#       * The current status of the broadcast.
+#       * Allowed values: queuing, sending, complete, cancelled
+#       * Read-only
+#   
+#   - source
+#       * How the message originated within Telerivet
+#       * Allowed values: phone, provider, web, api, service, webhook, scheduled
+#       * Read-only
+#   
+#   - simulated (bool)
+#       * Whether this message was simulated within Telerivet for testing (and not actually
+#           sent to or received by a real phone)
+#       * Read-only
+#   
+#   - label_ids (array)
+#       * List of IDs of labels applied to all messages in the broadcast
+#       * Read-only
+#   
+#   - vars (Hash)
+#       * Custom variables stored for this message
+#       * Read-only
+#   
+#   - price (number)
+#       * The total price of all messages in this broadcast, if known.
+#       * Read-only
+#   
+#   - price_currency
+#       * The currency of the message price, if applicable.
+#       * Read-only
+#   
+#   - reply_count (int)
+#       * The number of replies received in response to a message sent in this broadcast.
+#           (Replies are not included in `message_count` ,`status_counts`, or `price`.)
+#       * Read-only
+#   
+#   - last_reply_time (UNIX timestamp)
+#       * Time the most recent reply was received in response to a message sent in this
+#           broadcast, or null if no replies have been sent yet
+#       * Read-only
+#   
+#   - route_id (string, max 34 characters)
+#       * ID of the phone or route used to send the broadcast (if applicable)
+#       * Read-only
+#   
+#   - user_id (string, max 34 characters)
+#       * ID of the Telerivet user who sent the broadcast (if applicable)
+#       * Read-only
+#   
+#   - project_id
+#       * ID of the project this broadcast belongs to
+#       * Read-only
+#
+class Broadcast < Entity
+    #
+    # Cancels sending a broadcast that has not yet been completely sent. No additional messages
+    # will be queued, and any existing queued messages will be cancelled when they would otherwise
+    # have been sent (except for messages already queued on the Telerivet Android app, which will
+    # not be automatically cancelled).
+    # 
+    # Returns:
+    #     Telerivet::Broadcast
+    #
+    def cancel()
+        require_relative 'broadcast'
+        Broadcast.new(@api, @api.do_request("POST", get_base_api_path() + "/cancel"))
+    end
+
+    def id
+        get('id')
+    end
+
+    def recipients
+        get('recipients')
+    end
+
+    def recipients_str
+        get('recipients_str')
+    end
+
+    def time_created
+        get('time_created')
+    end
+
+    def last_message_time
+        get('last_message_time')
+    end
+
+    def last_send_time
+        get('last_send_time')
+    end
+
+    def status_counts
+        get('status_counts')
+    end
+
+    def message_count
+        get('message_count')
+    end
+
+    def estimated_count
+        get('estimated_count')
+    end
+
+    def message_type
+        get('message_type')
+    end
+
+    def content
+        get('content')
+    end
+
+    def audio_url
+        get('audio_url')
+    end
+
+    def tts_lang
+        get('tts_lang')
+    end
+
+    def tts_voice
+        get('tts_voice')
+    end
+
+    def is_template
+        get('is_template')
+    end
+
+    def status
+        get('status')
+    end
+
+    def source
+        get('source')
+    end
+
+    def simulated
+        get('simulated')
+    end
+
+    def label_ids
+        get('label_ids')
+    end
+
+    def price
+        get('price')
+    end
+
+    def price_currency
+        get('price_currency')
+    end
+
+    def reply_count
+        get('reply_count')
+    end
+
+    def last_reply_time
+        get('last_reply_time')
+    end
+
+    def route_id
+        get('route_id')
+    end
+
+    def user_id
+        get('user_id')
+    end
+
+    def project_id
+        get('project_id')
+    end
+
+    def get_base_api_path()
+        "/projects/#{get('project_id')}/broadcasts/#{get('id')}"
+    end
+ 
+end
+
+end

data/lib/telerivet/contact.rb

@@ -145,6 +145,9 @@ class Contact < Entity
     #     - time_created[max] (UNIX timestamp)
     #         * Filter messages created before a particular time
     #     
+    #     - external_id
+    #         * Filter messages by ID from an external provider
+    #     
     #     - contact_id
     #         * ID of the contact who sent/received the message
     #     

data/lib/telerivet/contactservicestate.rb

@@ -1,6 +1,6 @@
-
-module Telerivet
-
+
+module Telerivet
+
 #
 # Represents the current state of a particular contact for a particular Telerivet service.
 # 
@@ -55,7 +55,7 @@ module Telerivet
 #       * ID of the project this contact/service state belongs to
 #       * Read-only
 #
-class ContactServiceState < Entity
+class ContactServiceState < Entity
     #
     # Saves the state id and any custom variables for this contact. If the state id is null, this
     # is equivalent to calling reset().
@@ -103,6 +103,6 @@ class ContactServiceState < Entity
         "/projects/#{get('project_id')}/services/#{get('service_id')}/states/#{get('contact_id')}"
     end
  
-end
-
-end
+end
+
+end