telerivet 1.4.5 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -39,11 +39,12 @@ class Label < Entity
39
39
  #
40
40
  # - message_type
41
41
  # * Filter messages by message_type
42
- # * Allowed values: sms, mms, ussd, call, service
42
+ # * Allowed values: sms, mms, ussd, ussd_session, call, chat, service
43
43
  #
44
44
  # - source
45
45
  # * Filter messages by source
46
- # * Allowed values: phone, provider, web, api, service, webhook, scheduled
46
+ # * Allowed values: phone, provider, web, api, service, webhook, scheduled,
47
+ # integration
47
48
  #
48
49
  # - starred (bool)
49
50
  # * Filter messages by starred/unstarred
@@ -51,7 +52,7 @@ class Label < Entity
51
52
  # - status
52
53
  # * Filter messages by status
53
54
  # * Allowed values: ignored, processing, received, sent, queued, failed,
54
- # failed_queued, cancelled, delivered, not_delivered
55
+ # failed_queued, cancelled, delivered, not_delivered, read
55
56
  #
56
57
  # - time_created[min] (UNIX timestamp)
57
58
  # * Filter messages created on or after a particular time
@@ -61,18 +62,26 @@ class Label < Entity
61
62
  #
62
63
  # - external_id
63
64
  # * Filter messages by ID from an external provider
65
+ # * Allowed modifiers: external_id[ne], external_id[exists]
64
66
  #
65
67
  # - contact_id
66
68
  # * ID of the contact who sent/received the message
69
+ # * Allowed modifiers: contact_id[ne], contact_id[exists]
67
70
  #
68
71
  # - phone_id
69
72
  # * ID of the phone (basic route) that sent/received the message
70
73
  #
71
74
  # - broadcast_id
72
75
  # * ID of the broadcast containing the message
76
+ # * Allowed modifiers: broadcast_id[ne], broadcast_id[exists]
73
77
  #
74
78
  # - scheduled_id
75
79
  # * ID of the scheduled message that created this message
80
+ # * Allowed modifiers: scheduled_id[ne], scheduled_id[exists]
81
+ #
82
+ # - group_id
83
+ # * Filter messages sent or received by contacts in a particular group. The group must
84
+ # be a normal group, not a dynamic group.
76
85
  #
77
86
  # - sort
78
87
  # * Sort the results based on a field
@@ -18,17 +18,17 @@ module Telerivet
18
18
  # - status
19
19
  # * Current status of the message
20
20
  # * Allowed values: ignored, processing, received, sent, queued, failed, failed_queued,
21
- # cancelled, delivered, not_delivered
21
+ # cancelled, delivered, not_delivered, read
22
22
  # * Read-only
23
23
  #
24
24
  # - message_type
25
25
  # * Type of the message
26
- # * Allowed values: sms, mms, ussd, call, service
26
+ # * Allowed values: sms, mms, ussd, ussd_session, call, chat, service
27
27
  # * Read-only
28
28
  #
29
29
  # - source
30
30
  # * How the message originated within Telerivet
31
- # * Allowed values: phone, provider, web, api, service, webhook, scheduled
31
+ # * Allowed values: phone, provider, web, api, service, webhook, scheduled, integration
32
32
  # * Read-only
33
33
  #
34
34
  # - time_created (UNIX timestamp)
@@ -71,6 +71,13 @@ module Telerivet
71
71
  # * List of IDs of labels applied to this message
72
72
  # * Read-only
73
73
  #
74
+ # - route_params (Hash)
75
+ # * Route-specific parameters for the message. The parameters object may have keys
76
+ # matching the `phone_type` field of a phone (basic route) that may be used to send the
77
+ # message. The corresponding value is an object with route-specific parameters to use
78
+ # when the message is sent by that type of route.
79
+ # * Read-only
80
+ #
74
81
  # - vars (Hash)
75
82
  # * Custom variables stored for this message
76
83
  # * Updatable via API
@@ -86,8 +93,12 @@ module Telerivet
86
93
  # * Updatable via API
87
94
  #
88
95
  # - external_id
