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 User An individual or organization who has a business relationship with a carrier. BYOC stands for Bring Your Own Carrier.
Network Provider An individual or organization with their own VoIP gateway to access the PSTN.

Audience

This documentation is intended for Carriers and BYOC Users, and Network Providers as defined above.

Introduction

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

There are three kinds of use-cases depending on who you are.

  1. Carriers use Somleng to offer their own branded CPaaS services to their customers.
  2. BYOC users use Somleng directly or offer CPaaS services to their customers by connecting through a carrier that they have a business relationship with.
  3. Network Providers use Somleng directly or offer CPaaS services to their customers by connecting through a VoIP Gateway that they own or manage.

Getting Started

We recommend you try out Somleng by signing up for a carrier account here . If you're looking to install Somleng on your local machine read the Getting Started Guide . Note: This requires some technical knowledge.

Once you have an account you can begin configuring your it to handle programmable voice and SMS.

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 users and network providers to send/receive calls and SMS via the Account API .

Typically a carrier would create an account for each of their customers. BYOC users and network providers 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 Content Possible Values Example
Number The phone number or short code E.164 formatted number or short code. e.g. 85512345678 or 1234 1234
Enabled Whether to enable or disable the phone number true or false defaults to true true

Sample CSV Data
  Number,Enabled
  1234,false
  85512345678,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 users.
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 network providers.

IP Address Authentication

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

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:
    • 52.74.4.205
    • 18.136.239.28
    • 3.0.30.251
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 address on your firewall:
    • 13.250.230.15
    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 Network Providers.

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.

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 network providers 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.

Users

Carrier owners can invite their colleagues to the dashboard.

To invite a user to the Dashboard:

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

The user will receive an email inviting them to the dashboard. Users with the owner role can manage other users, update their role and reset their 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 network providers to use Somleng with their own VoIP gateway which provides access the PSTN, thereby removing the need for a commercial agreement with a carrier.

Note: Being a network provider isn't restricted to carriers or organizations. Any individual can become a network provider as long as they have access to a VoIP Gateway.

How it works

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

The network provider 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. 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
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.

Config Mode Description
Single Server Mode Use this mode to associate all channels on your GoIP gateway to a single SIP Trunk on Somleng.
Note: You can use this mode together with a Routing Prefix to control which channel an outbound call with be routed to. Please refer to the GoIP User Manual for more information about Routing Prefix and the channel selection algorithm.
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.
Note: This mode requires you so set a Routing Prefix for each group.
  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

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.

SMS Gateway Configuration Guide

Setting up an SMS Gateway allows network providers 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 a network provider isn't restricted to carriers or organizations. Any individual can become a network provider as long as they have access to their own SMS infrastructure.

How it works

Network providers connect to Somleng via Somleng's SMS Gateway App installed on-premise, or on the cloud infrastructure managed by the network provider.

Customers can then use the Account API to send and receive SMS though the network provider'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.

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.