vonage 7.20.0 → 8.0.0.beta

Sign up to get free protection for your applications and to get access to all the features.
Files changed (79) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +87 -386
  3. data/lib/vonage/applications.rb +4 -12
  4. data/lib/vonage/client.rb +0 -42
  5. data/lib/vonage/client_error.rb +1 -1
  6. data/lib/vonage/config.rb +1 -9
  7. data/lib/vonage/errors.rb +20 -37
  8. data/lib/vonage/gsm7.rb +1 -1
  9. data/lib/vonage/jwt.rb +0 -17
  10. data/lib/vonage/keys.rb +0 -2
  11. data/lib/vonage/logger.rb +3 -5
  12. data/lib/vonage/messaging/channels/viber.rb +1 -8
  13. data/lib/vonage/messaging/channels/whats_app.rb +1 -3
  14. data/lib/vonage/messaging.rb +0 -11
  15. data/lib/vonage/namespace.rb +57 -128
  16. data/lib/vonage/numbers.rb +6 -29
  17. data/lib/vonage/server_error.rb +1 -1
  18. data/lib/vonage/signature.rb +5 -5
  19. data/lib/vonage/sms.rb +20 -20
  20. data/lib/vonage/version.rb +1 -1
  21. data/lib/vonage/video/archives.rb +53 -18
  22. data/lib/vonage/video/list_response.rb +11 -0
  23. data/lib/vonage/video/moderation.rb +22 -7
  24. data/lib/vonage/video/signals.rb +9 -4
  25. data/lib/vonage/video/streams.rb +12 -6
  26. data/lib/vonage/video.rb +13 -31
  27. data/lib/vonage/voice/actions/connect.rb +3 -27
  28. data/lib/vonage/voice/actions/conversation.rb +2 -2
  29. data/lib/vonage/voice/actions/pay.rb +107 -0
  30. data/lib/vonage/voice/actions/talk.rb +2 -11
  31. data/lib/vonage/voice/talk.rb +1 -11
  32. data/lib/vonage/voice.rb +0 -22
  33. data/lib/vonage.rb +0 -2
  34. data/vonage.gemspec +1 -2
  35. metadata +9 -65
  36. data/lib/vonage/api_error.rb +0 -33
  37. data/lib/vonage/meetings/applications.rb +0 -25
  38. data/lib/vonage/meetings/dial_in_numbers/list_response.rb +0 -11
  39. data/lib/vonage/meetings/dial_in_numbers.rb +0 -23
  40. data/lib/vonage/meetings/recordings.rb +0 -36
  41. data/lib/vonage/meetings/rooms/list_response.rb +0 -11
  42. data/lib/vonage/meetings/rooms.rb +0 -155
  43. data/lib/vonage/meetings/sessions/list_response.rb +0 -11
  44. data/lib/vonage/meetings/sessions.rb +0 -28
  45. data/lib/vonage/meetings/themes/list_response.rb +0 -11
  46. data/lib/vonage/meetings/themes.rb +0 -218
  47. data/lib/vonage/meetings.rb +0 -38
  48. data/lib/vonage/number_insight_2.rb +0 -36
  49. data/lib/vonage/proactive_connect/events/list_response.rb +0 -11
  50. data/lib/vonage/proactive_connect/events.rb +0 -68
  51. data/lib/vonage/proactive_connect/item.rb +0 -104
  52. data/lib/vonage/proactive_connect/items/file_response.rb +0 -32
  53. data/lib/vonage/proactive_connect/items/list_response.rb +0 -11
  54. data/lib/vonage/proactive_connect/items.rb +0 -107
  55. data/lib/vonage/proactive_connect/list.rb +0 -168
  56. data/lib/vonage/proactive_connect/lists/list_response.rb +0 -11
  57. data/lib/vonage/proactive_connect/lists.rb +0 -35
  58. data/lib/vonage/proactive_connect.rb +0 -33
  59. data/lib/vonage/subaccounts/balance_transfers/list_response.rb +0 -11
  60. data/lib/vonage/subaccounts/credit_transfers/list_response.rb +0 -11
  61. data/lib/vonage/subaccounts/list_response.rb +0 -15
  62. data/lib/vonage/subaccounts.rb +0 -203
  63. data/lib/vonage/users/list_response.rb +0 -11
  64. data/lib/vonage/users.rb +0 -156
  65. data/lib/vonage/verify2/channels/email.rb +0 -36
  66. data/lib/vonage/verify2/channels/silent_auth.rb +0 -45
  67. data/lib/vonage/verify2/channels/sms.rb +0 -53
  68. data/lib/vonage/verify2/channels/voice.rb +0 -32
  69. data/lib/vonage/verify2/channels/whats_app.rb +0 -38
  70. data/lib/vonage/verify2/channels/whats_app_interactive.rb +0 -32
  71. data/lib/vonage/verify2/start_verification_options.rb +0 -62
  72. data/lib/vonage/verify2/workflow.rb +0 -39
  73. data/lib/vonage/verify2/workflow_builder.rb +0 -25
  74. data/lib/vonage/verify2.rb +0 -93
  75. data/lib/vonage/video/archives/list_response.rb +0 -11
  76. data/lib/vonage/video/broadcasts/list_response.rb +0 -11
  77. data/lib/vonage/video/broadcasts.rb +0 -75
  78. data/lib/vonage/video/sip.rb +0 -48
  79. data/lib/vonage/video/streams/list_response.rb +0 -11
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: e62d74b123d37c098faef65853320aa4860642c2c483da541480a39bdfd4da6d
4
- data.tar.gz: d7717268228d1d05a627164a1355265e071b094ffe4667fdc508afcc15580657
3
+ metadata.gz: e003a6ed3211d3eace84884bf3fb03d21b81f097b13aba079f1906daf95380ff
4
+ data.tar.gz: 956c6921b50df45aaf2f1901b08ccd3cb164c2553b23d8e45570f63dcdf6f960
5
5
  SHA512:
6
- metadata.gz: 38310bd39902127226b3fd48bc0cc675ed958c33b816493926e8379dfc3460f03fedaa0d6a2f080195cca50cc539411ba0082ec26bc77343b8b523b52b2bc946
7
- data.tar.gz: 69de80f50b4d1add808f1a9225c2881dfce85fe0285afce01da9a750f8ceec2e1caba03e1c0c30fa02c3039a6d6b1e1dc050c32fb8884d5873af0579c4b57013
6
+ metadata.gz: 1500879cd4a974009f6510cf12ea15b4ce60a9163f916b8a5e07fe785323c24c6909134163b21e29afc9c251550fd36a9e348c2ff7eac3b18b45f0e4ef7e1be1
7
+ data.tar.gz: fe368d23b897a7f1b2b9ba473c993a351ffb1233ef80304c16ec69ed28692c93e422c7a453f8d0da14b6e038424c215026a945d7ccee9b4a26412e3ecbe5435f
data/README.md CHANGED
@@ -12,20 +12,15 @@ need a Vonage account. Sign up [for free at vonage.com][signup].
12
12
  * [Installation](#installation)
13
13
  * [Usage](#usage)
14
14
  * [Logging](#logging)
15
- * [Exceptions](#exceptions)
16
15
  * [Overriding the default hosts](#overriding-the-default-hosts)
17
16
  * [JWT authentication](#jwt-authentication)
18
17
  * [Webhook signatures](#webhook-signatures)
19
18
  * [Pagination](#pagination)
20
- * [Messages API](#messages-api)
21
- * [Verify API v2](#verify-api-v2)
22
- * [Voice API](#voice-api)
23
- * [NCCO Builder](#ncco-builder)
19
+ * [NCCO Builder](#ncco-builder)
24
20
  * [Documentation](#documentation)
25
- * [Supported APIs](#supported-apis)
26
- * [Other SDKs and Tools](#other-sdks-and-tools)
21
+ * [Frequently Asked Questions](#frequently-asked-questions)
22
+ * [Supported APIs](#supported-apis)
27
23
  * [License](#license)
28
- * [Contribute](#contribute)
29
24
 
30
25
 
31
26
  ## Requirements
@@ -68,47 +63,8 @@ For production you can specify the `VONAGE_API_KEY` and `VONAGE_API_SECRET`
68
63
  environment variables instead of specifying the key and secret explicitly,
69
64
  keeping your credentials out of source control.
70
65
 
71
- For APIs which use a JWT for authentication you'll need to pass `application_id` and `private_key` arguments to the
72
- `Client` constructor as well as or instead of `api_key` and `api_secret`. See [JWT Authentication](#jwt-authentication).
73
66
 
74
- It is also possible to over-ride the default hosts at `Client` instantiation. See [Overriding the default hosts](overriding-the-default-hosts).
75
-
76
- ### JWT authentication
77
-
78
- To call newer endpoints that support JWT authentication such as the Voice API and Messages API you'll
79
- also need to specify the `application_id` and `private_key` options. For example:
80
-
81
- ```ruby
82
- client = Vonage::Client.new(application_id: application_id, private_key: private_key)
83
- ```
84
-
85
- Both arguments should have string values corresponding to the `id` and `private_key`
86
- values returned in a ["create an application"](https://developer.nexmo.com/api/application.v2#createApplication)
87
- response. These credentials can be stored in a datastore, in environment variables,
88
- on disk outside of source control, or in some kind of key management infrastructure.
89
-
90
- By default the library generates a short lived JWT per request. To generate a long lived
91
- JWT for multiple requests or to specify JWT claims directly use `Vonage::JWT.generate` and
92
- the token option. For example:
93
-
94
- ```ruby
95
- claims = {
96
- application_id: application_id,
97
- private_key: 'path/to/private.key',
98
- nbf: 1483315200,
99
- ttl: 800
100
- }
101
-
102
- token = Vonage::JWT.generate(claims)
103
-
104
- client = Vonage::Client.new(token: token)
105
- ```
106
-
107
- Documentation for the Vonage Ruby JWT generator gem can be found at
108
- [https://www.rubydoc.info/github/nexmo/nexmo-jwt-ruby](https://www.rubydoc.info/github/nexmo/nexmo-jwt-ruby).
109
- The documentation outlines all the possible parameters you can use to customize and build a token with.
110
-
111
- ### Logging
67
+ ## Logging
112
68
 
113
69
  Use the logger option to specify a logger. For example:
114
70
 
@@ -124,48 +80,8 @@ By default the library sets the logger to `Rails.logger` if it is defined.
124
80
 
125
81
  To disable logging set the logger to `nil`.
126
82
 
127
- ### Exceptions
128
-
129
- Where exceptions result from an error response from the Vonage API (HTTP responses that aren't ion the range `2xx` or `3xx`), the `Net::HTTPResponse` object will be available as a property of the `Exception` object via a `http_response` getter method (where there is no `Net::HTTPResponse` object associated with the exception, the value of `http_response` will be `nil`).
130
-
131
- You can rescue the the exception to access the `http_response`, as well as use other getters provided for specific parts of the response. For example:
132
-
133
- ```ruby
134
- begin
135
- verification_request = client.verify2.start_verification(
136
- brand: 'Acme',
137
- workflow: [{channel: 'sms', to: '44700000000'}]
138
- )
139
- rescue Vonage::APIError => error
140
- if error.http_response
141
- error.http_response # => #<Net::HTTPUnauthorized 401 Unauthorized readbody=true>
142
- error.http_response_code # => "401"
143
- error.http_response_headers # => {"date"=>["Sun, 24 Sep 2023 11:08:47 GMT"], ...rest of headers}
144
- error.http_response_body # => {"title"=>"Unauthorized", ...rest of body}
145
- end
146
- end
147
- ```
148
-
149
- For certain legacy API products, such as the [SMS API](https://developer.vonage.com/en/messaging/sms/overview), [Verify v1 API](https://developer.vonage.com/en/verify/verify-v1/overview) and [Number Insight v1 API](https://developer.vonage.com/en/number-insight/overview), a `200` response is received even in situations where there is an API-related error. For exceptions raised in these situation, rather than a `Net::HTTPResponse` object, a `Vonage::Response` object will be made available as a property of the exception via a `response` getter method. The properties on this object will depend on the response data provided by the API endpoint. For example:
150
-
151
- ```ruby
152
- begin
153
- sms = client.sms.send(
154
- from: 'Vonage',
155
- to: '44700000000',
156
- text: 'Hello World!'
157
- )
158
- rescue Vonage::Error => error
159
- if error.is_a? Vonage::ServiceError
160
- error.response # => #<Vonage::Response:0x0000555b2e49d4f8>
161
- error.response.messages.first.status # => "4"
162
- error.response.messages.first.error_text # => "Bad Credentials"
163
- error.response.http_response # => #<Net::HTTPOK 200 OK readbody=true>
164
- end
165
- end
166
- ```
167
83
 
168
- ### Overriding the default hosts
84
+ ## Overriding the default hosts
169
85
 
170
86
  To override the default hosts that the SDK uses for HTTP requests, you need to
171
87
  specify the `api_host`, `rest_host` or both in the client configuration. For example:
@@ -180,138 +96,104 @@ client = Vonage::Client.new(
180
96
  By default the hosts are set to `api.nexmo.com` and `rest.nexmo.com`, respectively.
181
97
 
182
98
 
99
+ ## JWT authentication
183
100
 
101
+ To call newer endpoints that support JWT authentication such as the Voice API and Messages API you'll
102
+ also need to specify the `application_id` and `private_key` options. For example:
184
103
 
185
- ### Webhook signatures
186
-
187
- Certain Vonage APIs provide signed [webhooks](https://developer.vonage.com/en/getting-started/concepts/webhooks) as a means of verifying the origin of the webhooks. The exact signing mechanism varies depending on the API.
188
-
189
- #### Signature in Request Body
190
-
191
- The [SMS API](https://developer.vonage.com/en/messaging/sms/overview) signs the webhook request using a hash digest. This is assigned to a `sig` parameter in the request body.
192
-
193
- You can verify the webhook request using the `Vonage::SMS#verify_webhook_sig` method. As well as the **request params** from the received webhook, the method also needs access to the signature secret associated with the Vonage account (available from the [Vonage Dashboard](https://dashboard.nexmo.com/settings)), and the signature method used for signing (e.g. `sha512`), again this is based on thes setting in the Dashboard.
104
+ ```ruby
105
+ client = Vonage::Client.new(application_id: application_id, private_key: private_key)
106
+ ```
194
107
 
195
- There are a few different ways of providing these values to the method:
108
+ Both arguments should have string values corresponding to the `id` and `private_key`
109
+ values returned in a ["create an application"](https://developer.nexmo.com/api/application.v2#createApplication)
110
+ response. These credentials can be stored in a datastore, in environment variables,
111
+ on disk outside of source control, or in some kind of key management infrastructure.
196
112
 
197
- 1. Pass all values to the method invocation.
113
+ By default the library generates a short lived JWT per request. To generate a long lived
114
+ JWT for multiple requests or to specify JWT claims directly use `Vonage::JWT.generate` and
115
+ the token option. For example:
198
116
 
199
117
  ```ruby
200
- client = Vonage::Client.new
118
+ claims = {
119
+ application_id: application_id,
120
+ private_key: 'path/to/private.key',
121
+ nbf: 1483315200,
122
+ ttl: 800
123
+ }
201
124
 
202
- client.sms.verify_webhook_sig(
203
- webhook_params: params,
204
- signature_secret: 'secret',
205
- signature_method: 'sha512'
206
- ) # => returns true if the signature is valid, false otherwise
207
- ```
125
+ token = Vonage::JWT.generate(claims)
208
126
 
209
- 2. Set `signature_secret` and `signature_method` at `Client` instantiation.
127
+ client = Vonage::Client.new(token: token)
128
+ ````
210
129
 
211
- ```ruby
212
- client = Vonage::Client.new(
213
- signature_secret: 'secret',
214
- signature_method: 'sha512'
215
- )
130
+ Documentation for the Vonage Ruby JWT generator gem can be found at
131
+ [https://www.rubydoc.info/github/nexmo/nexmo-jwt-ruby](https://www.rubydoc.info/github/nexmo/nexmo-jwt-ruby).
132
+ The documentation outlines all the possible parameters you can use to customize and build a token with.
216
133
 
217
- client.sms.verify_webhook_sig(webhook_params: params) # => returns true if the signature is valid, false otherwise
218
- ```
134
+ ## Webhook signatures
219
135
 
220
- 3. Set `signature_secret` and `signature_method` on the `Config` object.
136
+ To check webhook signatures you'll also need to specify the `signature_secret` option. For example:
221
137
 
222
138
  ```ruby
223
139
  client = Vonage::Client.new
224
140
  client.config.signature_secret = 'secret'
225
141
  client.config.signature_method = 'sha512'
226
142
 
227
- client.sms.verify_webhook_sig(webhook_params: params) # => returns true if the signature is valid, false otherwise
228
- ```
229
-
230
- 4. Set `signature_secret` and `signature_method` as environment variables named `VONAGE_SIGNATURE_SECRET` and `VONAGE_SIGNATURE_METHOD`
231
-
232
- ```ruby
233
- client = Vonage::Client.new
234
-
235
- client.sms.verify_webhook_sig(webhook_params: params) # => returns true if the signature is valid, false otherwise
236
- ```
237
-
238
- **Note:** Webhook signing for the SMS API is not switched on by default. You'll need to contact support@vonage.com to enable message signing on your account.
239
-
240
- #### Signed JWT in Header
241
-
242
- The [Voice API](https://developer.vonage.com/en/voice/voice-api/overview) and [Messages API](https://developer.vonage.com/en/messages/overview) both include an `Authorization` header in their webhook requests. The value of this header includes a JSON Web Token (JWT) signed using the Signature Secret associated with your Vonage account.
243
-
244
- The `Vonage::Voice` and `Vonage::Messaging` classes both define a `verify_webhook_token` method which can be used to verify the JWT received in the webhook `Authorization` header.
245
-
246
- To verify the JWT, you'll first need to extract it from the `Authorization` header. The header value will look something like the following:
247
-
248
- ```ruby
249
- "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1OTUyN" # remainder of token omitted for brevity
143
+ if client.signature.check(request.GET)
144
+ # valid signature
145
+ else
146
+ # invalid signature
147
+ end
250
148
  ```
251
149
 
252
- Note: we are only interested in the token itself, which comes *after* the word `Bearer` and the space.
150
+ Alternatively you can set the `VONAGE_SIGNATURE_SECRET` environment variable.
253
151
 
254
- Once you have extrated the token, you can pass it to the `verify_webhook_token` method in order to verify it.
152
+ Note: you'll need to contact support@nexmo.com to enable message signing on your account.
255
153
 
256
- The method also needs access to the the method also needs access to the signature secret associated with the Vonage account (available from the [Vonage Dashboard](https://dashboard.nexmo.com/settings)). There are a few different ways of providing this value to the method:
154
+ ## Pagination
257
155
 
258
- 1. Pass all values to the method invocation.
156
+ Vonage APIs paginate list requests. This means that if a collection is requested that is larger than the API default, the API will return the first page of items in the collection. The Ruby SDK provides an `auto_advance` parameter that will traverse through the pages and return all the results in one response object.
259
157
 
260
- ```ruby
261
- client = Vonage::Client.new
158
+ The `auto_advance` parameter is set to a default of `true` for the following APIs:
262
159
 
263
- client.voice.verify_webhook_token(
264
- token: extracted_token,
265
- signature_secret: 'secret'
266
- ) # => returns true if the token is valid, false otherwise
267
- ```
160
+ * [Account API](https://developer.nexmo.com/api/developer/account)
161
+ * [Application API](https://developer.nexmo.com/api/application.v2)
162
+ * [Conversation API](https://developer.nexmo.com/api/conversation)
163
+ * [Voice API](https://developer.nexmo.com/api/voice)
268
164
 
269
- 2. Set `signature_secret` at `Client` instantiation.
165
+ To modify the `auto_advance` behavior you can specify it in your method:
270
166
 
271
167
  ```ruby
272
- client = Vonage::Client.new(
273
- signature_secret: 'secret'
274
- )
275
-
276
- client.voice.verify_webhook_token(token: extracted_token) # => returns true if the token is valid, false otherwise
168
+ client.applications.list(auto_advance: false)
277
169
  ```
278
170
 
279
- 3. Set `signature_secret` on the `Config` object.
171
+ ## NCCO Builder
280
172
 
281
- ```ruby
282
- client = Vonage::Client.new
283
- client.config.signature_secret = 'secret'
284
- client.config.signature_method = 'sha512'
173
+ The Vonage Voice API accepts instructions via JSON objects called NCCOs. Each NCCO can be made up multiple actions that are executed in the order they are written. The Vonage API Developer Portal contains an [NCCO Reference](https://developer.vonage.com/voice/voice-api/ncco-reference) with instructions and information on all the parameters possible.
285
174
 
286
- client.voice.verify_webhook_token(token: extracted_token) # => returns true if the token is valid, false otherwise
287
- ```
175
+ The SDK includes an NCCO builder that you can use to build NCCOs for your Voice API methods.
288
176
 
289
- 4. Set `signature_secret` as an environment variable named `VONAGE_SIGNATURE_SECRET`
177
+ For example, to build `talk` and `input` NCCO actions and then combine them into a single NCCO you would do the following:
290
178
 
291
179
  ```ruby
292
- client = Vonage::Client.new
180
+ talk = Vonage::Voice::Ncco.talk(text: 'Hello World!')
181
+ input = Vonage::Voice::Ncco.input(type: ['dtmf'], dtmf: { bargeIn: true })
182
+ ncco = Vonage::Voice::Ncco.build(talk, input)
293
183
 
294
- client.voice.verify_webhook_token(token: extracted_token) # => returns true if the token is valid, false otherwise
184
+ # => [{:action=>"talk", :text=>"Hello World!"}, {:action=>"input", :type=>["dtmf"], :dtmf=>{:bargeIn=>true}}]
295
185
  ```
296
186
 
297
- ### Pagination
298
-
299
- Vonage APIs paginate list requests. This means that if a collection is requested that is larger than the API default, the API will return the first page of items in the collection. The Ruby SDK provides an `auto_advance` parameter that will traverse through the pages and return all the results in one response object.
300
-
301
- The `auto_advance` parameter is set to a default of `true` for the following APIs:
302
-
303
- * [Account API](https://developer.nexmo.com/api/developer/account)
304
- * [Application API](https://developer.nexmo.com/api/application.v2)
305
- * [Conversation API](https://developer.nexmo.com/api/conversation)
306
- * [Voice API](https://developer.nexmo.com/api/voice)
307
-
308
- To modify the `auto_advance` behavior you can specify it in your method:
187
+ Once you have the constructed NCCO you can then use it in a Voice API request:
309
188
 
310
189
  ```ruby
311
- client.applications.list(auto_advance: false)
190
+ response = client.voice.create({
191
+ to: [{type: 'phone', number: '14843331234'}],
192
+ from: {type: 'phone', number: '14843335555'},
193
+ ncco: ncco
194
+ })
312
195
  ```
313
196
 
314
-
315
197
  ## Messages API
316
198
 
317
199
  The [Vonage Messages API](https://developer.vonage.com/messages/overview) allows you to send messages over a number of different channels, and various message types within each channel. See the Vonage Developer Documentation for a [complete API reference](https://developer.vonage.com/api/messages-olympus) listing all the channel and message type combinations.
@@ -338,210 +220,39 @@ Once the message data is created, you can then send the message.
338
220
  response = client.messaging.send(to: "447700900000", from: "447700900001", **message)
339
221
  ```
340
222
 
341
- ## Verify API v2
342
-
343
- The [Vonage Verify API v2](https://developer.vonage.com/en/verify/verify-v2/overview) allows you to manage 2FA verification workflows over a number of different channels such as SMS, WhatsApp, WhatsApp Interactive, Voice, Email, and Silent Authentication, either individually or in combination with each other. See the Vonage Developer Documentation for a [complete API reference](https://developer.vonage.com/en/api/verify.v2) listing all the channels, verification options, and callback types.
344
-
345
- The Ruby SDK provides two methods for interacting with the Verify v2 API:
346
-
347
- - `Verify2#start_verification`: starts a new verification request. Here you can specify options for the request and the workflow to be used.
348
- - `Verify2#check_code`: for channels where the end-user is sent a one-time code, this method is used to verify the code against the `request_id` of the verification request created by the `start_verification` method.
349
-
350
- ### Creating a Verify2 Object
351
-
352
- ```ruby
353
- verify = client.verify2
354
- ```
355
-
356
- ### Making a verification request
357
-
358
- For simple requests, you may prefer to manually set the value for `workflow` (an array of one or more hashes containing the settings for a particular channel) and any optional params.
359
-
360
- Example with the required `:brand` and `:workflow` arguments:
361
-
362
- ```ruby
363
- verification_request = verify.start_verification(
364
- brand: 'Acme',
365
- workflow: [{channel: 'sms', to: '447000000000'}]
366
- )
367
- ```
368
-
369
- Example with the required `:brand` and `:workflow` arguments, and an optional `code_length`:
370
-
371
- ```ruby
372
- verification_request = verify.start_verification(
373
- brand: 'Acme',
374
- workflow: [{channel: 'sms', to: '447000000000'}],
375
- code_length: 6
376
- )
377
- ```
378
-
379
- For more complex requests (e.g. with mutliple workflow channels or addtional options), or to take advantage of built-in input validation, you can use the `StartVerificationOptions` object and the `Workflow` and various channel objects or the `WorkflowBuilder`:
380
-
381
- #### Create options using StartVerificationOptions object
382
-
383
- ```ruby
384
- opts = verify.start_verification_options(
385
- locale: 'fr-fr',
386
- code_length: 6,
387
- client_ref: 'abc-123'
388
- ).to_h
389
-
390
- verification_request = verify.start_verification(
391
- brand: 'Acme',
392
- workflow: [{channel: 'email', to: 'alice.example.com'}],
393
- **opts
394
- )
395
- ```
396
-
397
- #### Create workflow using Workflow and Channel objects
398
-
399
- ```ruby
400
- # Instantiate a Workflow object
401
- workflow = verify.workflow
402
-
403
- # Add channels to the workflow
404
- workflow << workflow.sms(to: '447000000000')
405
- workflow << workflow.email(to: 'alice.example.com')
406
-
407
- # Channel data is encpsulated in channel objects stored in the Workflow list array
408
- workflow.list
409
- # => [ #<Vonage::Verify2::Channels::SMS:0x0000561474a74778 @channel="sms", @to="447000000000">,
410
- #<Vonage::Verify2::Channels::Email:0x0000561474c51a28 @channel="email", @to="alice.example.com">]
411
-
412
- # To use the list as the value for `:workflow` in a `start_verification` request call,
413
- # the objects must be hashified
414
- workflow_list = workflow.hashified_list
415
- # => [{:channel=>"sms", :to=>"447000000000"}, {:channel=>"email", :to=>"alice.example.com"}]
416
-
417
- verification_request = verify.start_verification(brand: 'Acme', workflow: workflow_list)
418
- ```
419
-
420
- #### Create a workflow using the WorkflowBuilder
421
-
422
- ```ruby
423
- workflow = verify.workflow_builder.build do |builder|
424
- builder.add_voice(to: '447000000001')
425
- builder.add_whatsapp(to: '447000000000')
426
- end
427
-
428
- workflow_list = workflow.hashified_list
429
- # => [{:channel=>"voice", :to=>"447000000001"}, {:channel=>"whatsapp", :to=>"447000000000"}]
430
-
431
- verification_request = verify.start_verification(brand: 'Acme', workflow: workflow_list)
432
- ```
433
-
434
- ### Cancelling a request
435
-
436
- You can cancel in in-progress verification request
437
-
438
- ```ruby
439
- # Get the `request_id` from the Vonage#Response object returned by the `start_verification` method call
440
- request_id = verification_request.request_id
441
-
442
- verify.cancel_verification_request(request_id: request_id)
443
- ```
444
-
445
- ### Checking a code
446
-
447
- ```ruby
448
- # Get the `request_id` from the Vonage#Response object returned by the `start_verification` method call
449
- request_id = verification_request.request_id
450
-
451
- # Get the one-time code via user input
452
- # e.g. from params in a route handler or controller action for a form input
453
- code = params[:code]
454
-
455
- begin
456
- code_check = verify.check_code(request_id: request_id, code: code)
457
- rescue => error
458
- # an invalid code will raise an exception of type Vonage::ClientError
459
- end
460
-
461
- if code_check.http_response.code == '200'
462
- # code is valid
463
- end
464
- ```
465
-
466
- ## Voice API
467
-
468
- The [Vonage Voice API](The [Vonage Verify API v2](https://developer.vonage.com/en/verify/verify-v2/overview) allows you to automate voice interactions by creating calls, streaming audio, playing text to speech, playing DTMF tones, and other actions. See the Vonage Developer Documentation for a [complete API reference](https://developer.vonage.com/en/api/voice) listing all the Voice API capabilities.
469
-
470
- The Ruby SDK provides numerous methods for interacting with the Voice v2 API. Here's an example of using the `create` method to make an outbound text-to-speech call:
471
-
472
- ```ruby
473
- response = client.voice.create(
474
- to: [{
475
- type: 'phone',
476
- number: '447700900000'
477
- }],
478
- from: {
479
- type: 'phone',
480
- number: '447700900001'
481
- },
482
- answer_url: [
483
- 'https://raw.githubusercontent.com/nexmo-community/ncco-examples/gh-pages/text-to-speech.json'
484
- ]
485
- )
486
- ```
487
-
488
- ### NCCO Builder
489
-
490
- The Vonage Voice API accepts instructions via JSON objects called NCCOs. Each NCCO can be made up multiple actions that are executed in the order they are written. The Vonage API Developer Portal contains an [NCCO Reference](https://developer.vonage.com/voice/voice-api/ncco-reference) with instructions and information on all the parameters possible.
491
-
492
- The SDK includes an NCCO builder that you can use to build NCCOs for your Voice API methods.
493
-
494
- For example, to build `talk` and `input` NCCO actions and then combine them into a single NCCO you would do the following:
495
-
496
- ```ruby
497
- talk = Vonage::Voice::Ncco.talk(text: 'Hello World!')
498
- input = Vonage::Voice::Ncco.input(type: ['dtmf'], dtmf: { bargeIn: true })
499
- ncco = Vonage::Voice::Ncco.build(talk, input)
500
-
501
- # => [{:action=>"talk", :text=>"Hello World!"}, {:action=>"input", :type=>["dtmf"], :dtmf=>{:bargeIn=>true}}]
502
- ```
503
-
504
- Once you have the constructed NCCO you can then use it in a Voice API request:
505
-
506
- ```ruby
507
- response = client.voice.create({
508
- to: [{type: 'phone', number: '14843331234'}],
509
- from: {type: 'phone', number: '14843335555'},
510
- ncco: ncco
511
- })
512
- ```
513
-
514
223
  ## Documentation
515
224
 
516
- Vonage Ruby SDK documentation: https://www.rubydoc.info/github/Vonage/vonage-ruby-sdk
225
+ Vonage Ruby documentation: https://www.rubydoc.info/github/Vonage/vonage-ruby-sdk
517
226
 
518
- Vonage Ruby SDK code examples: https://github.com/Vonage/vonage-ruby-code-snippets
227
+ Vonage Ruby code examples: https://github.com/Nexmo/nexmo-ruby-code-snippets
519
228
 
520
229
  Vonage APIs API reference: https://developer.nexmo.com/api
521
230
 
522
- ## Supported APIs
523
-
524
- The following is a list of Vonage APIs for which the Ruby SDK currently provides support:
231
+ ## Frequently Asked Questions
525
232
 
526
- * [Account API](https://developer.vonage.com/en/account/overview)
527
- * [Application API](https://developer.vonage.com/en/application/overview)
528
- * [Meetings API](https://developer.vonage.com/en/meetings/overview)
529
- * [Messages API](https://developer.vonage.com/en/messages/overview)
530
- * [Number Insight API](https://developer.vonage.com/en/number-insight/overview)
531
- * [Numbers API](https://developer.vonage.com/en/numbers/overview)
532
- * [Proactive Connect API](https://developer.vonage.com/en/proactive-connect/overview) *
533
- * [Redact API](https://developer.vonage.com/en/redact/overview)
534
- * [SMS API](https://developer.vonage.com/en/messaging/sms/overview)
535
- * [Subaccounts API](https://developer.vonage.com/en/account/subaccounts/overview)
536
- * [Verify API](https://developer.vonage.com/en/verify/overview)
537
- * [Voice API](https://developer.vonage.com/en/verify/overview)
538
-
539
- \* The Proactive Connect API is partially supported in the SDK. Specifically, the Events, Items, and Lists endpoints are supported.
540
-
541
- ## Other SDKs and Tools
542
-
543
- You can find information about other Vonage SDKs and Tooling on our [Developer Portal](https://developer.vonage.com/en/tools).
233
+ ## Supported APIs
544
234
 
235
+ The following is a list of Vonage APIs and whether the Ruby SDK provides support for them:
236
+
237
+ | API | API Release Status | Supported?
238
+ |----------|:---------:|:-------------:|
239
+ | Account API | General Availability |✅|
240
+ | Alerts API | General Availability |✅|
241
+ | Application API | General Availability |✅|
242
+ | Audit API | Beta |❌|
243
+ | Conversation API | Beta |❌|
244
+ | Dispatch API | Beta |❌|
245
+ | External Accounts API | Beta |❌|
246
+ | Media API | Beta | ❌|
247
+ | Messages API | General Availability |✅|
248
+ | Number Insight API | General Availability |✅|
249
+ | Number Management API | General Availability |✅|
250
+ | Pricing API | General Availability |✅|
251
+ | Redact API | Developer Preview |✅|
252
+ | Reports API | Beta |❌|
253
+ | SMS API | General Availability |✅|
254
+ | Verify API | General Availability |✅|
255
+ | Voice API | General Availability |✅|
545
256
 
546
257
  ## License
547
258
 
@@ -549,13 +260,3 @@ This library is released under the [Apache 2.0 License][license]
549
260
 
550
261
  [signup]: https://dashboard.nexmo.com/sign-up?utm_source=DEV_REL&utm_medium=github&utm_campaign=ruby-client-library
551
262
  [license]: LICENSE.txt
552
-
553
- ## Contribute!
554
-
555
- _We :heart: contributions to this library!_
556
-
557
- It is a good idea to [talk to us](https://developer.vonage.com/community/slack)
558
- first if you plan to add any new functionality.
559
- Otherwise, [bug reports](https://github.com/Vonage/vonage-ruby-sdk/issues),
560
- [bug fixes](https://github.com/Vonage/vonage-ruby-sdk/pulls) and feedback on the
561
- library are always appreciated.
@@ -33,8 +33,6 @@ module Vonage
33
33
  #
34
34
  # response = client.applications.create(params)
35
35
  #
36
- # @param [Hash] params
37
- #
38
36
  # @option params [required, String] :name
39
37
  # Application name.
40
38
  #
@@ -46,9 +44,7 @@ module Vonage
46
44
  # This contains the configuration for each product.
47
45
  # This replaces the application `type` from version 1 of the Application API.
48
46
  #
49
- # @option params [Hash] :privacy
50
- # - **:improve_ai** (Boolean) If set to `true``, Vonage may store and use your content and data for the improvement
51
- # of Vonage's AI based services and technologies.
47
+ # @param [Hash] params
52
48
  #
53
49
  # @return [Response]
54
50
  #
@@ -77,7 +73,7 @@ module Vonage
77
73
  # Set this to `false` to not auto-advance through all the pages in the record
78
74
  # and collect all the data. The default is `true`.
79
75
  # @param [Hash] params
80
- #
76
+ #
81
77
  # @return [ListResponse]
82
78
  #
83
79
  # @see https://developer.nexmo.com/api/application.v2#listApplication
@@ -113,9 +109,6 @@ module Vonage
113
109
  # @example
114
110
  # response = client.applications.update(id, answer_method: 'POST')
115
111
  #
116
- # @param [String] id
117
- # @param [Hash] params
118
- #
119
112
  # @option params [required, String] :name
120
113
  # Application name.
121
114
  #
@@ -127,9 +120,8 @@ module Vonage
127
120
  # This contains the configuration for each product.
128
121
  # This replaces the application `type` from version 1 of the Application API.
129
122
  #
130
- # @option params [Hash] :privacy
131
- # - **:improve_ai** (Boolean) If set to `true``, Vonage may store and use your content and data for the improvement
132
- # of Vonage's AI based services and technologies.
123
+ # @param [String] id
124
+ # @param [Hash] params
133
125
  #
134
126
  # @return [Response]
135
127
  #