89
- # * The ID of this message from an external SMS gateway provider (e.g. Twilio or Nexmo),
90
- # if available.
96
+ # * The ID of this message from an external SMS gateway provider (e.g. Twilio or
97
+ # Vonage), if available.
98
+ # * Read-only
99
+ #
100
+ # - num_parts (number)
101
+ # * The number of SMS parts associated with the message, if applicable and if known.
91
102
  # * Read-only
92
103
  #
93
104
  # - price (number)
@@ -122,15 +133,6 @@ module Telerivet
122
133
  # * Allowed values: female, male
123
134
  # * Read-only
124
135
  #
125
- # - mms_parts (array)
126
- # * A list of parts in the MMS message, the same as returned by the
127
- # [getMMSParts](#Message.getMMSParts) method.
128
- #
129
- # Note: This property is only present when retrieving an individual
130
- # MMS message by ID, not when querying a list of messages. In other cases, use
131
- # [getMMSParts](#Message.getMMSParts).
132
- # * Read-only
133
- #
134
136
  # - track_clicks (boolean)
135
137
  # * If true, URLs in the message content are short URLs that redirect to a destination
136
138
  # URL.
@@ -138,12 +140,22 @@ module Telerivet
138
140
  #
139
141
  # - short_urls (array)
140
142
  # * For text messages containing short URLs, this is an array of objects with the
141
- # properties `short_url`, `link_type`, and `time_clicked` (the first time that URL was
142
- # clicked). If `link_type` is "redirect", the object also contains a `destination_url`
143
- # property. If `link_type` is "media", the object also contains an `media_index`
144
- # property (the index in the media array). If `link_type` is "service", the object also
145
- # contains a `service_id` property. This property is undefined for messages that do not
146
- # contain short URLs.
143
+ # properties `short_url`, `link_type`, `time_clicked` (the first time that URL was
144
+ # clicked), and `expiration_time`. If `link_type` is "redirect", the object also
145
+ # contains a `destination_url` property. If `link_type` is "media", the object also
146
+ # contains an `media_index` property (the index in the media array). If `link_type` is
147
+ # "service", the object also contains a `service_id` property. This property is
148
+ # undefined for messages that do not contain short URLs.
149
+ # * Read-only
150
+ #
151
+ # - network_code (string)
152
+ # * A string identifying the network that sent or received the message, if known. For
153
+ # mobile networks, this string contains the 3-digit mobile country code (MCC) followed
154
+ # by the 2- or 3-digit mobile network code (MNC), which results in a 5- or 6-digit
155
+ # number. For lists of mobile network operators and their corresponding MCC/MNC values,
156
+ # see [Mobile country code Wikipedia
157
+ # article](https://en.wikipedia.org/wiki/Mobile_country_code). The network_code property
158
+ # may be non-numeric for messages not sent via mobile networks.
147
159
  # * Read-only
148
160
  #
149
161
  # - media (array)
@@ -154,6 +166,27 @@ module Telerivet
154
166
  # temporary and may not be valid for more than 1 day.
155
167
  # * Read-only
156
168
  #
169
+ # - mms_parts (array)
170
+ # * A list of parts in the MMS message (only for incoming MMS messages received via
171
+ # Telerivet Gateway Android app).
172
+ #
173
+ # Each MMS part in the list is an object with the following
174
+ # properties:
175
+ #
176
+ # - cid: MMS content-id
177
+ # - type: MIME type
178
+ # - filename: original filename
179
+ # - size (int): number of bytes
180
+ # - url: URL where the content for this part is stored (secret but
181
+ # publicly accessible, so you could link/embed it in a web page without having to
182
+ # re-host it yourself)
183
+ #
184
+ # In general, the `media` property of the message is recommended for
185
+ # retrieving information about MMS media files, instead of `mms_parts`.
186
+ # The `mms_parts` property is also only present when retrieving an
187
+ # individual MMS message by ID, not when querying a list of messages.
188
+ # * Read-only
189
+ #
157
190
  # - time_clicked (UNIX timestamp)
158
191
  # * If the message contains any short URLs, this is the first time that a short URL in
159
192
  # the message was clicked. This property is undefined for messages that do not contain
@@ -237,18 +270,15 @@ class Message < Entity
237
270
  end
238
271
 
239
272
  #
