Open Source Documentation

This documentation is Open Source and written in plain HTML. If you see an error or want to contribute to improving the docs, please consider submitting a pull request .


Terminology

Before we begin, here is some general terminology that is important for understanding this article.

Term Meaning
Carrier A carrier (telecom company, mobile network operator (MNO), aggregator etc) who offers routes to/from the Public Switched Telephone Network (PSTN). E.g. AT&T, Verizon
BYOC Entity An individual or organization who has a business relationship with a carrier. E.g. a carrier's customer. BYOC stands for Bring Your Own Carrier.
Independent Entity An individual or organization with their own VoIP/SMS gateway.


Audience

This documentation is intended for Carriers, and BYOC entities, and Independent entities as defined above.


Introduction

Somleng is an Open Source, white-labeled, Cloud Communications Platform as a Service (CPaaS), and Telco-as-a-Service (TaaS) featuring programmable voice and SMS.

There are a number of different use-cases depending on your role as a Carrier, BYOC entity or Independent entity as defined above.

Here are some common use-cases:

  • Carriers use Somleng to offer their own branded CPaaS services to their customers. Some examples of carriers who use Somleng are C3ntro Telecom and Fibernetics .
  • BYOC entities use Somleng directly by connecting to their carrier that they have a business relationship with. Some examples of BYOC entities who use Somleng are UNICEF and People In Need .
  • Independent entities use Somleng directly by connecting through a VoIP/SMS Gateway that they own or manage. An example of an Independent entity who uses Somleng is Rumsan .

It's also possible for both BYOC and Independent entities to create their own branded CPaaS with Somleng by leveraging their existing connection to a carrier or VoIP/SMS Gateway.


Getting Started

We highly recommend trying out Somleng by signing up for a free carrier account , then working through the tutorials. This will allow you explore and understand Somleng's features without having to worry about installing the full-stack on your local machine.

If you are looking to install Somleng on your local machine, please read the Installation Guide.

All users are required to setup two factor authentication (2FA) the first time they sign in to the Dashboard. We recommend Authy , Google Authenticator or your password manager to setup 2FA.


Tutorials

This section contains various tutorials which will help you learn more about Somleng's features. We recommend that you complete the tutorials using a free carrier account rather than a local installation.

Build your own Phone Verification Service

In this tutorial you will build your own Phone Verification Service which can then be used by your own applications.

Prerequisites

  1. Sign up for 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 Verification Service.
  3. Create a SMS Gateway.
  4. Create a SIP Trunk.
  5. Run the Somleng SMS Gateway Application.
  6. Register your softphone with the SIP Trunk.
  7. Start a new Verification Flow.
  8. Receive the verification code via the SMS Gateway Application.
  9. Resend the verification code via a call.
  10. Receive the verification via a call.
  11. Complete the Verification Flow.

1. Create a Customer Account.

In this step you create a new customer account (not to be confused with your carrier account) 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 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.

3. Create a SMS Gateway.

In this step you create a new SMS Gateway which will handle the delivery of verification codes via SMS.

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. Enter a Default sender. This will be used as the sender id when sending verification codes. A default sender can an E.164 number or short code.
  5. Press Create SMS gateway.

4. Create a SIP Trunk.

In this step you create a new SIP Trunk which will handle the delivery of verification codes via phone call.

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. Enter a Default sender. This will be used as the sender id when sending verification codes via phone call. A default sender can an E.164 number or short code.
  6. Press Create SIP trunk.

5. 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 .

6. 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.

7. 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 authToken from the account you created in Step 1.
  • Set verificationServiceSid from the verification service you created in Step 3.
// To run this code, download the Somleng.js helper library from:
// https://www.somleng.org/docs/twilio_api/#helper-libraries

// Then, find your Account SID and Auth Token from the Somleng console
// and set the following 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));
                  

8. 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.

9. 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 call as shown below. Remember to also set the accountSid, authToken and verificationServiceSid like you did in Step 8.

// To run this code, download the Somleng.js helper library from:
// https://www.somleng.org/docs/twilio_api/#helper-libraries

// Then, find your Account SID and Auth Token from the Somleng console
// and set the following 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));

10. 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.

11. 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 authToken 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.
// To run this code, download the Somleng.js helper library from:
// https://www.somleng.org/docs/twilio_api/#helper-libraries

// Then, find your Account SID and Auth Token from the Somleng console
// and set the following 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 completed the tutorial and built your own phone verification service!

What we learned:

  1. Customer accounts (not to be confused with your carrier account) are used to manage access to the API. You can create as many customer accounts as you need.
  2. A Verification Service is a set of common configurations used to create and check verifications. A verification service includes a Friendly name and a Code length.
  3. An SMS Gateway is used to deliver SMS messages including verification codes.
  4. A SIP Trunk is used to send voice calls including verification codes.
  5. The Somleng SMS Gateway Application is a stand-alone application which runs on your local machine and communicates with the SMS Gateway. It allows you to take full control of the SMS delivery process.
  6. The somleng-node helper library can be used to start and check verification flows from your application.

Connect Somleng to Amazon Chime

In this tutorial you will learn how to connect Somleng to your Amazon Chime account. This tutorial will build on the previous tutorial, allowing you to send verification codes (and other automated voice calls) to real phone numbers.

It's recommended that you complete the previous tutorial before attempting this one. Some of the steps required to complete this tutorial are the same as the previous tutorial and are not repeated.

Prerequisites

  1. Complete the previous tutorial.
  2. Have access to an Amazon Chime Pro account. You can sign up here .

Overview

The following diagram shows how it works:

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

  1. Create a new Chime Voice Connector
  2. Create a new Phone Number
  3. Configure a new SIP Trunk
  4. Test a call to your own number
  5. Test a call to an international number

1. Create a new Chime Voice Connector

In this step you create and configure a new Voice Connector on Amazon Chime.

Perform the following steps:

  1. Under Amazon Chime SDK, create a new Voice Connector.
  2. Give the Voice connector a name.
  3. Set Encryption to Disabled.
  4. Press Create Voice Connector
  5. Configure the termination settings
    1. On the Termination tab, set Termination status to Enabled.
    2. Under Allowed hosts list, add the following IP addresses:
      • 13.250.230.15/32
      • 52.4.242.134/32
      These are Somleng's public IP address documented here.
    3. Press Save.
  6. Assign a phone number.
    1. On the Phone numbers tab, press Assign from inventory.
    2. Select a phone number from the list and press Assign from inventory.

2. Create a new Phone Number

In this step you create a new phone number on Somleng which matches the phone number you configured in Step 1 on Chime. This phone number will be used as the caller ID when routing calls through Chime.

In addition we'll assign this new number to the customer account that you created in the previous tutorial, so that you can use it can be used to send generic voice calls as well as verification calls.

Note: The phone number you create in this step must exactly match the phone number assigned in the previous step otherwise Chime will reject your calls.

Perform the following steps:

  1. From the Somleng Dashboard, under the Phone Numbers menu, click the icon to create a new phone number.
  2. Enter the same phone number that you configured in Step 1 on Chime.
  3. Assign the phone number to the customer account that you created in the previous tutorial.
  4. Press Create Phone number.

