telerivet 1.3.0 → 1.4.6

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.
@@ -25,6 +25,18 @@ module Telerivet
25
25
  # * Number of rows in the table
26
26
  # * Read-only
27
27
  #
28
+ # - show_add_row (bool)
29
+ # * Whether to allow adding or importing rows via the web app
30
+ # * Updatable via API
31
+ #
32
+ # - show_stats (bool)
33
+ # * Whether to show row statistics in the web app
34
+ # * Updatable via API
35
+ #
36
+ # - show_contact_columns (bool)
37
+ # * Whether to show 'Contact Name' and 'Phone Number' columns in the web app
38
+ # * Updatable via API
39
+ #
28
40
  # - vars (Hash)
29
41
  # * Custom variables stored for this data table
30
42
  # * Updatable via API
@@ -64,7 +76,7 @@ class DataTable < Entity
64
76
  # * Default: asc
65
77
  #
66
78
  # - page_size (int)
67
- # * Number of results returned per page (max 200)
79
+ # * Number of results returned per page (max 500)
68
80
  # * Default: 50
69
81
  #
70
82
  # - offset (int)
@@ -136,8 +148,9 @@ class DataTable < Entity
136
148
 
137
149
  #
138
150
  # Gets a list of all fields (columns) defined for this data table. The return value is an
139
- # array of objects with the properties 'name' and 'variable'. (Fields are automatically
140
- # created any time a DataRow's 'vars' property is updated.)
151
+ # array of objects with the properties 'name', 'variable', 'type', 'order', 'readonly', and
152
+ # 'lookup_key'. (Fields are automatically created any time a DataRow's 'vars' property is
153
+ # updated.)
141
154
  #
142
155
  # Returns:
143
156
  # array
@@ -146,6 +159,37 @@ class DataTable < Entity
146
159
  return @api.do_request("GET", get_base_api_path() + "/fields")
147
160
  end
148
161
 
162
+ #
163
+ # Allows customizing how a field (column) is displayed in the Telerivet web app.
164
+ #
165
+ # Arguments:
166
+ # - variable
167
+ # * The variable name of the field to create or update.
168
+ # * Required
169
+ #
170
+ # - options (Hash)
171
+ #
172
+ # - name (string, max 64 characters)
173
+ # * Display name for the field
174
+ #
175
+ # - type (string)
176
+ # * Field type
177
+ # * Allowed values: text, long_text, number, boolean, email, url, audio, phone_number,
178
+ # date, date_time, groups, route, select, buttons
179
+ #
180
+ # - order (int)
181
+ # * Order in which to display the field
182
+ #
183
+ # - readonly (bool)
184
+ # * Set to true to prevent editing the field in the Telerivet web app
185
+ #
186
+ # Returns:
187
+ # object
188
+ #
189
+ def set_field_metadata(variable, options = nil)
190
+ return @api.do_request("POST", get_base_api_path() + "/fields/#{variable}", options)
191
+ end
192
+
149
193
  #
150
194
  # Returns the number of rows for each value of a given variable. This can be used to get the
151
195
  # total number of responses for each choice in a poll, without making a separate query for
@@ -194,6 +238,30 @@ class DataTable < Entity
194
238
  get('num_rows')
195
239
  end
196
240
 
241
+ def show_add_row
242
+ get('show_add_row')
243
+ end
244
+
245
+ def show_add_row=(value)
246
+ set('show_add_row', value)
247
+ end
248
+
249
+ def show_stats
250
+ get('show_stats')
251
+ end
252
+
253
+ def show_stats=(value)
254
+ set('show_stats', value)
255
+ end
256
+
257
+ def show_contact_columns
258
+ get('show_contact_columns')
259
+ end
260
+
261
+ def show_contact_columns=(value)
262
+ set('show_contact_columns', value)
263
+ end
264
+
197
265
  def project_id
198
266
  get('project_id')
199
267
  end
@@ -103,7 +103,7 @@ class Group < Entity
103
103
  # * Default: asc
104
104
  #
105
105
  # - page_size (int)
106
- # * Number of results returned per page (max 200)
106
+ # * Number of results returned per page (max 500)
107
107
  # * Default: 50
108
108
  #
109
109
  # - offset (int)
@@ -126,7 +126,7 @@ class Group < Entity
126
126
  #
127
127
  # - message_type
128
128
  # * Filter scheduled messages by message_type
129
- # * Allowed values: sms, mms, ussd, call
129
+ # * Allowed values: sms, mms, ussd, call, service
130
130
  #
131
131
  # - time_created (UNIX timestamp)
132
132
  # * Filter scheduled messages by time_created
@@ -148,7 +148,7 @@ class Group < Entity
148
148
  # * Default: asc
149
149
  #
150
150
  # - page_size (int)
151
- # * Number of results returned per page (max 200)
151
+ # * Number of results returned per page (max 500)
152
152
  # * Default: 50
153
153
  #
154
154
  # - offset (int)
@@ -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
42
+ # * Allowed values: sms, mms, ussd, call, 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
@@ -66,7 +67,13 @@ class Label < Entity
66
67
  # * ID of the contact who sent/received the message
67
68
  #
68
69
  # - phone_id
69
- # * ID of the phone that sent/received the message
70
+ # * ID of the phone (basic route) that sent/received the message
71
+ #
72
+ # - broadcast_id
73
+ # * ID of the broadcast containing the message
74
+ #
75
+ # - scheduled_id
76
+ # * ID of the scheduled message that created this message
70
77
  #
71
78
  # - sort
72
79
  # * Sort the results based on a field
@@ -79,7 +86,7 @@ class Label < Entity
79
86
  # * Default: asc
80
87
  #
81
88
  # - page_size (int)
82
- # * Number of results returned per page (max 200)
89
+ # * Number of results returned per page (max 500)
83
90
  # * Default: 50
84
91
  #
85
92
  # - offset (int)