240
- # Retrieves a list of MMS parts for this message (empty for non-MMS messages).
273
+ # (Deprecated) Retrieves a list of MMS parts for this message (only for incoming MMS messages
274
+ # received via Telerivet Gateway Android app).
275
+ # Note: This only works for MMS messages received via the Telerivet
276
+ # Gateway Android app.
277
+ # In general, the `media` property of the message is recommended for
278
+ # retrieving information about MMS media files.
241
279
  #
242
- # Each MMS part in the list is an object with the following
243
- # properties:
244
- #
245
- # - cid: MMS content-id
246
- # - type: MIME type
247
- # - filename: original filename
248
- # - size (int): number of bytes
249
- # - url: URL where the content for this part is stored (secret but
250
- # publicly accessible, so you could link/embed it in a web page without having to re-host it
251
- # yourself)
280
+ # The return value has the same format as the `mms_parts` property of
281
+ # the Message object.
252
282
  #
253
283
  # Returns:
254
284
  # array
@@ -364,6 +394,10 @@ class Message < Entity
364
394
  get('label_ids')
365
395
  end
366
396
 
397
+ def route_params
398
+ get('route_params')
399
+ end
400
+
367
401
  def priority
368
402
  get('priority')
369
403
  end
@@ -380,6 +414,10 @@ class Message < Entity
380
414
  get('external_id')
381
415
  end
382
416
 
417
+ def num_parts
418
+ get('num_parts')
419
+ end
420
+
383
421
  def price
384
422
  get('price')
385
423
  end
@@ -408,10 +446,6 @@ class Message < Entity
408
446
  get('tts_voice')
409
447
  end
410
448
 
411
- def mms_parts
412
- get('mms_parts')
413
- end
414
-
415
449
  def track_clicks
416
450
  get('track_clicks')
417
451
  end
@@ -420,10 +454,18 @@ class Message < Entity
420
454
  get('short_urls')
421
455
  end
422
456
 
457
+ def network_code
458
+ get('network_code')
459
+ end
460
+
423
461
  def media
424
462
  get('media')
425
463
  end
426
464
 
465
+ def mms_parts
466
+ get('mms_parts')
467
+ end
468
+
427
469
  def time_clicked
428
470
  get('time_clicked')
429
471
  end
@@ -15,11 +15,53 @@ module Telerivet
15
15
  # * Updatable via API
16
16
  #
17
17
  # - timezone_id
18
- # * Billing quota time zone ID; see
19
- # <http://en.wikipedia.org/wiki/List_of_tz_database_time_zones>
18
+ # * Billing quota time zone ID; see [List of tz database time zones Wikipedia
19
+ # article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
20
20
  # * Updatable via API
21
21
  #
22
22
  class Organization < Entity
23
+ #
24
+ # Creates a new project.
25
+ #
26
+ # Some project settings are not currently possible to configure via
27
+ # the API, and can only be edited via the web app after the project is created.
28
+ #
29
+ # Arguments:
30
+ # - options (Hash)
31
+ # * Required
32
+ #
33
+ # - name (string)
34
+ # * Name of the project to create, which must be unique in the organization.
35
+ # * Required
36
+ #
37
+ # - timezone_id
38
+ # * Default TZ database timezone ID; see [List of tz database time zones Wikipedia
39
+ # article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones). This timezone
40
+ # is used when computing statistics by date.
41
+ #
42
+ # - url_slug
43
+ # * Unique string used as a component of the project's URL in the Telerivet web app.
44
+ # If not provided, a URL slug will be generated automatically.
45
+ #
46
+ # - auto_create_contacts (bool)
47
+ # * If true, a contact will be automatically created for each unique phone number that
48
+ # a message is sent to or received from. If false, contacts will not automatically be
49
+ # created (unless contact information is modified by an automated service). The
50
+ # Conversations tab in the web app will only show messages that are associated with a
51
+ # contact.
52
+ # * Default: 1
53
+ #
54
+ # - vars
55
+ # * Custom variables and values to set for this project
56
+ #
57
+ # Returns:
58
+ # Telerivet::Project
59
+ #
60
+ def create_project(options)
61
+ require_relative 'project'
62
+ Project.new(@api, @api.do_request("POST", get_base_api_path() + "/projects", options))
63
+ end
64
+
23
65
  #
