Two-Factor Authentication
Combine different channels on the Infobip platform to send one-time PINs to your customers.
The one-time PIN (OTP) number is generated and sent to the user’s mobile phone. The end user receives the OTP and types it into the application to confirm their identity.
This tutorial explains how to use the Infobip authentication solutions for two-factor authentication. We combined Voice and Video, SMS, and Number Lookup.
There are various ways how you can incorporate the two-factor authentication into your business use case to resolve any issues your customers may have. You can use it to:
- Confirm phone numbers
- Update account settings
- Confirm customers have filled out a login form
- Confirm transactions
Setup consists of two parts and requires only two API calls to complete the setup process—application setup and message template setup. Later, you will reuse message template(s) to send out PINs.
Process Workflow
This is how the functioning workflow looks like in action.
Before Getting Started
To get started with this tutorial, you must have an Infobip account. Log in or sign up for an account.
You'll also need the API key and base URL. Read more at Getting Started with Infobip API.
Implementation Steps
This tutorial can be implemented using API. You can use SMS or Voice as a communication channel.
2FA over SMS API
Step 1 - Set Up Application
The application represents your service. It’s good practice to have separate applications for separate services. You may also have separate applications for the same service but different use cases.
For example, 2FA for login may be represented as one application and 2FA for changing the password as another.
Separating these cases in different applications allows you to choose different options and behavior for each use case (like PIN attempts or PIN limits).
Request example:
{
"name":"Test application BASIC",
"configuration": {
"pinAttempts": 10,
"allowMultiplePinVerifications": true,
"pinTimeToLive": "15m",
"verifyPinLimit": "1/3s",
"sendPinPerApplicationLimit": "10000/1d",
"sendPinPerPhoneNumberLimit": "3/1d"
},
"enabled": true
}Read more about the Application Setup process. This covers how to create a new application as well as update it, list all applications, or get application by ID.
Step 2 - Set Up Message Template
This is the message body with the PIN placeholder that is sent to end users.
You may create many message templates per single application and therefore use the same application for different use cases or different languages.
When you create your message template, you will be provided with the message template ID, which you will be using later when sending PINs. By referencing a message template ID, our system generates a PIN, places the PIN in the message template and finally sends the message with the PIN to the end user.
Request example:
{
"pinType":"NUMERIC",
"pinPlaceholder":"",
"messageText":"Your pin is ",
"pinLength":4,
"senderId":"Infobip 2FA",
"language": "en",
"repeatDTMF": "1#",
"speechRate": 1
}Read through the Message Template Setup article for more info on how to create/update a new message template, list all message templates, or get a single message template.
NOTE
To use the 2FA client-side methods, you need to be authorized over API key. Learn how to authorize.
After setting up the application, message template, and authorization process, you can start generating and sending PIN codes via SMS to the provided destination.
Request example:
{
"applicationId": "HJ675435E3A6EA43432G5F37A635KJ8B",
"messageId": "0130269F44AFD07AEBC2FEFEB30398A0",
"from": "InfoSMS",
"to": "41793026727"
}To learn more on how to send PIN over SMS, resend PIN over SMS, send PIN over Voice, resend PIN over Voice, and verify PIN, refer to the Send and Verify PIN article available in the Infobip API reference.
2FA over Voice API
You can also use Infobip Voice and Video solution to send 2FA PIN to your customers. This means the PIN will be read out loud to the end user when they pick up the phone.
Here are the prerequisites that you'll need to complete this scenario:
For more details, refer to the Get Started with Infobip API article.
If you've already set up your account, you can start using the Voice API. Infobip provides API requests for sending voice messages, such as Advanced Voice message - POST /tts/3/advanced.
Refer to Voice API documentation for more details.
Request example:
{
"bulkId": "Example Voice Message",
"messages": [
{
"text": "Hello, your code is 5 8 4 2.",
"language": "en",
"voice": {
"name": "Joanna",
"gender": "female"
},
"from": "38761222333",
"destinations": [
{
"to": "38762555888"
}
]
}
]
}What's great here is that you can customize how you want your messages to be delivered with Voice messages API.
Here are some useful tips and tricks on how to do that!
- Spaces Between Digits
When sending your voice message, write the OTP digits with spaces between digits. e.g., 5 8 4 2. This way each digit is read separately in the audio file as five, eight, four, two.
If you write it without spaces, the message will be read as five thousand eight hundred and forty-two.
- Speech Rate
You can expand the voice message request with some additional features for a better user experience. e.g., adjusting the speech rate. For such cases, use advanced voice messages.
To slow down the speech rate, add the speechRate parameter. Use this to allow your end users enough time to write down the code.
The default value of this field is 1, but the range goes from 0.5 to 2. The lower the number, the slower the speech rate.
{
"bulkId": "Example Voice Message",
"messages": [
{
"text": "Hello, your code is 5 8 4 2.",
"language": "en",
"voice": {
"name": "Joanna",
"gender": "female"
},
"speechRate": 0.7,
"from": "38761222333",
"destinations": [
{
"to": "38762555888"
}
]
}
]
}- Repeat Digits
To allow the end user to repeat their voice message, use response codes ( DTMF feature). If you add this option, the end user can tap the keypad on their phone to repeat the message. Just be sure to define the trigger. Then you probably don't need to slow down the speech rate.
Infobip Voice API has three different request parameters for repeat digits functionality:
repeatDtmf – The trigger. Indicates which digit the end user should press for the message to be repeated.
maxDtmf – Defines the maximum number of digits the end user can enter. If you set it to 1, Infobip only registers one digit, the first one the end user taps.
dtmfTimeout – Defines the number of minutes Infobip will wait for the end user to tap a digit. In our code example, we have set it to 5 seconds, meaning This means the end user has 5 seconds to respond by entering a digit or digits.
Again, test and see what works best for your business use case.
{
"bulkId": "Example Voice Message",
"messages": [
{
"text": "Hello, your code is 5 8 4 2. Please press 5 to repeat.",
"language": "en",
"voice": {
"name": "Joanna",
"gender": "female"
},
"repeatDtmf": "5",
"maxDtmf": 1,
"dtmfTimeout": 5,
"from": "38761222333",
"destinations": [
{
"to": "38762555888"
}
]
}
]
}- Insert Double Commas (,,)
Adding double commas actually means adding a pause which will change the speech pattern to a more natural one. No additional parameters are needed.
When sending OTPs, you can add a double comma after each digit, even before the first digit. This will give the end user more time to prepare and save/write down the PIN.
If one pause is not enough, you can add more double commas. It is important that you test different cases and based on the outcome, use the best possible solution for you.
{
"bulkId": "Example Voice Message",
"messages": [
{
"text": "Hello, your code is,, 5,, 8,, 4,, 2.",
"language": "en",
"voice": {
"name": "Joanna",
"gender": "female"
},
"from": "38761709300",
"destinations": [
{
"to": "38762021106"
}
]
}
]