@@ -23,12 +23,12 @@ module Telerivet
23
23
  #
24
24
  # - message_type
25
25
  # * Type of the message
26
- # * Allowed values: sms, mms, ussd, call
26
+ # * Allowed values: sms, mms, ussd, call, 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)
@@ -40,6 +40,10 @@ module Telerivet
40
40
  # and messages that have not yet been sent)
41
41
  # * Read-only
42
42
  #
43
+ # - time_updated (UNIX timestamp)
44
+ # * The time that the message was last updated in Telerivet.
45
+ # * Read-only
46
+ #
43
47
  # - from_number (string)
44
48
  # * The phone number that the message originated from (your number for outgoing
45
49
  # messages, the contact's number for incoming messages)
@@ -71,6 +75,11 @@ module Telerivet
71
75
  # * Custom variables stored for this message
72
76
  # * Updatable via API
73
77
  #
78
+ # - priority (int)
79
+ # * Priority of this message. Telerivet will attempt to send messages with higher
80
+ # priority numbers first. Only defined for outgoing messages.
81
+ # * Read-only
82
+ #
74
83
  # - error_message
75
84
  # * A description of the error encountered while sending a message. (This field is
76
85
  # omitted from the API response if there is no error message.)
@@ -122,13 +131,42 @@ module Telerivet
122
131
  # [getMMSParts](#Message.getMMSParts).
123
132
  # * Read-only
124
133
  #
134
+ # - track_clicks (boolean)
135
+ # * If true, URLs in the message content are short URLs that redirect to a destination
136
+ # URL.
137
+ # * Read-only
138
+ #
139
+ # - short_urls (array)
140
+ # * 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.
147
+ # * Read-only
148
+ #
149
+ # - media (array)
150
+ # * For text messages containing media files, this is an array of objects with the
151
+ # properties `url`, `type` (MIME type), `filename`, and `size` (file size in bytes).
152
+ # Unknown properties are null. This property is undefined for messages that do not
153
+ # contain media files. Note: For files uploaded via the Telerivet web app, the URL is
154
+ # temporary and may not be valid for more than 1 day.
155
+ # * Read-only
156
+ #
157
+ # - time_clicked (UNIX timestamp)
158
+ # * If the message contains any short URLs, this is the first time that a short URL in
159
+ # the message was clicked. This property is undefined for messages that do not contain
160
+ # short URLs.
161
+ # * Read-only
162
+ #
125
163
  # - service_id (string, max 34 characters)
126
164
  # * ID of the service that handled the message (for voice calls, the service defines the
127
165
  # call flow)
128
166
  # * Read-only
129
167
  #
130
168
  # - phone_id (string, max 34 characters)
131
- # * ID of the phone that sent or received the message
169
+ # * ID of the phone (basic route) that sent or received the message
132
170
  # * Read-only
133
171
  #
134
172
  # - contact_id (string, max 34 characters)
@@ -136,13 +174,17 @@ module Telerivet
136
174
  # * Read-only
137
175
  #
138
176
  # - route_id (string, max 34 characters)
139
- # * ID of the route that sent the message (if applicable)
177
+ # * ID of the custom route that sent the message (if applicable)
140
178
  # * Read-only
141
179
  #
142
180
  # - broadcast_id (string, max 34 characters)
143
181
  # * ID of the broadcast that this message is part of (if applicable)
144
182
  # * Read-only
145
183
  #
184
+ # - scheduled_id (string, max 34 characters)
185
+ # * ID of the scheduled message that created this message is part of (if applicable)
186
+ # * Read-only
187
+ #
146
188
  # - user_id (string, max 34 characters)
147
189
  # * ID of the Telerivet user who sent the message (if applicable)
148
190
  # * Read-only
@@ -290,6 +332,10 @@ class Message < Entity
290
332
  get('time_sent')
291
333
  end
292
334
 
335
+ def time_updated
336
+ get('time_updated')
337
+ end
338
+
293
339
  def from_number
294
340
  get('from_number')
295
341
  end
@@ -318,6 +364,10 @@ class Message < Entity
318
364
  get('label_ids')
319
365
  end
320
366
 
367
+ def priority
368
+ get('priority')
369
+ end
370
+
321
371
  def error_message
322
372
  get('error_message')
323
373
  end
@@ -362,6 +412,22 @@ class Message < Entity
362
412
  get('mms_parts')
363
413
  end
364
414
 
415
+ def track_clicks
416
+ get('track_clicks')
417
+ end
418
+
419
+ def short_urls
420
+ get('short_urls')
421
+ end
422
+
423
+ def media
424
+ get('media')
425
+ end
426
+
427
+ def time_clicked
428
+ get('time_clicked')
429
+ end
430
+
365
431
  def service_id
366
432
  get('service_id')
367
433
  end
@@ -382,6 +448,10 @@ class Message < Entity
382
448
  get('broadcast_id')
383
449
  end
384
450
 
451
+ def scheduled_id
452
+ get('scheduled_id')
453
+ end
454
+
385
455
  def user_id
386
456
  get('user_id')
387
457
  end
@@ -120,7 +120,7 @@ class Organization < Entity
120
120
  # * Default: asc
121
121
  #
122
122
  # - page_size (int)
123
- # * Number of results returned per page (max 200)
123
+ # * Number of results returned per page (max 500)
124
124
  # * Default: 50
125
125
  #
126
126
  # - offset (int)
@@ -4,6 +4,10 @@ module Telerivet
4
4
  #
5
5
  # Represents a phone or gateway that you use to send/receive messages via Telerivet.
6
6
  #
7
+ # Basic Routes were formerly referred to as "Phones" within Telerivet. API
8
+ # methods, parameters, and properties related to Basic Routes continue to use the term "Phone"
9
+ # to maintain backwards compatibility.
10
+ #
7
11
  # Fields:
8
12
  #
9
13
  # - id (string, max 34 characters)
@@ -15,11 +19,11 @@ module Telerivet
15
19
  # * Updatable via API
