telerivet 1.1.7 → 1.2.1

data/lib/telerivet/datarow.rb

@@ -1,6 +1,6 @@
-
-module Telerivet
-
+
+module Telerivet
+
 #
 # Represents a row in a custom data table.
 # 
@@ -47,7 +47,7 @@ module Telerivet
 #       * ID of the project this data row belongs to
 #       * Read-only
 #
-class DataRow < Entity
+class DataRow < Entity
     #
     # Saves any fields or custom variables that have changed for this data row.
     #
@@ -102,6 +102,6 @@ class DataRow < Entity
         "/projects/#{get('project_id')}/tables/#{get('table_id')}/rows/#{get('id')}"
     end
  
-end
-
-end
+end
+
+end

data/lib/telerivet/datatable.rb

@@ -1,11 +1,10 @@
-
-module Telerivet
-
+
+module Telerivet
+
 #
 # Represents a custom data table that can store arbitrary rows.
 # 
-# For example, poll services use data tables to store a row for each
-# response.
+# For example, poll services use data tables to store a row for each response.
 # 
 # DataTables are schemaless -- each row simply stores custom variables. Each
 # variable name is equivalent to a different "column" of the data table.
@@ -34,7 +33,7 @@ module Telerivet
 #       * ID of the project this data table belongs to
 #       * Read-only
 #
-class DataTable < Entity
+class DataTable < Entity
     #
     # Queries rows in this data table.
     # 
@@ -203,6 +202,6 @@ class DataTable < Entity
         "/projects/#{get('project_id')}/tables/#{get('id')}"
     end
  
-end
-
-end
+end
+
+end

data/lib/telerivet/group.rb

@@ -1,6 +1,6 @@
-
-module Telerivet
-
+
+module Telerivet
+
 #
 # Represents a group used to organize contacts within Telerivet.
 # 
@@ -34,7 +34,7 @@ module Telerivet
 #       * ID of the project this group belongs to
 #       * Read-only
 #
-class Group < Entity
+class Group < Entity
     #
     # Queries contacts that are members of the given group.
     # 
@@ -209,6 +209,6 @@ class Group < Entity
         "/projects/#{get('project_id')}/groups/#{get('id')}"
     end
  
-end
-
-end
+end
+
+end

data/lib/telerivet/label.rb

@@ -1,6 +1,6 @@
-
-module Telerivet
-
+
+module Telerivet
+
 #
 # Represents a label used to organize messages within Telerivet.
 # 
@@ -26,7 +26,7 @@ module Telerivet
 #       * ID of the project this label belongs to
 #       * Read-only
 #
-class Label < Entity
+class Label < Entity
     #
     # Queries messages with the given label.
     # 
@@ -59,6 +59,9 @@ class Label < 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
     #     
@@ -129,6 +132,6 @@ class Label < Entity
         "/projects/#{get('project_id')}/labels/#{get('id')}"
     end
  
-end
-
-end
+end
+
+end

data/lib/telerivet/message.rb

@@ -59,7 +59,7 @@ module Telerivet
 #       * Updatable via API
 #   
 #   - simulated (bool)
-#       * Whether this message is was simulated within Telerivet for testing (and not actually
+#       * Whether this message was simulated within Telerivet for testing (and not actually
 #           sent to or received by a real phone)
 #       * Read-only
 #   
@@ -98,6 +98,21 @@ module Telerivet
 #           known.
 #       * 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
+#   
 #   - mms_parts (array)
 #       * A list of parts in the MMS message, the same as returned by the
 #           [getMMSParts](#Message.getMMSParts) method.
@@ -124,6 +139,10 @@ module Telerivet
 #       * ID of the route that sent the message (if applicable)
 #       * Read-only
 #   
+#   - broadcast_id (string, max 34 characters)
+#       * ID of the broadcast that this message is part of (if applicable)
+#       * Read-only
+#   
 #   - user_id (string, max 34 characters)
 #       * ID of the Telerivet user who sent the message (if applicable)
 #       * Read-only
@@ -327,6 +346,18 @@ class Message < Entity
         get('ring_time')
     end
 
+    def audio_url
+        get('audio_url')
+    end
+
+    def tts_lang
+        get('tts_lang')
+    end
+
+    def tts_voice
+        get('tts_voice')
+    end
+
     def mms_parts
         get('mms_parts')
     end
