telerivet 1.4.5 → 1.6.1

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.
@@ -82,11 +82,31 @@ class Project < Entity
82
82
  # short URLs.
83
83
  # * Default: false
84
84
  #
85
+ # - short_link_params (Hash)
86
+ # *
87
+ # If `track_clicks` is true, `short_link_params` may be used to specify
88
+ # custom parameters for each short link in the message. The following parameters are
89
+ # supported:
90
+ #
91
+ # `domain` (string): A custom short domain name to use for the short
92
+ # links. The domain name must already be registered for your project or organization.
93
+ #
94
+ # `expiration_sec` (integer): The number of seconds after the message is
95
+ # created (queued to send) when the short links will stop forwarding to the
96
+ # destination URL.
97
+ # If null, the short links will not expire.
98
+ #
85
99
  # - media_urls (array)
86
100
  # * URLs of media files to attach to the text message. If `message_type` is `sms`,
87
101
  # short links to each media URL will be appended to the end of the content (separated
88
102
  # by a new line).
89
103
  #
104
+ # - route_params (Hash)
105
+ # * Route-specific parameters for the message. The parameters object should have one
106
+ # or more keys matching the `phone_type` field of a phone (basic route) that may be
107
+ # used to send the message. The corresponding value should be an object with
108
+ # route-specific parameters to use if the message is sent by that type of route.
109
+ #
90
110
  # - label_ids (array)
91
111
  # * List of IDs of labels to add to this message
92
112
  #
@@ -202,6 +222,20 @@ class Project < Entity
202
222
  # short URLs.
203
223
  # * Default: false
204
224
  #
225
+ # - short_link_params (Hash)
226
+ # *
227
+ # If `track_clicks` is true, `short_link_params` may be used to specify
228
+ # custom parameters for each short link in the message. The following parameters are
229
+ # supported:
230
+ #
231
+ # `domain` (string): A custom short domain name to use for the short
232
+ # links. The domain name must already be registered for your project or organization.
233
+ #
234
+ # `expiration_sec` (integer): The number of seconds after the message is
235
+ # created (queued to send) when the short links will stop forwarding to the
236
+ # destination URL.
237
+ # If null, the short links will not expire.
238
+ #
205
239
  # - media_urls (array)
206
240
  # * URLs of media files to attach to the text message. If `message_type` is `sms`,
207
241
  # short links to each URL will be appended to the end of the content (separated by a
@@ -210,6 +244,12 @@ class Project < Entity
210
244
  # - vars (Hash)
211
245
  # * Custom variables to set for each message
212
246
  #
247
+ # - route_params (Hash)
248
+ # * Route-specific parameters for the messages in the broadcast. The parameters object
249
+ # may have keys matching the `phone_type` field of a phone (basic route) that may be
250
+ # used to send messages in this broadcast. The corresponding value is an object with
251
+ # route-specific parameters to use when sending messages with that type of route.
252
+ #
213
253
  # - service_id
214
254
  # * Service to invoke for each recipient (when `message_type` is `call` or `service`)
215
255
  # * Required if message_type is service
@@ -295,11 +335,36 @@ class Project < Entity
295
335
  # available variables)](#variables)
296
336
  # * Default: false
297
337
  #
338
+ # - track_clicks (boolean)
339
+ # * If true, URLs in the message content will automatically be replaced with unique
340
+ # short URLs.
341
+ # * Default: false
342
+ #
343
+ # - short_link_params (Hash)
344
+ # *
345
+ # If `track_clicks` is true, `short_link_params` may be used to specify
346
+ # custom parameters for each short link in the message. The following parameters are
347
+ # supported:
348
+ #
349
+ # `domain` (string): A custom short domain name to use for the short
350
+ # links. The domain name must already be registered for your project or organization.
351
+ #
352
+ # `expiration_sec` (integer): The number of seconds after the message is
353
+ # created (queued to send) when the short links will stop forwarding to the
354
+ # destination URL.
355
+ # If null, the short links will not expire.
356
+ #
298
357
  # - media_urls (array)
299
358
  # * URLs of media files to attach to the text message. If `message_type` is `sms`,
300
359
  # short links to each media URL will be appended to the end of the content (separated
301
360
  # by a new line).
302
361
  #
362
+ # - route_params (Hash)
363
+ # * Route-specific parameters to apply to all messages. The parameters object may have
364
+ # keys matching the `phone_type` field of a phone (basic route) that may be used to
365
+ # send messages. The corresponding value is an object with route-specific parameters
366
+ # to use when sending messages with that type of route.
367
+ #
303
368
  # - vars (Hash)
304
369
  # * Custom variables to store with the message
305
370
  #
@@ -325,6 +390,10 @@ class Project < Entity
325
390
  # (Other properties of the Message object are
326
391
  # omitted in order to reduce the amount of redundant data sent in each API
327
392
  # response.)