16
20
  #
17
21
  # - phone_number (string)
18
- # * Phone number of the phone
22
+ # * Phone number or sender ID
19
23
  # * Updatable via API
20
24
  #
21
25
  # - phone_type
22
- # * Type of this phone/gateway (e.g. android, twilio, nexmo, etc)
26
+ # * Type of this phone/route (e.g. android, twilio, nexmo, etc)
23
27
  # * Read-only
24
28
  #
25
29
  # - country
@@ -107,11 +111,12 @@ class Phone < Entity
107
111
  #
108
112
  # - message_type
109
113
  # * Filter messages by message_type
110
- # * Allowed values: sms, mms, ussd, call
114
+ # * Allowed values: sms, mms, ussd, call, service
111
115
  #
112
116
  # - source
113
117
  # * Filter messages by source
114
- # * Allowed values: phone, provider, web, api, service, webhook, scheduled
118
+ # * Allowed values: phone, provider, web, api, service, webhook, scheduled,
119
+ # integration
115
120
  #
116
121
  # - starred (bool)
117
122
  # * Filter messages by starred/unstarred
@@ -134,7 +139,13 @@ class Phone < Entity
134
139
  # * ID of the contact who sent/received the message
135
140
  #
136
141
  # - phone_id
137
- # * ID of the phone that sent/received the message
142
+ # * ID of the phone (basic route) that sent/received the message
143
+ #
144
+ # - broadcast_id
145
+ # * ID of the broadcast containing the message
146
+ #
147
+ # - scheduled_id
148
+ # * ID of the scheduled message that created this message
138
149
  #
139
150
  # - sort
140
151
  # * Sort the results based on a field
@@ -147,7 +158,7 @@ class Phone < Entity
147
158
  # * Default: asc
148
159
  #
149
160
  # - page_size (int)
150
- # * Number of results returned per page (max 200)
161
+ # * Number of results returned per page (max 500)
151
162
  # * Default: 50
152
163
  #
153
164
  # - offset (int)
@@ -37,16 +37,17 @@ module Telerivet
37
37
  #
38
38
  class Project < Entity
39
39
  #
40
- # Sends one message (SMS, voice call, or USSD request).
40
+ # Sends one message (SMS, MMS, voice call, or USSD request).
41
41
  #
42
42
  # Arguments:
43
43
  # - options (Hash)
44
44
  # * Required
45
45
  #
46
46
  # - message_type
47
- # * Type of message to send
48
- # * Allowed values: sms, ussd, call
49
- # * Default: sms
47
+ # * Type of message to send. If `text`, will use the default text message type for the
48
+ # selected route.
49
+ # * Allowed values: sms, mms, ussd, call, text
50
+ # * Default: text
50
51
  #
51
52
  # - content
52
53
  # * Content of the message to send (if `message_type` is `call`, the text will be
@@ -63,7 +64,46 @@ class Project < Entity
63
64
  #
64
65
  # - route_id
65
66
  # * ID of the phone or route to send the message from
66
- # * Default: default sender phone ID for your project
67
+ # * Default: default sender route ID for your project
68
+ #
69
+ # - status_url
70
+ # * Webhook callback URL to be notified when message status changes
71
+ #
72
+ # - status_secret
73
+ # * POST parameter 'secret' passed to status_url
74
+ #
75
+ # - is_template (bool)
76
+ # * Set to true to evaluate variables like [[contact.name]] in message content. [(See
77
+ # available variables)](#variables)
78
+ # * Default: false
79
+ #
80
+ # - track_clicks (boolean)
81
+ # * If true, URLs in the message content will automatically be replaced with unique
82
+ # short URLs.
83
+ # * Default: false
84
+ #
85
+ # - media_urls (array)
86
+ # * URLs of media files to attach to the text message. If `message_type` is `sms`,
87
+ # short links to each media URL will be appended to the end of the content (separated
88
+ # by a new line).
89
+ #
90
+ # - label_ids (array)
91
+ # * List of IDs of labels to add to this message
92
+ #
93
+ # - vars (Hash)
94
+ # * Custom variables to store with the message
95
+ #
96
+ # - priority (int)
97
+ # * Priority of the message. Telerivet will attempt to send messages with higher
98
+ # priority numbers first (for example, so you can prioritize an auto-reply ahead of a
99
+ # bulk message to a large group).
100
+ # * Allowed values: 1, 2
101
+ # * Default: 1
102
+ #
103
+ # - simulated (bool)
104
+ # * Set to true to test the Telerivet API without actually sending a message from the
105
+ # route
106
+ # * Default: false
67
107
  #
68
108
  # - service_id
69
109
  # * Service that defines the call flow of the voice call (when `message_type` is
@@ -90,37 +130,6 @@ class Project < Entity
90
130
  # * The name of the text-to-speech voice (when message_type=call)
91
131
  # * Allowed values: female, male
92
132
  # * Default: female
93
- #
94
- # - status_url
95
- # * Webhook callback URL to be notified when message status changes
96
- #
97
- # - status_secret
98
- # * POST parameter 'secret' passed to status_url
99
- #
100
- # - is_template (bool)
101
- # * Set to true to evaluate variables like [[contact.name]] in message content. [(See
102
- # available variables)](#variables)
103
- # * Default: false
104
- #
105
- # - label_ids (array)
106
- # * List of IDs of labels to add to this message
107
- #
108
- # - vars (Hash)
109
- # * Custom variables to store with the message
110
- #
111
- # - priority (int)
112
- # * Priority of the message (currently only observed for Android phones). Telerivet
113
- # will attempt to send messages with higher priority numbers first (for example, so
114
- # you can prioritize an auto-reply ahead of a bulk message to a large group).
115
- # * Default: 1
116
- #
117
- # - user_id
118
- # * ID of the Telerivet user account that sent the message (use
119
- # [project.getUsers](#Project.getUsers) to look up user IDs). In order to use this
120
- # parameter, the user account associated with the API key must have administrator
121
- # permissions for the project, and the user account associated with the user_id
122
- # parameter must have access to the project.
123
- # * Default: User account associated with the API key
124
133
  #
