Skip to content

Commit

Permalink
Add documentation for templates
Browse files Browse the repository at this point in the history
  • Loading branch information
@SMadani
SMadani committed Oct 24, 2024
1 parent 91fb93f commit c9d0578
Show file tree
Hide file tree
Showing 2 changed files with 235 additions and 22 deletions.
7 changes: 4 additions & 3 deletions src/main/java/com/vonage/client/verify2/TemplateFragment.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,9 +47,10 @@ public final class TemplateFragment extends JsonableBaseObject {
/**
* Create a new template fragment. All parameters are required.
*
* @param channel The channel type for the template.
* @param locale The BCP-47 locale for the template.
* @param text The text content of the template.
* @param channel Channel type for the template.
* @param locale BCP-47 locale for the template.
* @param text Text content of the template. There are 4 reserved variables available to use:
* {@code ${code}}, {@code ${brand}}, {@code ${time-limit}} and {@code ${time-limit-unit}}.
*/
public TemplateFragment(FragmentChannel channel, String locale, String text) {
this(text);
Expand Down
250 changes: 231 additions & 19 deletions src/main/java/com/vonage/client/verify2/Verify2Client.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,7 @@ private UUID validateFragmentId(UUID fragmentId) {
* <li><b>409</b>: Concurrent verifications to the same number are not allowed.</li>
* <li><b>422</b>: The value of one or more parameters is invalid.</li>
* <li><b>429</b>: Rate limit hit. Please wait and try again.</li>
* <li><b>500</b>: An error occurred on the Vonage platform.</li>
* </ul>
*/
public VerificationResponse sendVerification(VerificationRequest request) {
Expand All @@ -139,23 +140,24 @@ public VerificationResponse sendVerification(VerificationRequest request) {

/**
* Check a supplied code against an existing verification request. If the code is valid,
* this method will return normally. Otherwise, a {@link VerifyResponseException} will be
* thrown with the following status and reasons:
*
* <ul>
* <li><b>400</b>: The provided code does not match the expected value.</li>
* <li><b>404</b>: Request ID was not found or it has been verified already.</li>
* <li><b>409</b>: The current workflow step does not support a code.</li>
* <li><b>410</b>: An incorrect code has been provided too many times.</li>
* <li><b>429</b>: Rate limit hit. Please wait and try again.</li>
* </ul>
* this method will return normally. Otherwise, a {@link VerifyResponseException} will be thrown.
*
* @param requestId ID of the verify request, obtained from {@link VerificationResponse#getRequestId()}.
* @param code The code supplied by the user.
*
* @return Details of the verification request (if the code matched).
*
* @throws VerifyResponseException If the code was invalid, or any other error.
* @throws VerifyResponseException If the code could not be verified. This could be for the following reasons:
* <ul>
* <li><b>400</b>: The provided code does not match the expected value.</li>
* <li><b>401</b>: Invalid credentials.</li>
* <li><b>402</b>: Low balance.</li>
* <li><b>404</b>: Request ID was not found or it has been verified already.</li>
* <li><b>409</b>: The current workflow step does not support a code.</li>
* <li><b>410</b>: An incorrect code has been provided too many times.</li>
* <li><b>429</b>: Rate limit hit. Please wait and try again.</li>
* <li><b>500</b>: An error occurred on the Vonage platform.</li>
* </ul>
*/
public VerifyCodeResponse checkVerificationCode(UUID requestId, String code) {
return verifyRequest.execute(new VerifyCodeRequestWrapper(
Expand All @@ -171,83 +173,293 @@ public VerifyCodeResponse checkVerificationCode(UUID requestId, String code) {
*
* @param requestId ID of the verify request, obtained from {@link VerificationResponse#getRequestId()}.
*
* @throws VerifyResponseException If the request ID was not found, or it has been verified already.
* @throws VerifyResponseException If the request could not be cancelled. This could be for the following reasons:
* <ul>
* <li><b>401</b>: Invalid credentials.</li>
* <li><b>402</b>: Low balance.</li>
* <li><b>404</b>: Request ID was not found or it has been verified / cancelled already.</li>
* <li><b>500</b>: An error occurred on the Vonage platform.</li>
* </ul>
*/
public void cancelVerification(UUID requestId) {
cancel.execute(validateRequestId(requestId));
}

/**
* Move the request onto the next workflow, if available. If successful, this method will return normally.
* Otherwise, a {@link VerifyResponseException} will be thrown with the following status and reasons:
* Otherwise, a {@link VerifyResponseException} will be thrown.
*
* @param requestId ID of the verify request, obtained from {@link VerificationResponse#getRequestId()}.
*
* @throws VerifyResponseException If the workflow could not be advanced. This could be for the following reasons:
* <ul>
* <li><b>401</b>: Invalid credentials.</li>
* <li><b>404</b>: Request ID was not found or it has been verified already.</li>
* <li><b>409</b>: There are no more events left to trigger.</li>
* <li><b>500</b>: An error occurred on the Vonage platform.</li>
* </ul>
*
* @param requestId ID of the verify request, obtained from {@link VerificationResponse#getRequestId()}.
*
* @throws VerifyResponseException If the request ID was not found.
* @since 8.5.0
*/
public void nextWorkflow(UUID requestId) {
nextWorkflow.execute(validateRequestId(requestId));
}

/**
* Create a new custom template.
*
* @param name Reference name for the template. Must not contain spaces or special characters other than _ and -.
*
* @return The created template metadata.
*
* @throws VerifyResponseException If the template could not be created. This could be for the following reasons:
* <ul>
* <li><b>401</b>: Invalid credentials.</li>
* <li><b>402</b>: Low balance.</li>
* <li><b>403</b>: Template management is not enabled for your account.</li>
* <li><b>409</b>: A template with the same name already exists, or you have more than 9 templates.</li>
* <li><b>429</b>: Rate limit hit. Please wait and try again.</li>
* <li><b>500</b>: An error occurred on the Vonage platform.</li>
* </ul>
*
* @since 8.13.0
*/
public Template createTemplate(String name) {
return createTemplate.execute(new Template(Objects.requireNonNull(name, "Name is required."), null));
}

/**
* List all custom templates associated with the account.
*
* @return The list of templates.
*
* @throws VerifyResponseException If the templates could not be retrieved. This could be for the following reasons:
* <ul>
* <li><b>401</b>: Invalid credentials.</li>
* <li><b>402</b>: Low balance.</li>
* <li><b>403</b>: Template management is not enabled for your account.</li>
* <li><b>429</b>: Rate limit hit. Please wait and try again.</li>
* <li><b>500</b>: An error occurred on the Vonage platform.</li>
* </ul>
*
* @since 8.13.0
*/
public List<Template> listTemplates() {
return listTemplates(1, 1000).getTemplates();
return listTemplates(1, 100).getTemplates();
}

public ListTemplatesResponse listTemplates(Integer page, Integer pageSize) {
// Not useful since there can only be 10 templates at a time.
ListTemplatesResponse listTemplates(Integer page, Integer pageSize) {
return listTemplates.execute(new ListTemplatesRequest(page, pageSize, null));
}

/**
* Retrieve a specific template.
*
* @param templateId ID of the template to retrieve.
*
* @return The template metadata.
*
* @throws VerifyResponseException If the template could not be retrieved. This could be for the following reasons:
* <ul>
* <li><b>401</b>: Invalid credentials.</li>
* <li><b>402</b>: Low balance.</li>
* <li><b>403</b>: Template management is not enabled for your account.</li>
* <li><b>404</b>: Template ID was not found.</li>
* <li><b>429</b>: Rate limit hit. Please wait and try again.</li>
* <li><b>500</b>: An error occurred on the Vonage platform.</li>
* </ul>
*
* @since 8.13.0
*/
public Template getTemplate(UUID templateId) {
return getTemplate.execute(validateTemplateId(templateId));
}

/**
* Update an existing template.
*
* @param templateId ID of the template to update.
* @param name New reference name for the template. Must not contain spaces or special characters.
* @param isDefault Whether this template should be the default for the account.
*
* @return The updated template metadata.
*
* @throws VerifyResponseException If the template could not be updated. This could be for the following reasons:
* <ul>
* <li><b>401</b>: Invalid credentials.</li>
* <li><b>402</b>: Low balance.</li>
* <li><b>403</b>: Template management is not enabled for your account.</li>
* <li><b>404</b>: Template ID was not found.</li>
* <li><b>409</b>: A template with the same name already exists, or you have more than 9 templates.</li>
* <li><b>429</b>: Rate limit hit. Please wait and try again.</li>
* <li><b>500</b>: An error occurred on the Vonage platform.</li>
* </ul>
*
* @since 8.13.0
*/
public Template updateTemplate(UUID templateId, String name, Boolean isDefault) {
Template template = new Template(name, isDefault);
template.id = validateTemplateId(templateId);
return updateTemplate.execute(template);
}

/**
* Delete a template.
*
* @param templateId ID of the template to delete.
*
* @throws VerifyResponseException If the template could not be deleted. This could be for the following reasons:
* <ul>
* <li><b>401</b>: Invalid credentials.</li>
* <li><b>402</b>: Low balance.</li>
* <li><b>403</b>: Template management is not enabled for your account.</li>
* <li><b>404</b>: Template not found.</li>
* <li><b>409</b>: Template contains undeleted fragments or is the default.</li>
* <li><b>429</b>: Rate limit hit. Please wait and try again.</li>
* <li><b>500</b>: An error occurred on the Vonage platform.</li>
* </ul>
*
* @since 8.13.0
*/
public void deleteTemplate(UUID templateId) {
deleteTemplate.execute(validateTemplateId(templateId));
}

/**
* Create a new template fragment.
*
* @param templateId ID of the template to which the fragment belongs.
* @param fragment The fragment to create.
*
* @return The created fragment metadata.
*
* @throws VerifyResponseException If the fragment could not be created. This could be for the following reasons:
* <ul>
* <li><b>401</b>: Invalid credentials.</li>
* <li><b>402</b>: Low balance.</li>
* <li><b>403</b>: Template management is not enabled for your account.</li>
* <li><b>404</b>: Template ID was not found.</li>
* <li><b>409</b>: Fragment for this channel and locale already exists.</li>
* <li><b>422</b>: Invalid parameters (e.g. unsupported locale or invalid text variables).</li>
* <li><b>429</b>: Rate limit hit. Please wait and try again.</li>
* <li><b>500</b>: An error occurred on the Vonage platform.</li>
* </ul>
*
* @since 8.13.0
*/
public TemplateFragment createTemplateFragment(UUID templateId, TemplateFragment fragment) {
Objects.requireNonNull(fragment, "Template fragment is required.").templateId = validateTemplateId(templateId);
return createFragment.execute(fragment);
}

/**
* List all fragments associated with a template.
*
* @param templateId ID of the template to list fragments for.
*
* @return The list of fragments.
*
* @throws VerifyResponseException If the fragments could not be retrieved. This could be for the following reasons:
* <ul>
* <li><b>401</b>: Invalid credentials.</li>
* <li><b>402</b>: Low balance.</li>
* <li><b>403</b>: Template management is not enabled for your account.</li>
* <li><b>404</b>: Template ID was not found.</li>
* <li><b>429</b>: Rate limit hit. Please wait and try again.</li>
* <li><b>500</b>: An error occurred on the Vonage platform.</li>
* </ul>
*
* @since 8.13.0
*/
public List<TemplateFragment> listTemplateFragments(UUID templateId) {
return listTemplateFragments(templateId, 1, 1000).getTemplateFragments();
}

public ListTemplateFragmentsResponse listTemplateFragments(UUID templateId, Integer page, Integer pageSize) {
// Not useful in the general case to expose.
ListTemplateFragmentsResponse listTemplateFragments(UUID templateId, Integer page, Integer pageSize) {
return listFragments.execute(new ListTemplatesRequest(page, pageSize, validateTemplateId(templateId)));
}

/**
* Retrieve a specific fragment.
*
* @param templateId ID of the template to which the fragment belongs.
* @param fragmentId ID of the fragment to retrieve.
*
* @return The fragment metadata.
*
* @throws VerifyResponseException If the fragment could not be retrieved. This could be for the following reasons:
* <ul>
* <li><b>401</b>: Invalid credentials.</li>
* <li><b>402</b>: Low balance.</li>
* <li><b>403</b>: Template management is not enabled for your account.</li>
* <li><b>404</b>: Fragment not found for the provided IDs.</li>
* <li><b>429</b>: Rate limit hit. Please wait and try again.</li>
* <li><b>500</b>: An error occurred on the Vonage platform.</li>
* </ul>
*
* @since 8.13.0
*/
public TemplateFragment getTemplateFragment(UUID templateId, UUID fragmentId) {
TemplateFragment fragment = new TemplateFragment();
fragment.templateId = validateTemplateId(templateId);
fragment.fragmentId = validateFragmentId(fragmentId);
return getFragment.execute(fragment);
}

/**
* Update an existing template fragment.
*
* @param templateId ID of the template to which the fragment belongs.
*
* @param fragmentId ID of the fragment to update.
*
* @param text New text for the fragment.
* There are 4 reserved variables available to use: ${code}, ${brand}, ${time-limit} and ${time-limit-unit}.
*
* @return The updated fragment metadata.
*
* @throws VerifyResponseException If the fragment could not be updated. This could be for the following reasons:
* <ul>
* <li><b>401</b>: Invalid credentials.</li>
* <li><b>402</b>: Low balance.</li>
* <li><b>403</b>: Template management is not enabled for your account.</li>
* <li><b>404</b>: Fragment not found for the provided IDs.</li>
* <li><b>409</b>: Fragment for this channel and locale already exists.</li>
* <li><b>422</b>: Invalid parameters (e.g. unsupported locale or invalid text variables).</li>
* <li><b>429</b>: Rate limit hit. Please wait and try again.</li>
* <li><b>500</b>: An error occurred on the Vonage platform.</li>
* </ul>
*
* @since 8.13.0
*/
public TemplateFragment updateTemplateFragment(UUID templateId, UUID fragmentId, String text) {
TemplateFragment fragment = new TemplateFragment(text);
fragment.templateId = validateTemplateId(templateId);
fragment.fragmentId = validateFragmentId(fragmentId);
return updateFragment.execute(fragment);
}

/**
* Delete a template fragment.
*
* @param templateId ID of the template to which the fragment belongs.
* @param fragmentId ID of the fragment to delete.
*
* @throws VerifyResponseException If the fragment could not be deleted. This could be for the following reasons:
* <ul>
* <li><b>401</b>: Invalid credentials.</li>
* <li><b>402</b>: Low balance.</li>
* <li><b>403</b>: Template management is not enabled for your account.</li>
* <li><b>404</b>: Fragment not found for the provided IDs.</li>
* <li><b>409</b>: Fragment is in use by a template or is the default.</li>
* <li><b>429</b>: Rate limit hit. Please wait and try again.</li>
* <li><b>500</b>: An error occurred on the Vonage platform.</li>
* </ul>
*
* @since 8.13.0
*/
public void deleteTemplateFragment(UUID templateId, UUID fragmentId) {
TemplateFragment fragment = new TemplateFragment();
fragment.templateId = validateTemplateId(templateId);
Expand Down

0 comments on commit c9d0578

Please sign in to comment.