393
+ # If the `messages` parameter in the API request
394
+ # contains items with `to_number` values that are associated with blocked contacts,
395
+ # the `id` and `status` properties corresponding to those items will be null, and no
396
+ # messages will be sent to those numbers.
328
397
  #
329
398
  # - broadcast_id
330
399
  # * ID of broadcast that these messages are associated with, if `broadcast_id` or
@@ -447,6 +516,20 @@ class Project < Entity
447
516
  # short URLs.
448
517
  # * Default: false
449
518
  #
519
+ # - short_link_params (Hash)
520
+ # *
521
+ # If `track_clicks` is true, `short_link_params` may be used to specify
522
+ # custom parameters for each short link in the message. The following parameters are
523
+ # supported:
524
+ #
525
+ # `domain` (string): A custom short domain name to use for the short
526
+ # links. The domain name must already be registered for your project or organization.
527
+ #
528
+ # `expiration_sec` (integer): The number of seconds after the message is
529
+ # created (queued to send) when the short links will stop forwarding to the
530
+ # destination URL.
531
+ # If null, the short links will not expire.
532
+ #
450
533
  # - is_template (bool)
451
534
  # * Set to true to evaluate variables like [[contact.name]] in message content
452
535
  # * Default: false
@@ -456,6 +539,12 @@ class Project < Entity
456
539
  # short links to each media URL will be appended to the end of the content (separated
457
540
  # by a new line).
458
541
  #
542
+ # - route_params (Hash)
543
+ # * Route-specific parameters to use when sending the message. The parameters object
544
+ # may have keys matching the `phone_type` field of a phone (basic route) that may be
545
+ # used to send the message. The corresponding value is an object with route-specific
546
+ # parameters to use when sending a message with that type of route.
547
+ #
459
548
  # - label_ids (array)
460
549
  # * Array of IDs of labels to add to the sent messages (maximum 5). Does not apply
461
550
  # when `message_type`=`service`, since the labels are determined by the service
@@ -648,6 +737,9 @@ class Project < Entity
648
737
  # Arguments:
649
738
  # - options (Hash)
650
739
  #
740
+ # - group_id
741
+ # * Filter contacts within a group
742
+ #
651
743
  # - name
652
744
  # * Filter contacts by name
653
745
  # * Allowed modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt],
@@ -657,28 +749,26 @@ class Project < Entity
657
749
  # * Filter contacts by phone number
658
750
  # * Allowed modifiers: phone_number[ne], phone_number[prefix],
659
751
  # phone_number[not_prefix], phone_number[gte], phone_number[gt], phone_number[lt],
660
- # phone_number[lte]
752
+ # phone_number[lte], phone_number[exists]
661
753
  #
662
754
  # - time_created (UNIX timestamp)
663
755
  # * Filter contacts by time created
664
- # * Allowed modifiers: time_created[ne], time_created[min], time_created[max]
756
+ # * Allowed modifiers: time_created[min], time_created[max]
665
757
  #
666
758
  # - last_message_time (UNIX timestamp)
667
759
  # * Filter contacts by last time a message was sent or received
668
- # * Allowed modifiers: last_message_time[exists], last_message_time[ne],
669
- # last_message_time[min], last_message_time[max]
760
+ # * Allowed modifiers: last_message_time[min], last_message_time[max],
761
+ # last_message_time[exists]
670
762
  #
671
763
  # - last_incoming_message_time (UNIX timestamp)
672
764
  # * Filter contacts by last time a message was received
673
- # * Allowed modifiers: last_incoming_message_time[exists],
674
- # last_incoming_message_time[ne], last_incoming_message_time[min],
675
- # last_incoming_message_time[max]
765
+ # * Allowed modifiers: last_incoming_message_time[min],
766
+ # last_incoming_message_time[max], last_incoming_message_time[exists]
676
767
  #
677
768
  # - last_outgoing_message_time (UNIX timestamp)
678
769
  # * Filter contacts by last time a message was sent
679
- # * Allowed modifiers: last_outgoing_message_time[exists],
680
- # last_outgoing_message_time[ne], last_outgoing_message_time[min],
681
- # last_outgoing_message_time[max]
770
+ # * Allowed modifiers: last_outgoing_message_time[min],
771
+ # last_outgoing_message_time[max], last_outgoing_message_time[exists]
682
772
  #
683
773
  # - incoming_message_count (int)
684
774
  # * Filter contacts by number of messages received from the contact
@@ -695,9 +785,9 @@ class Project < Entity
695
785
  #
696
786
  # - vars (Hash)
697
787
  # * Filter contacts by value of a custom variable (e.g. vars[email], vars[foo], etc.)