125
134
  # Returns:
126
135
  # Telerivet::Message
@@ -131,17 +140,22 @@ class Project < Entity
131
140
  end
132
141
 
133
142
  #
134
- # Sends an SMS message (optionally with mail-merge templates) or voice call to a group or a
135
- # list of up to 500 phone numbers
143
+ # Sends a text message (optionally with mail-merge templates) or voice call to a group or a
144
+ # list of up to 500 phone numbers.
145
+ #
146
+ # With `message_type`=`service`, invokes an automated service (such as
147
+ # a poll) for a group or list of phone numbers. Any service that can be triggered for a
148
+ # contact can be invoked via this method, whether or not the service actually sends a message.
136
149
  #
137
150
  # Arguments:
138
151
  # - options (Hash)
139
152
  # * Required
140
153
  #
141
154
  # - message_type
142
- # * Type of message to send
143
- # * Allowed values: sms, call
144
- # * Default: sms
155
+ # * Type of message to send. If `text`, will use the default text message type for the
156
+ # selected route.
157
+ # * Allowed values: sms, mms, call, service, text
158
+ # * Default: text
145
159
  #
146
160
  # - content
147
161
  # * Content of the message to send
@@ -157,11 +171,48 @@ class Project < Entity
157
171
  #
158
172
  # - route_id
159
173
  # * ID of the phone or route to send the message from
160
- # * Default: default sender phone ID
174
+ # * Default: default sender route ID
175
+ #
176
+ # - title (string)
177
+ # * Title of the broadcast. If a title is not provided, a title will automatically be
178
+ # generated from the recipient group name or phone numbers.
179
+ #
180
+ # - status_url
181
+ # * Webhook callback URL to be notified when message status changes
182
+ #
183
+ # - status_secret
184
+ # * POST parameter 'secret' passed to status_url
185
+ #
186
+ # - label_ids (array)
187
+ # * Array of IDs of labels to add to all messages sent (maximum 5). Does not apply
188
+ # when `message_type`=`service`, since the labels are determined by the service
189
+ # itself.
190
+ #
191
+ # - exclude_contact_id
192
+ # * Optionally excludes one contact from receiving the message (only when group_id is
193
+ # set)
194
+ #
195
+ # - is_template (bool)
196
+ # * Set to true to evaluate variables like [[contact.name]] in message content [(See
197
+ # available variables)](#variables)
198
+ # * Default: false
199
+ #
200
+ # - track_clicks (boolean)
201
+ # * If true, URLs in the message content will automatically be replaced with unique
202
+ # short URLs.
203
+ # * Default: false
204
+ #
205
+ # - media_urls (array)
206
+ # * URLs of media files to attach to the text message. If `message_type` is `sms`,
207
+ # short links to each URL will be appended to the end of the content (separated by a
208
+ # new line).
209
+ #
210
+ # - vars (Hash)
211
+ # * Custom variables to set for each message
161
212
  #
162
213
  # - service_id
163
- # * Service that defines the call flow of the voice call (when `message_type` is
164
- # `call`)
214
+ # * Service to invoke for each recipient (when `message_type` is `call` or `service`)
215
+ # * Required if message_type is service
165
216
  #
166
217
  # - audio_url
167
218
  # * The URL of an MP3 file to play when the contact answers the call (when
@@ -184,6 +235,51 @@ class Project < Entity
184
235
  # * The name of the text-to-speech voice (when message_type=call)
185
236
  # * Allowed values: female, male
186
237
  # * Default: female
238
+ #
239
+ # Returns:
240
+ # Telerivet::Broadcast
241
+ #
242
+ def send_broadcast(options)
243
+ require_relative 'broadcast'
244
+ Broadcast.new(@api, @api.do_request("POST", get_base_api_path() + "/send_broadcast", options))
245
+ end
246
+
247
+ #
248
+ # Sends up to 100 different messages in a single API request. This method is significantly
249
+ # faster than sending a separate API request for each message.
250
+ #
251
+ # Arguments:
252
+ # - options (Hash)
253
+ # * Required
254
+ #
255
+ # - messages (array)
256
+ # * Array of up to 100 objects with `content` and `to_number` properties. Each object
257
+ # may also contain the optional properties `status_url`, `status_secret`, `vars`,
258
+ # and/or `priority`, which override the parameters of the same name defined below, to
259
+ # allow passing different values for each message.
260
+ # * Required
261
+ #
262
+ # - message_type
263
+ # * Type of message to send. If `text`, will use the default text message type for the
264
+ # selected route.
265
+ # * Allowed values: sms, mms, chat, text
266
+ # * Default: text
267
+ #
268
+ # - route_id
269
+ # * ID of the phone or route to send the messages from
270
+ # * Default: default sender route ID
271
+ #
272
+ # - broadcast_id (string)
273
+ # * ID of an existing broadcast to associate the messages with
274
+ #
275
+ # - broadcast_title (string)
276
+ # * Title of broadcast to create (when `broadcast_id` is not provided).
277
+ # When sending more than 100 messages over multiple API
278
+ # requests, you can associate all messages with the same broadcast by providing a
279
+ # `broadcast_title` parameter in the first
280
+ # API request, then retrieving the `broadcast_id` property
281
+ # from the API response, and passing it as the `broadcast_id` parameter in subsequent
282
+ # API requests.
187
283
  #
188
284
  # - status_url
189
285
  # * Webhook callback URL to be notified when message status changes
@@ -192,19 +288,71 @@ class Project < Entity
192
288
  # * POST parameter 'secret' passed to status_url
193
289
  #
194
290
  # - label_ids (array)
