Build your own Phone Verification Service (2024)

In this tutorial you’ll build your own Phone Verification Service using Somleng which can be used in your own applications.

What is Somleng?

Somleng is an Open Source Telco-as-a-Service (TaaS) and Communications-Platform-as-a-Service (CPaaS). It’s mainly used in humanitarian contexts, helping to save lives and improve the lives of children, however it can also be used to handle communications in your own projects!

Why build your own Phone Verification Service?

There are a number of reasons why you might want to build your own Phone Verification Service. Here are some of the most common reasons:

1. Twilio is expensive! Twilio charges $0.05 per successful verification plus their standard fees per channel.
2. You want to bring your communications in-house. Somleng gives you an alternative to other CPaaS products. It’s 100% Open Source and released under the MIT license.

Let’s get into it!

Prerequisites

1. Sign up for a free Somleng carrier account. Note: You can also install Somleng on your local machine, but it’s just easier to try things out using a free carrier account.
2. Verify your email address.
3. Login and setup two factor authentication (2FA).
4. Install Docker on your local machine.

Overview

Below is an overview of the steps required to complete this tutorial:

1. Create a Customer Account.
2. Create a Phone Number.
3. Create a Verification Service.
4. Create a SMS Gateway.
5. Create a SIP Trunk.
6. Run the Somleng SMS Gateway Application.
7. Register your softphone with the SIP Trunk.
8. Start a new Verification Flow.
9. Receive the verification code via the SMS Gateway Application.
10. Resend the verification code via a call.
11. Receive the verification via a call.
12. Complete the Verification Flow.

1. Create a Customer Account.

In this step you create a new customer account (not to be confused with the carrier account you just signed up for) which will generate a set of credentials used to authenticate to the Verify API.

Perform the following steps:

1. Under the Accounts menu, click the icon to create a new account.
2. Give the account a name.
3. Choose a premium TTS voice (such as Polly.Joanna) from the default TTS Voice dropdown. This will be used by your verification service to determine the TTS provider (Basic or Polly) when sending verification codes via phone call.
4. Press Create Account.

2. Create a Phone Number.

In this step you create a new phone number. This number will be used to send out verification codes. One phone number can be used to send out verification codes across multiple customer accounts, so there is no need to assign it to the customer account.

Perform the following steps:

1. Under the Phone Numbers menu, click the icon to create a new phone number.
2. Enter a number. It can be a short-code or a full phone number in E.164 format .
3. Press Create Phone number.

3. Create a Verification Service.

In this step you create a new Verification Service and assign it to the account created in Step 1. A Verification Service is the set of common configurations used to create and check verifications.

Perform the following steps:

1. Under the Verify menu, select Services.
2. Click the icon to create a new verification service.
3. Give your verification service a friendly name. This is the brand name that appears in the body of your verification messages.
4. Assign your verification service to the account you created in Step 1.
5. Press Create Verification service.

See Also

How SMS Verification Works | Syniverse

4. Create a SMS Gateway.

In this step you create a new SMS Gateway which will handle the delivery of verification codes via SMS. You’ll set the SMS Gateway’s default sender to the phone number you created in Step 2.

Note: In this step there is no need to connect the SMS gateway to your customer account. The SMS Gateway will handle the delivery of SMS messages across all of your customer accounts.

Perform the following steps:

1. Under the Messaging menu, select SMS Gateways.
2. Click the icon to create a new SMS gateway.
3. Give your SMS Gateway a name.
4. Select the phone number you created in Step 2 as the Default sender.
5. Press Create SMS gateway.

5. Create a SIP Trunk.

In this step you create a new SIP Trunk which will handle the delivery of verification codes via phone call. You’ll set the SIP Trunk’s default sender to the phone number you created in Step 2.

Note: Similar to the SMS Gateway, there is no need to connect the SIP Trunk to your customer account. The SIP Trunk will handle the delivery of voice calls across all of your customer accounts.

Perform the following steps:

1. Under the Voice menu, select SIP Trunks.
2. Click the icon to create a new SIP trunk.
3. Under Authentication mode, choose Client credentials.
4. Give your SIP Trunk a name.
5. Select the phone number you created in Step 2 as the Default sender.
6. Press Create SIP trunk.

6. Run the Somleng SMS Gateway Application.

In this step you’ll run the Somleng SMS Gateway Application on your local machine. This Application connects to the SMS Gateway you created in Step 4, and allows you to take full control of the SMS delivery process.

For this tutorial we will be running the SMS Gateway Application in dummy mode, but you could also run it in another mode (such as smpp or goip) which will allow it to communicate with your local SMS Gateway infrastructure.

Use the following command to run the Somleng SMS Gateway Application on your local machine. Make sure you replace <replace-me-with-your-device-token> with the SMS gateway device token you created in Step 4.

Note: this step requires that you have Docker already installed. See somleng/somleng-sms-gateway for more info.

$ docker run -p 3210:3210 somleng/sms-gateway somleng-sms-gateway -k <replace-me-with-your-device-token> dummy

After your SMS Gateway Application is running on your local machine you should see the connection status update to Connected. You can also view the connection status on your local machine by visiting http://localhost:3210 .

7. Register your softphone with the SIP Trunk.

In this step you’ll register your softphone with the SIP trunk we created in Step 5. This will allow you to receive verification calls on your local machine. In this tutorial we’re using the Telephone Softphone Application for Mac, but you can use whichever softphone you prefer.