@@ -347,6 +378,10 @@ class Message < Entity
         get('route_id')
     end
 
+    def broadcast_id
+        get('broadcast_id')
+    end
+
     def user_id
         get('user_id')
     end

data/lib/telerivet/mobilemoneyreceipt.rb

@@ -1,6 +1,6 @@
-
-module Telerivet
-
+
+module Telerivet
+
 #
 # Represents a receipt received from a mobile money system such as Safaricom M-Pesa (Kenya),
 # Vodacom M-Pesa (Tanzania), or Tigo Pesa (Tanzania).
@@ -91,7 +91,7 @@ module Telerivet
 #       * ID of the project this receipt belongs to
 #       * Read-only
 #
-class MobileMoneyReceipt < Entity
+class MobileMoneyReceipt < Entity
     #
     # Saves any fields or custom variables that have changed for this mobile money receipt.
     #
@@ -182,6 +182,6 @@ class MobileMoneyReceipt < Entity
         "/projects/#{get('project_id')}/receipts/#{get('id')}"
     end
  
-end
-
-end
+end
+
+end

data/lib/telerivet/phone.rb

@@ -1,6 +1,6 @@
-
-module Telerivet
-
+
+module Telerivet
+
 #
 # Represents a phone or gateway that you use to send/receive messages via Telerivet.
 # 
@@ -94,7 +94,7 @@ module Telerivet
 #           (only present for Android phones)
 #       * Read-only
 #
-class Phone < Entity
+class Phone < Entity
     #
     # Queries messages sent or received by this phone.
     # 
@@ -127,6 +127,9 @@ class Phone < 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
     #     
@@ -254,6 +257,6 @@ class Phone < Entity
         "/projects/#{get('project_id')}/phones/#{get('id')}"
     end
  
-end
-
-end
+end
+
+end

data/lib/telerivet/project.rb

@@ -1,6 +1,6 @@
-
-module Telerivet
-
+
+module Telerivet
+
 #
 # Represents a Telerivet project.
 # 
@@ -23,11 +23,15 @@ module Telerivet
 #           <http://en.wikipedia.org/wiki/List_of_tz_database_time_zones>
 #       * Read-only
 #   
+#   - url_slug
+#       * Unique string used as a component of the project's URL in the Telerivet web app
+#       * Read-only
+#   
 #   - vars (Hash)
 #       * Custom variables stored for this project
 #       * Updatable via API
 #
-class Project < Entity
+class Project < Entity
     #
     # Sends one message (SMS, voice call, or USSD request).
     # 
@@ -35,8 +39,14 @@ class Project < Entity
     #   - options (Hash)
     #       * Required
     #     
+    #     - message_type
+    #         * Type of message to send
+    #         * Allowed values: sms, ussd, call
+    #         * Default: sms
+    #     
     #     - content
-    #         * Content of the message to send
+    #         * Content of the message to send (if message_type=call, the text will be spoken
+    #             during a text-to-speech call)
     #         * Required if sending SMS message
     #     
     #     - to_number (string)
@@ -52,8 +62,29 @@ class Project < Entity
     #         * Default: default sender phone ID for your project
     #     
     #     - service_id
-    #         * Service that defines the call flow of the voice call
-    #         * Required if sending voice call
+    #         * Service that defines the call flow of the voice call (when message_type=call)
+    #     
+    #     - audio_url
+    #         * The URL of an MP3 file to play when the contact answers the call (when
+    #             message_type=call).
+    #             
+    #             If audio_url is provided, the text-to-speech voice is not used to say
+    #             `content`, although you can optionally use `content` to indicate the script for the
+    #             audio.
+    #             
+    #             For best results, use an MP3 file containing only speech. Music is not
+    #             recommended because the audio quality will be low when played over a phone line.
+    #     
+    #     - tts_lang
+    #         * The language of the text-to-speech voice (when message_type=call)
+    #         * 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
+    #         * Default: en-US
+    #     
+    #     - tts_voice
+    #         * The name of the text-to-speech voice (when message_type=call)
+    #         * Allowed values: female, male
+    #         * Default: female
     #     
     #     - status_url
     #         * Webhook callback URL to be notified when message status changes
