One-Time Password Field

The One-Time Password field allows you to set up one-time password verification via email in seconds. Here we’ll break down the field itself in detail, if you need steps on how to get started using the field, check out this documentation article first.

Field Settings Reference

The One-Time Password fields ships with most of the stock field settings for Gravity Forms fields like label, descriptions, etc., we’ll be mostly focusing just on our own custom field settings here.

General

Source Field

This is where you’ll select which field on the form will be used to source the value that points the one-time password to the user. This must either be an actual Email field (Advanced Fields > Email) if using Email verification or an actual Phone field (Advanced Fields > Phone) if using SMS verification. If you’re using something simpler and more generic like a single line text field to collect emails/phone numbers, that will not work with the field.

Digits

This setting controls how many digits the generated one-time passwords will be.

By default this is set to 6 characters, there is no specific limit set in the product as to the max amount of digits you can set here but we wouldn’t recommend setting it to be more than 12 from a user experience standpoint. Most one-time passwords you see in the wild are typically 6-12 characters, and something in that range is what your users will likely be expecting to be sent.

Expiration

This setting controls how long the one-time password is valid for.

Your users will have however long you set here between one-time password generation and them verifying that one-time password in the field.

If the expiration is hit, the one-time password is no longer valid and the user will need to start the verification flow over via the field prior to fully submitting the form in a valid state.

When the expiration is hit, the user will get a validation error that the password is invalid, and to try again.

This setting defaults to 10 minutes, but can be set to any minute based value between 1 minute and 300 minutes.

Overall, it is recommended to split the difference between giving your users a decent amount of time to verify the password, especially since emails can take a little bit to reach an inbox, but not so long that the password could be potentially compromised/give a malicious actor time to compromise an email account and get access to the password.

Note: The one-time passwords are formed using the current security salts in your site’s wp-config.php, if those salts are changed between a one-time password being sent to a user and them verifying it, the password will no longer be valid. This is another reason not to set your expiration time to be too high, as many security plugins for WordPress will auto-rotate these security salts automatically, periodically.

Required

This is not one of our own settings, but rather a default Gravity Forms field setting, however, we’re covering it here because it is a setting we’d highly recommend enabling on the One-Time Password field especially if you want each user to complete the one-time password verification.

Also important to note here, if the field is marked as not being a required field, the user can skip the one-time password verification and submit the form. However, if the user engages with the one-time password field, the field and one-time password verification will become a psuedo-required field from that point and a valid, unexpired, one-time password will be required to submit the form in a valid state.

Important General Settings Note: All of the above settings will be put into a disabled state and will appear greyed out once the form has started creating entries with the One-Time Password field added as we can’t allow these settings to be changed on the fly once that has happened.

If you need to adjust these field settings after your initial implementation of the field, you’ll need to replace the existing field with a new version where the settings can be edited (you will also need to update any usage of merge tags elsewhere in your form with the new field ID).

Message

Only visible when using a Phone field as the source field as part of SMS verification.

This allows you to configure the content of the SMS that will be sent to the user.

The merge tag for the One-Time Password field must be used to insert the actual one-time password into the message.

From Phone Number

Only visible when using a Phone field as the source field as part of SMS verification.

This allows you to configure the phone number in your connected Twilio account that will be used to send the SMS.

It is required to chose a number here on principal when configuring the field, but as there is no actual validation in the Gravity Forms editor for field settings, if you don’t set a number here (either on purpose or on accident), the first number in the dropdown will be used by default when sending SMS automatically.

Note: If you’re in test mode, you won’t see any numbers here, the default test number for your Twilio account will be used.

Appearance

We provide a few settings in the Appearance tab of the field settings to allow you to set custom text for a number of different strings that are used with the field.

These settings are especially useful if you want to drop in a quick translations for any of these text strings or would rather use something custom instead of the default.

If any of these are left blank, the default text strings for that specific element will be used.

Note: This is not an exhaustive list of text strings your user may see in the field, if you want to change a text string that isn’t included below, we’d recommend using the Say What? plugin. Be sure to use the cosmicgiant_onetimepassword text domain when setting up your text changes in Say What? so they get applied to the text in the field.

Send Verification Code Button

The text used for the button that is visible when the field first renders that initially sends the one-time password to the user.

Resend Verification Code Button

The text used for the button that resends the code to the user. Visible after the one-time password is first sent.

Verify Code Button

The text used for the button to verify the one-time password. Visible after the one-time password is first sent.

Password Sent Message

The feedback that is served to the user after a one-time password is successfully sent to them.

Validation Success Message

The feedback that is served to the user when a one-time password is successfully validated through the field.

Merge Tag

Usage

The field merge tag for the One-Time Password field has three parameters and generally follows the normal formatting for field merge tags in Gravity Forms: {[descriptor]:[field_id]:[modifier]}

[descriptor]

Optional. A user defined value for readability. By default when using the merge tags widget, this will be the field name.

[field_id]

Required. This is the field ID of the One-Time Password field you want to pull data from using the merge tag. As One-Time Password fields are multi-part fields with multiple hidden sub-inputs that store various data related to password verification, this can be either the base field ID or the base field ID plus the sub-input number, e.g. 6.1, 6.2, or 6.3.

[modifier]

Optional. A flag you can specify to modify the output of the specified merge tag. A list of possible modifiers can be found below.

Examples

Default usage

The default usage of the merge tag is in notifications bound to the “One-Time Password” notification event to output the password that your form submitters will need to enter back into the form to complete verification. This is used by specifying the normal version of the field merge tag with no other modifiers, e.g.

{One-Time Password:1}

If you’d like to output information tied to the field post submission in elements like confirmations and notifications, you have a few options there (note the additional sub inputs specified after the field ID):

Output the password that was verified:

{One-Time Password:1}

Output the time the password was generated:

{One-Time Password:1.2}

Output the time the password was verified:

{One-Time Password:1.3}

Modifiers

:format

When used with one of the time based sub-inputs shown above, this modifier can be used to format the output of the merge tag from a UNIX timestamp to a more human readable format in your desired format.

Example

If you want to output the verification time in a more human-readable format, you can do something like the following:

{One-Time Password (Verification Time):6.3:format:d/m/y\ \a\t\ h\:i\:s}

The above will format the timestamp to display a full representation of the date along with the time.

The :format modifier can be used with most PHP date format character to get things formatted the way you want, you can find a chart of all of the PHP date format characters here.

Note: Gravity Forms core automatically forces lowercase characters on field merge tag modifiers, because of this only lowercase PHP date format characters can be used with this modifier. If an uppercase character is entered in the modifier, it will automatically be forced to lowercase; we have no control over this behavior at the add-on level.

Save and Continue

One-Time Password does work within Save and Continue, however, your users will have to re-verify via the One-Time Password field each time they resume the draft submission from the link generated via Save and Continue.