Carrier Documentation

Authentication

You must sign into 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 instead.

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.

A word of warning. If you update your sudomain

Accounts

Accounts are used by carriers, carrier customers and BYOC users to send/receive calls and SMS via Somleng's implementation of Twilio's REST API.

Typically a carrier would create an account for each of their customers. BYOC users might create an account for each project or just create one account for their usage.

There are two types of accounts. Carrier managed and customer managed.

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.

Inbound SIP Trunks

Inbound SIP Trunks are used to configure inbound dialing to Somleng (aka Direct Inbound Dialing). When you create an Inbound SIP Trunk you specify the source IP address from which SIP invite is sent from. Somleng uses this information to determine the carrier, account and how to handle the call.

Once you have setup your inbound SIP trunk, you can then send SIP to any of the following endpoints. We recommend that you use sip.somleng.org for high-availability.

To create an inbound SIP trunk via the Dashboard:

1. Sign in to the Dashboard and from the side-navigation, click Inbound SIP Trunks.
2. Click the icon to create a new inbound SIP trunk.
3. Fill out the form, specifying a friendly name for the inbound SIP trunk and the source IP address.
4. Choose Create Inbound SIP Trunk.

Outbound SIP Trunks

Outbound SIP Trunks are used to configure outbound dialing from Somleng. When you create an Outbound SIP Trunk you specify the destination host to send outbound calls. You can specify your host as either a fully qualified domain name (FQDN) or IP address. The outbound SIP trunk configuration determines the dial string that will be used to send calls to your SIP server.

SIP and RTP from Somleng sent through a NAT Gateway from the IP address below. You should allow this IP address on your firewall. You may also need to setup Symmetric Latching on your device.

To create an outbound SIP trunk via the Dashboard:

1. Sign in to the Dashboard and from the side-navigation, click Outbound SIP Trunks.
2. Click the icon to create a new outbound SIP trunk.
3. Fill out the form, specifying a friendly name for the outbound SIP trunk and the host. You can also optionally configure a numeric dial string prefix, add a plus prefix or configure a trunk prefix.
4. Choose Create Outbound SIP Trunk.

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 be configured with a Voice URL which returns TwiML for controlling the call. This can either be done by the carrier or by the account owner (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. Fill out the form specifying a Voice URL and optionally a Status Callback URL. The Voice URL should return valid TwiML and will be executed when an inbound call is received by Somleng.
4. Choose Update Configuration.

Import Phone Numbers

In order to bulk import phone numbers, you can upload a CSV file from the Dashboard.

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

Sample CSV Data

Number,Enabled
1234,false
85512345678,true

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.

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 that 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 that 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 that the API is always available at api.somleng.org regardless of whether you set a custom API host or not.