195
- # * Array of IDs of labels to add to all messages sent (maximum 5)
196
- #
197
- # - exclude_contact_id
198
- # * Optionally excludes one contact from receiving the message (only when group_id is
199
- # set)
291
+ # * Array of IDs of labels to add to each message (maximum 5)
200
292
  #
201
293
  # - is_template (bool)
202
294
  # * Set to true to evaluate variables like [[contact.name]] in message content [(See
203
295
  # available variables)](#variables)
204
296
  # * Default: false
205
297
  #
298
+ # - media_urls (array)
299
+ # * URLs of media files to attach to the text message. If `message_type` is `sms`,
300
+ # short links to each media URL will be appended to the end of the content (separated
301
+ # by a new line).
302
+ #
206
303
  # - vars (Hash)
207
- # * Custom variables to set for each message
304
+ # * Custom variables to store with the message
305
+ #
306
+ # - priority (int)
307
+ # * Priority of the message. Telerivet will attempt to send messages with higher
308
+ # priority numbers first (for example, so you can prioritize an auto-reply ahead of a
309
+ # bulk message to a large group).
310
+ # * Allowed values: 1, 2
311
+ # * Default: 1
312
+ #
313
+ # - simulated (bool)
314
+ # * Set to true to test the Telerivet API without actually sending a message from the
315
+ # route
316
+ # * Default: false
317
+ #
318
+ # Returns:
319
+ # (associative array)
320
+ # - messages (array)
321
+ # * List of objects representing each newly created message, with the same length
322
+ # and order as provided in the `messages` parameter in the API request.
323
+ # Each object has the `id` and `status` properties,
324
+ # and may have the property `error_message`.
325
+ # (Other properties of the Message object are
326
+ # omitted in order to reduce the amount of redundant data sent in each API
327
+ # response.)
328
+ #
329
+ # - broadcast_id
330
+ # * ID of broadcast that these messages are associated with, if `broadcast_id` or
331
+ # `broadcast_title` parameter is provided in the API request.
332
+ #
333
+ def send_multi(options)
334
+ data = @api.do_request("POST", get_base_api_path() + "/send_multi", options)
335
+ return data
336
+ end
337
+
338
+ #
339
+ # (Deprecated) Send a message a to group or a list of phone numbers.
340
+ # This method is only needed to maintain backward compatibility with
341
+ # code developed using previous versions of the client library.
342
+ # Use `sendBroadcast` or `sendMulti` instead.
343
+ #
344
+ # Arguments:
345
+ # - options (Hash)
346
+ # * Required
347
+ #
348
+ # - message_type
349
+ #
350
+ # - content
351
+ # * Required
352
+ #
353
+ # - group_id
354
+ #
355
+ # - to_numbers
208
356
  #
209
357
  # Returns:
210
358
  # (associative array)
@@ -212,8 +360,7 @@ class Project < Entity
212
360
  # * Number of messages queued to send
213
361
  #
214
362
  # - broadcast_id
215
- # * ID of broadcast created for this message batch. If `count_queued` is 0 or 1, a
216
- # broadcast will not be created, and the `broadcast_id` property will be null.
363
+ # * ID of broadcast created for this message batch.
217
364
  #
218
365
  def send_messages(options)
219
366
  data = @api.do_request("POST", get_base_api_path() + "/messages/send_batch", options)
@@ -225,13 +372,18 @@ class Project < Entity
225
372
  # messages approximately once every 15 seconds, so it is not possible to control the exact
226
373
  # second at which a scheduled message is sent.
227
374
  #
375
+ # With `message_type`=`service`, schedules an automated service (such
376
+ # as a poll) to be invoked for a group or list of phone numbers. Any service that can be
377
+ # triggered for a contact can be scheduled via this method, whether or not the service
378
+ # actually sends a message.
379
+ #
228
380
  # Arguments:
229
381
  # - options (Hash)
230
382
  # * Required
231
383
  #
232
384
  # - message_type
233
385
  # * Type of message to send
234
- # * Allowed values: sms, ussd, call
386
+ # * Allowed values: sms, ussd, call, service
235
387
  # * Default: sms
236
388
  #
237
389
  # - content
@@ -262,11 +414,11 @@ class Project < Entity
262
414
  #
263
415
  # - route_id
264
416
  # * ID of the phone or route to send the message from
265
- # * Default: default sender phone ID
417
+ # * Default: default sender route ID
266
418
  #
267
419
  # - service_id
268
- # * Service that defines the call flow of the voice call (when `message_type` is
269
- # `call`)
420
+ # * Service to invoke for each recipient (when `message_type` is `call` or `service`)
421
+ # * Required if message_type is service
270
422
  #
271
423
  # - audio_url
272
424
  # * The URL of an MP3 file to play when the contact answers the call (when
@@ -290,12 +442,24 @@ class Project < Entity
290
442
  # * Allowed values: female, male
291
443
  # * Default: female
292
444
  #
445
+ # - track_clicks (boolean)
446
+ # * If true, URLs in the message content will automatically be replaced with unique
447
+ # short URLs.
448
+ # * Default: false
449
+ #
293
450
  # - is_template (bool)
294
451
  # * Set to true to evaluate variables like [[contact.name]] in message content
295
452
  # * Default: false
296
453
  #
454
+ # - media_urls (array)
455
+ # * URLs of media files to attach to the text message. If `message_type` is `sms`,
456
+ # short links to each media URL will be appended to the end of the content (separated
457
+ # by a new line).
458
+ #
297
459
  # - label_ids (array)
298
- # * Array of IDs of labels to add to the sent messages (maximum 5)
460
+ # * Array of IDs of labels to add to the sent messages (maximum 5). Does not apply
461
+ # when `message_type`=`service`, since the labels are determined by the service
462
+ # itself.
299
463
  #
300
464
  # - timezone_id
301
465
  # * TZ database timezone ID; see
@@ -308,6 +472,10 @@ class Project < Entity
308
472
  #
309
473
  # - end_time_offset (int)
