feat(verify2): Add template_id support (#612)

Author: dragonmantank

CHANGELOG.md

@@ -5,6 +5,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 # Unreleasd
 - Video: Added post-call transcription options
 - Video: Added connections list calls
+- Verify v2: Added support for `template_id` parameter
 
 # [9.8.0] - 2025-01-29
 - Added deprecation notice for Java 8/1.8 users. Version 9.x will be the final version to support Java 8.

src/main/java/com/vonage/client/verify2/VerificationRequest.java

@@ -40,12 +40,13 @@ public class VerificationRequest implements Jsonable {
 	@JsonProperty("locale") protected final Locale locale;
 	protected final Integer channelTimeout, codeLength;
 	protected final Boolean fraudCheck;
-	protected final String brand, code, clientRef;
+	protected final String brand, code, clientRef, templateId;
 	protected final List<Workflow> workflows;
 
 	VerificationRequest(Builder builder) {
 		locale = builder.locale;
 		clientRef = builder.clientRef;
+		templateId = builder.templateId;
 		fraudCheck = builder.fraudCheck != null && !builder.fraudCheck ? false : null;
 		if ((brand = builder.brand) == null || brand.trim().isEmpty()) {
 			throw new IllegalArgumentException("Brand name is required.");
@@ -158,6 +159,17 @@ public Boolean getFraudCheck() {
 		return fraudCheck;
 	}
 
+	/**
+	 * A custom template ID to use for the verification. This parameter works only when
+	 * the channel is SMS or RCS.
+	 *
+	 * @return The template ID, or {@code null} if not set.
+	 */
+	@JsonProperty("template_id")
+	public String getTemplateId() {
+		return templateId;
+	}
+
 	/**
 	 * Workflows are a sequence of actions that Vonage use to reach the user you wish to verify with a PIN code.
 	 *
@@ -190,7 +202,7 @@ public static Builder builder() {
 
 	public static final class Builder {
 		Boolean fraudCheck;
-		String brand, code, clientRef;
+		String brand, code, clientRef, templateId;
 		Integer timeout, codeLength;
 		Locale locale;
 		final List<Workflow> workflows = new ArrayList<>(1);
@@ -364,6 +376,20 @@ public Builder fraudCheck() {
 			return fraudCheck(false);
 		}
 
+		/**
+		 * (OPTIONAL)
+		 * Set a custom template ID to use for the verification. This parameter works only when
+		 * the channel is SMS or RCS.
+		 *
+		 * @param templateId The template ID to use.
+		 *
+		 * @return This builder.
+		 */
+		public Builder templateId(String templateId) {
+			this.templateId = templateId;
+			return this;
+		}
+
 		/**
 		 * Constructs a VerificationRequest with this builder's properties.
 		 *

src/test/java/com/vonage/client/verify2/VerificationRequestTest.java

@@ -20,6 +20,9 @@
 import com.vonage.client.verify2.VerificationRequest.Builder;
 import static org.junit.jupiter.api.Assertions.*;
 import org.junit.jupiter.api.*;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
 import java.util.Arrays;
 import java.util.Collections;
 import java.util.Locale;
@@ -44,6 +47,39 @@ Builder newBuilder() {
 		return VerificationRequest.builder().brand(BRAND);
 	}
 
+	/**
+	 * Loads a JSON resource file and replaces placeholders with provided values.
+	 * This follows the pattern used in identityinsights tests for better maintainability.
+	 *
+	 * @param filename The resource filename (relative to this test class)
+	 * @param placeholders Variable arguments of key-value pairs (key, value, key, value, ...)
+	 * @return The JSON string with placeholders replaced
+	 * @throws IOException If the resource cannot be loaded
+	 */
+	private String loadJsonResource(String filename, String... placeholders) throws IOException {
+		try (InputStream is = getClass().getResourceAsStream(filename)) {
+			if (is == null) {
+				throw new IOException("Could not find resource: " + filename);
+			}
+			byte[] buffer = new byte[1024];
+			StringBuilder sb = new StringBuilder();
+			int bytesRead;
+			while ((bytesRead = is.read(buffer)) != -1) {
+				sb.append(new String(buffer, 0, bytesRead, StandardCharsets.UTF_8));
+			}
+			String json = sb.toString().trim();
+			
+			// Replace placeholders
+			for (int i = 0; i < placeholders.length; i += 2) {
+				if (i + 1 < placeholders.length) {
+					json = json.replace(placeholders[i], placeholders[i + 1]);
+				}
+			}
+			
+			return json;
+		}
+	}
+
 	Builder newBuilderAllParams() {
 		return newBuilder().codeLength(CODE_LENGTH).clientRef(CLIENT_REF)
 				.channelTimeout(CHANNEL_TIMEOUT).locale(LOCALE).fraudCheck();
@@ -366,6 +402,35 @@ public void testWhatsappWorkflowWithoutSender() {
 		assertEquals(expectedJson, request.toJson());
 	}
 
+	@Test
+	public void testTemplateId() throws Exception {
+		String templateId = "4ed3027d-8762-44a0-aa3f-c393717413a4";
+		
+		// Test with SMS workflow - using JSON resource file
+		String expectedSmsJson = loadJsonResource(
+			"verification-request-with-template-id.json",
+			"TEMPLATE_ID_PLACEHOLDER", templateId
+		);
+		
+		VerificationRequest smsRequest = newBuilder()
+				.addWorkflow(new SmsWorkflow(TO_NUMBER))
+				.templateId(templateId)
+				.build();
+		assertEquals(templateId, smsRequest.getTemplateId());
+		assertEquals(expectedSmsJson, smsRequest.toJson());
+		
+		// Test without template_id - using JSON resource file
+		String expectedJsonWithoutTemplate = loadJsonResource(
+			"verification-request-without-template-id.json"
+		);
+		
+		VerificationRequest requestWithoutTemplate = newBuilder()
+				.addWorkflow(new SmsWorkflow(TO_NUMBER))
+				.build();
+		assertNull(requestWithoutTemplate.getTemplateId());
+		assertEquals(expectedJsonWithoutTemplate, requestWithoutTemplate.toJson());
+	}
+
 	@Test
 	public void triggerJsonProcessingException() {
 		class SelfRefrencing extends VerificationRequest {

src/test/resources/com/vonage/client/verify2/verification-request-with-template-id.json

@@ -0,0 +1 @@
+{"brand":"Vonage","template_id":"TEMPLATE_ID_PLACEHOLDER","workflow":[{"channel":"sms","to":"447700900000"}]}

src/test/resources/com/vonage/client/verify2/verification-request-without-template-id.json

@@ -0,0 +1 @@
+{"brand":"Vonage","workflow":[{"channel":"sms","to":"447700900000"}]}