3. Configure a new SIP Trunk.

In this step you configure a new SIP Trunk on Somleng to point to the newly created Voice Connector in Step 1.

If you recall from the previous tutorial, we already created a SIP trunk to handle calls to our local softphone. In this step you'll create a new SIP trunk to handle the delivery of calls through Chime. You'll still keep the SIP trunk created in the previous tutorial to handle calls to your softphone.

In a real-world scenario this setup would be useful for routing calls through a different SIP trunk depending on the destination. For example you might want to handle domestic calls through your own VoIP gateway and international calls through Chime.

We can simulate this scenario in reverse, by configuring the new SIP trunk to only handle calls with a certain prefix. All other prefixes will be routed though the default SIP Trunk which points to your local softphone. This way you can test a a call destined to your real phone number, which will be routed though Chime and a call destined to an overseas number, which will be routed to your local softphone.

Perform the following steps:

  1. From the Somleng Dashboard, under the Voice menu, select SIP Trunks.
  2. Click the icon to create a new SIP trunk.
  3. Under Authentication mode, choose IP address.
  4. Give your SIP Trunk a name (e.g Amazon Chime).
  5. Set the Outbound Dialing Host to the Outbound host name that was when you created the Chime Voice Connector in Step 1. The host should be of the form your-chime-host-id.voiceconnector.chime.aws
  6. Under Route prefixes add the international dialing code (e.g. +855) for your real phone number. This will be used to correctly select this SIP trunk based on the destination number.
  7. Enter the phone number you created in Step 2 as the Default sender.
  8. Check Plus prefix. This send outbound calls using a plus (+) prefix is a requirement of Chime.
  9. Press Create SIP trunk.

4. Test a call to your own number

In this step you'll test a call to your own phone number which should be routed though Chime.

Below is an example of how to use the Phone Calls API using the somleng-node helper library.

The Phone Calls API is different from the Verification API used in the previous tutorial. It allows you to send automated phone calls and control them using TwiML and requires the following parameters:

to
The phone number that will receive the call.
from
The phone number that will be used to make the call. This number must be assigned to the customer account you created in the previous tutorial, and must match the number created in Step 2.
twiml
TwiML instructions to control the call.

Run the code below substituting the following:

  • Set accountSid and authToken from the account you created in the previous tutorial.
  • Set to to the phone number which will receive the call.
  • Set from to the number you configured in Step 2.
  • Optionally update the twiml as you like.
// To run this code, download the Somleng.js helper library from:
// https://www.somleng.org/docs/twilio_api/#helper-libraries

// Then, find your Account SID and Auth Token from the Somleng console
// and set the following 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 to = "change-me"; // A phone number which will receive the call
const from = "change-me"; // This should exactly match the number configured in Step 2.
const twiml = "<Response><Say>Hello World from the Somleng Chime Tutorial! How are you today?</Say><Play>https://demo.twilio.com/docs/classic.mp3</Play></Response>"

const client = require('somleng')(accountSid, authToken);

client.calls
  .create({ to: to, from: from, twiml: twiml })
  .then(call => console.log(call.sid));

You should receive a phone call to your real phone number delivered through the SIP Trunk connected to Chime. Pick up the call and listen to the message. You should hear what you have entered in the TwiML instructions above.

Note: Instead of running this code, you could also re-run the Verification Flow as show in the previous tutorial. You should receive the verification code on your real phone number delivered through Chime.

5. Test a call to an international number

In this step you'll test a call to an international number (with a prefix different from your own number), which should be routed to your local softphone.

In order to complete this step, simply update the to parameter to a phone number which does not match the international prefix of your own number. This will result in the SIP trunk from the previous tutorial being selected and therefore the call should be routed to your local softphone.

Go ahead and run the code again from the previous step. Remember to replace the to parameter and keep the rest the same.

You should receive a phone call to your real phone number delivered through the SIP Trunk connected to your local softphone. Pick up the call and listen to the message. You should hear what you have entered in the TwiML instructions from the previous step.

🎉 Congratulations!

Congratulations! You have successfully completed the tutorial and connected Somleng to Chime.

What we learned:

  1. How to connect Somleng to Amazon Chime.
  2. A Phone number must be assigned to a customer account in order to use it in the Phone Calls API .
  3. Multiple SIP Trunks can be configured to handle routing based on the destination phone number.
  4. The Phone Calls API is different from the Verification API . It can be used to create outbound calls and control the call via TwiML instructions .

Invite customers to use your CPaaS

So far, you've learned how to build your own phone verification service, and optionally connected it to Amazon Chime. You have essentially built your own branded, Communications Platform as a Service or CPaaS.

In this tutorial you'll learn how to invite your own customers to use your new CPaaS. Your customers will be able to integrate phone verifications and programmable voice and messaging into their own applications, while you remain in complete control over their access.

1. Update your carrier settings.

In this step, you'll update your carrier settings and add a logo. In this tutorial we're using an imaginary company called Rocket Communications.

Perform the following steps:

  1. Click on Carrier Settings from the main menu.
  2. Upload your company's logo.
  3. Optionally update other details about your company.
  4. Press Update Carrier Settings.

2. Create a new Account for your customer.

In this step you create a new account for your customer. There are two types of accounts on Somleng namely: Carrier Managed and Customer Managed. As the name suggests, Customer Managed accounts are managed by the carrier's customer, who will get access to the Dashboard and can manage their own Account SID and Auth Token. Here we'll create a customer account for our imaginary customer Elvie Padberg from Klocko Block, but feel free to use your own customer details.

Perform the following steps:

  1. Under the Accounts menu, click the icon to create a new account.
  2. Give the account a name.
  3. Under Owner, enter the customer's name and email address.
    Note: You cannot invite yourself as your own customer. You must use a different email address than the one you used to sign up for Somleng. However, in order to complete this tutorial you'll need to choose an email that you have access to, so you can explore the dashboard from the customer's perspective. If you only have one email address you can use the following trick: your-email+customer-email@your-domain.tld. For example, if your real email address is bob@example.com and your customer's name is Elive Padberg, enter bob+elvie.padberg@example.com.
  4. Choose a premium TTS voice (such as Polly.Joanna) from the default TTS Voice dropdown. This will be used to determine the TTS provider (Basic or Polly) when sending phone calls.
  5. Press Create Account.

3. Log in to the Dashboard as if you are the customer.

In this step, you'll log in to the Dashboard as if you are the customer. To do this you'll first need to log out of your carrier account, then click the customer invitation link from your email.

Note: In a real-world scenario you would never log in to the customer's account. The goal of this step is to understand the customer's experience.

Perform the following steps:

  1. Click on your avatar in the top right corner and select Logout from the dropdown.
  2. Check your email. You should have received a customer invitation email when completing the previous step.
  3. Follow the link in the email and set your password.
  4. Setup two factor authentication (2FA).

You should now be viewing the dashboard from the customer's perspective.

4. Explore the Dashboard and API docs from the customer's perspective.

In this step, feel free to click around and explore the Dashboard from the customer's perspective.