310
474
  # * Number of seconds from now until the recurring message will stop
475
+ #
476
+ # - vars (Hash)
477
+ # * Custom variables to set for this scheduled message, which will be copied to each
478
+ # message sent from this scheduled message
311
479
  #
312
480
  # Returns:
313
481
  # Telerivet::ScheduledMessage
@@ -339,7 +507,7 @@ class Project < Entity
339
507
  # * Required
340
508
  #
341
509
  # - phone_id
342
- # * ID of the phone that received the message
510
+ # * ID of the phone (basic route) that received the message
343
511
  # * Required
344
512
  #
345
513
  # - to_number
@@ -423,6 +591,57 @@ class Project < Entity
423
591
  Contact.new(@api, @api.do_request("POST", get_base_api_path() + "/contacts", options))
424
592
  end
425
593
 
594
+ #
595
+ # Creates and/or updates up to 200 contacts in a single API call. When creating or updating a
596
+ # large number of contacts, this method is significantly faster than sending a separate API
597
+ # request for each contact.
598
+ #
599
+ # By default, if the phone number for any contact matches an existing
600
+ # contact, the existing contact will be updated with any information provided. This behavior
601
+ # can be modified by setting the `lookup_key` parameter to look up contacts by another field,
602
+ # including a custom variable.
603
+ #
604
+ # If any contact was not found matching the provided `lookup_key`, a
605
+ # new contact will be created.
606
+ #
607
+ # Arguments:
608
+ # - options (Hash)
609
+ # * Required
610
+ #
611
+ # - contacts (array)
612
+ # * Array of up to 200 objects which may contain the properties `name` (string),
613
+ # `phone_number` (string), `vars` (object), and `send_blocked` (boolean). All
614
+ # properties are optional, unless used as a lookup key; however, either a `name` or
615
+ # `phone_number` property must be provided for new contacts.
616
+ # * Required
617
+ #
618
+ # - lookup_key
619
+ # * The field used to search for a matching contact, or 'none' to always create a new
620
+ # contact. To search by a custom variable, precede the variable name with 'vars.'.
621
+ # * Allowed values: phone_number, id, vars.variable_name, none
622
+ # * Default: phone_number
623
+ #
624
+ # - add_group_ids (array)
625
+ # * ID of one or more groups to add these contacts as members (max 5)
626
+ #
627
+ # - remove_group_ids (array)
628
+ # * ID of one or more groups to remove these contacts as members (max 5)
629
+ #
630
+ # - default_route_id
631
+ # * ID of the route to use by default to send messages to these contacts
632
+ #
633
+ # Returns:
634
+ # (associative array)
635
+ # - contacts (array)
636
+ # * List of objects representing each contact, with the same length and order as
637
+ # provided in the `contacts` parameter in the API request. Each object has a string
638
+ # `id` property.
639
+ #
640
+ def import_contacts(options)
641
+ data = @api.do_request("POST", get_base_api_path() + "/import_contacts", options)
642
+ return data
643
+ end
644
+
426
645
  #
427
646
  # Queries contacts within the given project.
428
647
  #
@@ -491,7 +710,7 @@ class Project < Entity
491
710
  # * Default: asc
492
711
  #
493
712
  # - page_size (int)
494
- # * Number of results returned per page (max 200)
713
+ # * Number of results returned per page (max 500)
495
714
  # * Default: 50
496
715
  #
497
716
  # - offset (int)
@@ -571,7 +790,7 @@ class Project < Entity
571
790
  # * Default: asc
572
791
  #
573
792
  # - page_size (int)
574
- # * Number of results returned per page (max 200)
793
+ # * Number of results returned per page (max 500)
575
794
  # * Default: 50
576
795
  #
577
796
  # - offset (int)
@@ -630,11 +849,12 @@ class Project < Entity
630
849
  #
631
850
  # - message_type
632
851
  # * Filter messages by message_type
633
- # * Allowed values: sms, mms, ussd, call
852
+ # * Allowed values: sms, mms, ussd, call, service
634
853
  #
635
854
  # - source
636
855
  # * Filter messages by source
637
- # * Allowed values: phone, provider, web, api, service, webhook, scheduled
856
+ # * Allowed values: phone, provider, web, api, service, webhook, scheduled,
857
+ # integration
638
858
  #
639
859
  # - starred (bool)
640
860
  # * Filter messages by starred/unstarred
@@ -657,7 +877,13 @@ class Project < Entity
657
877
  # * ID of the contact who sent/received the message
658
878
  #
659
879
  # - phone_id
660
- # * ID of the phone that sent/received the message
880
+ # * ID of the phone (basic route) that sent/received the message
881
+ #
882
+ # - broadcast_id
883
+ # * ID of the broadcast containing the message
884
+ #
885
+ # - scheduled_id
886
+ # * ID of the scheduled message that created this message
661
887
  #
662
888
  # - sort
663
889
  # * Sort the results based on a field
@@ -670,7 +896,7 @@ class Project < Entity
670
896
  # * Default: asc
671
897
  #
672
898
  # - page_size (int)
673
- # * Number of results returned per page (max 200)
899
+ # * Number of results returned per page (max 500)
674
900
  # * Default: 50
675
901
  #
676
902
  # - offset (int)
@@ -746,7 +972,7 @@ class Project < Entity
746
972
  # * Default: asc
747
973
  #
748
974
  # - page_size (int)
749
- # * Number of results returned per page (max 200)
975
+ # * Number of results returned per page (max 500)
750
976
  # * Default: 50
751
977
  #
752
978
  # - offset (int)
@@ -818,7 +1044,7 @@ class Project < Entity
818
1044
  # * Default: asc
819
1045
  #
820
1046
  # - page_size (int)
821
- # * Number of results returned per page (max 200)
1047
+ # * Number of results returned per page (max 500)
822
1048
  # * Default: 50
823
1049
  #
824
1050
  # - offset (int)
