telerivet 1.4.5 → 1.7.0

data/lib/telerivet/label.rb

@@ -39,11 +39,12 @@ class Label < 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
-    #         * Allowed values: phone, provider, web, api, service, webhook, scheduled
+    #         * Allowed values: phone, provider, web, api, service, webhook, scheduled,
+    #             integration
     #     
     #     - starred (bool)
     #         * Filter messages by starred/unstarred
@@ -51,7 +52,7 @@ class Label < 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
@@ -61,18 +62,26 @@ class Label < 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

data/lib/telerivet/message.rb

@@ -18,17 +18,17 @@ module Telerivet
 #   - status
 #       * Current status of the message
 #       * Allowed values: ignored, processing, received, sent, queued, failed, failed_queued,
-#           cancelled, delivered, not_delivered
+#           cancelled, delivered, not_delivered, read
 #       * Read-only
 #   
 #   - message_type
 #       * Type of the message
-#       * Allowed values: sms, mms, ussd, call, service
+#       * Allowed values: sms, mms, ussd, ussd_session, call, chat, service
 #       * Read-only
 #   
 #   - source
 #       * How the message originated within Telerivet
-#       * Allowed values: phone, provider, web, api, service, webhook, scheduled
+#       * Allowed values: phone, provider, web, api, service, webhook, scheduled, integration
 #       * Read-only
 #   
 #   - time_created (UNIX timestamp)
@@ -71,6 +71,13 @@ module Telerivet
 #       * List of IDs of labels applied to this message
 #       * Read-only
 #   
+#   - route_params (Hash)
+#       * Route-specific parameters for the message. The parameters object may have keys
+#           matching the `phone_type` field of a phone (basic route) that may be used to send the
+#           message. The corresponding value is an object with route-specific parameters to use
+#           when the message is sent by that type of route.
+#       * Read-only
+#   
 #   - vars (Hash)
 #       * Custom variables stored for this message
 #       * Updatable via API
@@ -86,8 +93,12 @@ module Telerivet
 #       * Updatable via API
 #   
 #   - external_id
-#       * The ID of this message from an external SMS gateway provider (e.g. Twilio or Nexmo),
-#           if available.
+#       * The ID of this message from an external SMS gateway provider (e.g. Twilio or
+#           Vonage), if available.
+#       * Read-only
+#   
+#   - num_parts (number)
+#       * The number of SMS parts associated with the message, if applicable and if known.
 #       * Read-only
 #   
 #   - price (number)
@@ -122,15 +133,6 @@ module Telerivet
 #       * 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.
-#           
-#           Note: This property is only present when retrieving an individual
-#           MMS message by ID, not when querying a list of messages. In other cases, use
-#           [getMMSParts](#Message.getMMSParts).
-#       * Read-only
-#   
 #   - track_clicks (boolean)
 #       * If true, URLs in the message content are short URLs that redirect to a destination
 #           URL.
@@ -138,12 +140,22 @@ module Telerivet
 #   
 #   - short_urls (array)
 #       * For text messages containing short URLs, this is an array of objects with the
-#           properties `short_url`, `link_type`, and `time_clicked` (the first time that URL was
-#           clicked). If `link_type` is "redirect", the object also contains a `destination_url`
-#           property. If `link_type` is "media", the object also contains an `media_index`
-#           property (the index in the media array). If `link_type` is "service", the object also
-#           contains a `service_id` property. This property is undefined for messages that do not
-#           contain short URLs.
+#           properties `short_url`, `link_type`, `time_clicked` (the first time that URL was
+#           clicked), and `expiration_time`. If `link_type` is "redirect", the object also
+#           contains a `destination_url` property. If `link_type` is "media", the object also
+#           contains an `media_index` property (the index in the media array). If `link_type` is
+#           "service", the object also contains a `service_id` property. This property is
+#           undefined for messages that do not contain short URLs.
+#       * Read-only
+#   
+#   - network_code (string)
+#       * A string identifying the network that sent or received the message, if known. For
+#           mobile networks, this string contains the 3-digit mobile country code (MCC) followed
+#           by the 2- or 3-digit mobile network code (MNC), which results in a 5- or 6-digit
+#           number. For lists of mobile network operators and their corresponding MCC/MNC values,
+#           see [Mobile country code Wikipedia
+#           article](https://en.wikipedia.org/wiki/Mobile_country_code). The network_code property
+#           may be non-numeric for messages not sent via mobile networks.
 #       * Read-only
 #   
 #   - media (array)