Notice the following:

  • Your company's logo appears in the top left of the Dashboard.
  • The customer can manage their own Account SID and Auth Token.
  • The customer cannot view or manage any carrier resources such as SIP Trunks, SMS Gateways etc.
  • The customer can only see resources (e.g. Phone Calls, Messages etc) that belong to their account.
  • The API docs are branded with your company's name and logo.

5. Use the API and Dashboard from the customer's perspective.

In this step, you'll explore using the Verify API from the customer's perspective.

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.
  4. Press Create Verification service.

Make sure your softphone is still registered with the SIP trunk that you created in the first tutorial.

Then, run the code below substituting the following:

  • Set accountSid and authToken from the values shown on the Account Settings page.
  • Set verificationServiceSid from the verification service you just created.
// To run this code, download the Somleng.js helper library from:
// https://www.somleng.org/docs/twilio_api/#helper-libraries

// Then, find your Account SID and Auth Token from the Somleng console
// and set the following 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));

You can now view the verification from the customer's perspective from the Verify menu on the Dashboard.

If you completed the first tutorial, and your softphone is still connected, then you should receive the verification call.

Note: In this step we demonstrated that your customers can use the Verify API, which is connected to your SIP infrastructure. In a real-world scenario you would connect your SIP trunk to a VoIP Gateway, Amazon Chime or your own SIP Infrastructure.

6. Control API Access for your customer.

To finish up this tutorial, we'll show you how to control your customer's access from the Carrier Dashboard. To do this you'll first need to log out of your customer's account, and login again to your carrier account.

Perform the following steps:

  1. Click on your customer's avatar in the top right corner and select Logout from the dropdown.
  2. Log in to your carrier account.
  3. Under the Accounts menu, click the SID of the Account belonging to your customer.
  4. Click the button.
  5. Notice that most of the fields are disabled, but you can toggle the Enabled switch.
  6. Press Update Account to save your changes.

Note: Disabling the account, will prevent your customer from accessing the API, but your customer will still have access to the Dashboard in order for them to view their data.

🎉 Congratulations!

Congratulations! You have successfully completed this tutorial and invited your first customer to use your CPaaS.

What we learned:

  1. Customer managed accounts (as opposed to Carrier managed accounts) are used by your customers. When you create a customer managed account, you specify an owner's name and email address. The owner will then receive an invitation email and can then sign-in to the dashboard and manage their own Account.
  2. When your customer signs in to the Dashboard, he will see your company's branding and logo both on the Dashboard and in the API Docs.
  3. The customer can use the API and helper libraries in his own applications.
  4. The customer can only see the data (phone calls, messages, verifications etc) that belongs to him.
  5. You can control the customer's API access from the carrier dashboard.

Connect Somleng with Retell AI

In this tutorial you'll learn how connect Somleng with Retell AI to power your call operations with Voice AI without Twilio. In order to handle call terminations, we'll be using Amazon Chime, but you can replace Chime with your own voice termination provider or infrastructure.

Prerequisites

  1. Complete the Verify tutorial.
  2. Complete the Chime tutorial.
  3. Sign up for a free Retell AI trial account.
  4. Install Node.js and ngrok .

1. Obtain your Retell AI credentials

  1. Login to your Retell AI account, select API Keys from the menu and copy your API key.
  2. Select Agents from the menu, select and Agent and copy the Agent ID as shown below.

2. Run the retell_server.js application

  1. Download retell_server.js and package.json from the Somleng SWITCH testing repository
  2. Install the required packages with npm
    npm install
  3. Run retell_server.js replacing RETELL_AI_API_KEY and RETELL_AI_AGENT_ID with the values from Step 1. After running this command you should see the server running on localhost:3000.
    node retell_server.js --api_key RETELL_AI_API_KEY --agent_id RETELL_AI_AGENT_ID --port 3000
  4. In another terminal window run the following command to expose the server to the internet.
    ngrok http 3000
  5. Note the forwarding URL: It should look something like this: https://eb3c-229-14-127-42.ngrok-free.app

3. Confirm you have completed the previous tutorials

Ensure you have completed the Verify and Chime tutorials. You will need to have configured a Somleng customer account, a SIP trunk which is connected to Chime, and a phone number to continue.

4. Talk with the AI

In this step we'll create an outbound call to your number. After you answer the call, Somleng will request TwiML instructions from the ngrok URL obtained from Step 2. Ngrok will forward the request to the retell_server.js application which will connect your call to Retell AI.

Run the following code:

// To run this code, download the Somleng.js helper library from:
// https://www.somleng.org/docs/twilio_api/#helper-libraries

// Then, find your Account SID and Auth Token from the Somleng console
// and set the following environment variables.
// const accountSid = process.env.SOMLENG_ACCOUNT_SID;
// const authToken = process.env.SOMLENG_AUTH_TOKEN;

const accountSid = "change-me"; // Replace with the accountSid obtained when completing the Verify tutorial.
const authToken = "change-me"; // Replace with the authToken obtained when completing the Verify tutorial.
const to = "change-me"; // A phone number which will receive the call.
const from = "change-me"; // This should exactly match the number obtained from the Chime tutorial.
const url = "change-me"; // Replace with the ngrok URL obtained from step 2.

const client = require('somleng')(accountSid, authToken);

client.calls
  .create({ to: to, from: from, url: `${url}/connect` })
  .then(call => console.log(call.sid));

🎉 Congratulations!

Congratulations! You have successfully completed the tutorial and connected Somleng with Retell AI.

What we learned:

  1. Retell AI works with Somleng out of the box. This makes it possible to replace Twilio with Somleng for your existing workflows.
  2. You can replace Chime with your own infrastructure or voice termination provider.
  3. You can also replace Retell AI with Vocode to have a complete solution built on open source software.

Using the Dashboard

The dashboard can be used to manually provision carrier resources. Use the Carrier API to automate the provisioning of carrier resources.

Authentication

You must sign in to the dashboard via your subdomain to use Somleng. The sign in URL is https://your-subdomain.app.somleng.org/users/sign_in. If you have setup a custom domain all users may access the dashboard through your custom domain as well.

All users are required to setup two factor authentication (2FA) the first time they sign in. We recommend Authy , Google Authenticator or your password manager to setup 2FA.

Carrier Settings

Here you will find various settings for your carrier. Under General, you'll see your company's name, subdomain, website, country and logo. Under Developer, you'll see your Carrier API Key, as well as your webhook URL and signing secret for verifying webhooks . If you've setup a custom domain this will appear under the Custom Domain section.

To update your carrier settings:

  1. Sign in to the Dashboard and from the side-navigation, click Carrier Settings.
  2. Click the icon to edit your settings.
  3. Make your desired changes.
  4. Choose Update Carrier Settings.

Accounts

Accounts are used by carriers, carrier customers, BYOC entities and independent entities to send/receive calls and SMS via the Account API .

Typically a carrier would create an account for each of their customers. BYOC entities and independent entities on the other hand might create an account for each customer or project or just create one global account for their own usage.

There are two types of accounts. Carrier managed and customer managed described below:

Account type Description
Carrier Managed Carrier managed accounts are managed by carriers. These types of accounts can be either used by carriers themselves, or by the carrier's customers.
Customer Managed Customer managed accounts are managed by the carrier's customers directly. These types of accounts can be created via the dashboard by specifying an account owner when creating the account. After providing the account owner's name and email address, the owner will be invited to the dashboard and can manage their own account. The customer will also have access to their Account SID and Auth Token. The carrier can still disable and enable customer accounts from the Dashboard.