698
- # * Allowed modifiers: vars[foo][exists], vars[foo][ne], vars[foo][prefix],
699
- # vars[foo][not_prefix], vars[foo][gte], vars[foo][gt], vars[foo][lt], vars[foo][lte],
700
- # vars[foo][min], vars[foo][max]
788
+ # * Allowed modifiers: vars[foo][ne], vars[foo][prefix], vars[foo][not_prefix],
789
+ # vars[foo][gte], vars[foo][gt], vars[foo][lt], vars[foo][lte], vars[foo][min],
790
+ # vars[foo][max], vars[foo][exists]
701
791
  #
702
792
  # - sort
703
793
  # * Sort the results based on a field
@@ -776,8 +866,8 @@ class Project < Entity
776
866
  #
777
867
  # - last_active_time (UNIX timestamp)
778
868
  # * Filter phones by last active time
779
- # * Allowed modifiers: last_active_time[exists], last_active_time[ne],
780
- # last_active_time[min], last_active_time[max]
869
+ # * Allowed modifiers: last_active_time[min], last_active_time[max],
870
+ # last_active_time[exists]
781
871
  #
782
872
  # - sort
783
873
  # * Sort the results based on a field
@@ -843,6 +933,9 @@ class Project < Entity
843
933
  # Arguments:
844
934
  # - options (Hash)
845
935
  #
936
+ # - label_id
937
+ # * Filter messages with a label
938
+ #
846
939
  # - direction
847
940
  # * Filter messages by direction
848
941
  # * Allowed values: incoming, outgoing
@@ -853,7 +946,8 @@ class Project < Entity
853
946
  #
854
947
  # - source
855
948
  # * Filter messages by source
856
- # * Allowed values: phone, provider, web, api, service, webhook, scheduled
949
+ # * Allowed values: phone, provider, web, api, service, webhook, scheduled,
950
+ # integration
857
951
  #
858
952
  # - starred (bool)
859
953
  # * Filter messages by starred/unstarred
@@ -861,7 +955,7 @@ class Project < Entity
861
955
  # - status
862
956
  # * Filter messages by status
863
957
  # * Allowed values: ignored, processing, received, sent, queued, failed,
864
- # failed_queued, cancelled, delivered, not_delivered
958
+ # failed_queued, cancelled, delivered, not_delivered, read
865
959
  #
866
960
  # - time_created[min] (UNIX timestamp)
867
961
  # * Filter messages created on or after a particular time
@@ -871,18 +965,26 @@ class Project < Entity
871
965
  #
872
966
  # - external_id
873
967
  # * Filter messages by ID from an external provider
968
+ # * Allowed modifiers: external_id[ne], external_id[exists]
874
969
  #
875
970
  # - contact_id
876
971
  # * ID of the contact who sent/received the message
972
+ # * Allowed modifiers: contact_id[ne], contact_id[exists]
877
973
  #
878
974
  # - phone_id
879
975
  # * ID of the phone (basic route) that sent/received the message
880
976
  #
881
977
  # - broadcast_id
882
978
  # * ID of the broadcast containing the message
979
+ # * Allowed modifiers: broadcast_id[ne], broadcast_id[exists]
883
980
  #
884
981
  # - scheduled_id
885
982
  # * ID of the scheduled message that created this message
983
+ # * Allowed modifiers: scheduled_id[ne], scheduled_id[exists]
984
+ #
985
+ # - group_id
986
+ # * Filter messages sent or received by contacts in a particular group. The group must
987
+ # be a normal group, not a dynamic group.
886
988
  #
887
989
  # - sort
888
990
  # * Sort the results based on a field
@@ -1018,6 +1120,298 @@ class Project < Entity
1018
1120
  return Broadcast.new(@api, {'project_id' => self.id, 'id' => id}, false)
1019
1121
  end
1020
1122
 