@@ -903,7 +1129,7 @@ class Project < Entity
903
1129
  # * Default: asc
904
1130
  #
905
1131
  # - page_size (int)
906
- # * Number of results returned per page (max 200)
1132
+ # * Number of results returned per page (max 500)
907
1133
  # * Default: 50
908
1134
  #
909
1135
  # - offset (int)
@@ -988,7 +1214,7 @@ class Project < Entity
988
1214
  # * Default: asc
989
1215
  #
990
1216
  # - page_size (int)
991
- # * Number of results returned per page (max 200)
1217
+ # * Number of results returned per page (max 500)
992
1218
  # * Default: 50
993
1219
  #
994
1220
  # - offset (int)
@@ -1059,7 +1285,7 @@ class Project < Entity
1059
1285
  #
1060
1286
  # - message_type
1061
1287
  # * Filter scheduled messages by message_type
1062
- # * Allowed values: sms, mms, ussd, call
1288
+ # * Allowed values: sms, mms, ussd, call, service
1063
1289
  #
1064
1290
  # - time_created (UNIX timestamp)
1065
1291
  # * Filter scheduled messages by time_created
@@ -1081,7 +1307,7 @@ class Project < Entity
1081
1307
  # * Default: asc
1082
1308
  #
1083
1309
  # - page_size (int)
1084
- # * Number of results returned per page (max 200)
1310
+ # * Number of results returned per page (max 500)
1085
1311
  # * Default: 50
1086
1312
  #
1087
1313
  # - offset (int)
@@ -1157,7 +1383,7 @@ class Project < Entity
1157
1383
  # * Default: asc
1158
1384
  #
1159
1385
  # - page_size (int)
1160
- # * Number of results returned per page (max 200)
1386
+ # * Number of results returned per page (max 500)
1161
1387
  # * Default: 50
1162
1388
  #
1163
1389
  # - offset (int)
@@ -1205,37 +1431,19 @@ class Project < Entity
1205
1431
  end
1206
1432
 
1207
1433
  #
1208
- # Queries mobile money receipts within the given project.
1434
+ # Queries custom routes that can be used to send messages (not including Phones).
1209
1435
  #
1210
1436
  # Arguments:
1211
1437
  # - options (Hash)
1212
1438
  #
1213
- # - tx_id
1214
- # * Filter receipts by transaction ID
1215
- #
1216
- # - tx_type
1217
- # * Filter receipts by transaction type
1218
- # * Allowed values: receive_money, send_money, pay_bill, deposit, withdrawal,
1219
- # airtime_purchase, balance_inquiry, reversal
1220
- #
1221
- # - tx_time (UNIX timestamp)
1222
- # * Filter receipts by transaction time
1223
- # * Allowed modifiers: tx_time[ne], tx_time[min], tx_time[max]
1224
- #
1225
1439
  # - name
1226
- # * Filter receipts by other person's name
1440
+ # * Filter routes by name
1227
1441
  # * Allowed modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt],
1228
1442
  # name[lt], name[lte]
1229
1443
  #
1230
- # - phone_number
1231
- # * Filter receipts by other person's phone number
1232
- # * Allowed modifiers: phone_number[ne], phone_number[prefix],
1233
- # phone_number[not_prefix], phone_number[gte], phone_number[gt], phone_number[lt],
1234
- # phone_number[lte]
1235
- #
1236
1444
  # - sort
1237
1445
  # * Sort the results based on a field
1238
- # * Allowed values: default
1446
+ # * Allowed values: default, name
1239
1447
  # * Default: default
1240
1448
  #
1241
1449
  # - sort_dir
@@ -1244,7 +1452,7 @@ class Project < Entity
1244
1452
  # * Default: asc
1245
1453
  #
1246
1454
  # - page_size (int)
1247
- # * Number of results returned per page (max 200)
1455
+ # * Number of results returned per page (max 500)
1248
1456
  # * Default: 50
1249
1457
  #
1250
1458
  # - offset (int)
@@ -1252,60 +1460,82 @@ class Project < Entity
1252
1460
  # * Default: 0
1253
1461
  #
1254
1462
  # Returns:
1255
- # Telerivet::APICursor (of Telerivet::MobileMoneyReceipt)
1463
+ # Telerivet::APICursor (of Telerivet::Route)
1256
1464
  #
1257
- def query_receipts(options = nil)
1258
- require_relative 'mobilemoneyreceipt'
1259
- @api.cursor(MobileMoneyReceipt, get_base_api_path() + "/receipts", options)
1465
+ def query_routes(options = nil)
1466
+ require_relative 'route'
1467
+ @api.cursor(Route, get_base_api_path() + "/routes", options)
1260
1468
  end
1261
1469
 
1262
1470
  #
1263
- # Retrieves the mobile money receipt with the given ID.
1471
+ # Gets a custom route by ID
1264
1472
  #
1265
1473
  # Arguments:
1266
1474
  # - id
1267
- # * ID of the mobile money receipt
1475
+ # * ID of the route
1268
1476
  # * Required
1269
1477
  #
1270
1478
  # Returns:
1271
- # Telerivet::MobileMoneyReceipt
1479
+ # Telerivet::Route
1272
1480
  #
1273
- def get_receipt_by_id(id)
1274
- require_relative 'mobilemoneyreceipt'
1275
- MobileMoneyReceipt.new(@api, @api.do_request("GET", get_base_api_path() + "/receipts/#{id}"))
1481
+ def get_route_by_id(id)
1482
+ require_relative 'route'
1483
+ Route.new(@api, @api.do_request("GET", get_base_api_path() + "/routes/#{id}"))
1276
1484
  end
1277
1485
 
1278
1486
  #
1279
- # Initializes the mobile money receipt with the given ID without making an API request.
1487
+ # Initializes a custom route by ID without making an API request.
1280
1488
  #
1281
1489
  # Arguments:
1282
1490
  # - id
1283
- # * ID of the mobile money receipt
1491
+ # * ID of the route
1284
1492
  # * Required