To create an account via the Dashboard:

  1. Sign in to the Dashboard and from the side-navigation, click Accounts.
  2. Click the icon to create a new account.
  3. Fill out the form, specifying a name for the account and optionally the owner's name and email address to create a customer account.
  4. Choose Create Account.

Phone Numbers

Phone Numbers represent direct inbound dialing (DID) numbers. A phone number can be either an E.164 formatted phone number or a short code. When you create a phone number you can optionally assign it to an account.

Once provisioned and assigned to an account, phone numbers can then be configured for inbound dialing and/or inbound messaging.

Note: This configuration can either be done by the carrier or by an account admin (for customer managed accounts).

To create a phone number via the Dashboard:

  1. Sign in to the Dashboard and from the side-navigation, click Phone Numbers.
  2. Click the icon to create a new phone number.
  3. Fill out the form, specifying the phone number or short code, and optionally assign it to an account.
  4. Choose Create Phone number.

Once the phone number has been created, you can configure it. To configure a phone number via the Dashboard:

  1. From the Phone Numbers page, find the phone number you want to configure.
  2. From the gear icon select Configure.
  3. Optionally configure the phone number to handle inbound calls.
    • Under Voice, specify a Voice URL and Voice Method. This will configure your phone number for inbound dialing. The Voice URL should return valid TwiML for Programmable Voice and will be executed when an inbound call is received by Somleng.
    • Optionally configure a Status Callback URL and Status Callback Method which will be used to deliver status updates for inbound calls to this number.
  4. Optionally configure the phone number to handle inbound messages.
    • Under Messaging, specify a SMS URL and SMS Method. This will configure your phone number for inbound messaging. The SMS URL should return valid TwiML for Programmable SMS and will be executed when an inbound message is received by Somleng.
    • Optionally configure a Messaging Service. This is useful if you want to apply a set of configuration to multiple phone numbers, instead of configuring each phone number individually.
  5. Choose Update Configuration.

After you have configured a phone number, the configuration will be shown on the next screen.

Import Phone Numbers

In order to bulk import phone numbers, you can upload a CSV file from the Dashboard. Somleng requires a CSV file in the following format:

  1. From the Phone Numbers page, click the upload button .
  2. Select the CSV file of phone numbers to import.
  3. Choose Upload.

Column Header Required/Optional Content Possible Values Example
number Required The phone number or short code E.164 formatted number or short code. e.g. +12505550199 or 77730 12505550199
type Required The type of phone number One of either local, mobile, toll_free, short_code, or alphanumeric_sender_id local
visibility Optional The visibility of the phone number One of either private, public, or disabled defaults to public for phone numbers with a price or private for phone numbers without one. true public
country Optional The country of the phone number Optional ISO 3166-1 alpha-2 country code. If not provided, will try to resolve from the phone number CA
price Optional The monthly price you want to charge for the phone number A positive value in the billing currency of the carrier 1.15
region Optional The state or province abbreviation of this phone number's location Optional ISO 3166-2 subdivision code ON
locality Optional The locality or city of this phone number's location The name of a city or locality Toronto
lata Optional The local access and transport area (LATA). Applicable only for phone numbers from the US and Canada. LATA code 888
rate_center Optional The Rate center of this phone number. Applicable only for phone numbers from the US and Canada. Rate center name NEWTORONTO
latitude Optional The latitude of this phone number's location. Applicable only for phone numbers from the US and Canada. Latitude 43.6008
longitude Optional The longitude of this phone number's location. Applicable only for phone numbers from the US and Canada. Longitude -79.5053
meta_* Optional Custom metadata. The column name must start with meta_. E.g. meta_my_custom_field The value for the custom field: E.g. My custom value My custom value
marked_for_deletion Optional Marks the phone number for deletion true true

Sample CSV for creating phone numbers
number,type,visibility,country,price,region,locality,lata,rate_center,latitude,longitude,meta_my_custom_field,meta_another_custom_field
+12505550199,local,public,CA,1.15,ON,Toronto,888,NEWTORONTO,43.6008,-79.5053,My custom value,Another custom value
Sample CSV for deleting phone numbers
number,marked_for_deletion
+12505550199,true

Voice

This section contains everything you need related to configuring programmable Voice.

SIP Trunks

SIP Trunks are used to configure both inbound and outbound dialing, both to and from Somleng. We define inbound dialing (also known as Direct Inbound Dialing (DID)) as calls terminated by Somleng, and outbound dialing as calls originated by Somleng.

When you create a SIP Trunk you first choose the authentication mode. There are two authentication modes available described below:

Authentication mode Description
IP Address Choose this mode if you have a public static IP address and are not behind a NAT. This mode is best suited for carriers and BYOC entities.
Client Credentials Choose this mode if you do not have a public static IP address or are behind a NAT. This mode is best suited for independent entities.

IP Address Authentication

Note: This mode is best suited for Carriers and BYOC entities.

Inbound Dialing

When you configure a SIP trunk for inbound dialing via IP address authentication the following rules apply:

  1. You must provide a public static IP address as the Source IP. This IP address is used to authenticate the carrier when inbound calls are received.
  2. You must connect to our public gateway via one of the IP addresses listed below:
    • 15.197.218.231
    • 3.33.238.177
Outbound Dialing

When you configure a SIP trunk for outbound dialing via IP address authentication the following rules apply:

  1. You must provide a host to connect to. You can specify your host as either a fully qualified domain name (FQDN) or IP address.
  2. You must allow the following IP addresses on your firewall:
    • Singapore Region: 13.250.230.15
    • North America Region: 52.4.242.134
    Note: Both media and SIP is sent from this IP address.
  3. You must support NAT Traversal and Symmetric Latching. Read more.

To configure a SIP trunk via IP address authentication:

  1. Sign in to the Dashboard and from the side-navigation, click SIP Trunks.
  2. Click the icon to create a new SIP trunk.
  3. Under General, select IP address for Authentication mode.
  4. Under Inbound Dialing, enter a public static IP address for inbound call authentication.
  5. Under Outbound Dialing, enter a domain name or IP address for outbound calls.
  6. Choose Create SIP Trunk.

After you create your SIP Trunk you'll see the configuration details on the next screen.

Client Credentials Authentication

Note: This mode is best suited for independent entities.

When you configure a SIP trunk via client credentials authentication you don't need a public status IP address. Instead you authenticate with Somleng via SIP registration. After you configure a SIP trunk in this mode you will be given a unique set of client credentials which can be used to authenticate with Somleng. These credentials can be used directly when configuring your client gateway.

To configure a SIP trunk via client credentials authentication:

  1. Sign in to the Dashboard and from the side-navigation, click SIP Trunks.
  2. Click the icon to create a new SIP trunk.
  3. Under General, select Client credentials for Authentication mode.
  4. Under Inbound Dialing, it's recommended to select the default country code of the caller. This allows your VoIP gateway to work with national dialing numbers. Somleng will try to normalize number into E.164 format using this setting.
  5. Choose Create SIP Trunk.