@@ -154,6 +166,27 @@ module Telerivet
 #           temporary and may not be valid for more than 1 day.
 #       * Read-only
 #   
+#   - mms_parts (array)
+#       * A list of parts in the MMS message (only for incoming MMS messages received via
+#           Telerivet Gateway Android app).
+#           
+#           Each MMS part in the list is an object with the following
+#           properties:
+#           
+#           - cid: MMS content-id
+#           - type: MIME type
+#           - filename: original filename
+#           - size (int): number of bytes
+#           - url: URL where the content for this part is stored (secret but
+#           publicly accessible, so you could link/embed it in a web page without having to
+#           re-host it yourself)
+#           
+#           In general, the `media` property of the message is recommended for
+#           retrieving information about MMS media files, instead of `mms_parts`.
+#           The `mms_parts` property is also only present when retrieving an
+#           individual MMS message by ID, not when querying a list of messages.
+#       * Read-only
+#   
 #   - time_clicked (UNIX timestamp)
 #       * If the message contains any short URLs, this is the first time that a short URL in
 #           the message was clicked.  This property is undefined for messages that do not contain
@@ -237,18 +270,15 @@ class Message < Entity
     end
 
     #
-    # Retrieves a list of MMS parts for this message (empty for non-MMS messages).
+    # (Deprecated) Retrieves a list of MMS parts for this message (only for incoming MMS messages
+    # received via Telerivet Gateway Android app).
+    # Note: This only works for MMS messages received via the Telerivet
+    # Gateway Android app.
+    # In general, the `media` property of the message is recommended for
+    # retrieving information about MMS media files.
     # 
-    # Each MMS part in the list is an object with the following
-    # properties:
-    # 
-    # - cid: MMS content-id
-    # - type: MIME type
-    # - filename: original filename
-    # - size (int): number of bytes
-    # - url: URL where the content for this part is stored (secret but
-    # publicly accessible, so you could link/embed it in a web page without having to re-host it
-    # yourself)
+    # The return value has the same format as the `mms_parts` property of
+    # the Message object.
     # 
     # Returns:
     #     array
@@ -364,6 +394,10 @@ class Message < Entity
         get('label_ids')
     end
 
+    def route_params
+        get('route_params')
+    end
+
     def priority
         get('priority')
     end
@@ -380,6 +414,10 @@ class Message < Entity
         get('external_id')
     end
 
+    def num_parts
+        get('num_parts')
+    end
+
     def price
         get('price')
     end
@@ -408,10 +446,6 @@ class Message < Entity
         get('tts_voice')
     end
 
-    def mms_parts
-        get('mms_parts')
-    end
-
     def track_clicks
         get('track_clicks')
     end
@@ -420,10 +454,18 @@ class Message < Entity
         get('short_urls')
     end
 
+    def network_code
+        get('network_code')
+    end
+
     def media
         get('media')
     end
 
+    def mms_parts
+        get('mms_parts')
+    end
+
     def time_clicked
         get('time_clicked')
     end

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,11 +113,12 @@ 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
-    #         * Allowed values: phone, provider, web, api, service, webhook, scheduled
+    #         * Allowed values: phone, provider, web, api, service, webhook, scheduled,
+    #             integration
     #     
     #     - starred (bool)
     #         * Filter messages by starred/unstarred
@@ -123,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
@@ -133,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
@@ -173,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