001/* 002 * Copyright 2020 Vonage 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016package com.vonage.client.verify; 017 018import com.fasterxml.jackson.annotation.JsonValue; 019 020import java.util.Locale; 021 022/** 023 * Describes a Verify request when passed to {@link VerifyEndpoint}. 024 */ 025public class VerifyRequest extends BaseRequest { 026 private LineType type; 027 private String brand; 028 private String from; 029 private Workflow workflow; 030 031 032 033 /** 034 * Constructor. 035 * 036 * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> 037 * format. 038 * @param brand (required) The name of the company or app to be verified for. Must not be longer than 18 039 * characters. 040 * @deprecated this construtor is deprecated use {@link Builder} to contruct a 2FA verify request 041 */ 042 @Deprecated 043 public VerifyRequest(final String number, final String brand) { 044 this(number, brand, null, -1, null, null); 045 } 046 047 /** 048 * Constructor. 049 * 050 * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> 051 * format. 052 * @param brand (required) The name of the company or app you are verifying for. Must not be longer than 18 053 * characters. 054 * @param from (optional The Vonage number to use as the sender for the verification SMS message and calls, in 055 * <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> format. 056 * @deprecated this construtor is deprecated use {@link Builder} to contruct a 2FA verify request 057 */ 058 @Deprecated 059 public VerifyRequest(final String number, final String brand, final String from) { 060 this(number, brand, from, -1, null, null); 061 } 062 063 /** 064 * Constructor. 065 * 066 * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> 067 * format. 068 * @param brand (required) The name of the company or app you are verifying for. Must not be longer than 18 069 * characters. 070 * @param from (optional The Vonage number to use as the sender for the verification SMS message and calls, in 071 * <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> format. 072 * @param length (optional) The length of the verification code to be sent to the user. Must be either 4 or 6. Use 073 * -1 to use the default value. 074 * @param locale (optional) Override the default locale used for verification. By default the locale is determined 075 * from the country code included in {@code number} 076 * @deprecated this construtor is deprecated use {@link Builder} instead 077 */ 078 @Deprecated 079 public VerifyRequest(final String number, final String brand, final String from, final int length, final Locale locale) { 080 this(number, brand, from, length, locale, null); 081 } 082 083 /** 084 * Constructor. 085 * 086 * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> 087 * format. 088 * @param brand (required) The name of the company or app you are verifying for. Must not be longer than 18 089 * characters. 090 * @param from (optional A short alphanumeric string to specify the SenderID for SMS sent by Verify. Depending on 091 * the destination of the phone number you are applying, restrictions may apply. By default, sender_id 092 * is {@code VERIFY}. Must be 11 characters or fewer. 093 * @param length (optional) The length of the verification code to be sent to the user. Must be either 4 or 6. Use 094 * -1 to use the default value. 095 * @param locale (optional) Override the default locale used for verification. By default the locale is determined 096 * from the country code included in {@code number} 097 * @param type (optional) If provided, restrict the verification to the specified network type. Contact 098 * support@nexmo.com to enable this feature. 099 */ 100 @Deprecated 101 public VerifyRequest(final String number, final String brand, final String from, final int length, final Locale locale, final LineType type) { 102 super(number, length, locale); 103 104 this.type = type; 105 this.brand = brand; 106 this.from = from; 107 this.workflow = null; 108 setCountry(null); 109 setPinExpiry(null); 110 setNextEventWait(null); 111 } 112 113 public VerifyRequest(Builder builder) { 114 super(builder.number, builder.length, builder.locale, builder.country, builder.pinExpiry, builder.nextEventWait); 115 brand = builder.brand; 116 from = builder.senderId; 117 type = builder.type; 118 workflow = builder.workflow; 119 } 120 121 /** 122 * @return the name of the company or app to be verified for. 123 */ 124 public String getBrand() { 125 return this.brand; 126 } 127 128 129 /** 130 * @return the type of network the verification will be restricted to. This value has no effect unless it has been 131 * enabled by contacting {@code support@nexmo.com}. 132 */ 133 public LineType getType() { 134 return type; 135 } 136 137 138 /** 139 * @param type the type of network the verification will be restricted to. This value has no effect unless it has been 140 * enabled by contacting {@code support@nexmo.com}. 141 * @deprecated since 5.5.0 use {@link VerifyRequest.Builder} to create a 2FA verification request 142 * @see Builder#type(LineType) 143 */ 144 public void setType(LineType type) { 145 this.type = type; 146 } 147 148 149 /** 150 * @return the short alphanumeric string to specify the SenderID for SMS sent by Verify, or {@code null} if one was 151 * not provided. This value is specified in some {@link BaseRequest} sub-class constructors. 152 * <p> 153 * If this value is {@code null</tt>, the sender_id used will be <tt>VERIFY}. 154 */ 155 public String getFrom() { 156 return from; 157 } 158 159 /** 160 * @param from the short alphanumeric string to specify the SenderID for SMS sent by Verify. 161 * @deprecated since 5.5.0 use {@link VerifyRequest.Builder} to create a 2FA verification request 162 * @see VerifyRequest.Builder#senderId(String) 163 */ 164 public void setFrom(String from) { 165 this.from = from; 166 } 167 168 /** 169 * Types of phone line to be specified for {@link VerifyRequest#type}. This option is not generally available. It will 170 * cause an error to be returned if your account doesn't have access to use this option. 171 */ 172 public enum LineType { 173 ALL, MOBILE, LANDLINE, 174 } 175 176 /** 177 * @return The predefined sequence of SMS and TTS (Text To Speech) actions to use in order to convey the PIN to your 178 * user. 179 */ 180 public Workflow getWorkflow() { 181 return workflow; 182 } 183 184 /** 185 * @param workflow The workflow to use for conveying the PIN to your user. 186 * @deprecated since 5.5.0 use {@link VerifyRequest.Builder} to create a 2FA verification request 187 * @see Builder#workflow(Workflow) 188 */ 189 public void setWorkflow(Workflow workflow) { 190 this.workflow = workflow; 191 } 192 193 /** 194 * Enumeration representing different verification workflows. 195 * <p> 196 * See: https://developer.nexmo.com/verify/guides/workflows-and-events for more details. 197 */ 198 public enum Workflow { 199 /** 200 * The default workflow. 201 */ 202 SMS_TTS_TTS(1), 203 SMS_SMS_TTS(2), 204 TTS_TTS(3), 205 SMS_SMS(4), 206 SMS_TTS(5), 207 SMS(6), 208 TTS(7); 209 210 private final int id; 211 212 Workflow(int id) { 213 this.id = id; 214 } 215 216 @JsonValue 217 public int getId() { 218 return id; 219 } 220 } 221 222 @Override 223 public String toString() { 224 return "VerifyRequest{" + 225 super.toString() + 226 ", type=" + type + 227 ", brand='" + brand + '\'' + 228 ", workflow=" + workflow + 229 '}'; 230 } 231 232 /** 233 * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> 234 * format. 235 * @param brand (required) The name of the company or app to be verified for. Must not be longer than 18 236 * characters. 237 * @return A new Builder to start building. 238 */ 239 public static Builder builder(String number, String brand) { 240 return new Builder(number, brand); 241 } 242 243 /** 244 * Builder to create a Two Factor Authentication request 245 * @since 5.5.0 246 */ 247 public static class Builder { 248 249 private String brand; 250 private String senderId; 251 private LineType type; 252 private Workflow workflow; 253 private String number; 254 private Locale locale; 255 private Integer length; 256 private Integer pinExpiry; 257 private Integer nextEventWait; 258 private String country; 259 260 /** 261 * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> 262 * format. 263 * @param brand (required) The name of the company or app to be verified for. Must not be longer than 18 264 * characters. 265 */ 266 public Builder(String number, String brand) { 267 this.number = number; 268 this.brand = brand; 269 } 270 271 /** 272 * @param senderId the short alphanumeric string to specify the SenderID for SMS sent by Verify. 273 * @return {@link Builder} 274 * 275 */ 276 public Builder senderId(String senderId) { 277 this.senderId = senderId; 278 return this; 279 } 280 281 /** 282 * @param type the type of network the verification will be restricted to. This value has no effect unless it has been 283 * enabled by contacting {@code support@nexmo.com}. 284 * @return {@link Builder} 285 **/ 286 public Builder type(LineType type) { 287 this.type = type; 288 return this; 289 } 290 291 /** 292 * Set the predefined sequence of SMS and TTS (Text To Speech) actions to use in order to convey the PIN to your 293 * user. See https://developer.vonage.com/verify/guides/workflows-and-events 294 * 295 * @param workflow The workflow to use for conveying the PIN to your user. 296 * @return {@link Builder} 297 */ 298 public Builder workflow(Workflow workflow) { 299 this.workflow = workflow; 300 return this; 301 } 302 303 /** 304 * @param locale (optional) Override the default locale used for verification. By default the locale is determined 305 * from the country code included in {@code number} 306 * @return {@link Builder} 307 */ 308 public Builder locale(Locale locale) { 309 this.locale = locale; 310 return this; 311 } 312 313 /** 314 * @param length (optional) The length of the verification code to be sent to the user. Must be either 4 or 6. Use 315 * -1 to use the default value. 316 * @return {@link Builder} 317 */ 318 public Builder length(Integer length) { 319 this.length = length; 320 return this; 321 } 322 323 /** 324 * @param pinExpiry (optional) the PIN validity time from generation, in seconds. Default is 300 seconds 325 * @return {@link Builder} 326 */ 327 public Builder pinExpiry(Integer pinExpiry) { 328 this.pinExpiry = pinExpiry; 329 return this; 330 } 331 332 /** 333 * @param nextEventWait (optional) the wait time between attempts to deliver the PIN. A number between 600-900. 334 * @return {@link Builder} 335 */ 336 public Builder nextEventWait(Integer nextEventWait) { 337 this.nextEventWait = nextEventWait; 338 return this; 339 } 340 341 /** 342 * The country for the destination phone number. 343 * <p> 344 * If you wish to used localised number formats or you are not sure if number is correctly formatted, set this to a 345 * two-character country code. For example, GB, US. Verify will work out the international phone number for you. 346 * </p> 347 * 348 * @param country a String containing a 2-character country code 349 * @return {@link Builder} 350 */ 351 public Builder country(String country) { 352 this.country = country; 353 return this; 354 } 355 356 public VerifyRequest build() { 357 return new VerifyRequest(this); 358 } 359 } 360}