After you create your SIP Trunk you'll see the generated credentials on the next screen.

Text To Speech (TTS)

Text To Speech (TTS), also known as speech synthesis, is a process in which text is converted into a human-sounding voice.

The <Say> verb allows you to provide plain text that Somleng converts to synthesized speech. For example, when Somleng executes the following TwiML during a call, the caller hears "Hello world!" The synthesized voice the caller hears is the default voice and language of the Somleng Account (configured in the Account Settings).

<Response>
<Say>Hello world!</Say>
</Response>

<Say> also allows you to modify the language, accent, and voice of the synthesized speech via the language and voice attributes. The example below uses Amazon Polly's "Joanna" voice and American English:

<Response>
<Say language="en-US" voice="Polly.Joanna">Hello. I am Joanna and I speak American English!</Say>
</Response>

The language attribute of <Say> also allows you to override the default voice that is configured for the Somleng Account. For example, if the account's default TTS voice is Polly.Joanna (Female, en-US), but wish to use German for a specific call, set the language attribute to de-DE in your TwiML. This will choose another voice from the Polly provider which supports German.

<Response>
<Say language="de-DE">Hallo. Ich spreche Deutsch!</Say>
</Response>

Note: the TTS provider is always preserved when using this feature. For example if the account's default TTS voice is Basic.Kal (Male, en-US), using the TwiML above won't have any effect because German is not available in the Basic provider.

You can also use Premium voices which are generated using the latest technology and innovation in synthesized speech, providing the most human-like, expressive and natural-sounding text-to-speech voices possible, with higher quality than Standard voices. The voices in this tier are currently provided by Amazon (Amazon Polly Neural).

As well as setting the default TTS voice to a premium voice in the dashboard, you can also use the voice attribute to override a premium voice. For example:

<Response>
<Say voice="Polly.Danielle-Neural">Hello. I am Danielle!</Say>
</Response>

Messaging

This section contains everything you need related to configuring programmable SMS.

SMS Gateways

SMS Gateways are used by Somleng for SMS origination and termination. Configuring an SMS Gateway allows you to fully control your own SMS infrastructure.

When you configure an SMS gateway on the Dashboard, you receive a Device Token which uniquely identifies your SMS Gateway. You'll then need to install the Somleng SMS Gateway App on your on-premise or cloud infrastructure. Normally, you'll only need to configure a single SMS Gateway, however if you require multiple SMS gateways, you'll need to run an instance of the for each one. Once the app is running on your local infrastructure and connected to Somleng, the SMS Gateway will show Connected on the Dashboard.

To configure an SMS Gateway:

  1. Sign in to the Dashboard and from the side-navigation, click SMS Gateways under Messaging.
  2. Click the icon to create a new SMS Gateway.
  3. Enter a name for your SMS Gateway.
  4. Enter the maximum number of channels your SMS gateway supports. Leave it blank for unlimited channels.
  5. Choose Create SMS gateway.

After you create your SMS Gateway you'll see your Device Token on the next screen.

Channel Groups

An SMS gateway channel group allows you control which channels are used by your SMS Gateway to terminate outbound messages. This is mainly used by independent entities who connect via a GSM Gateway.

For example let's assume your GSM Gateway has 4 available channels. Now, let's assume you insert 2 SIM cards belong to a carrier called "Smart", 1 SIM card belonging to a carrier called "Metfone", and another SIM card belonging to a carrier called "Cellcard".

Channel groups allow you to specify which messages will be routed through the "Smart" SIM cards, which messages will be routed through the "Metfone" SIM cards and which messages will be routed through the "Cellcard" SIM cards.

To configure a Channel Group:

  1. Sign in to the Dashboard and from the side-navigation, click Channel Groups under Messaging.
  2. Click the icon to create a new Channel Group.
  3. Enter a name for your Channel Group.
  4. Assign the channel group to an SMS Gateway.
  5. Specify a comma separated list of prefixes (including the country code) for the Channel Group. This list is used to match the channel group by the destination number of an outbound message.
  6. Select the channels that you want to associate with the channel group. The available channels are derived from the maximum number of channels you specified on your SMS Gateway.
  7. Choose Create Channel group.

After you have created your Channel Group you can see the configuration details.

Messaging Services

Messaging services allow you to apply messaging configuration to of a group of phone numbers, rather than having to configure each one individually.

To configure an Messaging Service:

  1. Sign in to the Dashboard and from the side-navigation, click Messaging Services under Messaging.
  2. Click the icon to create a new Messaging Service.
  3. Enter a name for your Messaging Service.
  4. Choose Next.
  5. Add phone numbers to your Messaging Service by selecting them from the Sender Pool. Note these phone numbers must already be assigned to the account you selected above.
  6. Choose the default behavior for inbound messages received by the numbers in the pool. You can either:
    • Defer to sender's webhook (Default). This will fallback to configuration for the individual phone number.
    • Drop the message. Your application will ignore inbound messages. You won't be charged for them and they won't show up on the dashboard.
    • Send a webhook. Invoke a HTTP webhook for all incoming messages in the sender pool.
  7. If you chose Send a webhook in the previous step you must enter a Inbound Request URL and Inbound request method to request for incoming messages.
  8. Optionally configure a Status Callback URL for all outbound messages in the sender pool.
  9. Configure Smart encoding for outbound messages. If this is turned on Smart encoding will apply to all outbound messages in the number pool.
  10. Choose Create Messaging service.

After you have configured your messaging service you can see the configuration details.

Team

Carrier owners can invite their team to the dashboard.

To invite a team member to the Dashboard:

  1. Sign in to the Dashboard and from the side-navigation, click Team.
  2. Click the icon to invite a new team member.
  3. Fill out the form, specifying the team member's name, email and role.
  4. Choose Send an invitation.

The team member will receive an email inviting him to use the dashboard. Team members with the owner role can manage another team member including updating his role and resetting his 2FA.


Custom Domain Configuration Guide

Setting up a custom domain allows you to fully white-label Somleng and brand it for your company. This includes the branded dashboard, emails, Carrier API and Account API references.

How it works

When you setup a custom domain you need to setup proxy between your domain and Somleng in order for SSL termination to work correctly. Below we describe two methods for doing this via AWS Cloudfront or Nginx. We recommend using AWS Cloudfront unless your have specific custom requirements or you cannot use AWS.

Setup your custom domain

Follow the steps below to configure your custom domain:

  1. Setup a reverse proxy via AWS Cloudfront (recommended) or Nginx.
  2. Test out your custom domain.
  3. Configure your custom domain via the Somleng Dashboard.

1(a). Configure an AWS Cloudfront Distribution (Recommended)

Skip this step if you prefer to use Nginx instead.

In order to make this step easier, we've created a Terraform module automates the configuration and management of your AWS Cloudfront distributions via Terraform .

Using the Terraform Module (Recommended)

In order to use the terraform module you need to setup and install Terraform first. We recommend following the Terraform AWS tutorial to get started.

