Customizing the error messages shown for Phone Enrollment for New Universal Login

Problem statement

We noticed that when entering phone number during MFA enrollment

  1. if entering a short value such as “000” in the phone number, the message returned is “Phone number is too short”.

  2. if entering a long value over 30 digits for the phone number, the message returned is “Could not start voice call. Please try again later.” or “Could not send SMS. Please try again later.”.

What is the keys for both messages and how to customize them?


Currently, the New Universal Login page performs the following validations before any further checks/hooks are called:

  • The phone number (not including country code) has a minimum length of 4
  • The phone number (including country code) has a maximum length of 30 (and the text field will only accept 30 characters)
  • The phone number provided must only consist of digits

Because long/short digits does not pass this basic validation, the text of the error is not currently customizable.

However, if you are using a custom hook for sending your SMS/Voice calls, you can make use of this error type for numbers that pass the basic validation mentioned above:

cb(new SendPhoneMessageError("YOUR_CUSTOMISED_ERROR_TEXT", err))

This “SendPhoneMessageError” is not currently documented regretfully, but we were able to find this was in the backlog of documentation tasks to be added. You could also make use of the context.language parameter available in hooks to localize this error as well. There is an example of this localization given for pre-user registration hooks you could use as a starting point here: