Documentation

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 Phone Number.

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

Perform the following steps:

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

3. Create a Verification Service.

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

Perform the following steps:

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

4. Create a SMS Gateway.

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

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

Perform the following steps:

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

5. Create a SIP Trunk.

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

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

Perform the following steps:

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

6. Run the Somleng SMS Gateway Application.

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

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

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

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

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

7. Register your softphone with the SIP Trunk.

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

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

To configure your softphone perform the following steps:

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

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

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

8. Start a new Verification Flow

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

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

Run the code below substituting the following:

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

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

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

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

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

10. Resend the verification code via a call.

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

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

11. Receive the verification via a call.

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

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

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

12. Complete the flow by confirming the verification code.

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

Run the code below, substituting the following:

1. Set accountSid and 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.

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 Phone Number is required to send out verification codes.
3. 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.
4. An SMS Gateway is used to deliver SMS messages including verification codes.
5. A SIP Trunk is used to send voice calls including verification codes.
6. 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.
7. The somleng-node helper library can be used to start and check verification flows from your application.

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 13.250.230.15/32. This is 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. Select 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.

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.

Prerequisites

1. Complete the Build your own Phone Verification Service tutorial.
2. Optionally complete the Connect Somleng to Amazon Chime tutorial.

Overview

Below is an overview of the steps that we'll cover in this tutorial:

1. Update your carrier settings.
2. Create a new Account for your customer.
3. Log in to the Dashboard as if you are the customer.
4. Explore the Dashboard and API docs from the customer's perspective.
5. Use the API from the customer's perspective.
6. Control API Access for your customer.

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.

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.

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:

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

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

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:

• GoIP .

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.

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

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

Account SID:           account-sid
Auth Token:            auth-token
Phone Number:  1234
---------------------------------------------
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.