1123
+ #
1124
+ # Creates and starts an asynchronous task that is applied to all entities matching a filter
1125
+ # (e.g. contacts, messages, or data rows).
1126
+ # Tasks are designed to efficiently process a large number of
1127
+ # entities. When processing a large number of entities,
1128
+ # tasks are much faster than using the API to query and loop over
1129
+ # all objects matching a filter.
1130
+ #
1131
+ # Several different types of tasks are supported, including
1132
+ # applying services to contacts, messages, or data rows;
1133
+ # adding or removing contacts from a group; blocking or unblocking
1134
+ # sending messages to a contact; updating a custom variable;
1135
+ # deleting contacts, messages, or data rows; or exporting data to
1136
+ # CSV.
1137
+ #
1138
+ # When using a task to apply a Custom Actions or Cloud Script API
1139
+ # service (`apply_service_to_contacts`, `apply_service_to_rows`, or
1140
+ # `apply_service_to_messages`),
1141
+ # the `task` variable will be available within the service. The
1142
+ # service can use custom variables on the task object (e.g. `task.vars.example`), such as
1143
+ # to store aggregate statistics for the rows matching the filter.
1144
+ #
1145
+ # Arguments:
1146
+ # - options (Hash)
1147
+ # * Required
1148
+ #
1149
+ # - task_type
1150
+ # * Type of task to create. Each `task_type` applies to a certain type of entity (such
1151
+ # as a contact, message, or data row).
1152
+ #
1153
+ # Tasks for contacts:
1154
+ #
1155
+ # - `update_contact_var`
1156
+ # - `add_group_members`
1157
+ # - `remove_group_members`
1158
+ # - `set_conversation_status`
1159
+ # - `set_send_blocked`
1160
+ # - `apply_service_to_contacts`
1161
+ # - `delete_contacts`
1162
+ # - `export_contacts`
1163
+ #
1164
+ # Tasks for data rows:
1165
+ #
1166
+ # - `update_row_var`
1167
+ # - `apply_service_to_rows`
1168
+ # - `delete_rows`
1169
+ # - `export_rows`
1170
+ #
1171
+ # Tasks for messages:
1172
+ #
1173
+ # - `cancel_messages`
1174
+ # - `resend_messages`
1175
+ # - `retry_message_services`
1176
+ # - `apply_service_to_messages`
1177
+ # - `add_label`
1178
+ # - `remove_label`
1179
+ # - `update_message_var`
1180
+ # - `delete_messages`
1181
+ # - `export_messages`
1182
+ # * Allowed values: update_contact_var, delete_contacts, add_group_members,
1183
+ # remove_group_members, set_conversation_status, set_send_blocked,
1184
+ # apply_service_to_contacts, update_row_var, delete_rows, apply_service_to_rows,
1185
+ # delete_messages, cancel_messages, resend_messages, retry_message_services,
1186
+ # apply_service_to_messages, add_label, remove_label, update_message_var,
1187
+ # export_messages, export_contacts, export_rows
1188
+ # * Required
1189
+ #
1190
+ # - task_params (Hash)
1191
+ # * Parameters applied to all matching rows (specific to `task_type`).
1192
+ #
1193
+ # **`apply_service_to_contacts`**,
1194
+ # **`apply_service_to_messages`**, **`apply_service_to_rows`**:
1195
+ # <table>
1196
+ # <tr><td> `service_id` </td> <td> The ID of the
1197
+ # service to apply (string) </td></tr>
1198
+ # <tr><td> `variables` </td> <td> Optional object
1199
+ # containing up to 25 temporary variable names and their corresponding values to set
1200
+ # when invoking the service. Values may be strings, numbers, or boolean (true/false).
1201
+ # String values may be up to 4096 bytes in length. Arrays and objects are not
1202
+ # supported. Within Custom Actions, each variable can be used like [[$name]] (with a
1203
+ # leading $ character and surrounded by double square brackets). Within a Cloud Script
1204
+ # API service or JavaScript action, each variable will be available as a global
1205
+ # JavaScript variable like $name (with a leading $ character). (object) </td></tr>
1206
+ # </table>
1207
+ # <br />
1208
+ # **`update_contact_var`**, **`update_message_var`**,
1209
+ # **`update_row_var`**:
1210
+ # <table>
1211
+ # <tr><td> `variable` </td> <td> The custom variable
1212
+ # name (string) </td></tr>
1213
+ # <tr><td> `value` </td> <td> The value to set
1214
+ # (string, boolean, float, null) </td></tr>
1215
+ # </table>
1216
+ # <br />
1217
+ # **`add_group_members`**, **`remove_group_members`**:
1218
+ # <table>
1219
+ # <tr><td> `group_id` </td> <td> The ID of the group
1220
+ # (string) </td></tr>
1221
+ # </table>
1222
+ # <br />
1223
+ # **`add_label`**, **`remove_label`**:
1224
+ # <table>
1225
+ # <tr><td> `label_id` </td> <td> The ID of the label
1226
+ # (string) </td></tr>
1227
+ # </table>
1228
+ # <br />
1229
+ # **`resend_messages`**:
1230
+ # <table>
1231
+ # <tr><td> `route_id` </td> <td> ID of the new route
1232
+ # to use, or null to use the original route (string) </td></tr>
1233
+ # </table>
1234
+ # <br />
1235
+ # **`set_send_blocked`**:
1236
+ # <table>
1237
+ # <tr><td> `send_blocked` </td> <td> `true` to block
1238
+ # sending messages, `false` to unblock sending messages (boolean) </td></tr>
1239
+ # </table>
1240
+ # <br />
1241
+ # **`set_conversation_status`**:
1242
+ # <table>
1243
+ # <tr><td> `conversation_status` </td> <td> "active",
1244
+ # "handled", or "closed" (string) </td></tr>
1245
+ # </table>
1246
+ # <br />
1247
+ # **`export_contacts`**, **`export_messages`**,
1248
+ # **`export_rows`**:
1249
+ # <table>
1250
+ # <tr><td>`storage_id` </td> <td> ID of a storage
1251
+ # provider where the CSV file will be saved. (string)
1252
+ #
1253
+ # Currently only AWS S3 is supported as a storage
1254
+ # provider.
1255
+ # This requires creating a S3 bucket in your own
1256
+ # AWS account, as well as an IAM user with access key and secret that has permission
1257
+ # to write to that bucket.
1258
+ # You can configure your own S3 bucket as a
1259
+ # storage provider on the <a href="/dashboard/a/storage">Storage Providers</a> page.
1260
+ #
1261
+ # Direct downloads are not supported when
1262
+ # exporting data via the API.
1263
+ # (string) </td></tr>
1264
+ # <tr><td>`filename` </td> <td> Path within the
1265
+ # storage backend where the CSV file will be saved </td></tr>
1266
+ # <tr><td>`column_ids` </td> <td> IDs of columns to
1267
+ # save in the CSV file. If not provided, all default columns will be saved. (array of
1268
+ # strings, optional) </td></tr>
1269
+ # </table>
1270
+ # <br />
1271
+ # **`delete_contacts`**, **`delete_messages`**,
1272
+ # **`delete_rows`**, **`cancel_messages`**, **`retry_message_services`**: <br />
1273
+ # No parameters.
1274
+ #
1275
+ # - filter_type
1276
+ # * Type of filter defining the rows that the task is applied to.
1277
+ #
1278
+ # Each `filter_type` queries a certain type of
1279
+ # entity (such as contacts, messages, or data rows).
1280
+ #
1281
+ # In general, the `task_type` and the
1282
+ # `filter_type` must return the same type of entity; however, tasks applied to
1283
+ # contacts (other than `export_contacts`) can also be applied
1284
+ # when the filter returns entities that are
1285
+ # associated with a contact, such as messages or data rows. (Note that in this case,
1286
+ # it is possible for the task to be applied multiple times to an individual contact if
1287
+ # multiple messages or data rows are associated with the same contact.)
1288
+ # * Allowed values: query_contacts, contact_ids, query_rows, row_ids, query_messages,
1289
+ # message_ids
1290
+ # * Required
1291
+ #
1292
+ # - filter_params (Hash)
1293
+ # * Parameters defining the rows that the task is applied to (specific to
1294
+ # `filter_type`).
1295
+ #
1296
+ # **`query_contacts`**: <br />
1297
+ # The same filter parameters as used by
1298
+ # [project.queryContacts](#Project.queryContacts). If you want to apply the task to
1299
+ # all contacts, use the parameters {"all": true}.
1300
+ #
1301
+ # **`contact_ids`**:
1302
+ # <table>
1303
+ # <tr><td> `contact_ids` </td> <td> IDs of up to 100
1304
+ # contacts to apply this task to (array of strings) </td></tr>
1305
+ # </table>
1306
+ #
1307
+ # **`query_messages`**: <br />
1308
+ # The same filter parameters as used by
1309
+ # [project.queryMessages](#Project.queryMessages). If you want to apply the task to
1310
+ # all messages, use the parameters {"all": true}.
1311
+ #
1312
+ # **`message_ids`**:
1313
+ # <table>
1314
+ # <tr><td> `message_ids` </td> <td> IDs of up to 100
1315
+ # messages to apply this task to (array of strings) </td></tr>
1316
+ # </table>
1317
+ #
1318
+ # **`query_rows`**: <br />
1319
+ # The same filter parameters as used by
1320
+ # [table.queryRows](#DataTable.queryRows). If you want to apply the task to all rows
1321
+ # in the table, use the parameters {"all": true}.
1322
+ #
1323
+ # **`row_ids`**:
1324
+ # <table>
1325
+ # <tr><td> `row_ids` </td> <td> IDs of up to 100 data
1326
+ # rows to apply this task to (array of strings) </td></tr>
1327
+ # </table>
1328
+ # * Required
1329
+ #
1330
+ # - table_id (string, max 34 characters)
1331
+ # * ID of the data table this task is applied to (if applicable).
1332
+ #
1333
+ # Required if filter_type is `query_rows` or `row_ids`.
1334
+ #
1335
+ # - vars (Hash)
1336
+ # * Initial custom variables to set for the task.
1337
+ #
1338
+ # If the task applies a service, the service can read
1339
+ # and write custom variables on the task object (e.g. `task.vars.example`), such as
1340
+ # to store aggregate statistics for the rows matching
1341
+ # the filter.
1342
+ #
1343
+ # Returns:
1344
+ # Telerivet::Task
1345
+ #
1346
+ def create_task(options)
1347
+ require_relative 'task'
1348
+ Task.new(@api, @api.do_request("POST", get_base_api_path() + "/tasks", options))
1349
+ end
1350
+
1351
+ #
1352
+ # Queries batch tasks within the given project.
1353
+ #
1354
+ # Arguments:
1355
+ # - options (Hash)
1356
+ #
1357
+ # - sort
1358
+ # * Sort the results based on a field
1359
+ # * Allowed values: default
1360
+ # * Default: default
1361
+ #
1362
+ # - sort_dir
1363
+ # * Sort the results in ascending or descending order
1364
+ # * Allowed values: asc, desc
1365
+ # * Default: asc
1366
+ #
1367
+ # - page_size (int)
1368
+ # * Number of results returned per page (max 500)
1369
+ # * Default: 50
1370
+ #
1371
+ # - offset (int)
1372
+ # * Number of items to skip from beginning of result set
1373
+ # * Default: 0
1374
+ #
1375
+ # Returns:
1376
+ # Telerivet::APICursor (of Telerivet::Task)
1377
+ #
1378
+ def query_tasks(options = nil)
1379
+ require_relative 'task'
1380
+ @api.cursor(Task, get_base_api_path() + "/tasks", options)
1381
+ end
1382
+
1383
+ #
1384
+ # Retrieves the task with the given ID.
1385
+ #
1386
+ # Arguments:
1387
+ # - id
1388
+ # * ID of the task
1389
+ # * Required
1390
+ #
1391
+ # Returns:
1392
+ # Telerivet::Task
1393
+ #
1394
+ def get_task_by_id(id)
1395
+ require_relative 'task'
1396
+ Task.new(@api, @api.do_request("GET", get_base_api_path() + "/tasks/#{id}"))
1397
+ end
1398
+
1399
+ #
1400
+ # Initializes the task with the given ID without making an API request.
1401
+ #
1402
+ # Arguments:
1403
+ # - id
1404
+ # * ID of the task
1405
+ # * Required
1406
+ #
1407
+ # Returns:
1408
+ # Telerivet::Task
1409
+ #
1410
+ def init_task_by_id(id)
1411
+ require_relative 'task'
1412
+ return Task.new(@api, {'project_id' => self.id, 'id' => id}, false)
1413
+ end
1414
+
1021
1415
  #