Note: Instead of registering your softphone, you could register a VoIP gateway that you own or manage with the SIP trunk. This would allow you to send real voice calls.

To configure your softphone perform the following steps:

1. Copy the Username, Password and Domain fields from the SIP trunk you created in Step 5.
2. Paste them into the corresponding fields in the account configuration of your softphone.
3. Set the Reregister (or equivalent keep-alive setting) in your softphone to a value of less than 30 seconds. This will cause your softphone to re-register with Somleng at a regular interval to ensure the connection stays alive. Note: In order to enable this setting in the Telephone App you need to disable the account first.

After you have registered your softphone with the SIP trunk you should see the SIP registration status update to Available on your softphone.

The screenshots below show the SIP registration details from the SIP trunk you created in Step 5 and the corresponding fields in account configuration of the SIP phone.

8. Start a new Verification Flow

In this step you start a new Verification Flow using the somleng-node helper library. In reality this code would be part of you or your customer’s application which using your Phone Verification Service.

Note: The somleng-node helper library is just a light-weight wrapper around the twilio-node helper library which enables it to be used with Somleng. This is possible because Somleng’s API is compatible with Twilio’s API. If we don’t yet have an official helper library for your programming language, you should be be able to use the corresponding Twilio helper library with some minimal configuration changes to make it work with Somleng. Alternatively you can connect to Somleng’s API directly by following the API docs.

Run the code below substituting the following:

• Set accountSid and from the account you created in Step 1.
• Set verificationServiceSid from the verification service you created in Step 3.

// Download the helper library from https://github.com/somleng/somleng-node and follow the instructions
// Find your Account SID and Auth Token from the Somleng console
// and set the environment variables.
// const accountSid = process.env.SOMLENG_ACCOUNT_SID;
// const authToken = process.env.SOMLENG_AUTH_TOKEN;
const accountSid = "change-me";
const authToken = "change-me";
const verificationServiceSid = "change-me";
const to = "+15017122661";
const channel = "sms";
const client = require('somleng')(accountSid, authToken);
client.verify.v2.services(verificationServiceSid)
 .verifications
 .create({to: to, channel: channel})
 .then(verification => console.log(verification.sid));

9. Receive the verification code via the SMS Gateway Application.

In this step you will receive the verification code via the SMS Gateway Application running on your local machine.

After running the code in the previous step, check your terminal window which is running the SMS Gateway Application. You should see the verification message appear in the logs.

Note: If you’re running the SMS Gateway Application in dummy mode, a real SMS will not be sent to the recipients phone.

10. Resend the verification code via a call.

In this step you resend the verification code via a call.

Re-run the code in Step 8, but this time update the channel to callas shown below. Remember to also set the accountSid and verificationServiceSid like you did in Step 8, if you are using the example below.

// Download the helper library from https://github.com/somleng/somleng-node and follow the instructions
// Find your Account SID and Auth Token from the Somleng console
// and set the environment variables.
// const accountSid = process.env.SOMLENG_ACCOUNT_SID;
// const authToken = process.env.SOMLENG_AUTH_TOKEN;
const accountSid = "change-me";
const authToken = "change-me";
const verificationServiceSid = "change-me";
const to = "+15017122661";
const channel = "call";
const client = require('somleng')(accountSid, authToken);
client.verify.v2.services(verificationServiceSid)
 .verifications
 .create({to: to, channel: channel})
 .then(verification => console.log(verification.sid));

11. Receive the verification via a call.

In this step you will receive the verification code via a call.

After running the code in the previous step, you should receive a call to the softphone you configured in Step 7. Answer the call to hear the verification code.

Note: If you don’t receive a phone call, check the verification logs in the Dashboard. If you see the call failed, try restarting your softphone and try again. The logs can be found under by clicking on Verifications under the Verify menu.

12. Complete the flow by confirming the verification code.

In this step you complete the flow by confirming the verification code.

Run the code below, substituting the following:

1. Set accountSid and from the account you created in Step 1.
2. Set verificationServiceSid from the verification service you created in Step 3.
3. Set verificationCode from the verification code received via SMS or call in Step 9 or Step 11.

// Download the helper library from https://github.com/somleng/somleng-node and follow the instructions
// Find your Account SID and Auth Token from the Somleng console
// and set the environment variables.
// const accountSid = process.env.SOMLENG_ACCOUNT_SID;
// const authToken = process.env.SOMLENG_AUTH_TOKEN;
const accountSid = "change-me";
const authToken = "change-me";
const verificationServiceSid = "change-me";
const to = "+15017122661";
const verificationCode = "change-me"
const client = require('somleng')(accountSid, authToken);
client.verify.v2.services(verificationServiceSid)
 .verificationChecks
 .create({to: to, code: verificationCode})
 .then(verification_check => console.log(verification_check.status));

After you complete the flow you can view the Verification and the associated logs from the Dashboard.

1. Under the Verify menu, select Verifications.
2. Click on the verification you just created in the list.

🎉 Congratulations!

Congratulations! You have successfully built your own phone verification service!

Next Steps?

The next step is to connect your Verification Service to Amazon Chime to receive verifications to your phone.

You can follow the next tutorial here: https://www.somleng.org/docs.html#tutorials