# somleng_proxy.tf
  module "somleng_proxy_dashboard" {
  source = "github.com/somleng/terraform-aws-cloudfront-reverse-proxy"

  host = "your-domain.example.com" # Replace this with your custom domain
  origin = "your-domain.app.somleng.org" # Replace this with your Somleng subdomain
  origin_custom_headers = [
  {
  "name" = "X-Forwarded-Host",
  "value" = "your-domain.example.com" # Replace with your custom domain
  }
  ]

  allowed_origin_request_headers = [
  "X-CSRF-Token",
  "X-Requested-With"
  ]

  zone_id = aws_route53_zone.example_com.zone_id # Optional. Leave blank if not using route53.
  certificate_arn = "existing-certificate-arn" # Optional. Leave blank to create a new certificate.
  }

  # Optionally configure a custom API endpoint
  module "somleng_proxy_api" {
  source = "github.com/somleng/terraform-aws-cloudfront-reverse-proxy"

  host = "your-api-domain.example.com" # Replace this with your custom API domain
  origin = "api.somleng.org"

  # DO NOT set X-Forwarded-Host

  zone_id = aws_route53_zone.example_com.zone_id # Optional. Leave blank if not using route53.
  certificate_arn = "existing-certificate-arn" # Optional. Leave blank to create a new certificate.
  }

The terraform configuration above will configure two AWS cloudfront distributions (one for the dashboard and one for the API) and optionally create SSL certificates managed by AWS Certificate Manager. If you're using route53 to manage your domain, the module will also create records pointing your custom domain to the AWS cloudfront distributions.

Note: The second module, somleng_proxy_api is optional and only required if you want to configure a custom API endpoint.

Configuring Cloudfront Manually

Although we highly recommend using the terraform module above, you can also configure your Cloudfront distributions from the AWS Console.

Dashboard Configuration

  1. Sign in to the AWS Management Console and open the CloudFront console.
  2. Choose Create Distribution
  3. Update the 'Origin' settings.
    • Set 'Origin domain to' your-subdomain.app.somleng.org replacing your-subdomain with your Somleng subdomain.
    • Set 'Protocol' to HTTPS only
    • 'HTTPS port' should be set to 443
    • Set 'Minimum origin SSL protocol' to TLSv1.2
    • Under 'Add custom header' click Add header.
      • Enter X-Forwarded-Host for the Header name
      • Enter your-domain.example.com for the Value. Remember to replace your-domain.example.comwith your actual domain.
    • 'Enable Origin Shield' should be set to No
  4. Update the 'Default cache behavior' settings.
    • Set 'Compress objects automatically' to No.
    • Set 'Viewer protocol policy' to Redirect HTTP to HTTPS
    • Set 'Allowed HTTP methods' to GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
    • Set 'Restrict viewer access' to No
  5. Update the 'Cache key and origin requests' settings
    • Select Cache policy and origin request policy (recommended)
    • Under 'Cache policy', click Create policy
      • Update the 'Details' settings
        • Set 'Name' to somleng-proxy
      • Update the 'TTL Settings'
        • Set 'Minimum TTL' to 0
        • Set 'Maximum TTL' to 1
        • Set 'Default TTL' to 0
      • Update the 'Cache key settings'
        • Under 'Headers', select Include the following headers
        • Select the following headers:
          • Authorization
          • Accept-Encoding
        • Set 'Query strings' to None
        • Set 'Cookies' to None
      • Update the 'Compression support' settings
        • Deselect both Gzip and Brotli
      • Click Create
    • Under 'Origin request policy', click Create policy
      • Update the 'Details' settings
        • Set 'Name' to somleng-proxy
      • Update the 'Origin request settings'
        • Under 'Headers', select Include the following headers
        • Select the following headers:
          • Origin
          • Accept-Charset
          • Accept
          • Access-Control-Request-Method
          • Access-Control-Request-Headers
          • Referer
          • User-Agent
          • Content-Type
          • X-CSRF-Token
          • X-Requested-With
        • Set 'Query strings' to All
        • Set 'Cookies' to All
        • Click Create
  6. Update the 'Settings'
    • Set 'Price class' to Use all edge locations (best performance)
    • Set 'Alternate domain name (CNAME)' to your-domain.example.com
    • Set 'Custom SSL certificate' to your certificate or click the link to Request certificate.
    • Set security policy to TLSv1.2_2021 (recommended) or to the latest recommended policy.
  7. Click Create distribution

API Configuration (optional)

Repeat the exact same process above to create a distribution for your custom API domain, with the following modifications:

  • Set 'Origin domain to' api.somleng.org
  • DO NOT set the X-Forwarded-Host header

1(b). Nginx Reverse Proxy

Skip this step if you prefer to use AWS Cloudfront (recommended) instead.

The following Nginx configuration can be used to setup an Nginx reverse proxy to Somleng.

  server {
  listen 443;
  server_name dashboard.example.com; # replace this with your dashboard domain

  ssl_certificate /path/to/your/fullchain.pem;
  ssl_certificate_key /path/to/your/privatekey.pem;

  location / {
  proxy_set_header X-Forwarded-Host dashboard.example.com; # replace this with your dashboard domain
  proxy_pass "https://your-subdomain.app.somleng.org:443";
  }
  }

  # Optionally configure a custom API endpoint
  # Note: DO NOT set X-Forwarded-Host for your custom API endpoint
  server {
  listen 443;
  server_name api.example.com; # replace this with your api domain

  ssl_certificate /path/to/your/fullchain.pem;
  ssl_certificate_key /path/to/your/privatekey.pem;

  location / {
  proxy_pass "https://api.somleng.org:443";
  }
  }

2. Test your custom domain

After you have setup your reverse proxy via AWS Cloudfront or Nginx you can test it out by going to your-domain.example.com. You should see your carrier logo and the sign in page.

Try to sign in and interact with the dashboard. Note if you get a 422 error after signing in, try clearing your browser cookies and try again.

3. Configure your custom domain via the Somleng Dashboard.

The final step is to configure your custom domain via the Somleng Dashboard. Note: This step should only be done after you have setup and tested your reverse proxy via AWS Cloudfront or Nginx.

  1. Sign in to the Dashboard and from the side-navigation, click Carrier Settings.
  2. Click the icon to edit your settings.
  3. Under custom domain, enter your dashboard and API hosts.
  4. Choose Update Carrier Settings.

After configuring the custom dashboard host, customer transactional emails (such as forgot password, account invitations, etc) will link to your-domain.example.com. Carrier user transaction emails are still linked to your-subdomain.app.somleng.org.

You should also have branded API customer documentation available at your-domain.example.com/docs/api. Setting the custom API endpoint will additionally update the API documentation examples with your your-api.domain.example.com.

Note: The API is always available at api.somleng.org regardless of whether you set a custom API host or not.


Client Gateway Configuration Guide

Setting up a client gateway allows independent entities to use Somleng with their own VoIP gateway which provides access the PSTN, thereby removing the need for a commercial agreement with a carrier.

How it works

An independent entity configures their VoIP gateway to connect to Somleng. After the configuration is complete the independent entity can originate outbound calls through their VoIP gateway using the Account API and terminate and control inbound calls via TwiML.

The independent entity can also use Somleng to offer 3rd party access to the PSTN in their country via their VoIP gateway.

Configuration Overview