24
66
  # Saves any fields that have changed for this organization.
25
67
  #
@@ -98,6 +140,86 @@ class Organization < Entity
98
140
  return @api.do_request("GET", get_base_api_path() + "/usage/#{usage_type}")
99
141
  end
100
142
 
143
+ #
144
+ # Retrieves statistics about messages sent or received via Telerivet. This endpoint returns
145
+ # historical data that is computed shortly after midnight each day in the project's time zone,
146
+ # and does not contain message statistics for the current day.
147
+ #
148
+ # Arguments:
149
+ # - options (Hash)
150
+ # * Required
151
+ #
152
+ # - start_date (string)
153
+ # * Start date of message statistics, in YYYY-MM-DD format
154
+ # * Required
155
+ #
156
+ # - end_date (string)
157
+ # * End date of message statistics (inclusive), in YYYY-MM-DD format
158
+ # * Required
159
+ #
160
+ # - rollup (string)
161
+ # * Date interval to group by
162
+ # * Allowed values: day, week, month, year, all
163
+ # * Default: day
164
+ #
165
+ # - properties (string)
166
+ # * Comma separated list of properties to group by
167
+ # * Allowed values: org_id, org_name, org_industry, project_id, project_name, user_id,
168
+ # user_email, user_name, phone_id, phone_name, phone_type, direction, source, status,
169
+ # network_code, network_name, message_type, service_id, service_name, simulated, link
170
+ #
171
+ # - metrics (string)
172
+ # * Comma separated list of metrics to return (summed for each distinct value of the
173
+ # requested properties)
174
+ # * Allowed values: count, num_parts, duration, price
175
+ # * Required
176
+ #
177
+ # - currency (string)
178
+ # * Three-letter ISO 4217 currency code used when returning the 'price' field. If the
179
+ # original price was in a different currency, it will be converted to the requested
180
+ # currency using the approximate current exchange rate.
181
+ # * Default: USD
182
+ #
183
+ # - filters (Hash)
184
+ # * Key-value pairs of properties and corresponding values; the returned statistics
185
+ # will only include messages where the property matches the provided value. Only the
186
+ # following properties are supported for filters: `user_id`, `phone_id`, `direction`,
187
+ # `source`, `status`, `service_id`, `simulated`, `message_type`, `network_code`
188
+ #
189
+ # Returns:
190
+ # (associative array)
191
+ # - intervals (array)
192
+ # * List of objects representing each date interval containing at least one message
193
+ # matching the filters.
194
+ # Each object has the following properties:
195
+ #
196
+ # <table>
197
+ # <tr><td> start_time </td> <td> The UNIX timestamp of the start
198
+ # of the interval (int) </td></tr>
199
+ # <tr><td> end_time </td> <td> The UNIX timestamp of the end of
200
+ # the interval, exclusive (int) </td></tr>
201
+ # <tr><td> start_date </td> <td> The date of the start of the
202
+ # interval in YYYY-MM-DD format (string) </td></tr>
203
+ # <tr><td> end_date </td> <td> The date of the end of the
204
+ # interval in YYYY-MM-DD format, inclusive (string) </td></tr>
205
+ # <tr><td> groups </td> <td> Array of groups for each
206
+ # combination of requested property values matching the filters (array)
207
+ # <br /><br />
208
+ # Each object has the following properties:
209
+ # <table>
210
+ # <tr><td> properties </td> <td> An object of key/value
211
+ # pairs for each distinct value of the requested properties (object) </td></tr>
212
+ # <tr><td> metrics </td> <td> An object of key/value pairs
213
+ # for each requested metric (object) </td></tr>
214
+ # </table>
215
+ # </td></tr>
216
+ # </table>
217
+ #
218
+ def get_message_stats(options)
219
+ data = @api.do_request("GET", get_base_api_path() + "/message_stats", options)
220
+ return data
221
+ end
222
+
101
223
  #
102
224
  # Queries projects in this organization.
103
225
  #
@@ -2,7 +2,8 @@
2
2
  module Telerivet
3
3
 
4
4
  #
5
- # Represents a phone or gateway that you use to send/receive messages via Telerivet.
5
+ # Represents a basic route (i.e. a phone or gateway) that you use to send/receive messages via
6
+ # Telerivet.
6
7
  #