@@ -69,11 +100,6 @@ class Project < Entity
     #     - label_ids (array)
     #         * List of IDs of labels to add to this message
     #     
-    #     - message_type
-    #         * Type of message to send
-    #         * Allowed values: sms, ussd, call
-    #         * Default: sms
-    #     
     #     - vars (Hash)
     #         * Custom variables to store with the message
     #     
@@ -82,6 +108,14 @@ class Project < Entity
     #             will attempt to send messages with higher priority numbers first (for example, so
     #             you can prioritize an auto-reply ahead of a bulk message to a large group).
     #         * Default: 1
+    #     
+    #     - user_id
+    #         * ID of the Telerivet user account that sent the message (use
+    #             [project.getUsers](#Project.getUsers) to look up user IDs). In order to use this
+    #             parameter, the user account associated with the API key must have administrator
+    #             permissions for the project, and the user account associated with the user_id
+    #             parameter must have access to the project.
+    #         * Default: User account associated with the API key
     #   
     # Returns:
     #     Telerivet::Message
@@ -99,6 +133,11 @@ class Project < Entity
     #   - options (Hash)
     #       * Required
     #     
+    #     - message_type
+    #         * Type of message to send
+    #         * Allowed values: sms, call
+    #         * Default: sms
+    #     
     #     - content
     #         * Content of the message to send
     #         * Required if sending SMS message
@@ -116,8 +155,29 @@ class Project < Entity
     #         * Default: default sender phone ID
     #     
     #     - service_id
-    #         * Service that defines the call flow of the voice call
-    #         * Required if sending voice call
+    #         * Service that defines the call flow of the voice call (when message_type=call)
+    #     
+    #     - audio_url
+    #         * The URL of an MP3 file to play when the contact answers the call (when
+    #             message_type=call).
+    #             
+    #             If audio_url is provided, the text-to-speech voice is not used to say
+    #             `content`, although you can optionally use `content` to indicate the script for the
+    #             audio.
+    #             
+    #             For best results, use an MP3 file containing only speech. Music is not
+    #             recommended because the audio quality will be low when played over a phone line.
+    #     
+    #     - tts_lang
+    #         * The language of the text-to-speech voice (when message_type=call)
+    #         * 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
+    #         * Default: en-US
+    #     
+    #     - tts_voice
+    #         * The name of the text-to-speech voice (when message_type=call)
+    #         * Allowed values: female, male
+    #         * Default: female
     #     
     #     - status_url
     #         * Webhook callback URL to be notified when message status changes
@@ -132,11 +192,6 @@ class Project < Entity
     #         * Optionally excludes one contact from receiving the message (only when group_id is
     #             set)
     #     
-    #     - message_type
-    #         * Type of message to send
-    #         * Allowed values: sms, call
-    #         * Default: sms
-    #     
     #     - is_template (bool)
     #         * Set to true to evaluate variables like [[contact.name]] in message content [(See
     #             available variables)](#variables)
@@ -149,9 +204,14 @@ class Project < Entity
     #     (associative array)
     #       - count_queued (int)
     #           * Number of messages queued to send
+    #       
+    #       - broadcast_id
+    #           * ID of broadcast created for this message batch. If count\_queued is 0 or 1, a
+    #               broadcast will not be created, and the broadcast\_id property will be null.
     #
     def send_messages(options)
-        return @api.do_request("POST", get_base_api_path() + "/messages/send_batch", options)
+        data = @api.do_request("POST", get_base_api_path() + "/messages/send_batch", options)
+        return data
     end
 
     #
@@ -163,6 +223,11 @@ class Project < Entity
     #   - options (Hash)
     #       * Required
     #     
+    #     - message_type
+    #         * Type of message to send
+    #         * Allowed values: sms, ussd
+    #         * Default: sms
+    #     
     #     - content
     #         * Content of the message to schedule
     #         * Required if sending SMS message
@@ -194,13 +259,29 @@ class Project < Entity
     #         * Default: default sender phone ID
     #     
     #     - service_id