Note: You can still follow along with these instructions even if you don't have a VoIP gateway yet. Instead of configuring you VoIP gateway, you can configure a softphone such as Telephone . This will allow you to create outbound calls through Somleng which should reach your softphone.

Below is an overview of the steps required to configure a client gateway:

  1. Create a SIP Trunk to obtain your SIP credentials.
  2. Create an account to obtain your Account SID and Auth Token for outbound dialing.
  3. Create a Phone Number for inbound dialing.
  4. Configure your VoIP Gateway to connect to Somleng.

Note: Currently Somleng officially supports the following gateways:

Other VoIP gateways may work as well but have not been tested. If you want to use Somleng with a different gateway please open an issue .

1. Create a SIP Trunk

Create a new SIP Trunk and configure it with client credentials authentication.

  1. Sign in to the Dashboard and from the side-navigation, click SIP Trunks.
  2. Click the icon to create a new SIP trunk.
  3. Under General, select Client credentials for the authentication mode.
  4. Set Max channels to the number of channels (or SIM cards) your have available on your VoIP Gateway.
  5. Under Inbound Dialing select the default country code of the caller. This should match the country code you use later when you create a phone number.
  6. Under Outbound Dialing optionally configure Route prefixes, Dial string prefix and select National dialing where appropriate.
  7. Choose Create SIP Trunk.

After you have created a SIP trunk you will see your client credentials on the next screen:

2. Create an Account

Create a new Account to obtain your Account SID and Auth Token for outbound dialing.

  1. Sign in to the Dashboard and from the side-navigation, click Accounts.
  2. Click the icon to create a new account.
  3. Enter a name for the account.
  4. Choose Create Account.

Note: You don't need explicity associate the account with the SIP trunk you created in the previous step. Somleng will automatically select the SIP trunk when a call is created or received.

After you have created your account, the SID and Auth Token are shown on the next screen:

3. Create a Phone Number

Create a new Phone Number and configure it for inbound dialing.

  1. Sign in to the Dashboard and from the side-navigation, click Phone Numbers.
  2. Click the icon to create a new phone number.
  3. Enter the phone number including he country code in E.164 format.
  4. Link the phone number to the account by selecting the account created in the previous step.
  5. Choose Create Phone number.

After you have created your phone number, you can configure it on the next screen:

  1. Click the dropdown and choose Configure.
  2. Configure the phone number by entering a Voice URL that returns valid TwiML for Programmable Voice .
  3. Configure other optional parameters for the phone number as necessary.
  4. Choose Update Configuration.

4. Configure your VoIP gateway

After you have completed the previous steps, you can now configure you VoIP gateway to connect to Somleng. Below is the configuration instructions for the following VoIP gateways:

GoIP Configuration

Follow the instructions below to configure the GoIP gateway to connect to Somleng.

  1. General Configuration
  2. Basic VoIP Configuration
  3. Advanced VoIP Configuration
  4. Call-In Configuration
  5. Testing
  6. Advanced Routing Configuration (Optional)
  7. Additional Resources
1. General Configuration

Note: Before completing this step, we recommend that you test out the GoIP gateway in isolation by inserting a SIM card into the device and making a call to the number in the device. The internal IVR of the GoIP gateway should answer the call.

In order to configure the GoIP gateway for inbound dialing, we need to turn off the in-built IVR.

  1. From the side-navigation, click Configurations -> Preferences.
  2. Set IVR to Disable
  3. Click Save Changes.
2. Basic VoIP Configuration

The next step is to configure the GoIP gateway to register with Somleng. There are 3 different modes of configuration depending on your circumstances. Please refer to the GoIP User Manual for more information about the different configuration modes and the channel selection algorithms.

Config Mode Description
Single Server Mode Use this mode to associate all channels on your GoIP gateway to a single SIP Trunk on Somleng.
This mode is best if you only have one group of SIM cards and you want to route evenly between all of them.
Config by Line Use this mode to associate a single channel on your GoIP gateway to a single SIP Trunk on Somleng.
Note: This mode requires you so set a Routing Prefix for each channel.
Config by Group Use this mode to associate a group of channels on your GoIP gateway to a single SIP trunk on Somleng.
This mode is useful if you want to route to a different group of SIM cards based on the number prefix. See Advanced Routing Configuration for more info.
  1. From the side-navigation, click Configurations -> Basic VoIP.
  2. Choose your preferred configuration mode as described above from Config Mode.
  3. Copy the Username from the Client Credentials section from Step 1 and paste it in the Authentication ID field.
  4. Copy the Password from the Client Credentials section from Step 1 and paste it in the Password field.
  5. Copy the Domain from the Client Credentials section from Step 1 and paste it in the SIP Registrar Server field.
  6. Optionally fill in Routing Prefix to control the channel selection algorithm. Please refer to the GoIP User Manual for more details.
  7. Click Save Changes.

Note: If you choose Config by Line or Config by Group you'll need to repeat the instructions above for each channel or group.

3. Advanced VoIP Configuration (Optional)

Configure DTMF Signaling under the Advance VoIP section.

  1. From the side-navigation, click Configurations -> Advance VoIP.
  2. Ensure NAT Keep-alive is set to Enable.
  3. Select None from Call OUT Auth Mode.
  4. Select Outband from DTMF Signaling.
  5. Select RFC 2833 from Outband DTMF Type.
  6. Ensure RTP Payload Type is set to 101.
  7. Click Save Changes.
4. Call-In Configuration

Configure caller-id forward mode and VoIP forwarding number.

  1. From the side-navigation, click Configurations -> Call In.
  2. Select Use Remote Party ID from CID Forward Mode.
  3. Ensure Call In is set to Enable.
  4. Fill in Forwarding to VoIP Number with the number you configured in Step 3.
  5. Click Save Changes.

Note: Repeat this step for each channel you need to configure.

5. Testing

Reboot, then test your configuration.

  1. From the side-navigation, click Tools -> Reboot.
  2. From the side-navigation, click Status -> General.
  3. Under Call Status and Setting ensure that Login, Call In and Call Out shows Y in each column.
  4. Test an inbound call by making a call to one of the phone numbers you configured in Step 3.
  5. Test an outbound call using the Account API . Use the credentials from the account you created in Step 2.
6. Advanced Routing Configuration (Optional)

Let's say you have a GoIP-8 with 3 groups of SIM Cards from 3 different mobile operators. Assume you have 4 SIM cards from Telco A, 3 SIM cards from Telco B, and 1 SIM Card from Telco C and you want to route calls from Telco A to group 1, Telco B to group 2 and Telco C to group 3 according to the table below.

No. of SIM cards Telco Prefixes Group Lines
4 Telco A 85510, 85515, 85516 Group 1 Lines 1-4
3 Telco B 85531, 85571, 85597 Group 2 Lines 5-7
1 Telco C 85511, 85512, 85517 Group 3 Line 8