1022
1416
  # Queries groups within the given project.
1023
1417
  #
@@ -1288,16 +1682,15 @@ class Project < Entity
1288
1682
  #
1289
1683
  # - time_created (UNIX timestamp)
1290
1684
  # * Filter scheduled messages by time_created
1291
- # * Allowed modifiers: time_created[ne], time_created[min], time_created[max]
1685
+ # * Allowed modifiers: time_created[min], time_created[max]
1292
1686
  #
1293
1687
  # - next_time (UNIX timestamp)
1294
1688
  # * Filter scheduled messages by next_time
1295
- # * Allowed modifiers: next_time[exists], next_time[ne], next_time[min],
1296
- # next_time[max]
1689
+ # * Allowed modifiers: next_time[min], next_time[max], next_time[exists]
1297
1690
  #
1298
1691
  # - sort
1299
1692
  # * Sort the results based on a field
1300
- # * Allowed values: default, name
1693
+ # * Allowed values: default, next_time
1301
1694
  # * Default: default
1302
1695
  #
1303
1696
  # - sort_dir
@@ -1369,7 +1762,7 @@ class Project < Entity
1369
1762
  #
1370
1763
  # - context
1371
1764
  # * Filter services that can be invoked in a particular context
1372
- # * Allowed values: message, call, contact, project
1765
+ # * Allowed values: message, call, ussd_session, row, contact, project
1373
1766
  #
