Iterable SMS OTP Extension

The Iterable SMS OTP extension adds SMS phone number verification to your Digioh campaigns. When a user submits their phone number, Iterable sends a one-time passcode by text. The user enters the code in the campaign to verify their number and complete the submission.

What You'll Learn

• How the OTP verification flow works between Digioh and Iterable

• How to structure your campaign with a phone collection page and a code verification page

• Which metadata keys are required and where to set them

• How to configure max OTP attempts and fallback page behaviour

• Important limitations and troubleshooting tips

What It Does

The Iterable SMS OTP extension connects Digioh with Iterable's SMS API to verify mobile phone numbers as part of a campaign signup flow. Here's the typical user journey:

1. The user enters their phone number on a campaign page and submits the form.

2. Iterable sends a verification code (OTP) to that phone number by text.

3. The campaign advances to a code entry page where the user types the code.

4. When the user submits the code, the extension calls the Iterable API to verify it.

5. On success, the campaign completes the submission and subscribes the user. On failure, the campaign shows an error and the user can retry.

Important: This extension requires an active Iterable account with SMS enabled and a valid Iterable integration ID configured in Digioh.

Campaign Structure Required

Your campaign needs at least two pages:

• Phone collection page — contains a phone number field. When the user submits it, Iterable sends the OTP.

• Code verification page — contains a text field for the OTP code. This page must have the iterable_sms_otp_submit_page_md metadata key set to true.

Warning: The extension uses Before Form Validation to intercept the form submit on the code page.  If the campaign doesn't have a dedicated code page with iterable_sms_otp_submit_page_md = true set, the extension won't intercept verification, and the OTP flow won't work.

How to Enable

This setup uses four required metadata keys across account, campaign, page, and field levels:

• iterable_sms_otp_integration_id → set at the campaign or account level

• iterable_sms_otp_code_md → set at the field level on your code input field

• iterable_sms_otp_submit_page_md → set at the page level on your code verification page

• iterable_sms_otp_error_alt_page_md → set at the page level on your alternate error page

1. Install the Iterable SMS OTP extension from the Extensions catalogue in your account.
   

2. Set your Iterable integration ID at the campaign level or the account level. See the metadata reference below. 

3. Add your phone collection page: add a phone field to the campaign's first page, and confirm the field name matches iterable_sms_otp_phone_md (default: phone).

4. Add your code verification page: create a second page, add a text field for the code, and set iterable_sms_otp_code_md on the field metadata.

5. Mark that same code verification page as the submit page: set iterable_sms_otp_submit_page_md to true on it.

6. Add your alternate error page: create a page for users who exceed the maximum OTP attempts, and set iterable_sms_otp_error_alt_page_md at the page level on it.

7. Optionally, configure the maximum number of attempts and a custom error message. See the metadata reference below.

8. Publish the campaign and test with a real mobile number.

Metadata Reference

Important Notes

• The extension only works if the Iterable integration ID is configured correctly. If it's missing, the extension logs an error and blocks form submission.
  
  

• All four required metadata keys must be set before the extension will function: 
  
  
• iterable_sms_otp_integration_id
•  iterable_sms_otp_code_md
• iterable_sms_otp_submit_page_md
• iterable_sms_otp_error_alt_page_md

• The OTP verification call goes to Digioh's pipeline endpoint, which proxies to the Iterable API. There's no direct client-side Iterable API call.

• In preview mode, the extension logs notifications but doesn't make live API calls. Always test with a published or QA-mode campaign.

• The verification attempt counter (boxapi.verifyCodeAttempt) increments on each failed attempt.Once it reaches the configured maximum, the campaign switches to the alternate error page.

• The iterable_sms_otp_submit_page_md key must be set at the page level, not on an element within the page. 

Questions? Reach out to support@digioh.com, we're happy to help.