Voice OTP

End users can choose to receive the one-time password (OTP) by receiving a phone call instead of an SMS message. This feature is especially useful in regions that have high levels of undelivered SMS messages. This functionality adds an option to the standard SMS OTP, since phone calls generally are more practical and reliable.

The Voice OTP option is available when after an SMS is sent to the end user. Once users are on the verification screen they will see a link letting them know that if they did not receive the SMS message, they can receive an automated voice call instead. If they choose this option, they will receive a voice call with the OTP.

This method will call the user and a virtual speaker will dictate a one-time password to the user. The user is responsible for hearing the PIN and entering it into the authentication screen. The voice will repeat 2 times.

Technical Design

API Integration

An application directly integrating with the Next Identity API will call the otp/send endpoint with the voice_with_otp attribute in the method parameter. This will create an outbound call to the consumer with an OTP. The application will accept the value of the OTP with the call to the otp/verify endpoint .

Journey:

  1. The application calls the otp/send endpoint with the voice_with_otp parameter. (See Send OTP).
  2. The user receives a call with the OTP and enters that into the OTP field in the screen.
  3. The application calls the otp/verify endpoint (see Verify OTP).
  4. The OTP is successfully verified.

The application can also display the resend link (see mockup for reference).

Sample call:

POST /idp/v1/otp/send

{
    "auth_type": "sms",
    "client_id": "c8462jyq9dnupu2q4j7sfjzvn6c87j92",
    "redirect_uri": "https://localhost.com",
    "user_id": "+15223450987",
    "locale": "en-US",
    "message": "This is your code: %code%",
    "method": "voice_with_otp"
}

Response Codes

All response codes for the otp/send endpoint are documented here.

Journeys Integration

Once the OTP is sent via SMS, if there is an issue receiving, the consumer can choose to receive the OTP via voice or SMS. Refer to the screens below:

545

One-time password login screen.

547

One-time password login screen after OTP is sent.

575

Account activation screen.

Configuration

Languages

The full list of supported languages is found here. These languages are used by passing the ISO locale value into the locale parameter. For example en-US, fr-FR, and others.

For unsupported locales, the Voice OTP functionality will not be available to the user, even if the option is selected.

Below is the list of unsupported locales:

  • ar-SA
  • bg-BG
  • cs-CZ
  • el-GR
  • fi-FI
  • gu-IN
  • hr-HR
  • hu-HU
  • id-ID
  • it-IT
  • kn-IN
  • mr-IN
  • ms-MY
  • sk-SK
  • sl-SI
  • sq-AL
  • sr-RS
  • ta-IN
  • th-TH
  • uk-UA
  • zh-CN
  • zh-HK
  • zh-MO

Message

The voice message received by the customer is:
“Dear Customer, your verification code is ###. Do not share the code with anyone.“
This message is set in the message parameter of the call to the otp/send endpoint.

📘

Note on using default translated message

Alternatively, you can configure the flow to have the default translated message so that the application does not need to pass in the value to the API call. If the translation key in the flow is available, you can omit the ‘message’ parameter.
The Flow translation key is voiceVerificationCodeMessage.

Translations

The 'message' parameter will be translated by the application and passed in. The locale parameter must be set to correspond with the language being sent in.
For example, in German, the message is "Sehr geehrter Kunde, ihre PIN ist %code%".
You must set locale to de-DE for the automated speaker to properly read the message.

Sample call with German voice OTP message

POST /idp/v1/otp/send

{
    "auth_type": "sms",
    "client_id": "c8462jyq9dnupu2q4j7sfjzvn6c87j92",
    "redirect_uri": "https://localhost.com",
    "user_id": "+4930291930276",
    "locale": "de-DE",
    "message": "Sehr geehrter, Kunde Ihre pin ist %code%",
    "method": "voice_with_otp"
}

📘

Note on the message for Voice OTP

Punctuations help with the cadence of the voice of the automated speaker. For example, a period indicates a long pause, while a comma, a short pause.
The PIN will be indicated with %code%.

Non-functional information

Regions

Telesign enables businesses to send and receive text messages from customers in 84 countries around the globe in order to provide support and engage them in the most ubiquitous method available.

Performance and Availability

Telesign Documentation

TeleSign API Availability 99.99%

TeleSign Service Level Metrics TeleSign will use commercially reasonable efforts to maintain a performance at or above the ​​Service Level Metric Target.

Rate limiting

The base rate limit is 50 transactions per second (TPS), but this can be increased, as needed.

Retry Mechanism

The consumer will be able to receive a voice call every 2 minutes and the PIN is valid for 15 minutes.