telerivet 1.5.0 → 1.7.0

data/lib/telerivet/organization.rb

@@ -15,11 +15,53 @@ module Telerivet
 #       * Updatable via API
 #   
 #   - timezone_id
-#       * Billing quota time zone ID; see
-#           <http://en.wikipedia.org/wiki/List_of_tz_database_time_zones>
+#       * Billing quota time zone ID; see [List of tz database time zones Wikipedia
+#           article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
 #       * Updatable via API
 #
 class Organization < Entity
+    #
+    # Creates a new project.
+    # 
+    # Some project settings are not currently possible to configure via
+    # the API, and can only be edited via the web app after the project is created.
+    # 
+    # Arguments:
+    #   - options (Hash)
+    #       * Required
+    #     
+    #     - name (string)
+    #         * Name of the project to create, which must be unique in the organization.
+    #         * Required
+    #     
+    #     - timezone_id
+    #         * Default TZ database timezone ID; see [List of tz database time zones Wikipedia
+    #             article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones). This timezone
+    #             is used when computing statistics by date.
+    #     
+    #     - url_slug
+    #         * Unique string used as a component of the project's URL in the Telerivet web app.
+    #             If not provided, a URL slug will be generated automatically.
+    #     
+    #     - auto_create_contacts (bool)
+    #         * If true, a contact will be automatically created for each unique phone number that
+    #             a message is sent to or received from. If false, contacts will not automatically be
+    #             created (unless contact information is modified by an automated service). The
+    #             Conversations tab in the web app will only show messages that are associated with a
+    #             contact.
+    #         * Default: 1
+    #     
+    #     - vars
+    #         * Custom variables and values to set for this project
+    #   
+    # Returns:
+    #     Telerivet::Project
+    #
+    def create_project(options)
+        require_relative 'project'
+        Project.new(@api, @api.do_request("POST", get_base_api_path() + "/projects", options))
+    end
+
     #
     # Saves any fields that have changed for this organization.
     #
@@ -98,6 +140,86 @@ class Organization < Entity
         return @api.do_request("GET", get_base_api_path() + "/usage/#{usage_type}")
     end
 
+    #
+    # Retrieves statistics about messages sent or received via Telerivet. This endpoint returns
+    # historical data that is computed shortly after midnight each day in the project's time zone,
+    # and does not contain message statistics for the current day.
+    # 
+    # Arguments:
+    #   - options (Hash)
+    #       * Required
+    #     
+    #     - start_date (string)
+    #         * Start date of message statistics, in YYYY-MM-DD format
+    #         * Required
+    #     
+    #     - end_date (string)
+    #         * End date of message statistics (inclusive), in YYYY-MM-DD format
+    #         * Required
+    #     
+    #     - rollup (string)
+    #         * Date interval to group by
+    #         * Allowed values: day, week, month, year, all
+    #         * Default: day
+    #     
+    #     - properties (string)
+    #         * Comma separated list of properties to group by
+    #         * Allowed values: org_id, org_name, org_industry, project_id, project_name, user_id,
+    #             user_email, user_name, phone_id, phone_name, phone_type, direction, source, status,
+    #             network_code, network_name, message_type, service_id, service_name, simulated, link
+    #     
+    #     - metrics (string)
+    #         * Comma separated list of metrics to return (summed for each distinct value of the
+    #             requested properties)
+    #         * Allowed values: count, num_parts, duration, price
+    #         * Required
+    #     
+    #     - currency (string)
+    #         * Three-letter ISO 4217 currency code used when returning the 'price' field. If the
+    #             original price was in a different currency, it will be converted to the requested
+    #             currency using the approximate current exchange rate.
+    #         * Default: USD
+    #     
+    #     - filters (Hash)
+    #         * Key-value pairs of properties and corresponding values; the returned statistics
+    #             will only include messages where the property matches the provided value. Only the
+    #             following properties are supported for filters: `user_id`, `phone_id`, `direction`,
+    #             `source`, `status`, `service_id`, `simulated`, `message_type`, `network_code`
+    #   
+    # Returns:
+    #     (associative array)
+    #       - intervals (array)
+    #           * List of objects representing each date interval containing at least one message
+    #               matching the filters.
+    #               Each object has the following properties:
+    #               
+    #               <table>
+    #               <tr><td> start_time </td> <td> The UNIX timestamp of the start
+    #               of the interval (int) </td></tr>
+    #               <tr><td> end_time </td> <td> The UNIX timestamp of the end of
+    #               the interval, exclusive (int) </td></tr>
+    #               <tr><td> start_date </td> <td> The date of the start of the
+    #               interval in YYYY-MM-DD format (string) </td></tr>
+    #               <tr><td> end_date </td> <td> The date of the end of the
+    #               interval in YYYY-MM-DD format, inclusive (string) </td></tr>
+    #               <tr><td> groups </td> <td> Array of groups for each
+    #               combination of requested property values matching the filters (array)
+    #               <br /><br />
+    #               Each object has the following properties:
+    #               <table>
+    #               <tr><td> properties </td> <td> An object of key/value
+    #               pairs for each distinct value of the requested properties (object) </td></tr>
+    #               <tr><td> metrics </td> <td> An object of key/value pairs
+    #               for each requested metric (object) </td></tr>
+    #               </table>
+    #               </td></tr>
+    #               </table>
+    #
+    def get_message_stats(options)
+        data = @api.do_request("GET", get_base_api_path() + "/message_stats", options)
+        return data
+    end
+
     #
     # Queries projects in this organization.
     # 

data/lib/telerivet/phone.rb

@@ -2,7 +2,8 @@
 module Telerivet
 
 #
-# Represents a phone or gateway that you use to send/receive messages via Telerivet.
+# Represents a basic route (i.e. a phone or gateway) that you use to send/receive messages via
+# Telerivet.
 # 
 # Basic Routes were formerly referred to as "Phones" within Telerivet. API
 # methods, parameters, and properties related to Basic Routes continue to use the term "Phone"
@@ -73,15 +74,16 @@ module Telerivet
 #   
 #   - android_sdk (int)
 #       * Android SDK level, indicating the approximate version of the Android OS installed on
-#           this phone; see
-#           <http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels>
+#           this phone; see [list of Android SDK
+#           levels](http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)
 #           (only present for Android phones)
 #       * Read-only
 #   
 #   - mccmnc
 #       * Code indicating the Android phone's current country (MCC) and mobile network
-#           operator (MNC); see <http://en.wikipedia.org/wiki/Mobile_country_code> (only present
-#           for Android phones). Note this is a string containing numeric digits, not an integer.
+#           operator (MNC); see [Mobile country code Wikipedia
+#           article](https://en.wikipedia.org/wiki/Mobile_country_code) (only present for Android
+#           phones). Note this is a string containing numeric digits, not an integer.
 #       * Read-only
 #   
 #   - manufacturer
@@ -100,7 +102,7 @@ module Telerivet
 #
 class Phone < Entity
     #
-    # Queries messages sent or received by this phone.
+    # Queries messages sent or received by this basic route.
     # 
     # Arguments:
     #   - options (Hash)
@@ -111,7 +113,7 @@ class Phone < Entity
     #     
     #     - message_type
     #         * Filter messages by message_type
-    #         * Allowed values: sms, mms, ussd, call, service
+    #         * Allowed values: sms, mms, ussd, ussd_session, call, chat, service
     #     
     #     - source
     #         * Filter messages by source
@@ -124,7 +126,7 @@ class Phone < Entity
     #     - status
     #         * Filter messages by status
     #         * Allowed values: ignored, processing, received, sent, queued, failed,
-    #             failed_queued, cancelled, delivered, not_delivered
+    #             failed_queued, cancelled, delivered, not_delivered, read
     #     
     #     - time_created[min] (UNIX timestamp)
     #         * Filter messages created on or after a particular time
@@ -134,18 +136,26 @@ class Phone < Entity
     #     
     #     - external_id
     #         * Filter messages by ID from an external provider
+    #         * Allowed modifiers: external_id[ne], external_id[exists]
     #     
     #     - contact_id
     #         * ID of the contact who sent/received the message
+    #         * Allowed modifiers: contact_id[ne], contact_id[exists]
     #     
     #     - phone_id
     #         * ID of the phone (basic route) that sent/received the message
     #     
     #     - broadcast_id
     #         * ID of the broadcast containing the message
+    #         * Allowed modifiers: broadcast_id[ne], broadcast_id[exists]
     #     
     #     - scheduled_id
     #         * ID of the scheduled message that created this message
+    #         * Allowed modifiers: scheduled_id[ne], scheduled_id[exists]
+    #     
+    #     - group_id
+    #         * Filter messages sent or received by contacts in a particular group. The group must
+    #             be a normal group, not a dynamic group.
     #     
     #     - sort
     #         * Sort the results based on a field
@@ -174,7 +184,7 @@ class Phone < Entity
     end
 
     #
-    # Saves any fields or custom variables that have changed for this phone.
+    # Saves any fields or custom variables that have changed for this basic route.
     #
     def save()
         super