1374
1767
  # - sort
1375
1768
  # * Sort the results based on a field
@@ -1510,6 +1903,274 @@ class Project < Entity
1510
1903
  return @api.do_request("GET", get_base_api_path() + "/users")
1511
1904
  end
1512
1905
 
1906
+ #
1907
+ # Returns information about each airtime transaction.
1908
+ #
1909
+ # Arguments:
1910
+ # - options (Hash)
1911
+ #
1912
+ # - time_created[min] (UNIX timestamp)
1913
+ # * Filter transactions created on or after a particular time
1914
+ #
1915
+ # - time_created[max] (UNIX timestamp)
1916
+ # * Filter transactions created before a particular time
1917
+ #
1918
+ # - contact_id
1919
+ # * Filter transactions sent to a particular contact
1920
+ #
1921
+ # - to_number
1922
+ # * Filter transactions sent to a particular phone number
1923
+ #
1924
+ # - service_id
1925
+ # * Filter transactions sent by a particular service
1926
+ #
1927
+ # - status
1928
+ # * Filter transactions by status
1929
+ # * Allowed values: pending, queued, processing, successful, failed, cancelled,
1930
+ # pending_payment, pending_approval
1931
+ #
1932
+ # - sort_dir
1933
+ # * Sort the results in ascending or descending order
1934
+ # * Allowed values: asc, desc
1935
+ # * Default: asc
1936
+ #
1937
+ # - page_size (int)
1938
+ # * Number of results returned per page (max 500)
1939
+ # * Default: 50
1940
+ #
1941
+ # - offset (int)
1942
+ # * Number of items to skip from beginning of result set
1943
+ # * Default: 0
1944
+ #
1945
+ # Returns:
1946
+ # Telerivet::APICursor (of Telerivet::AirtimeTransaction)
1947
+ #
1948
+ def query_airtime_transactions(options = nil)
1949
+ require_relative 'airtimetransaction'
1950
+ @api.cursor(AirtimeTransaction, get_base_api_path() + "/airtime_transactions", options)
1951
+ end
1952
+
1953
+ #
1954
+ # Gets an airtime transaction by ID
1955
+ #
1956
+ # Arguments:
1957
+ # - id
1958
+ # * ID of the airtime transaction
1959
+ # * Required
1960
+ #
1961
+ # Returns:
1962
+ # Telerivet::AirtimeTransaction
1963
+ #
1964
+ def get_airtime_transaction_by_id(id)
1965
+ require_relative 'airtimetransaction'
1966
+ AirtimeTransaction.new(@api, @api.do_request("GET", get_base_api_path() + "/airtime_transactions/#{id}"))
1967
+ end
1968
+
1969
+ #
1970
+ # Initializes an airtime transaction by ID without making an API request.
1971
+ #
1972
+ # Arguments:
1973
+ # - id
1974
+ # * ID of the airtime transaction
1975
+ # * Required
1976
+ #
1977
+ # Returns:
1978
+ # Telerivet::AirtimeTransaction
1979
+ #
1980
+ def init_airtime_transaction_by_id(id)
1981
+ require_relative 'airtimetransaction'
1982
+ return AirtimeTransaction.new(@api, {'project_id' => self.id, 'id' => id}, false)
1983
+ end
1984
+
1985
+ #
1986
+ # Gets a list of all custom fields defined for contacts in this project. The return value is
1987
+ # an array of objects with the properties 'name', 'variable', 'type', 'order', 'readonly', and
1988
+ # 'lookup_key'. (Fields are automatically created any time a Contact's 'vars' property is
1989
+ # updated.)
1990
+ #
1991
+ # Returns:
1992
+ # array
1993
+ #
1994
+ def get_contact_fields()
1995
+ return @api.do_request("GET", get_base_api_path() + "/contact_fields")
1996
+ end
1997
+
1998
+ #
1999
+ # Allows customizing how a custom contact field is displayed in the Telerivet web app.
2000
+ #
2001
+ # Arguments:
2002
+ # - variable
2003
+ # * The variable name of the field to create or update.
2004
+ # * Required
2005
+ #
2006
+ # - options (Hash)
2007
+ # * Required
2008
+ #
2009
+ # - name (string, max 64 characters)
2010
+ # * Display name for the field
2011
+ #
2012
+ # - type (int)
2013
+ # * Field type
2014
+ # * Allowed values: text, long_text, phone_number, email, url, audio, date, date_time,
2015
+ # number, boolean, select
2016
+ #
2017
+ # - order (int)
2018
+ # * Order in which to display the field
2019
+ #
2020
+ # - items (array)
2021
+ # * Array of up to 100 objects containing `value` and `label` string properties to
2022
+ # show in the dropdown list when type is `select`. Each `value` and `label` must be
2023
+ # between 1 and 256 characters in length.
2024
+ # * Required if type is `select`
2025
+ #
2026
+ # - readonly (bool)
2027
+ # * Set to true to prevent editing the field in the Telerivet web app
2028
+ #
2029
+ # - lookup_key (bool)
2030
+ # * Set to true to allow using this field as a lookup key when importing contacts via
2031
+ # the Telerivet web app
2032
+ #
2033
+ # - show_on_conversation (bool)
2034
+ # * Set to true to show field on Conversations tab
2035
+ #
2036
+ # Returns:
2037
+ # object
2038
+ #
2039
+ def set_contact_field_metadata(variable, options)
2040
+ return @api.do_request("POST", get_base_api_path() + "/contact_fields/#{variable}", options)
2041
+ end
2042
+
2043
+ #
2044
+ # Gets a list of all custom fields defined for messages in this project. The return value is
2045
+ # an array of objects with the properties 'name', 'variable', 'type', 'order', 'readonly', and
2046
+ # 'lookup_key'. (Fields are automatically created any time a Contact's 'vars' property is
2047
+ # updated.)
2048
+ #
2049
+ # Returns:
2050
+ # array
2051
+ #
2052
+ def get_message_fields()
2053
+ return @api.do_request("GET", get_base_api_path() + "/message_fields")
2054
+ end
2055
+
2056
+ #
2057
+ # Allows customizing how a custom message field is displayed in the Telerivet web app.
2058
+ #
2059
+ # Arguments:
2060
+ # - variable
2061
+ # * The variable name of the field to create or update.
2062
+ # * Required
2063
+ #
2064
+ # - options (Hash)
2065
+ # * Required
2066
+ #
2067
+ # - name (string, max 64 characters)
2068
+ # * Display name for the field
2069
+ #
2070
+ # - type (string)
2071
+ # * Field type
2072
+ # * Allowed values: text, long_text, phone_number, email, url, audio, date, date_time,
2073
+ # number, boolean, select
2074
+ #
2075
+ # - order (int)
2076
+ # * Order in which to display the field
2077
+ #
2078
+ # - items (array)
2079
+ # * Array of up to 100 objects containing `value` and `label` string properties to
2080
+ # show in the dropdown list when type is `select`. Each `value` and `label` must be
2081
+ # between 1 and 256 characters in length.
2082
+ # * Required if type is `select`
2083
+ #
2084
+ # - hide_values (bool)
2085
+ # * Set to true to avoid showing values of this field on the Messages page
2086
+ #
2087
+ # Returns:
2088
+ # object
2089
+ #
2090
+ def set_message_field_metadata(variable, options)
2091
+ return @api.do_request("POST", get_base_api_path() + "/message_fields/#{variable}", options)
2092
+ end
2093
+
2094
+ #
2095
+ # Retrieves statistics about messages sent or received via Telerivet. This endpoint returns
2096
+ # historical data that is computed shortly after midnight each day in the project's time zone,
2097
+ # and does not contain message statistics for the current day.
2098
+ #
2099
+ # Arguments:
2100
+ # - options (Hash)
2101
+ # * Required
2102
+ #
2103
+ # - start_date (string)
2104
+ # * Start date of message statistics, in YYYY-MM-DD format
2105
+ # * Required
2106
+ #
2107
+ # - end_date (string)
2108
+ # * End date of message statistics (inclusive), in YYYY-MM-DD format
2109
+ # * Required
2110
+ #
2111
+ # - rollup (string)
2112
+ # * Date interval to group by
2113
+ # * Allowed values: day, week, month, year, all
2114
+ # * Default: day
2115
+ #
2116
+ # - properties (string)
2117
+ # * Comma separated list of properties to group by
2118
+ # * Allowed values: org_id, org_name, org_industry, project_id, project_name, user_id,
2119
+ # user_email, user_name, phone_id, phone_name, phone_type, direction, source, status,
2120
+ # network_code, network_name, message_type, service_id, service_name, simulated, link
2121
+ #
2122
+ # - metrics (string)
2123
+ # * Comma separated list of metrics to return (summed for each distinct value of the
2124
+ # requested properties)
2125
+ # * Allowed values: count, num_parts, duration, price
2126
+ # * Required
2127
+ #
2128
+ # - currency (string)
2129
+ # * Three-letter ISO 4217 currency code used when returning the 'price' field. If the
2130
+ # original price was in a different currency, it will be converted to the requested
2131
+ # currency using the approximate current exchange rate.
2132
+ # * Default: USD
2133
+ #
2134
+ # - filters (Hash)
2135
+ # * Key-value pairs of properties and corresponding values; the returned statistics
2136
+ # will only include messages where the property matches the provided value. Only the
2137
+ # following properties are supported for filters: `user_id`, `phone_id`, `direction`,
2138
+ # `source`, `status`, `service_id`, `simulated`, `message_type`, `network_code`
2139
+ #
2140
+ # Returns:
2141
+ # (associative array)
2142
+ # - intervals (array)
2143
+ # * List of objects representing each date interval containing at least one message
2144
+ # matching the filters.
2145
+ # Each object has the following properties:
2146
+ #
2147
+ # <table>
2148
+ # <tr><td> start_time </td> <td> The UNIX timestamp of the start
2149
+ # of the interval (int) </td></tr>
2150
+ # <tr><td> end_time </td> <td> The UNIX timestamp of the end of
2151
+ # the interval, exclusive (int) </td></tr>
2152
+ # <tr><td> start_date </td> <td> The date of the start of the
2153
+ # interval in YYYY-MM-DD format (string) </td></tr>
2154
+ # <tr><td> end_date </td> <td> The date of the end of the
2155
+ # interval in YYYY-MM-DD format, inclusive (string) </td></tr>
2156
+ # <tr><td> groups </td> <td> Array of groups for each
2157
+ # combination of requested property values matching the filters (array)
2158
+ # <br /><br />
2159
+ # Each object has the following properties:
2160
+ # <table>
2161
+ # <tr><td> properties </td> <td> An object of key/value
2162
+ # pairs for each distinct value of the requested properties (object) </td></tr>
2163
+ # <tr><td> metrics </td> <td> An object of key/value pairs
2164
+ # for each requested metric (object) </td></tr>
2165
+ # </table>
2166
+ # </td></tr>
2167
+ # </table>
2168
+ #
2169
+ def get_message_stats(options)
2170
+ data = @api.do_request("GET", get_base_api_path() + "/message_stats", options)
2171
+ return data
2172
+ end
2173
+
1513
2174
  #
1514
2175
  # Saves any fields or custom variables that have changed for the project.
1515
2176
  #