7
8
  # Basic Routes were formerly referred to as "Phones" within Telerivet. API
8
9
  # methods, parameters, and properties related to Basic Routes continue to use the term "Phone"
@@ -73,15 +74,16 @@ module Telerivet
73
74
  #
74
75
  # - android_sdk (int)
75
76
  # * Android SDK level, indicating the approximate version of the Android OS installed on
76
- # this phone; see
77
- # <http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels>
77
+ # this phone; see [list of Android SDK
78
+ # levels](http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)
78
79
  # (only present for Android phones)
79
80
  # * Read-only
80
81
  #
81
82
  # - mccmnc
82
83
  # * Code indicating the Android phone's current country (MCC) and mobile network
83
- # operator (MNC); see <http://en.wikipedia.org/wiki/Mobile_country_code> (only present
84
- # for Android phones). Note this is a string containing numeric digits, not an integer.
84
+ # operator (MNC); see [Mobile country code Wikipedia
85
+ # article](https://en.wikipedia.org/wiki/Mobile_country_code) (only present for Android
86
+ # phones). Note this is a string containing numeric digits, not an integer.
85
87
  # * Read-only
86
88
  #
87
89
  # - manufacturer
@@ -100,7 +102,7 @@ module Telerivet
100
102
  #
101
103
  class Phone < Entity
102
104
  #
103
- # Queries messages sent or received by this phone.
105
+ # Queries messages sent or received by this basic route.
104
106
  #
105
107
  # Arguments:
106
108
  # - options (Hash)
@@ -111,11 +113,12 @@ class Phone < Entity
111
113
  #
112
114
  # - message_type
113
115
  # * Filter messages by message_type
114
- # * Allowed values: sms, mms, ussd, call, service
116
+ # * Allowed values: sms, mms, ussd, ussd_session, call, chat, service
115
117
  #
116
118
  # - source
117
119
  # * Filter messages by source
118
- # * Allowed values: phone, provider, web, api, service, webhook, scheduled
120
+ # * Allowed values: phone, provider, web, api, service, webhook, scheduled,
121
+ # integration
119
122
  #
120
123
  # - starred (bool)
121
124
  # * Filter messages by starred/unstarred
@@ -123,7 +126,7 @@ class Phone < Entity
123
126
  # - status
124
127
  # * Filter messages by status
125
128
  # * Allowed values: ignored, processing, received, sent, queued, failed,
126
- # failed_queued, cancelled, delivered, not_delivered
129
+ # failed_queued, cancelled, delivered, not_delivered, read
127
130
  #
128
131
  # - time_created[min] (UNIX timestamp)
129
132
  # * Filter messages created on or after a particular time
@@ -133,18 +136,26 @@ class Phone < Entity
133
136
  #
134
137
  # - external_id
135
138
  # * Filter messages by ID from an external provider
139
+ # * Allowed modifiers: external_id[ne], external_id[exists]
136
140
  #
137
141
  # - contact_id
138
142
  # * ID of the contact who sent/received the message
143
+ # * Allowed modifiers: contact_id[ne], contact_id[exists]
139
144
  #
140
145
  # - phone_id
141
146
  # * ID of the phone (basic route) that sent/received the message
142
147
  #
143
148
  # - broadcast_id
144
149
  # * ID of the broadcast containing the message
150
+ # * Allowed modifiers: broadcast_id[ne], broadcast_id[exists]
145
151
  #
146
152
  # - scheduled_id
147
153
  # * ID of the scheduled message that created this message
154
+ # * Allowed modifiers: scheduled_id[ne], scheduled_id[exists]
155
+ #
156
+ # - group_id
157
+ # * Filter messages sent or received by contacts in a particular group. The group must
158
+ # be a normal group, not a dynamic group.
148
159
  #
149
160
  # - sort
150
161
  # * Sort the results based on a field
@@ -173,7 +184,7 @@ class Phone < Entity
173
184
  end
174
185
 
175
186
  #
176
- # Saves any fields or custom variables that have changed for this phone.
187
+ # Saves any fields or custom variables that have changed for this basic route.
177
188
  #
178
189
  def save()
179
190
  super