1285
1493
  #
1286
1494
  # Returns:
1287
- # Telerivet::MobileMoneyReceipt
1495
+ # Telerivet::Route
1288
1496
  #
1289
- def init_receipt_by_id(id)
1290
- require_relative 'mobilemoneyreceipt'
1291
- return MobileMoneyReceipt.new(@api, {'project_id' => self.id, 'id' => id}, false)
1497
+ def init_route_by_id(id)
1498
+ require_relative 'route'
1499
+ return Route.new(@api, {'project_id' => self.id, 'id' => id}, false)
1292
1500
  end
1293
1501
 
1294
1502
  #
1295
- # Queries custom routes that can be used to send messages (not including Phones).
1503
+ # Returns an array of user accounts that have access to this project. Each item in the array
1504
+ # is an object containing `id`, `email`, and `name` properties. (The id corresponds to the
1505
+ # `user_id` property of the Message object.)
1506
+ #
1507
+ # Returns:
1508
+ # array
1509
+ #
1510
+ def get_users()
1511
+ return @api.do_request("GET", get_base_api_path() + "/users")
1512
+ end
1513
+
1514
+ #
1515
+ # Returns information about each airtime transaction.
1296
1516
  #
1297
1517
  # Arguments:
1298
1518
  # - options (Hash)
1299
1519
  #
1300
- # - name
1301
- # * Filter routes by name
1302
- # * Allowed modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt],
1303
- # name[lt], name[lte]
1520
+ # - time_created[min] (UNIX timestamp)
1521
+ # * Filter transactions created on or after a particular time
1304
1522
  #
1305
- # - sort
1306
- # * Sort the results based on a field
1307
- # * Allowed values: default, name
1308
- # * Default: default
1523
+ # - time_created[max] (UNIX timestamp)
1524
+ # * Filter transactions created before a particular time
1525
+ #
1526
+ # - contact_id
1527
+ # * Filter transactions sent to a particular contact
1528
+ #
1529
+ # - to_number
1530
+ # * Filter transactions sent to a particular phone number
1531
+ #
1532
+ # - service_id
1533
+ # * Filter transactions sent by a particular service
1534
+ #
1535
+ # - status
1536
+ # * Filter transactions by status
1537
+ # * Allowed values: pending, queued, processing, successful, failed, cancelled,
1538
+ # pending_payment, pending_approval
1309
1539
  #
1310
1540
  # - sort_dir
1311
1541
  # * Sort the results in ascending or descending order
@@ -1313,7 +1543,7 @@ class Project < Entity
1313
1543
  # * Default: asc
1314
1544
  #
1315
1545
  # - page_size (int)
1316
- # * Number of results returned per page (max 200)
1546
+ # * Number of results returned per page (max 500)
1317
1547
  # * Default: 50
1318
1548
  #
1319
1549
  # - offset (int)
@@ -1321,55 +1551,43 @@ class Project < Entity
1321
1551
  # * Default: 0
1322
1552
  #
1323
1553
  # Returns:
1324
- # Telerivet::APICursor (of Telerivet::Route)
1554
+ # Telerivet::APICursor (of Telerivet::AirtimeTransaction)
1325
1555
  #
1326
- def query_routes(options = nil)
1327
- require_relative 'route'
1328
- @api.cursor(Route, get_base_api_path() + "/routes", options)
1556
+ def query_airtime_transactions(options = nil)
1557
+ require_relative 'airtimetransaction'
1558
+ @api.cursor(AirtimeTransaction, get_base_api_path() + "/airtime_transactions", options)
1329
1559
  end
1330
1560
 
1331
1561
  #
1332
- # Gets a custom route by ID
1562
+ # Gets an airtime transaction by ID
1333
1563
  #
1334
1564
  # Arguments:
1335
1565
  # - id
1336
- # * ID of the route
1566
+ # * ID of the airtime transaction
1337
1567
  # * Required
1338
1568
  #
1339
1569
  # Returns:
1340
- # Telerivet::Route
1570
+ # Telerivet::AirtimeTransaction
1341
1571
  #
1342
- def get_route_by_id(id)
1343
- require_relative 'route'
1344
- Route.new(@api, @api.do_request("GET", get_base_api_path() + "/routes/#{id}"))
1572
+ def get_airtime_transaction_by_id(id)
1573
+ require_relative 'airtimetransaction'
1574
+ AirtimeTransaction.new(@api, @api.do_request("GET", get_base_api_path() + "/airtime_transactions/#{id}"))
1345
1575
  end
1346
1576
 
1347
1577
  #
1348
- # Initializes a custom route by ID without making an API request.
1578
+ # Initializes an airtime transaction by ID without making an API request.
1349
1579
  #
1350
1580
  # Arguments:
1351
1581
  # - id
1352
- # * ID of the route
1582
+ # * ID of the airtime transaction
1353
1583
  # * Required
1354
1584
  #
1355
1585
  # Returns:
1356
- # Telerivet::Route
1357
- #
1358
- def init_route_by_id(id)
1359
- require_relative 'route'
1360
- return Route.new(@api, {'project_id' => self.id, 'id' => id}, false)
1361
- end
1362
-
1363
- #
1364
- # Returns an array of user accounts that have access to this project. Each item in the array
1365
- # is an object containing `id`, `email`, and `name` properties. (The id corresponds to the
1366
- # `user_id` property of the Message object.)
1367
- #
1368
- # Returns:
1369
- # array
1586
+ # Telerivet::AirtimeTransaction
1370
1587
  #
1371
- def get_users()
1372
- return @api.do_request("GET", get_base_api_path() + "/users")
1588
+ def init_airtime_transaction_by_id(id)
1589
+ require_relative 'airtimetransaction'
1590
+ return AirtimeTransaction.new(@api, {'project_id' => self.id, 'id' => id}, false)
1373
1591
  end
1374
1592
 
1375
1593
  #