Documentation

Setting up Programmable Voice with Amazon Chime

After following this guide you'll be able to use the Somleng API to initiate control voice calls via your Amazon Chime account.

The following diagram shows how it works:

Overview

Below is an overview of the steps required to configure programmable voice via Amazon Chime:

1. Create a new Amazon Chime Voice Connector
2. Assign a new phone number to the connector
3. Sign up for a free Somleng Carrier Account
4. Configure a SIP Trunk
5. Create an account
6. Assign a phone number
7. Test it out

4. Configure a SIP trunk

Under the Voice menu, create a new SIP trunk.

1. Under Authentication mode, choose IP address.
2. Give your SIP trunk a name, e.g. Amazon Chime
3. Under Outbound Dialing, set the Host to the Outbound host name that was generated when you created the Amazon Chime Voice connector in Step 1. The value should be your-host.voiceconnector.chime.aws
4. Ensure that you enable Plus prefix. This is required by Amazon Chime.

5. Create an account

Under the Accounts menu, create a new account.

1. Give the account a name.
2. Press Create Account. The rest of the form is optional.

6. Assign a phone number

Under the Phone Numbers menu, create a phone number and assign it to the account created in the previous step.

1. Enter the number that you assigned to your Chime Voice Connector in Step 2.
2. Select the account that you created in Step 5.
3. Ensure the phone number is Enabled.
4. Press Create Phone Number

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:

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.

• To configure inbound dialing, set a Voice URL which should return valid TwiML for Programmable Voice
• To configure inbound messaging, set a SMS URL which should return valid TwiML for Programmable SMS

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.

  number,enabled,account_sid
  1234,false,ccdb7202-e487-436c-b964-c3acb7884c8f
  85512345678,true

Voice

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

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

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.

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.

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:

• GoIP .

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.

Configuration Overview

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

1. Create an SMS Gateway
2. Create an Account
3. Create and configure a Phone Number
4. Install the Somleng SMS Gateway App
5. Send an Outbound Message
6. Receive an Inbound Message
7. Additional Steps