In order to handle this situation complete the following steps.

  1. Configure 3 separate SIP Trunks (one for each Telco) as per the instructions in Step 1 of the Client Configuration Guide.

    For each SIP trunk specify:

    • Max channels. This should equal the number of SIM cards installed for the telco.
    • Route prefixes. A comma separated list of route prefixes for the telco. Must include the country code.
    • Dial string prefix. A unique numeric identifier for the group prepended to the dial string. This will be used by GoIP to identify the channel group.
    • Select National dialing. This will ensure that the national dialing format will be sent to your GoIP.

  2. Configure Basic VoIP configuration for each group created above, as per the instructions in Step 2 of the GoIP Configuration Guide.

    For each group specify:

    • Authentication ID. This should match the Username generated from the previous step.
    • Password. This should match the Password generated from the previous step.
    • SIP Registrar Server. This should match the Domain obtained from the previous step.
    • Routing Prefix: This should match the Dial string prefix configured above.

  3. Configure Call Out configuration for each channel.

    For each channel, specify a Dial Plan to remove the routing prefix setup in the previous step. This removes the prefix before calling out.

7. Additional Resources

Below is a list of additional resources for the GoIP Gateway.


SMS Gateway Configuration Guide

Setting up an SMS Gateway allows independent entities to provide programmable SMS through their own SMS infrastructure.

SMS infrastructure can mean anything from an API connection to a provider that you manage, a simple GSM Modem, or an SMPP connection to a carrier.

Note: Providing programmable SMS as an independent entity isn't restricted to carriers or organizations. Any individual can become an independent entity as long as they have access to their own SMS infrastructure.

How it works

independent entities connect to Somleng via Somleng's SMS Gateway App installed on-premise, or on the cloud infrastructure managed by the independent entity.

Customers can then use the Account API to send and receive SMS though the independent entity's SMS infrastructure.

1. Create an SMS Gateway

Create an SMS gateway via the Dashboard.

  1. Sign in to the Dashboard and from the side-navigation, click SMS Gateways under Messaging.
  2. Click the icon to create a new SMS Gateway.
  3. Enter a name for your SMS Gateway.
  4. Enter the maximum number of channels your SMS gateway supports. Leave it blank for unlimited channels.
  5. Choose Create SMS gateway.

After you create your SMS Gateway you'll see your Device Token on the next screen. You'll need this later in Step 4 when you install the SMS Gateway App.

2. Create an Account

Create an Account via the Dashboard.

Note: You can skip this step if you already have a carrier account setup.

  1. Sign in to the Dashboard and from the side-navigation, click Accounts.
  2. Click the icon to create a new account.
  3. Give the account a name.
  4. Choose Create Account.

You'll need to reference this account when you configure a Phone Number in Step 3 and when testing an outbound message in Step 5.

3. Create and configure a Phone Number

Create a new Phone Number and configure it for inbound messaging.

  1. Sign in to the Dashboard and from the side-navigation, click Phone Numbers.
  2. Click the icon to create a new phone number.
  3. Enter the phone number including he country code in E.164 format.
  4. Link the phone number to the account by selecting the account created in the previous step.
  5. Choose Create Phone number.

After you have created your phone number, you can configure it on the next screen:

  1. Click the dropdown and choose Configure.
  2. Under Messaging enter an SMS URL that returns valid TwiML for Programmable SMS . This will configure the phone number to handle inbound messages. You can use the following URL: https://tinyurl.com/demo-sms which returns valid TwiML.
  3. Choose GET from SMS method if you used the URL above.
  4. Choose Update Configuration.

After you have configured your phone number you can review the configuration on the next screen:

4. Download and Install the Somleng SMS Gateway App

The Somleng SMS Gateway App . is as a gateway between Somleng and your SMS infrastructure.

Detailed instructions on how to install, configure and deploy the app can be found on the Somleng SMS Gateway Github repository . You'll need the Device Token from Step 1. to connect the SMS Gateway App to Somleng.

Once the SMS Gateway app is configured and successfully connected to Somleng, you should see the connection status show Connected the Dashboard.

5. Send an Outbound Message

You can use the Account API to test sending an outbound SMS. Replacing the ACCOUNT-SID and AUTH-TOKEN with the information from the account you created in Step 2 you can use the following code to send an SMS:

curl 'https://api.somleng.org/2010-04-01/Accounts/ACCOUNT-SID/Messages.json' -X POST \
--data-urlencode 'To=+855715100860' \
--data-urlencode 'From=+85568308531' \
--data-urlencode 'Body=Hello from Somleng' \
-u ACCOUNT-SID:AUTH-TOKEN
Note: The From parameter must match the phone number you created in Step 3.

You should see the message appear in the Messages section of the Dashboard.

6. Receive an Inbound Message

In order to test an inbound SMS, simply send a message to the number you configured in Step 3.

If you have configured your phone number correctly you should see the message appear in the Messages section of the Dashboard as shown in Step 5.

If you don't see the message on the Dashboard, you can check the Error Logs section of the Dashboard.

7. Additional Steps

If you need more control over which channels outbound SMS are delivered though, you can configure one or more Channel Groups.

Instead of configuring each phone number individually, like we did in Step 3, you can configure a Messaging Service with shared configuration and apply it to multiple phone numbers.


Installation Guide

This guide is intended to get you up and running with Somleng on your local machine. It is not intended for production. If you are just getting started with Somleng we recommend following the Getting Started guide before attempting to install Somleng on your local machine.

Prerequisites

  1. Install Docker and git on your local machine.

Overview

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

  1. Clone the somleng-project repository.
  2. Pull the latest Docker images.
  3. Start Somleng.
  4. Seed the Database.
  5. Log in to the Dashboard.

1. Clone the somleng-project repository.

Clone the somleng-project repository.

git clone https://github.com/somleng/somleng-project.git && cd somleng-project

2. Pull the latest Docker images.

docker compose pull

3. Start Somleng.

docker compose up

4. Seed the Database

docker compose exec somleng bundle exec rails db:setup
You should get the following output:
Account SID:              account-sid
Auth Token:               auth-token
Phone Number:             1294
SMS Gateway Device Token: sms-gateway-device-token
---------------------------------------------
URL:                      http://my-carrier.app.lvh.me:3000/
Carrier User Email:       johndoe@carrier.com
Carrier User Password:    Somleng1234!
Carrier API Key:          carrier-api-key

5. Log in to the Dashboard

You should be now able to log in to the Somleng dashboard at http://my-carrier.app.lvh.me:3000 with the credentials from the output of the previous step.

Note: You'll need to setup two factor authentication (2FA) after the first time you sign in to the Dashboard. You can use the Authenticator browser extension if you don't already have another 2FA application.


RTP and Symmetric Latching

In IP address authentication mode SIP and RTP from Somleng is sent through a NAT Gateway. This means that the ports specified in the SDP in the SIP Invite from Somleng are unreachable which normally causes one-way audio issues. To work-around this problem, it is required that you enable Symmetric Latching and NAT traversal in your configuration.

Symmetric RTP means that the IP address and port pair used by an outbound RTP flow is reused for the inbound flow. The IP address and port are learned when the initial RTP flow is received on your device. The flow's source address and port are latched onto and used as the destination for the RTP sourced by the other side of the call. The IP address and port in the c line and m line respectively in the SDP message are ignored.

If your configuration does not support symmetric latching we can configure your account to use a symmetric NAT. Currently this option is not configurable on the dashboard. Please contact us for assistance.