-    #         * Service that defines the call flow of the voice call
-    #         * Required if sending voice call
-    #     
-    #     - message_type
-    #         * Type of message to send
-    #         * Allowed values: sms, ussd
-    #         * Default: sms
+    #         * Service that defines the call flow of the voice call (when message_type=call)
+    #     
+    #     - audio_url
+    #         * The URL of an MP3 file to play when the contact answers the call (when
+    #             message_type=call).
+    #             
+    #             If audio_url is provided, the text-to-speech voice is not used to say
+    #             `content`, although you can optionally use `content` to indicate the script for the
+    #             audio.
+    #             
+    #             For best results, use an MP3 file containing only speech. Music is not
+    #             recommended because the audio quality will be low when played over a phone line.
+    #     
+    #     - tts_lang
+    #         * The language of the text-to-speech voice (when message_type=call)
+    #         * 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
+    #         * Default: en-US
+    #     
+    #     - tts_voice
+    #         * The name of the text-to-speech voice (when message_type=call)
+    #         * Allowed values: female, male
+    #         * Default: female
     #     
     #     - is_template (bool)
     #         * Set to true to evaluate variables like [[contact.name]] in message content
@@ -562,6 +643,9 @@ class Project < 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
     #     
@@ -626,6 +710,82 @@ class Project < Entity
         return Message.new(@api, {'project_id' => self.id, 'id' => id}, false)
     end
 
+    #
+    # Queries broadcasts within the given project.
+    # 
+    # Arguments:
+    #   - options (Hash)
+    #     
+    #     - time_created[min] (UNIX timestamp)
+    #         * Filter broadcasts created on or after a particular time
+    #     
+    #     - time_created[max] (UNIX timestamp)
+    #         * Filter broadcasts created before a particular time
+    #     
+    #     - last_message_time[min] (UNIX timestamp)
+    #         * Filter broadcasts with most recent message on or after a particular time
+    #     
+    #     - last_message_time[max] (UNIX timestamp)
+    #         * Filter broadcasts with most recent message before a particular time
+    #     
+    #     - sort
+    #         * Sort the results based on a field
+    #         * Allowed values: default, last_message_time
+    #         * Default: default
+    #     
+    #     - sort_dir
+    #         * Sort the results in ascending or descending order
+    #         * Allowed values: asc, desc
+    #         * Default: asc
+    #     
+    #     - page_size (int)
+    #         * Number of results returned per page (max 200)
+    #         * Default: 50
+    #     
+    #     - offset (int)
+    #         * Number of items to skip from beginning of result set
+    #         * Default: 0
+    #   
+    # Returns:
+    #     Telerivet::APICursor (of Telerivet::Broadcast)
+    #
+    def query_broadcasts(options = nil)
+        require_relative 'broadcast'
+        @api.cursor(Broadcast, get_base_api_path() + "/broadcasts", options)
+    end
+
+    #
+    # Retrieves the broadcast with the given ID.
+    # 
+    # Arguments:
+    #   - id
+    #       * ID of the broadcast
+    #       * Required
+    #   
+    # Returns:
+    #     Telerivet::Broadcast
+    #
+    def get_broadcast_by_id(id)
+        require_relative 'broadcast'
+        Broadcast.new(@api, @api.do_request("GET", get_base_api_path() + "/broadcasts/#{id}"))
+    end
+
+    #
+    # Initializes the Telerivet broadcast with the given ID without making an API request.
+    # 
+    # Arguments:
+    #   - id
+    #       * ID of the broadcast
+    #       * Required
+    #   
+    # Returns:
+    #     Telerivet::Broadcast
+    #
+    def init_broadcast_by_id(id)
+        require_relative 'broadcast'
+        return Broadcast.new(@api, {'project_id' => self.id, 'id' => id}, false)
+    end
+
     #
     # Queries groups within the given project.
     # 
@@ -977,7 +1137,7 @@ class Project < Entity
     #     
     #     - context
     #         * Filter services that can be invoked in a particular context
-    #         * Allowed values: message, contact, project
+    #         * Allowed values: message, call, contact, project
     #     
     #     - sort
     #         * Sort the results based on a field
@@ -1228,10 +1388,14 @@ class Project < Entity
         get('timezone_id')
     end
 
+    def url_slug
+        get('url_slug')
+    end
+
     def get_base_api_path()
         "/projects/#{get('id')}"
     end
  
-end
-
-end
+end
+
+end