var notebook = RunKit.createNotebook({
element: document.getElementById("verify-tutorial-step-10-snippit"),
nodeVersion: "18.x.x",
- source: "// IMPORTANT: This code requires somleng-node >= 4.20.2\n// Due to an issue with RunKit the latest version might not be always available.\n// If you have issues running the code in RunKit, please try running it locally with the latest version of somleng-node.\n// Download the helper library from https://github.com/somleng/somleng-node and follow the instructions\n\n// Find your Account SID and Auth Token from the Somleng console\n// and set the environment variables.\n// const accountSid = process.env.SOMLENG_ACCOUNT_SID;\n// const authToken = process.env.SOMLENG_AUTH_TOKEN;\nconst accountSid = \"change-me\";\nconst authToken = \"change-me\";\nconst verificationServiceSid = \"change-me\";\nconst client = require('somleng')(accountSid, authToken);\n\nclient.verify.v2.services(verificationServiceSid)\n .verifications\n .create({to: '+15017122661', channel: 'call'})\n .then(verification => console.log(verification.sid));",
+ source: "// IMPORTANT: This code requires somleng-node >= 4.20.2\n// Due to an issue with RunKit the latest version might not be always available.\n// If you have issues running the code in RunKit, please try running it locally with the latest version of somleng-node.\n// Download the helper library from https://github.com/somleng/somleng-node and follow the instructions\n\n// Download the helper library from somleng.org/docs/twilio_api/#helper-libraries\n// Find your Account SID and Auth Token from the Somleng console\n// and set the environment variables.\n// const accountSid = process.env.SOMLENG_ACCOUNT_SID;\n// const authToken = process.env.SOMLENG_AUTH_TOKEN;\n\nconst accountSid = \"change-me\";\nconst authToken = \"change-me\";\nconst verificationServiceSid = \"change-me\";\nconst to = \"+15017122661\";\nconst channel = \"call\";\nconst client = require('somleng')(accountSid, authToken);\n\nclient.verify.v2.services(verificationServiceSid)\n .verifications\n .create({to: to, channel: channel})\n .then(verification => console.log(verification.sid));",
})
@@ -862,7 +865,7 @@
var notebook = RunKit.createNotebook({
element: document.getElementById("verify-tutorial-step-12-snippit"),
nodeVersion: "18.x.x",
- source: "// IMPORTANT: This code requires somleng-node >= 4.20.2\n// Due to an issue with RunKit the latest version might not be always available.\n// If you have issues running the code in RunKit, please try running it locally with the latest version of somleng-node.\n// Download the helper library from https://github.com/somleng/somleng-node and follow the instructions\n\n// Find your Account SID and Auth Token from the Somleng console\n// and set the environment variables.\n// const accountSid = process.env.SOMLENG_ACCOUNT_SID;\n// const authToken = process.env.SOMLENG_AUTH_TOKEN;\nconst accountSid = \"change-me\";\nconst authToken = \"change-me\";\nconst verificationServiceSid = \"change-me\";\nconst verificationCode = \"change-me\"\nconst client = require('somleng')(accountSid, authToken);\n\nclient.verify.v2.services(verificationServiceSid)\n .verificationChecks\n .create({to: '+15017122661', code: verificationCode})\n .then(verification_check => console.log(verification_check.status));",
+ source: "// IMPORTANT: This code requires somleng-node >= 4.20.2\n// Due to an issue with RunKit the latest version might not be always available.\n// If you have issues running the code in RunKit, please try running it locally with the latest version of somleng-node.\n// Download the helper library from https://github.com/somleng/somleng-node and follow the instructions\n\n// Download the helper library from somleng.org/docs/twilio_api/#helper-libraries\n// Find your Account SID and Auth Token from the Somleng console\n// and set the environment variables.\n// const accountSid = process.env.SOMLENG_ACCOUNT_SID;\n// const authToken = process.env.SOMLENG_AUTH_TOKEN;\n\nconst accountSid = \"change-me\";\nconst authToken = \"change-me\";\nconst verificationServiceSid = \"change-me\";\nconst to = \"+15017122661\";\nconst verificationCode = \"change-me\"\nconst client = require('somleng')(accountSid, authToken);\n\nclient.verify.v2.services(verificationServiceSid)\n .verificationChecks\n .create({to: to, code: verificationCode})\n .then(verification_check => console.log(verification_check.status));",
})
@@ -1363,917 +1366,1355 @@ 🎉 Congratulations!
-
-
-
-
-
-
- Using the Dashboard
-
-
- The dashboard can be used to manually provision carrier resources.
- Use the Carrier API
- to automate the provisioning of carrier resources.
-
+
+
+ Invite customers to use your CPaaS
+
-
-
- 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.
+ So far, you've learned how to
+ build your own phone verification service, and optionally
+ connected it to
+ Amazon Chime. You have essentially built your own branded, Communications Platform as a Service
+ or CPaaS.
-
-
-
- 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:
-
- -
- Sign in to the Dashboard and from the side-navigation, click Carrier Settings.
-
- -
- Click the icon to edit your settings.
-
- -
- Make your desired changes.
-
- -
- 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:
+ In this tutorial you'll learn how to invite your own customers to use your new CPaaS. Your
+ customers will
+ be able to
+ integrate phone verifications and programmable voice and messaging into their own
+ applications, while
+ you remain in complete control over their access.
-
-
-
-
- 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:
-
- -
- Sign in to the Dashboard and from the side-navigation, click Accounts.
-
- -
- Click the icon to create a new account.
-
- -
- Fill out the form, specifying a name for the account and optionally the owner's name and email
- address to create a customer account.
-
- -
- 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:
-
- -
- Sign in to the Dashboard and from the side-navigation, click Phone Numbers.
-
- -
- Click the icon to create a new phone number.
-
- -
- Fill out the form, specifying the phone number or short code, and optionally assign it to an
- account.
-
- -
- Choose Create Phone number.
-
-
-
-
- Once the phone number has been created, you can configure it. To configure a phone number via the
- Dashboard:
-
- -
- From the Phone Numbers page, find the phone number you want to configure.
-
- -
- From the gear icon select Configure.
-
- -
- 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.
-
-
-
- -
- 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.
-
-
-
- -
- Choose Update Configuration.
-
-
-
+
+
+ Prerequisites
+
-
- After you have configured a phone number, the configuration will be shown on the next screen.
-
+
+ -
+ Complete the Build your own Phone Verification Service
+ tutorial.
+
+ -
+ Optionally complete the Connect Somleng to Amazon Chime
+ tutorial.
+
+
+
- 
+
+
+ Overview
+
-
-
- 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:
+ Below is an overview of the steps that we'll cover in this tutorial:
+
+
-
- From the Phone Numbers page, click the upload button .
+ Update your carrier settings.
+
+ -
+ Create a new Account for your
+ customer.
-
- Select the CSV file of phone numbers to import.
+ Log in to the Dashboard as if you are the
+ customer.
-
- Choose Upload.
+ Explore the Dashboard and API docs from
+ the customer's perspective.
+
+ -
+ Use the API from the customer's
+ perspective.
+
+ -
+ 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.
-
-
-
- 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 truetrue
-
- account_sid
- Optionally associate an account with the phone number
- SID of account to associate
- ccdb7202-e487-436c-b964-c3acb7884c8f
-
-
+ Perform the following steps:
-
- Sample CSV Data
-
+
+ -
+ Click on Carrier Settings from the main menu.
+
+ -
+ Upload your company's logo.
+
+ -
+ Optionally update other details about your company.
+
+ -
+ Press Update Carrier Settings.
+
+
-
- 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.
-
+
+
+ 2. Create a new Account for your customer.
+
-
-
- 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:
+ 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.
+
-
-
-
- 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.
-
-
-
-
+ Perform the following steps:
-
-
- IP Address Authentication
-
-
- Note: This mode is best suited for Carriers and BYOC users.
-
+
+ -
+ Under the Accounts menu, click the
+ icon to create a new account.
+
-
-
- Inbound Dialing
-
+ -
+ Give the account a name.
+
-
- When you configure a SIP trunk for inbound dialing via IP address
- authentication the following rules apply:
-
-
- -
- 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.
-
- -
- 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
-
-
-
-
-
+ -
+ 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.
+
+
-
-
- Outbound Dialing
-
+ -
+ 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.
+
-
- When you configure a SIP trunk for outbound dialing via IP address
- authentication the following rules apply:
-
-
- -
- You must provide a host to connect to. You can specify your host as either a fully
- qualified domain name (FQDN) or IP address.
-
- -
- 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.
-
- -
- You must support NAT Traversal and Symmetric Latching. Read more.
-
-
-
+ -
+ Press Create Account.
+
+
-
- To configure a SIP trunk via IP address authentication:
-
- -
- Sign in to the Dashboard and from the side-navigation, click SIP Trunks.
-
- -
- Click the icon to create a new SIP trunk.
-
- -
- Under General, select IP address for Authentication mode.
-
- -
- Under Inbound Dialing, enter a public static IP address for inbound call authentication.
-
- -
- Under Outbound Dialing, enter a domain name or IP address for outbound calls.
-
- -
- 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:
-
- -
- Sign in to the Dashboard and from the side-navigation, click SIP Trunks.
-
- -
- Click the icon to create a new SIP trunk.
-
- -
- Under General, select Client credentials for Authentication mode.
-
- -
- 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.
-
- -
- Choose Create SIP Trunk.
-
-
-
-
-
- After you create your SIP Trunk you'll see the generated credentials on the next screen.
-
- 
-
-
+ 
-
-
- Text To Speech (TTS)
-
+
+
+ 3. Log in to the Dashboard as if you are the customer.
+
- Text To Speech (TTS), also known as speech synthesis, is a process in which text is converted into a
- human-sounding voice.
+ 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.
- The <Say> verb allows you to provide plain text that Somleng converts to
- synthesized speech.
-
- For example, when Somleng executes the following TwiML during a call, the caller hears "Hello
- world!"
- The synthesized voice the caller hears is the default voice and language of the Somleng Account
- (configured in the Account Settings).
+
+ 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.
+
-
-
<Response>
- <Say>Hello world!</Say>
-</Response>
-
+ Perform the following steps:
-
-
-
- <Say> also allows you to modify the language, accent, and voice of the synthesized
- speech via the language and voice attributes.
- The example below uses Amazon Polly's "Joanna" voice and American English:
-
-
-
<Response>
- <Say language="en-US" voice="Polly.Joanna">Hello. I am Joanna and I speak American English!</Say>
-</Response>
-
-
-
-
-
- The language attribute of <Say> also allows you to override the default voice that is
- configured for the Somleng Account.
- For example, if the account's default TTS voice is Polly.Joanna (Female, en-US), but wish
- to use German for a specific call, set the language attribute to de-DE in your
- TwiML.
- This will choose another voice from the Polly provider which supports German.
-
-
-
-
<Response>
- <Say language="de-DE">Hallo. Ich spreche Deutsch!</Say>
-</Response>
-
-
+
+ -
+ Click on your avatar in the top right corner and select
+ Logout from the dropdown.
+
-
- Note: the TTS provider is always preserved when using this feature.
- For example if the account's default TTS voice is Basic.Kal (Male, en-US), using the TwiML
- above won't have any effect
- because German is not available in the Basic provider.
-
+ -
+ Check your email. You should have received a customer invitation email when completing the
+ previous step.
+
-
- You can also use Premium voices which are generated using the latest technology and innovation in
- synthesized speech,
- providing the most human-like, expressive and natural-sounding text-to-speech voices possible, with
- higher quality than Standard voices.
- The voices in this tier are currently provided by Amazon (Amazon Polly Neural).
-
+ -
+ Follow the link in the email and set your password.
+
-
- As well as setting the default TTS voice to a premium voice in the dashboard, you can also use the
- voice attribute to override a premium voice.
- For example:
+
-
+ Setup two factor authentication (2FA).
+
+
-
-
<Response>
- <Say voice="Polly.Danielle-Neural">Hello. I am Danielle!</Say>
-</Response>
-
-
+
+ You should now be viewing the dashboard from the customer's perspective.
+
-
-
- Messaging
-
-
- This section contains everything you need related to configuring programmable SMS.
-
+ 
+ 
+
-
-
- SMS Gateways
-
+
+
+ 4. Explore the Dashboard and API docs from the customer's perspective.
+
- SMS Gateways are used by Somleng for SMS origination and termination.
- Configuring an SMS Gateway allows you to fully control your own SMS infrastructure.
+ In this step, feel free to click around and explore the Dashboard from the customer's perspective.
- 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.
+ Notice the following:
-
- To configure an SMS Gateway:
-
- -
- Sign in to the Dashboard and from the side-navigation, click SMS Gateways under
- Messaging.
-
- -
- Click the icon to create a new SMS Gateway.
-
+
-
- Enter a name for your SMS Gateway.
+ Your company's logo appears in the top left of the Dashboard.
- -
- Enter the maximum number of channels your SMS gateway supports. Leave it blank for unlimited
- channels.
+
- 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.
-
- Choose Create SMS gateway.
+ The API docs are branded with your company's name and logo.
-
-
-
-
- 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.
-
+
+
+ 5. Use the API and Dashboard from the customer's perspective.
+
- 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".
+ In this step, you'll explore using the Verify API from the customer's perspective.
- 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.
+ Perform the following steps:
-
- To configure a Channel Group:
-
- -
- Sign in to the Dashboard and from the side-navigation, click Channel Groups under
- Messaging.
-
+
-
- Click the icon to create a new Channel Group.
+ Under the Verify menu, select Services.
+
-
- Enter a name for your Channel Group.
+ Click the icon to create a new verification service.
+
-
- Assign the channel group to an SMS Gateway.
+ Give your verification service a friendly name.
+
-
- 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.
+ 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:
+
+
+
-
- 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.
+ Set
accountSid and authToken from the
+ values shown on the Account Settings page.
-
- Choose Create Channel group.
+ 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.
- After you have created your Channel Group you can see the configuration details.
+ 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:
+
+
+
+ -
+ Click on your customer's avatar in the top right corner and select
+ Logout from the dropdown.
+
+
+ -
+ Log in to your carrier account.
+
+
+ -
+ Under the Accounts menu, click the SID of the Account belonging to your
+ customer.
+
+
+ - Click the button.
+
+ -
+ Notice that most of the fields are disabled, but you can toggle the Enabled
+ switch.
+
+
+ -
+ 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.
+
+
+ 
+
-
-
- Messaging Services
-
+
+ 🎉 Congratulations!
- Messaging services allow you to apply messaging configuration to of a group of phone numbers, rather
- than having to configure each
- one individually.
+ Congratulations! You have successfully completed this tutorial and invited your first customer to
+ use your CPaaS.
- To configure an Messaging Service:
+ What we learned:
+
+
-
- Sign in to the Dashboard and from the side-navigation, click Messaging Services
- under Messaging.
-
- -
- Click the icon to create a new Messaging Service.
+ 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.
+
-
- Enter a name for your Messaging Service.
+ 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.
+
-
- Choose Next.
+ The customer can use the API and helper libraries in his own applications.
+
-
- 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.
+ The customer can only see the data (phone calls, messages, verifications etc) that belongs to him.
+
-
- 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.
-
-
+ You can control the customer's API access from the carrier dashboard.
+
+
+
+
+
+
+
+
+ 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:
+
-
- 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.
+ Sign in to the Dashboard and from the side-navigation, click Carrier Settings.
-
- Optionally configure a Status Callback URL for all outbound messages in the sender pool.
+ Click the icon to edit your settings.
-
- Configure Smart encoding for outbound messages. If this is turned on Smart encoding will apply to
- all outbound messages in the number pool.
+ Make your desired changes.
-
- Choose Create Messaging service.
+ Choose Update Carrier Settings.
+
+
+
+ Accounts
+
- After you have configured your messaging service you can see the configuration details.
+ Accounts are used by carriers, carrier customers, BYOC entities and independent entities to
+ send/receive
+ calls and SMS via the Account API .
-
- 
-
-
-
-
- Users
-
+
+ Typically a carrier would create an account for each of their customers.
+ BYOC entities and independent entities on the other hand might create an account for each customer
+ or
+ project or just create one global account for their own usage.
+
+
+ There are two types of accounts. Carrier managed and customer managed described below:
+
+
+
+
+
+
+ Account type
+ Description
+
+
+
+
+ Carrier Managed
+
+ Carrier managed accounts are managed by carriers.
+ These types of accounts can be either used by carriers themselves, or by the carrier's
+ customers.
+
+
+
+ Customer Managed
+
+ Customer managed accounts are managed by the carrier's customers directly.
+ These types of accounts can be created via the dashboard by specifying an account owner when
+ creating the account.
+ After providing the account owner's name and email address, the owner will be invited to the
+ dashboard and can manage their own account.
+ The customer will also have access to their Account SID and Auth Token.
+ The carrier can still disable and enable customer accounts from the Dashboard.
+
+
+
+
+
+
+ To create an account via the Dashboard:
+
+ -
+ Sign in to the Dashboard and from the side-navigation, click Accounts.
+
+ -
+ Click the icon to create a new account.
+
+ -
+ Fill out the form, specifying a name for the account and optionally the owner's name and email
+ address to create a customer account.
+
+ -
+ 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:
+
+ -
+ Sign in to the Dashboard and from the side-navigation, click Phone Numbers.
+
+ -
+ Click the icon to create a new phone number.
+
+ -
+ Fill out the form, specifying the phone number or short code, and optionally assign it to an
+ account.
+
+ -
+ Choose Create Phone number.
+
+
+
+
+ Once the phone number has been created, you can configure it. To configure a phone number via the
+ Dashboard:
+
+ -
+ From the Phone Numbers page, find the phone number you want to configure.
+
+ -
+ From the gear icon select Configure.
+
+ -
+ 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.
+
+
+
+ -
+ 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.
+
+
+
+ -
+ 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:
+
+ -
+ From the Phone Numbers page, click the upload button .
+
+ -
+ Select the CSV file of phone numbers to import.
+
+ -
+ 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 truetrue
+
+ account_sid
+ Optionally associate an account with the phone number
+ SID of account to associate
+ ccdb7202-e487-436c-b964-c3acb7884c8f
+
+
+
+
+
+ Sample CSV Data
+
+
+
+ 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.
+
+
+
+
+ SIP Trunks
+
+
+ SIP Trunks are used to configure both inbound and outbound dialing, both to and from Somleng.
+ We define inbound dialing (also known as Direct Inbound Dialing (DID)) as calls terminated by
+ Somleng,
+ and outbound dialing as calls originated by Somleng.
+
+
+ When you create a SIP Trunk you first choose the authentication mode. There are two authentication
+ modes available described below:
+
+
+
+
+
+ Authentication mode
+ Description
+
+
+
+
+ IP Address
+
+ Choose this mode if you have a public static IP address and are not behind
+ a
+ NAT.
+ This mode is best suited for carriers and BYOC entities.
+
+
+
+ Client Credentials
+
+ Choose this mode if you do not have a public static IP address or are
+ behind
+ a NAT.
+ This mode is best suited for independent entities.
+
+
+
+
+
+
+
+
+ IP Address Authentication
+
+
+ Note: This mode is best suited for Carriers and BYOC entities.
+
+
+
+
+ Inbound Dialing
+
+
+
+ When you configure a SIP trunk for inbound dialing via IP address
+ authentication the following rules apply:
+
+
+ -
+ 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.
+
+ -
+ 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:
+
+
+ -
+ You must provide a host to connect to. You can specify your host as either a fully
+ qualified domain name (FQDN) or IP address.
+
+ -
+ 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.
+
+ -
+ You must support NAT Traversal and Symmetric Latching. Read more.
+
+
+
+
+
+ To configure a SIP trunk via IP address authentication:
+
+ -
+ Sign in to the Dashboard and from the side-navigation, click SIP Trunks.
+
+ -
+ Click the icon to create a new SIP trunk.
+
+ -
+ Under General, select IP address for Authentication mode.
+
+ -
+ Under Inbound Dialing, enter a public static IP address for inbound call authentication.
+
+ -
+ Under Outbound Dialing, enter a domain name or IP address for outbound calls.
+
+ -
+ Choose Create SIP Trunk.
+
+
+
+
+
+ After you create your SIP Trunk you'll see the configuration details on the next screen.
+
+
+
+
+
+
+
+ Client Credentials Authentication
+
+
+ Note: This mode is best suited for independent entities.
+
+
+
+ When you configure a SIP trunk via client credentials authentication you
+ don't need a public
+ status IP address. Instead you authenticate with Somleng via SIP registration. After you
+ configure
+ a SIP trunk in this mode
+ you will be given a unique set of client credentials which can be used to authenticate with
+ Somleng. These credentials
+ can be used directly when configuring your client gateway.
+
+
+
+ To configure a SIP trunk via client credentials authentication:
+
+ -
+ Sign in to the Dashboard and from the side-navigation, click SIP Trunks.
+
+ -
+ Click the icon to create a new SIP trunk.
+
+ -
+ Under General, select Client credentials for Authentication mode.
+
+ -
+ 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.
+
+ -
+ Choose Create SIP Trunk.
+
+
+
+
+
+ After you create your SIP Trunk you'll see the generated credentials on the next screen.
+
+
+
+
+
+
+
+
+ Text To Speech (TTS)
+
+
+
+ Text To Speech (TTS), also known as speech synthesis, is a process in which text is converted into
+ a
+ human-sounding voice.
+
+
+
+ The <Say> verb allows you to provide plain text that Somleng converts to
+ synthesized speech.
+
+ For example, when Somleng executes the following TwiML during a call, the caller hears "Hello
+ world!"
+ The synthesized voice the caller hears is the default voice and language of the Somleng Account
+ (configured in the Account Settings).
+
+
+
+
+
<Response>
+ <Say>Hello world!</Say>
+</Response>
+
+
+
+
+
+
+ <Say> also allows you to modify the language, accent, and voice of the
+ synthesized
+ speech via the language and voice attributes.
+ The example below uses Amazon Polly's "Joanna" voice and American English:
+
+
+
<Response>
+ <Say language="en-US" voice="Polly.Joanna">Hello. I am Joanna and I speak American English!</Say>
+</Response>
+
+
+
+
- Carrier owners can invite their colleagues to the dashboard.
+ The language attribute of <Say> also allows you to override the default voice that
+ is
+ configured for the Somleng Account.
+ For example, if the account's default TTS voice is Polly.Joanna (Female, en-US), but wish
+ to use German for a specific call, set the language attribute to de-DE in
+ your
+ TwiML.
+ This will choose another voice from the Polly provider which supports German.
+
- To invite a user to the Dashboard:
-
- -
- Sign in to the Dashboard and from the side-navigation, click Users.
-
- -
- Click the icon to invite a new user.
-
- -
- Fill out the form, specifying the user's name, email and role.
- -
- Choose Send an invitation.
-
-
+ <Response>
+ <Say language="de-DE">Hallo. Ich spreche Deutsch!</Say>
+</Response>
+
+
- 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.
+ Note: the TTS provider is always preserved when using this feature.
+ For example if the account's default TTS voice is Basic.Kal (Male, en-US), using the
+ TwiML
+ above won't have any effect
+ because German is not available in the Basic provider.
-
-
-
-
-
-
- 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.
-
+
+ You can also use Premium voices which are generated using the latest technology and innovation in
+ synthesized speech,
+ providing the most human-like, expressive and natural-sounding text-to-speech voices possible, with
+ higher quality than Standard voices.
+ The voices in this tier are currently provided by Amazon (Amazon Polly Neural).
+
-
-
- How it works
-
+
+ As well as setting the default TTS voice to a premium voice in the dashboard, you can also use the
+ voice attribute to override a premium voice.
+ For example:
- 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.
+
<Response>
+ <Say voice="Polly.Danielle-Neural">Hello. I am Danielle!</Say>
+</Response>
+
+
+
+
+ Messaging
+
+
+ This section contains everything you need related to configuring programmable SMS.
+
+
+
+
+ SMS Gateways
+
+
+
+ SMS Gateways are used by Somleng for SMS origination and termination.
+ Configuring an SMS Gateway allows you to fully control your own SMS infrastructure.
+
+
+
+ When you configure an SMS gateway on the Dashboard,
+ you receive a Device Token which uniquely identifies your SMS Gateway.
+ You'll then need to install the
+ Somleng SMS Gateway
+ App
+ on your on-premise or cloud infrastructure.
+ Normally, you'll only need to configure a single SMS Gateway, however if you require multiple SMS
+ gateways, you'll need to run an instance of the
+ for each one. Once the app is running on your local infrastructure and connected to Somleng,
+ the SMS Gateway will show Connected on the Dashboard.
+
+
+
+ To configure an SMS Gateway:
+
+ -
+ Sign in to the Dashboard and from the side-navigation, click SMS Gateways under
+ Messaging.
+
+ -
+ Click the icon to create a new SMS Gateway.
+
+ -
+ Enter a name for your SMS Gateway.
+
+ -
+ Enter the maximum number of channels your SMS gateway supports. Leave it blank for unlimited
+ channels.
+
+ -
+ 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:
+
+ -
+ Sign in to the Dashboard and from the side-navigation, click Channel Groups
+ under
+ Messaging.
+
+ -
+ Click the icon to create a new Channel Group.
+
+ -
+ Enter a name for your Channel Group.
+
+ -
+ Assign the channel group to an SMS Gateway.
+
+ -
+ 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.
+
+ -
+ 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.
+
+ -
+ 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:
+
+ -
+ Sign in to the Dashboard and from the side-navigation, click Messaging Services
+ under Messaging.
+
+ -
+ Click the icon to create a new Messaging Service.
+
+ -
+ Enter a name for your Messaging Service.
+
+ -
+ Choose Next.
+
+ -
+ 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.
+
+ -
+ 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.
+
+
+
+ -
+ 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.
+
+ -
+ Optionally configure a Status Callback URL for all outbound messages in the sender pool.
+
+ -
+ Configure Smart encoding for outbound messages. If this is turned on Smart encoding will apply
+ to
+ all outbound messages in the number pool.
+
+ -
+ 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:
+
+ -
+ Sign in to the Dashboard and from the side-navigation, click Users.
+
+ -
+ Click the icon to invite a new user.
+
+ -
+ Fill out the form, specifying the user's name, email and role.
+ -
+ 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.
+
+
-
-
- Setup your custom domain
-
+
+
+
+
+ Custom Domain Configuration Guide
+
- Follow the steps below to configure your custom domain:
-
- -
- Setup a reverse proxy via AWS Cloudfront (recommended)
- or Nginx.
-
- -
- Test out your custom domain.
-
- -
- Configure
- your custom domain via the Somleng Dashboard.
-
-
+ 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.
-
-
-
- 1(a). Configure an AWS Cloudfront Distribution (Recommended)
-
+
+
+ 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
+
-
- Skip this step if you prefer to use Nginx instead.
-
+
+ Follow the steps below to configure your custom domain:
+
+ -
+ Setup a reverse proxy via AWS Cloudfront (recommended)
+ or Nginx.
+
+ -
+ Test out your custom
+ domain.
+
+ -
+ Configure
+ your custom domain via the Somleng Dashboard.
+
+
+
+
-
- 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 .
-
-
+
+
+ 1(a). Configure an AWS Cloudfront Distribution (Recommended)
+
-
-
- Using the Terraform Module (Recommended)
-
+
+ Skip this step if you prefer to use Nginx instead.
+
-
- 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.
-
-
-
+
+ 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"
@@ -2296,1668 +2737,1689 @@
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"
+# 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
+
+
+
+
+ -
+ Sign in to the AWS Management Console and open the CloudFront console.
+
+ -
+ Choose Create Distribution
+
+ -
+ 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
+
+
+
+ -
+ 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
+
+
+
+ -
+ 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
+
+
+
+
+
+
+
+
+ -
+ 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.
+
+
+
+
+ -
+ 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.
+
+
+
+ -
+ Sign in to the Dashboard and from the side-navigation, click Carrier Settings.
+
+ -
+ Click the icon to edit your settings.
+
+ -
+ Under custom domain, enter your dashboard and API hosts.
+
+ -
+ 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.
+
+
+
- host = "your-api-domain.example.com" # Replace this with your custom API domain
- origin = "api.somleng.org"
+
- # DO NOT set X-Forwarded-Host
+
+
+ Client Gateway Configuration Guide
+
- 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.
+ Setting up a client gateway allows
+ independent entities
+ to use Somleng with their own
+ VoIP gateway
+ which provides access the PSTN, thereby removing the need for a commercial agreement with a carrier.
-
-
- Note: The second module, somleng_proxy_api is optional and only
- required
- if you want to configure a custom API endpoint.
-
-
-
+
+
+ How it works
+
-
-
- Configuring Cloudfront Manually
-
+
+ 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.
+
-
- Although we highly recommend using the terraform module above, you can also configure your Cloudfront
- distributions from the AWS Console.
-
+
+ The independent entity can also use Somleng to offer 3rd party access to the PSTN in their country
+ via
+ their VoIP gateway.
+
+
-
- Dashboard Configuration
-
+
+
+ Configuration Overview
+
-
-
- -
- Sign in to the AWS Management Console and open the CloudFront console.
-
- -
- Choose Create Distribution
-
- -
- Update the 'Origin' settings.
-
-
+
+
+ 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:
+
+
+
+ -
+
+ Create a SIP Trunk
+ to obtain your SIP credentials.
+
+ -
+
+ Create an account
+ to obtain your Account SID and Auth Token for outbound dialing.
+
+ -
+
+ Create a Phone Number
+ for inbound dialing.
+
+ -
+
+ Configure your VoIP Gateway
+ to connect to Somleng.
+
+
+
+
+ Note: Currently Somleng officially supports the following gateways:
+
+ -
+ GoIP .
+
+
+
+ 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.
+
+
+
-
- Set 'Origin domain to' your-subdomain.app.somleng.org
- replacing your-subdomain with your Somleng subdomain.
+ Sign in to the Dashboard and from the side-navigation, click SIP Trunks.
-
- Set 'Protocol' to HTTPS only
+ Click the icon to create a new SIP trunk.
-
- 'HTTPS port' should be set to 443
+ Under General, select Client credentials for the authentication mode.
-
- Set 'Minimum origin SSL protocol' to TLSv1.2
+ Set Max channels to the number of channels (or SIM cards) your have available
+ on
+ your VoIP Gateway.
-
- 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.
-
-
+ 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.
-
- 'Enable Origin Shield' should be set to No
+ Under Outbound Dialing optionally configure Route prefixes, Dial string
+ prefix and select National dialing where appropriate.
-
-
- -
- Update the 'Default cache behavior' settings.
-
-
-
-
- Set 'Compress objects automatically' to No.
+ 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.
+
+
+
-
- Set 'Viewer protocol policy' to Redirect HTTP to HTTPS
+ Sign in to the Dashboard and from the side-navigation, click Accounts.
-
- Set 'Allowed HTTP methods' to GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
+ Click the icon to create a new account.
-
- Set 'Restrict viewer access' to No
+ Enter a name for the account.
-
-
- -
- Update the 'Cache key and origin requests' settings
-
-
- Select Cache policy and origin request policy (recommended)
+ Choose Create Account.
- -
- 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
-
-
+
+
+ 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.
+
+
-
- -
- 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
-
-
+
+ After you have created your account, the SID and Auth Token are shown on the next screen:
+
- -
- 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
-
-
-
-
-
-
-
+ 
+
-
- Update the 'Settings'
-
-
+
+
+ 3. Create a Phone Number
+
+
+
+ Create a new Phone Number and configure it for inbound
+ dialing.
+
+
-
- Set 'Price class' to Use all edge locations (best performance)
+ Sign in to the Dashboard and from the side-navigation, click Phone Numbers.
-
- Set 'Alternate domain name (CNAME)' to your-domain.example.com
+ Click the icon to create a new phone number.
-
- Set 'Custom SSL certificate' to your certificate or click the link to Request certificate.
+ Enter the phone number including he country code in E.164 format.
-
- Set security policy to TLSv1.2_2021 (recommended) or to the latest recommended
- policy.
+ Link the phone number to the account by selecting the account created in the previous step.
-
-
-
- -
- Click Create distribution
-
-
-
-
-
- API Configuration (optional)
-
+ -
+ Choose Create Phone number.
+
+
-
- Repeat the exact same process above to create a distribution for your custom API
- domain, with the following modifications:
-
-
+
+ After you have created your phone number, you can configure it on the next screen:
+
- -
- Set 'Origin domain to' api.somleng.org
-
- -
- DO NOT set the X-Forwarded-Host header
-
-
-
-
+ 
-
-
- 1(b). Nginx Reverse Proxy
-
+
+ -
+ Click the dropdown and choose
+ Configure.
+
+ -
+ Configure the phone number by entering a Voice URL that returns valid
+ TwiML for
+ Programmable Voice .
+
+ -
+ Configure other optional parameters for the phone number as necessary.
+
+ -
+ Choose Update Configuration.
+
+
-
- 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.
-
+
+
+ 4. Configure your VoIP gateway
+
-
-
- server {
- listen 443;
- server_name dashboard.example.com; # replace this with your dashboard domain
+
+ 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:
- ssl_certificate /path/to/your/fullchain.pem;
- ssl_certificate_key /path/to/your/privatekey.pem;
+
+ -
+ GoIP
+
+
+
+
- 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";
- }
- }
+
+
+ GoIP Configuration
+
- # 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
+
+ Follow the instructions below to configure the GoIP gateway to connect to Somleng.
+
- ssl_certificate /path/to/your/fullchain.pem;
- ssl_certificate_key /path/to/your/privatekey.pem;
+
+ -
+
+ General Configuration
+
+
+ -
+
+ Basic VoIP Configuration
+
+
+ -
+
+ Advanced VoIP Configuration
+
+
+ -
+
+ Call-In Configuration
+
+
+ -
+
+ Testing
+
+
+ -
+
+ Advanced Routing Configuration (Optional)
+
+
+ -
+
+ Additional Resources
+
+
+
- location / {
- proxy_pass "https://api.somleng.org:443";
- }
- }
-
-
+
+
+ 1. General Configuration
+
-
-
- 2. Test your custom domain
-
+
+
+ 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.
+
+
-
- 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.
-
+
+ In order to configure the GoIP gateway for inbound dialing, we need to turn off the in-built
+ IVR.
+
-
- 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.
-
-
+
+ -
+ From the side-navigation, click Configurations -> Preferences.
+
+ -
+ Set IVR to Disable
+
+ -
+ Click Save Changes.
+
+
-
-
- 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.
-
+
+
+ 2. Basic VoIP Configuration
+
-
- -
- Sign in to the Dashboard and from the side-navigation, click Carrier Settings.
-
- -
- Click the icon to edit your settings.
-
- -
- Under custom domain, enter your dashboard and API hosts.
-
- -
- Choose Update Carrier Settings.
-
-
+
+ The next step is to configure the GoIP gateway to register with Somleng. There are 3 different
+ modes of configuration depending on your
+ circumstances. Please refer to the
+ GoIP User
+ Manual
+ for more information about the different configuration modes and the channel selection
+ algorithms.
+
-
- 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.
-
+
+
+
+ Config Mode
+ Description
+
+
+
+
+ Single Server Mode
+
+ Use this mode to associate all channels on your GoIP gateway to a single SIP Trunk on
+ Somleng.
+
+
+ This mode is best if you only have one group of SIM cards and you want to route evenly
+ between all of them.
+
+
+
+
+ Config by Line
+
+ Use this mode to associate a single channel on your GoIP gateway to a single SIP Trunk on
+ Somleng.
+
+
+ Note: This mode requires you so set a Routing Prefix for each channel.
+
+
+
+
+ Config by Group
+
+ Use this mode to associate a group of channels on your GoIP gateway to a single SIP trunk
+ on
+ Somleng.
+
+
+ This mode is useful if you want to route to a different group of SIM cards based on the
+ number prefix.
+ See Advanced Routing Configuration for more info.
+
+
+
+
+
-
- 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.
-
+
+ -
+ From the side-navigation, click Configurations -> Basic VoIP.
+
+ -
+ Choose your preferred configuration mode as described above from Config Mode.
+
+ -
+ Copy the Username from the Client Credentials section from
+ Step 1
+ and paste it in the Authentication ID field.
+
+ -
+ Copy the Password from the Client Credentials section from
+ Step 1
+ and paste it in the Password field.
+
+ -
+ Copy the Domain from the Client Credentials section from
+ Step 1
+ and paste it in the SIP Registrar Server field.
+
+ -
+ Optionally fill in Routing Prefix to control the channel selection algorithm.
+ Please refer to the
+ GoIP User
+ Manual
+ for more details.
+
+ -
+ Click Save Changes.
+
+
-
- Note: The API is always available at api.somleng.org regardless of whether you set
- a custom API host or not.
-
-
-
+
+
+ Note: If you choose Config by Line or Config by Group you'll
+ need to repeat the instructions above for each channel or group.
+
+
-
+ 
+
-
-
- Client Gateway Configuration Guide
-
+
+
+ 3. Advanced VoIP Configuration (Optional)
+
-
- 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.
-
+
+ Configure DTMF Signaling under the Advance VoIP section.
+
-
-
- 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.
-
-
+
+ -
+ From the side-navigation, click Configurations -> Advance VoIP.
+
+ -
+ Ensure NAT Keep-alive is set to Enable.
+
+ -
+ Select None from Call OUT Auth Mode.
+
+ -
+ Select Outband from DTMF Signaling.
+
+ -
+ Select RFC 2833 from Outband DTMF Type.
+
+ -
+ Ensure RTP Payload Type is set to 101.
+
+ -
+ Click Save Changes.
+
+
-
-
- 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.
-
+
+
+ 4. Call-In Configuration
+
-
- The network provider can also use Somleng to offer 3rd party access to the PSTN in their country via
- their VoIP gateway.
-
-
+
+ Configure caller-id forward mode and VoIP forwarding number.
+
-
-
- Configuration Overview
-
+
+ -
+ From the side-navigation, click Configurations -> Call In.
+
+ -
+ Select Use Remote Party ID from CID Forward Mode.
+
+ -
+ Ensure Call In is set to Enable.
+
+ -
+ Fill in Forwarding to VoIP Number with the number you configured in
+ Step
+ 3.
+
+ -
+ Click Save Changes.
+
+
-
-
- 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.
-
-
+
+ Note: Repeat this step for each channel you need to configure.
+
-
- Below is an overview of the steps required to configure a client gateway:
-
+ 
+
-
- -
-
- Create a SIP Trunk
- to obtain your SIP credentials.
-
- -
-
- Create an account
- to obtain your Account SID and Auth Token for outbound dialing.
-
- -
-
- Create a Phone Number
- for inbound dialing.
-
- -
-
- Configure your VoIP Gateway
- to connect to Somleng.
-
-
+
+
+ 5. Testing
+
-
-
- Note: Currently Somleng officially supports the following gateways:
-
- -
- GoIP .
-
-
+
+ Reboot, then test your configuration.
+
- 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 .
-
-
-
+
+ -
+ From the side-navigation, click Tools -> Reboot.
+
+ -
+ From the side-navigation, click Status -> General.
+
+ -
+ Under Call Status and Setting ensure that Login, Call In and Call
+ Out shows Y in each column.
+
+ -
+ Test an inbound call by making a call to one of the phone numbers you configured in
+ Step
+ 3.
+
+ -
+ Test an outbound call using the
+ Account API .
+ Use the credentials from the account you created in
+
+ Step 2.
+
+
-
-
-
- 1. Create a SIP Trunk
-
+ 
+
-
- Create a new SIP Trunk and configure it with client
- credentials authentication.
-
+
+
+ 6. Advanced Routing Configuration (Optional)
+
-
- -
- Sign in to the Dashboard and from the side-navigation, click SIP Trunks.
-
- -
- Click the icon to create a new SIP trunk.
-
- -
- Under General, select Client credentials for the authentication mode.
-
- -
- Set Max channels to the number of channels (or SIM cards) your have available on
- your VoIP Gateway.
-
- -
- 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.
-
- -
- Under Outbound Dialing optionally configure Route prefixes, Dial string
- prefix and select National dialing where appropriate.
-
- -
- Choose Create SIP Trunk.
-
-
+
+ Let's say you have a GoIP-8 with 3 groups of SIM Cards from 3 different mobile operators. Assume
+ you have 4 SIM cards from Telco A,
+ 3 SIM cards from Telco B, and 1 SIM Card from Telco C and you want to route calls from Telco A
+ to
+ group 1,
+ Telco B to group 2 and Telco C to group 3 according to the table below.
+
-
+
+
+
+ No. of SIM cards
+ Telco
+ Prefixes
+ Group
+ Lines
+
+
+
+
+ 4
+ Telco A
+ 85510, 85515, 85516
+ Group 1
+ Lines 1-4
+
+
+
+ 3
+ Telco B
+ 85531, 85571, 85597
+ Group 2
+ Lines 5-7
+
+
+
+ 1
+ Telco C
+ 85511, 85512, 85517
+ Group 3
+ Line 8
+
+
+
-
- After you have created a SIP trunk you will see your client credentials on the next screen:
-
+
+ In order to handle this situation complete the following steps.
+
-
-
+
+ -
+
+ Configure 3 separate SIP Trunks (one for each Telco) as per the instructions in
+ Step 1 of
+ the Client Configuration Guide.
+
+
+ For each SIP trunk specify:
+
+ -
+ Max channels. This should equal the number of SIM cards installed for the
+ telco.
+
+ -
+ Route prefixes. A comma separated list of route prefixes for the telco.
+ Must include the country code.
+
+ -
+ Dial string prefix. A unique numeric identifier for the group prepended
+ to
+ the dial string. This will be used by GoIP to identify the channel group.
+
+ -
+ Select National dialing. This will ensure that the national dialing
+ format
+ will be sent to your GoIP.
+
+
+
-
-
- 2. Create an Account
-
+ 
+
-
- Create a new Account to obtain your Account SID and
- Auth Token
- for outbound dialing.
-
+ -
+
+ Configure Basic VoIP configuration for each group created above, as per the instructions in
+
+ Step
+ 2 of the GoIP Configuration Guide.
+
+
+
+ For each group specify:
+
+ -
+ Authentication ID. This should match the Username
+ generated from the previous step.
+
+ -
+ Password. This should match the Password generated from
+ the previous step.
+
+ -
+ SIP Registrar Server. This should match the Domain
+ obtained from the previous step.
+
+ -
+ Routing Prefix: This should match the Dial string prefix
+ configured above.
+
+
+
-
- -
- Sign in to the Dashboard and from the side-navigation, click Accounts.
-
- -
- Click the icon to create a new account.
-
- -
- Enter a name for the account.
-
- -
- Choose Create Account.
-
-
+ 
+
+ -
+
+ Configure Call Out configuration for each channel.
+
-
-
- 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.
-
-
+
+ For each channel, specify a Dial Plan to remove the routing prefix setup in
+ the previous step. This removes the prefix before calling out.
+
-
+ 
+
+
+
-
- After you have created your account, the SID and Auth Token are shown on the next screen:
-
-
-
+
+
+ 7. Additional Resources
+
-
-
- 3. Create a Phone Number
-
+
+ Below is a list of additional resources for the GoIP Gateway.
+
-
- Create a new Phone Number and configure it for inbound
- dialing.
-
+
+ -
+ GoIP User Manual
+
+ -
+ Latest
+ Firmware
+ .
+
+ -
+ Official
+ Website
+ .
+
+
+
+
+
+
-
- -
- Sign in to the Dashboard and from the side-navigation, click Phone Numbers.
-
- -
- Click the icon to create a new phone number.
-
- -
- Enter the phone number including he country code in E.164 format.
-
- -
- Link the phone number to the account by selecting the account created in the previous step.
-
- -
- Choose Create Phone number.
-
-
+
-
- After you have created your phone number, you can configure it on the next screen:
-
+
+
+ SMS Gateway Configuration Guide
+
-
+
+ Setting up an SMS Gateway allows
+ independent entities
+ to provide programmable SMS through their own SMS infrastructure.
+
-
- -
- Click the dropdown and choose
- Configure.
-
- -
- Configure the phone number by entering a Voice URL that returns valid
- TwiML for
- Programmable Voice .
-
- -
- Configure other optional parameters for the phone number as necessary.
-
- -
- Choose Update Configuration.
-
-
+
+ SMS infrastructure can mean anything from an API connection to a provider that you manage,
+ a simple GSM Modem, or an SMPP connection to a carrier.
+
-
-
+
+
+ Note: Providing programmable SMS as an independent entity isn't restricted to carriers or
+ organizations.
+ Any individual can become an independent entity as long as they have access to their own SMS
+ infrastructure.
+
+
-
+
- 4. Configure your VoIP gateway
+ How it works
+ 
+
- 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:
+ independent entities connect to Somleng via Somleng's SMS Gateway App installed on-premise, or on
+ the
+ cloud
+ infrastructure managed by the independent entity.
+
-
- -
- GoIP
-
-
+
+ Customers can then use the
+ Account API
+ to send and receive SMS though the independent entity's SMS infrastructure.
-
-
- GoIP Configuration
-
+
+
+ Configuration Overview
+
- Follow the instructions below to configure the GoIP gateway to connect to Somleng.
+ Below is an overview of the steps required to configure an SMS gateway:
-
-
- General Configuration
-
+ Create an SMS
+ Gateway
+
-
-
- Basic VoIP Configuration
-
+ Create an Account
+
-
-
- Advanced VoIP Configuration
-
+ Create and configure a
+ Phone Number
+
-
-
- Call-In Configuration
-
+ Install the
+ Somleng
+ SMS Gateway App
+
-
-
- Testing
-
+ Send an Outbound
+ Message
+
-
-
- Advanced Routing Configuration (Optional)
-
+ Receive an
+ Inbound Message
+
-
-
- Additional Resources
-
+ Additional Steps
+
-
-
- 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.
-
-
+
+
+
+ 1. Create an SMS Gateway
+
- In order to configure the GoIP gateway for inbound dialing, we need to turn off the in-built IVR.
+ Create an SMS gateway via the Dashboard.
-
- -
- From the side-navigation, click Configurations -> Preferences.
-
- -
- Set IVR to Disable
-
- -
- Click Save Changes.
-
-
-
-
-
-
-
-
- 2. Basic VoIP Configuration
-
-
- The next step is to configure the GoIP gateway to register with Somleng. There are 3 different
- modes of configuration depending on your
- circumstances. Please refer to the
- GoIP User
- Manual
- for more information about the different configuration modes and the channel selection algorithms.
-
-
-
-
-
- Config Mode
- Description
-
-
-
-
- Single Server Mode
-
- Use this mode to associate all channels on your GoIP gateway to a single SIP Trunk on
- Somleng.
-
-
- This mode is best if you only have one group of SIM cards and you want to route evenly
- between all of them.
-
-
-
-
- Config by Line
-
- Use this mode to associate a single channel on your GoIP gateway to a single SIP Trunk on
- Somleng.
-
-
- Note: This mode requires you so set a Routing Prefix for each channel.
-
-
-
-
- Config by Group
-
- Use this mode to associate a group of channels on your GoIP gateway to a single SIP trunk on
- Somleng.
-
-
- This mode is useful if you want to route to a different group of SIM cards based on the
- number prefix.
- See Advanced Routing Configuration for more info.
-
-
-
-
-
-
-
- From the side-navigation, click Configurations -> Basic VoIP.
-
- -
- Choose your preferred configuration mode as described above from Config Mode.
-
- -
- Copy the Username from the Client Credentials section from
- Step 1
- and paste it in the Authentication ID field.
+ Sign in to the Dashboard and from the side-navigation, click SMS Gateways under
+ Messaging.
-
- Copy the Password from the Client Credentials section from
- Step 1
- and paste it in the Password field.
+ Click the icon to create a new SMS Gateway.
-
- Copy the Domain from the Client Credentials section from
- Step 1
- and paste it in the SIP Registrar Server field.
+ Enter a name for your SMS Gateway.
-
- Optionally fill in Routing Prefix to control the channel selection algorithm.
- Please refer to the
- GoIP User
- Manual
- for more details.
+ Enter the maximum number of channels your SMS gateway supports. Leave it blank for unlimited
+ channels.
-
- Click Save Changes.
+ Choose Create SMS gateway.
+
-
- Note: If you choose Config by Line or Config by Group you'll
- need to repeat the instructions above for each channel or group.
-
+ 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.
-
+
-
-
- 3. Advanced VoIP Configuration (Optional)
-
+
+
+ 2. Create an Account
+
- Configure DTMF Signaling under the Advance VoIP section.
+ Create an Account via the Dashboard.
+
+
+ Note: You can skip this step if you already have a carrier account setup.
+
-
- From the side-navigation, click Configurations -> Advance VoIP.
-
- -
- Ensure NAT Keep-alive is set to Enable.
-
- -
- Select None from Call OUT Auth Mode.
-
- -
- Select Outband from DTMF Signaling.
+ Sign in to the Dashboard and from the side-navigation, click Accounts.
-
- Select RFC 2833 from Outband DTMF Type.
+ Click the icon to create a new account.
-
- Ensure RTP Payload Type is set to 101.
+ Give the account a name.
-
- Click Save Changes.
+ 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.
+
-
+
-
-
- 4. Call-In Configuration
-
+
+
+ 3. Create and configure a Phone Number
+
- Configure caller-id forward mode and VoIP forwarding number.
+ Create a new Phone Number and configure it for inbound
+ messaging.
-
- From the side-navigation, click Configurations -> Call In.
+ Sign in to the Dashboard and from the side-navigation, click Phone Numbers.
-
- Select Use Remote Party ID from CID Forward Mode.
+ Click the icon to create a new phone number.
-
- Ensure Call In is set to Enable.
+ Enter the phone number including he country code in E.164 format.
-
- Fill in Forwarding to VoIP Number with the number you configured in
- Step
- 3.
+ Link the phone number to the account by selecting the account created in the previous step.
-
- Click Save Changes.
+ Choose Create Phone number.
- Note: Repeat this step for each channel you need to configure.
+ After you have created your phone number, you can configure it on the next screen:
-
-
-
-
-
- 5. Testing
-
-
-
- Reboot, then test your configuration.
-
+
-
- From the side-navigation, click Tools -> Reboot.
-
- -
- From the side-navigation, click Status -> General.
+ Click the dropdown and choose
+ Configure.
-
- Under Call Status and Setting ensure that Login, Call In and Call
- Out shows Y in each column.
+ 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.
-
- Test an inbound call by making a call to one of the phone numbers you configured in
- Step
- 3.
+ Choose GET from SMS method if you used the URL above.
-
- Test an outbound call using the
- Account API .
- Use the credentials from the account you created in
-
- Step 2.
+ Choose Update Configuration.
-
-
-
-
-
- 6. Advanced Routing Configuration (Optional)
-
-
- Let's say you have a GoIP-8 with 3 groups of SIM Cards from 3 different mobile operators. Assume
- you have 4 SIM cards from Telco A,
- 3 SIM cards from Telco B, and 1 SIM Card from Telco C and you want to route calls from Telco A to
- group 1,
- Telco B to group 2 and Telco C to group 3 according to the table below.
+ After you have configured your phone number you can review the configuration on the next screen:
-
-
-
- No. of SIM cards
- Telco
- Prefixes
- Group
- Lines
-
-
-
-
- 4
- Telco A
- 85510, 85515, 85516
- Group 1
- Lines 1-4
-
+
+
-
- 3
- Telco B
- 85531, 85571, 85597
- Group 2
- Lines 5-7
-
+
+
+ 4. Download and Install the Somleng SMS Gateway App
+
-
- 1
- Telco C
- 85511, 85512, 85517
- Group 3
- Line 8
-
-
-
+
+ The
+ Somleng SMS Gateway
+ App .
+ is as a gateway between Somleng and your SMS infrastructure.
+
- In order to handle this situation complete the following steps.
+ 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.
-
- -
-
- Configure 3 separate SIP Trunks (one for each Telco) as per the instructions in
- Step 1 of
- the Client Configuration Guide.
-
-
- For each SIP trunk specify:
-
- -
- Max channels. This should equal the number of SIM cards installed for the
- telco.
-
- -
- Route prefixes. A comma separated list of route prefixes for the telco.
- Must include the country code.
-
- -
- Dial string prefix. A unique numeric identifier for the group prepended to
- the dial string. This will be used by GoIP to identify the channel group.
-
- -
- Select National dialing. This will ensure that the national dialing format
- will be sent to your GoIP.
-
-
-
+
+ Once the SMS Gateway app is configured and successfully connected to Somleng, you should see the
+ connection status show Connected
+ the Dashboard.
+
-
-
+ 
+
-
-
- Configure Basic VoIP configuration for each group created above, as per the instructions in
- Step
- 2 of the GoIP Configuration Guide.
-
+
+
+ 5. Send an Outbound Message
+
-
- For each group specify:
-
- -
- Authentication ID. This should match the Username
- generated from the previous step.
-
- -
- Password. This should match the Password generated from
- the previous step.
-
- -
- SIP Registrar Server. This should match the Domain
- obtained from the previous step.
-
- -
- Routing Prefix: This should match the Dial string prefix
- configured above.
-
-
-
+
+ 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
+
-
-
-
-
- Configure Call Out configuration for each channel.
-
+
+ Note: The From parameter must match the phone number you created in
+ Step 3.
+
+
-
- For each channel, specify a Dial Plan to remove the routing prefix setup in
- the previous step. This removes the prefix before calling out.
-
+
+ You should see the message appear in the Messages section of the Dashboard.
+
-
-
-
+ 
-
-
-
- 7. Additional Resources
-
+
+
+ 6. Receive an Inbound Message
+
- Below is a list of additional resources for the GoIP Gateway.
+ In order to test an inbound SMS, simply send a message to the number you configured in
+ Step 3.
-
- -
- GoIP User Manual
-
- -
- Latest Firmware
- .
-
- -
- Official Website
- .
-
-
-
-
-
-
-
-
+
+ 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.
+
-
-
- SMS Gateway Configuration Guide
-
+
+ If you don't see the message on the Dashboard, you can check the Error Logs
+ section
+ of the Dashboard.
+
-
- 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.
-
+
+
+ 7. Additional Steps
+
-
-
- 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.
-
-
+
+ If you need more control over which channels outbound SMS are delivered though, you can configure
+ one or more
+ Channel Groups.
+
-
-
- How it works
-
+
+ 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.
+
+
+
+
-
+
-
- Network providers connect to Somleng via Somleng's SMS Gateway App installed on-premise, or on the
- cloud
- infrastructure managed by the network provider.
-
+
+
+ Installation Guide
+
- Customers can then use the
- Account API
- to send and receive SMS though the network provider's SMS infrastructure.
+ This guide is intended to get you up and running with Somleng on your local machine. It is not
+ intended
+ for production. If you are just getting started with Somleng we recommend following the
+ Getting Started guide before
+ attempting to install Somleng on your local machine.
-
-
- Configuration Overview
+ Prerequisites
-
- Below is an overview of the steps required to configure an SMS gateway:
-
-
-
- Create an SMS
- Gateway
+ Install Docker and git on your local machine.
+
-
- Create an Account
-
+
+ Overview
+
+
+
+ Below is an overview of the steps required to complete this guide:
+
+
-
-
-
-
-
- 1. Create an SMS Gateway
-
-
-
- Create an SMS gateway via the Dashboard.
-
-
-
-
- -
- Sign in to the Dashboard and from the side-navigation, click SMS Gateways under
- Messaging.
-
- -
- Click the icon to create a new SMS Gateway.
-
- -
- Enter a name for your SMS Gateway.
-
- -
- Enter the maximum number of channels your SMS gateway supports. Leave it blank for unlimited
- channels.
-
- -
- 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
+ 1. Clone the somleng-project repository.
- Create an Account via the Dashboard.
-
-
- Note: You can skip this step if you already have a carrier account setup.
-
-
-
-
- -
- Sign in to the Dashboard and from the side-navigation, click Accounts.
-
- -
- Click the icon to create a new account.
-
- -
- Give the account a name.
-
- -
- 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.
+ Clone the somleng-project repository.
-
+ $ git clone https://github.com/somleng/somleng-project.git && cd somleng-project
-
+
- 3. Create and configure a Phone Number
+ 2. Pull the latest Docker images.
-
- Create a new Phone Number and configure it for inbound
- messaging.
-
-
-
- -
- Sign in to the Dashboard and from the side-navigation, click Phone Numbers.
-
- -
- Click the icon to create a new phone number.
-
- -
- Enter the phone number including he country code in E.164 format.
-
- -
- Link the phone number to the account by selecting the account created in the previous step.
-
- -
- Choose Create Phone number.
-
-
-
-
- After you have created your phone number, you can configure it on the next screen:
-
-
-
-
-
- -
- Click the dropdown and choose
- Configure.
-
- -
- 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.
-
- -
- Choose GET from SMS method if you used the URL above.
-
- -
- Choose Update Configuration.
-
-
-
-
- After you have configured your phone number you can review the configuration on the next screen:
-
-
-
+ $ docker-compose pull
-
+
- 4. Download and Install the Somleng SMS Gateway App
+ 3. Start Somleng.
-
- 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.
-
-
-
+ $ docker-compose up
-
+
- 5. Send an Outbound Message
+ 4. Seed the Database
-
- You can use the
- Account API to test sending an outbound SMS.
+
$ docker-compose exec somleng bundle exec rails db:setup
- 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:
+ You should get the following output:
-
-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
+
+
+Account SID: account-sid
+Auth Token: auth-token
+Inbound 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
-
-
- 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
+ 5. Log in to the Dashboard
- If you need more control over which channels outbound SMS are delivered though, you can configure
- one or more
- Channel Groups.
+ 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.
- 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.
+
+ 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.
+
-
-
-
-
-
-
- Installation Guide
-
-
-
- This guide is intended to get you up and running with Somleng on your local machine. It is not intended
- for production. If you are just getting started with Somleng we recommend following the
- Getting Started guide before
- attempting to install Somleng on your local machine.
-
-
-
- Prerequisites
-
-
-
-
-
- Overview
-
-
-
- Below is an overview of the steps required to complete this guide:
-
-
-
- -
- Clone the somleng-project repository.
-
-
- -
- Pull the latest Docker images.
-
- -
- Start Somleng.
-
-
- -
- Seed the Database.
-
-
- -
- Login to the Dashboard.
-
-
+
-
-
- 1. Clone the somleng-project repository.
-
+
+
+ RTP and Symmetric Latching
+
- Clone the somleng-project repository.
+ 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.
-
- $ git clone https://github.com/somleng/somleng-project.git && cd somleng-project
-
-
-
-
- 2. Pull the latest Docker images.
-
-
- $ docker-compose pull
-
-
-
-
- 3. Start Somleng.
-
-
- $ docker-compose up
-
-
-
-
- 4. Seed the Database
-
-
- $ docker-compose exec somleng bundle exec rails db:setup
-
- You should get the following output:
-
-
-
-Account SID: account-sid
-Auth Token: auth-token
-Inbound 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. Login 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.
+ 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.
-
- 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.
-
+ 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.
-
-
-
-
-
-
- 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.
-
+
-
-
-
-
-
-
+
+
+
🎉 Congratulations!
- - -- -
- Using the Dashboard -
-- The dashboard can be used to manually provision carrier resources. - Use the Carrier API - to automate the provisioning of carrier resources. -
++ Invite customers to use your CPaaS +
-- 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. + So far, you've learned how to + build your own phone verification service, and optionally + connected it to + Amazon Chime. You have essentially built your own branded, Communications Platform as a Service + or CPaaS.
-- 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: -
-
-
- - Sign in to the Dashboard and from the side-navigation, click Carrier Settings. - -
- - Click the icon to edit your settings. - -
- - Make your desired changes. - -
- - 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: + In this tutorial you'll learn how to invite your own customers to use your new CPaaS. Your + customers will + be able to + integrate phone verifications and programmable voice and messaging into their own + applications, while + you remain in complete control over their access.
--
| 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: -
-
-
- - Sign in to the Dashboard and from the side-navigation, click Accounts. - -
- - Click the icon to create a new account. - -
- - Fill out the form, specifying a name for the account and optionally the owner's name and email - address to create a customer account. - -
- - 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: -
-
-
- - Sign in to the Dashboard and from the side-navigation, click Phone Numbers. - -
- - Click the icon to create a new phone number. - -
- - Fill out the form, specifying the phone number or short code, and optionally assign it to an - account. - -
- - Choose Create Phone number. - -
- Once the phone number has been created, you can configure it. To configure a phone number via the - Dashboard: -
-
-
- - From the Phone Numbers page, find the phone number you want to configure. - -
- - From the gear icon select Configure. - -
-
- 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. - -
- -
- 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. - -
- - - Choose Update Configuration. - -
+ Prerequisites +
-- After you have configured a phone number, the configuration will be shown on the next screen. -
+-
+
- + Complete the Build your own Phone Verification Service + tutorial. + +
- + Optionally complete the Connect Somleng to Amazon Chime + tutorial. + +
+ + Overview +
-- 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: + Below is an overview of the steps that we'll cover in this tutorial: +
+- - From the Phone Numbers page, click the upload button . + Update your carrier settings. + +
- + Create a new Account for your + customer.
- - Select the CSV file of phone numbers to import. + Log in to the Dashboard as if you are the + customer.
- - Choose Upload. + Explore the Dashboard and API docs from + the customer's perspective. + +
- + Use the API from the customer's + perspective. + +
- + 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.
-
| 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 |
-
| account_sid | -Optionally associate an account with the phone number | -SID of account to associate | -ccdb7202-e487-436c-b964-c3acb7884c8f |
-
- Sample CSV Data -
+-
+
- + Click on Carrier Settings from the main menu. + +
- + Upload your company's logo. + +
- + Optionally update other details about your company. + +
- + Press Update Carrier Settings. + +
- 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. -
++ 2. Create a new Account for your customer. +
-- 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: + 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. +-
| 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. -
+-
+
- + Under the Accounts menu, click the + icon to create a new account. + -
- + Give the account a name. + -
- - 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. - -
-
- 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 - -
- -
+ 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, enterbob+elvie.padberg@example.com. + +
- - + 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. + -
- - You must provide a host to connect to. You can specify your host as either a fully - qualified domain name (FQDN) or IP address. - -
-
- You must allow the following IP address on your firewall:
-
-
-
- - 13.250.230.15 - -
- - - You must support NAT Traversal and Symmetric Latching. Read more. - -
- + Press Create Account. + +
- When you configure a SIP trunk for inbound dialing via IP address - authentication the following rules apply: -
--
-
- When you configure a SIP trunk for outbound dialing via IP address - authentication the following rules apply: -
--
-
- To configure a SIP trunk via IP address authentication: -
-
-
- - Sign in to the Dashboard and from the side-navigation, click SIP Trunks. - -
- - Click the icon to create a new SIP trunk. - -
- - Under General, select IP address for Authentication mode. - -
- - Under Inbound Dialing, enter a public static IP address for inbound call authentication. - -
- - Under Outbound Dialing, enter a domain name or IP address for outbound calls. - -
- - 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: -
-
-
- - Sign in to the Dashboard and from the side-navigation, click SIP Trunks. - -
- - Click the icon to create a new SIP trunk. - -
- - Under General, select Client credentials for Authentication mode. - -
- - 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. - -
- - Choose Create SIP Trunk. - -
- After you create your SIP Trunk you'll see the generated credentials on the next screen.
-
-
-
- Text To Speech (TTS) -
++ 3. Log in to the Dashboard as if you are the customer. +
- Text To Speech (TTS), also known as speech synthesis, is a process in which text is converted into a - human-sounding voice. + 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.
- The <Say> verb allows you to provide plain text that Somleng converts to
- synthesized speech.
-
- For example, when Somleng executes the following TwiML during a call, the caller hears "Hello
- world!"
- The synthesized voice the caller hears is the default voice and language of the Somleng Account
- (configured in the Account Settings).
+
+ 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.
+
-
<Response>
- <Say>Hello world!</Say>
-</Response>
-
- <Say> also allows you to modify the language, accent, and voice of the synthesized
- speech via the language and voice attributes.
- The example below uses Amazon Polly's "Joanna" voice and American English:
-
-
<Response>
- <Say language="en-US" voice="Polly.Joanna">Hello. I am Joanna and I speak American English!</Say>
-</Response>
-
- The language attribute of <Say> also allows you to override the default voice that is
- configured for the Somleng Account.
- For example, if the account's default TTS voice is Polly.Joanna (Female, en-US), but wish
- to use German for a specific call, set the language attribute to de-DE in your
- TwiML.
- This will choose another voice from the Polly provider which supports German.
-
-
<Response>
- <Say language="de-DE">Hallo. Ich spreche Deutsch!</Say>
-</Response>
--
+
- + Click on your avatar in the top right corner and select + Logout from the dropdown. + -
- + Check your email. You should have received a customer invitation email when completing the + previous step. + -
- + Follow the link in the email and set your password. + -
- + Setup two factor authentication (2FA). + +
- Note: the TTS provider is always preserved when using this feature.
- For example if the account's default TTS voice is Basic.Kal (Male, en-US), using the TwiML
- above won't have any effect
- because German is not available in the Basic provider.
-
- You can also use Premium voices which are generated using the latest technology and innovation in - synthesized speech, - providing the most human-like, expressive and natural-sounding text-to-speech voices possible, with - higher quality than Standard voices. - The voices in this tier are currently provided by Amazon (Amazon Polly Neural). -
+
- As well as setting the default TTS voice to a premium voice in the dashboard, you can also use the
- voice attribute to override a premium voice.
- For example:
+
-
<Response>
- <Say voice="Polly.Danielle-Neural">Hello. I am Danielle!</Say>
-</Response>
-+ You should now be viewing the dashboard from the customer's perspective. +
-- Messaging -
-- This section contains everything you need related to configuring programmable SMS. -
+
+
+ - SMS Gateways -
++ 4. Explore the Dashboard and API docs from the customer's perspective. +
- SMS Gateways are used by Somleng for SMS origination and termination. - Configuring an SMS Gateway allows you to fully control your own SMS infrastructure. + In this step, feel free to click around and explore the Dashboard from the customer's perspective.
- 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. + Notice the following:
-- To configure an SMS Gateway: -
-
-
- - Sign in to the Dashboard and from the side-navigation, click SMS Gateways under - Messaging. - -
- - Click the icon to create a new SMS Gateway. - +
- - Enter a name for your SMS Gateway. + Your company's logo appears in the top left of the Dashboard. -
- - Enter the maximum number of channels your SMS gateway supports. Leave it blank for unlimited - channels. +
- 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.
- - Choose Create SMS gateway. + The API docs are branded with your company's name and logo. -
- 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. -
++ 5. Use the API and Dashboard from the customer's perspective. +
- 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". + In this step, you'll explore using the Verify API from the customer's perspective.
- 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. + Perform the following steps:
-- To configure a Channel Group: -
-
-
- - Sign in to the Dashboard and from the side-navigation, click Channel Groups under - Messaging. - +
- - Click the icon to create a new Channel Group. + Under the Verify menu, select Services. +
- - Enter a name for your Channel Group. + Click the icon to create a new verification service. +
- - Assign the channel group to an SMS Gateway. + Give your verification service a friendly name. +
- - 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. + Press Create Verification service. +
-
- 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.
+ Set
accountSidandauthTokenfrom the + values shown on the Account Settings page. -
- Choose Create Channel group.
+ Set
verificationServiceSidfrom the verification service you just + created.
-
+ 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: +
+ ++ 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.
- After you have created your Channel Group you can see the configuration details. + 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: +
+ +-
+
- + Click on your customer's avatar in the top right corner and select + Logout from the dropdown. + + +
- + Log in to your carrier account. + + +
- + Under the Accounts menu, click the SID of the Account belonging to your + customer. + + +
- Click the button. + +
- + Notice that most of the fields are disabled, but you can toggle the Enabled + switch. + + +
- + 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. +
+ +
+ - Messaging Services -
+🎉 Congratulations!
- Messaging services allow you to apply messaging configuration to of a group of phone numbers, rather - than having to configure each - one individually. + Congratulations! You have successfully completed this tutorial and invited your first customer to + use your CPaaS.
- To configure an Messaging Service: + What we learned: +
+- - Sign in to the Dashboard and from the side-navigation, click Messaging Services - under Messaging. - -
- - Click the icon to create a new Messaging Service. + 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. +
- - Enter a name for your Messaging Service. + 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. +
- - Choose Next. + The customer can use the API and helper libraries in his own applications. +
- - 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. + The customer can only see the data (phone calls, messages, verifications etc) that belongs to him. +
-
- 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. - -
+
+ +
+ 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: +
- - 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. + Sign in to the Dashboard and from the side-navigation, click Carrier Settings.
- - Optionally configure a Status Callback URL for all outbound messages in the sender pool. + Click the icon to edit your settings.
- - Configure Smart encoding for outbound messages. If this is turned on Smart encoding will apply to - all outbound messages in the number pool. + Make your desired changes.
- - Choose Create Messaging service. + Choose Update Carrier Settings.
+ Accounts +
- After you have configured your messaging service you can see the configuration details. + Accounts are used by carriers, carrier customers, BYOC entities and independent entities to + send/receive + calls and SMS via the Account API .
- -
- - Users -
++ Typically a carrier would create an account for each of their customers. + BYOC entities and independent entities on the other hand might create an account for each customer + or + project or just create one global account for their own usage. +
++ There are two types of accounts. Carrier managed and customer managed described below: +
+ ++
| Account type | +Description | +
|---|---|
| Carrier Managed | ++ Carrier managed accounts are managed by carriers. + These types of accounts can be either used by carriers themselves, or by the carrier's + customers. + | +
| Customer Managed | ++ Customer managed accounts are managed by the carrier's customers directly. + These types of accounts can be created via the dashboard by specifying an account owner when + creating the account. + After providing the account owner's name and email address, the owner will be invited to the + dashboard and can manage their own account. + The customer will also have access to their Account SID and Auth Token. + The carrier can still disable and enable customer accounts from the Dashboard. + | +
+ To create an account via the Dashboard: +
-
+
- + Sign in to the Dashboard and from the side-navigation, click Accounts. + +
- + Click the icon to create a new account. + +
- + Fill out the form, specifying a name for the account and optionally the owner's name and email + address to create a customer account. + +
- + 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: +
-
+
- + Sign in to the Dashboard and from the side-navigation, click Phone Numbers. + +
- + Click the icon to create a new phone number. + +
- + Fill out the form, specifying the phone number or short code, and optionally assign it to an + account. + +
- + Choose Create Phone number. + +
+ Once the phone number has been created, you can configure it. To configure a phone number via the + Dashboard: +
-
+
- + From the Phone Numbers page, find the phone number you want to configure. + +
- + From the gear icon select Configure. + +
-
+ 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. + +
+ -
+ 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. + +
+ - + 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: +
-
+
- + From the Phone Numbers page, click the upload button . + +
- + Select the CSV file of phone numbers to import. + +
- + 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 |
+
| account_sid | +Optionally associate an account with the phone number | +SID of account to associate | +ccdb7202-e487-436c-b964-c3acb7884c8f |
+
+ Sample CSV Data +
+ ++ 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. +
+ ++ SIP Trunks +
++ SIP Trunks are used to configure both inbound and outbound dialing, both to and from Somleng. + We define inbound dialing (also known as Direct Inbound Dialing (DID)) as calls terminated by + Somleng, + and outbound dialing as calls originated by Somleng. +
+
+ When you create a SIP Trunk you first choose the authentication mode. There are two authentication + modes available described below: + ++
| Authentication mode | +Description | +
|---|---|
| IP Address | ++ Choose this mode if you have a public static IP address and are not behind + a + NAT. + This mode is best suited for carriers and BYOC entities. + | +
| Client Credentials | ++ Choose this mode if you do not have a public static IP address or are + behind + a NAT. + This mode is best suited for independent entities. + | +
+ IP Address Authentication +
++ Note: This mode is best suited for Carriers and BYOC entities. +
+ ++ When you configure a SIP trunk for inbound dialing via IP address + authentication the following rules apply: +
+-
+
- + 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. + +
-
+ 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 + +
+
+ When you configure a SIP trunk for outbound dialing via IP address + authentication the following rules apply: +
+-
+
- + You must provide a host to connect to. You can specify your host as either a fully + qualified domain name (FQDN) or IP address. + +
-
+ You must allow the following IP address on your firewall:
+
-
+
- + 13.250.230.15 + +
+ - + You must support NAT Traversal and Symmetric Latching. Read more. + +
+ To configure a SIP trunk via IP address authentication: +
-
+
- + Sign in to the Dashboard and from the side-navigation, click SIP Trunks. + +
- + Click the icon to create a new SIP trunk. + +
- + Under General, select IP address for Authentication mode. + +
- + Under Inbound Dialing, enter a public static IP address for inbound call authentication. + +
- + Under Outbound Dialing, enter a domain name or IP address for outbound calls. + +
- + Choose Create SIP Trunk. + +
+ After you create your SIP Trunk you'll see the configuration details on the next screen.
+
+
+
+ Client Credentials Authentication +
++ Note: This mode is best suited for independent entities. +
+ ++ When you configure a SIP trunk via client credentials authentication you + don't need a public + status IP address. Instead you authenticate with Somleng via SIP registration. After you + configure + a SIP trunk in this mode + you will be given a unique set of client credentials which can be used to authenticate with + Somleng. These credentials + can be used directly when configuring your client gateway. +
+ ++ To configure a SIP trunk via client credentials authentication: +
-
+
- + Sign in to the Dashboard and from the side-navigation, click SIP Trunks. + +
- + Click the icon to create a new SIP trunk. + +
- + Under General, select Client credentials for Authentication mode. + +
- + 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. + +
- + Choose Create SIP Trunk. + +
+ After you create your SIP Trunk you'll see the generated credentials on the next screen.
+
+
+
+ Text To Speech (TTS) +
+ ++ Text To Speech (TTS), also known as speech synthesis, is a process in which text is converted into + a + human-sounding voice. +
+ +
+ The <Say> verb allows you to provide plain text that Somleng converts to
+ synthesized speech.
+
+ For example, when Somleng executes the following TwiML during a call, the caller hears "Hello
+ world!"
+ The synthesized voice the caller hears is the default voice and language of the Somleng Account
+ (configured in the Account Settings).
+
+
<Response>
+ <Say>Hello world!</Say>
+</Response>
+
+ <Say> also allows you to modify the language, accent, and voice of the
+ synthesized
+ speech via the language and voice attributes.
+ The example below uses Amazon Polly's "Joanna" voice and American English:
+
+
<Response>
+ <Say language="en-US" voice="Polly.Joanna">Hello. I am Joanna and I speak American English!</Say>
+</Response>
+
- Carrier owners can invite their colleagues to the dashboard.
+ The language attribute of <Say> also allows you to override the default voice that
+ is
+ configured for the Somleng Account.
+ For example, if the account's default TTS voice is Polly.Joanna (Female, en-US), but wish
+ to use German for a specific call, set the language attribute to de-DE in
+ your
+ TwiML.
+ This will choose another voice from the Polly provider which supports German.
- To invite a user to the Dashboard: -
-
-
- - Sign in to the Dashboard and from the side-navigation, click Users. - -
- - Click the icon to invite a new user. - -
- - Fill out the form, specifying the user's name, email and role. -
- - Choose Send an invitation. - -
<Response>
+ <Say language="de-DE">Hallo. Ich spreche Deutsch!</Say>
+</Response>
+
- 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.
+ Note: the TTS provider is always preserved when using this feature.
+ For example if the account's default TTS voice is Basic.Kal (Male, en-US), using the
+ TwiML
+ above won't have any effect
+ because German is not available in the Basic provider.
- -
- 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. -
++ You can also use Premium voices which are generated using the latest technology and innovation in + synthesized speech, + providing the most human-like, expressive and natural-sounding text-to-speech voices possible, with + higher quality than Standard voices. + The voices in this tier are currently provided by Amazon (Amazon Polly Neural). +
-- How it works -
+
+ As well as setting the default TTS voice to a premium voice in the dashboard, you can also use the
+ voice attribute to override a premium voice.
+ For example:
- 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. +
<Response>
+ <Say voice="Polly.Danielle-Neural">Hello. I am Danielle!</Say>
+</Response>
++ Messaging +
++ This section contains everything you need related to configuring programmable SMS. +
+ ++ SMS Gateways +
+ ++ SMS Gateways are used by Somleng for SMS origination and termination. + Configuring an SMS Gateway allows you to fully control your own SMS infrastructure. +
+ ++ When you configure an SMS gateway on the Dashboard, + you receive a Device Token which uniquely identifies your SMS Gateway. + You'll then need to install the + Somleng SMS Gateway + App + on your on-premise or cloud infrastructure. + Normally, you'll only need to configure a single SMS Gateway, however if you require multiple SMS + gateways, you'll need to run an instance of the + for each one. Once the app is running on your local infrastructure and connected to Somleng, + the SMS Gateway will show Connected on the Dashboard. +
+ ++ To configure an SMS Gateway: +
-
+
- + Sign in to the Dashboard and from the side-navigation, click SMS Gateways under + Messaging. + +
- + Click the icon to create a new SMS Gateway. + +
- + Enter a name for your SMS Gateway. + +
- + Enter the maximum number of channels your SMS gateway supports. Leave it blank for unlimited + channels. + +
- + 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: +
-
+
- + Sign in to the Dashboard and from the side-navigation, click Channel Groups + under + Messaging. + +
- + Click the icon to create a new Channel Group. + +
- + Enter a name for your Channel Group. + +
- + Assign the channel group to an SMS Gateway. + +
- + 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. + +
- + 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. + +
- + 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: +
-
+
- + Sign in to the Dashboard and from the side-navigation, click Messaging Services + under Messaging. + +
- + Click the icon to create a new Messaging Service. + +
- + Enter a name for your Messaging Service. + +
- + Choose Next. + +
- + 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. + +
-
+ 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. + +
+ - + 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. + +
- + Optionally configure a Status Callback URL for all outbound messages in the sender pool. + +
- + Configure Smart encoding for outbound messages. If this is turned on Smart encoding will apply + to + all outbound messages in the number pool. + +
- + 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: +
-
+
- + Sign in to the Dashboard and from the side-navigation, click Users. + +
- + Click the icon to invite a new user. + +
- + Fill out the form, specifying the user's name, email and role. +
- + 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. +
+- Setup your custom domain -
++ +
+ Custom Domain Configuration Guide +
- Follow the steps below to configure your custom domain: -
-
-
- - Setup a reverse proxy via AWS Cloudfront (recommended) - or Nginx. - -
- - Test out your custom domain. - -
- - Configure - your custom domain via the Somleng Dashboard. - -
- 1(a). Configure an AWS Cloudfront Distribution (Recommended) -
++ 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 +
-- Skip this step if you prefer to use Nginx instead. -
++ Follow the steps below to configure your custom domain: +
-
+
- + Setup a reverse proxy via AWS Cloudfront (recommended) + or Nginx. + +
- + Test out your custom + domain. + +
- + Configure + your custom domain via the Somleng Dashboard. + +
- 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 . -
-+ 1(a). Configure an AWS Cloudfront Distribution (Recommended) +
-- Using the Terraform Module (Recommended) -
++ Skip this step if you prefer to use Nginx instead. +
-- 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. -
--
+
+ 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"
@@ -2296,1668 +2737,1689 @@
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"
+# 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 +
+ ++
-
+
- + Sign in to the AWS Management Console and open the CloudFront console. + +
- + Choose Create Distribution + +
-
+ 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 + +
+
+
+ -
+ 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 + +
+
+
+ -
+ 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 + +
+
+
+
+ -
+ Update the 'Details' settings
+
-
+ 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 + +
+
+
+
+ -
+ Update the 'Details' settings
+
+
+ -
+ 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. + +
+
+
+
+ - + 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. +
+ +-
+
- + Sign in to the Dashboard and from the side-navigation, click Carrier Settings. + +
- + Click the icon to edit your settings. + +
- + Under custom domain, enter your dashboard and API hosts. + +
- + 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. +
+- # DO NOT set X-Forwarded-Host +
+ Client Gateway Configuration Guide +
- 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. + Setting up a client gateway allows + independent entities + to use Somleng with their own + VoIP gateway + which provides access the PSTN, thereby removing the need for a commercial agreement with a carrier.
-
-
- Note: The second module, somleng_proxy_api is optional and only
- required
- if you want to configure a custom API endpoint.
-
-
+ How it works +
-- Configuring Cloudfront Manually -
++ 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. +
-- Although we highly recommend using the terraform module above, you can also configure your Cloudfront - distributions from the AWS Console. -
++ The independent entity can also use Somleng to offer 3rd party access to the PSTN in their country + via + their VoIP gateway. +
+- Dashboard Configuration -
++ Configuration Overview +
--
-
-
- - Sign in to the AWS Management Console and open the CloudFront console. - -
- - Choose Create Distribution - -
-
- Update the 'Origin' settings.
-
-
-
- + + Create a SIP Trunk + to obtain your SIP credentials. + +
- + + Create an account + to obtain your Account SID and Auth Token for outbound dialing. + +
- + + Create a Phone Number + for inbound dialing. + +
- + + Configure your VoIP Gateway + to connect to Somleng. + +
- + GoIP . + +
+ + + 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: +
+ +-
+
+ + Note: Currently Somleng officially supports the following gateways: +
+-
+
+ 1. Create a SIP Trunk +
+ ++ Create a new SIP Trunk and configure it with client + credentials authentication. +
+ +- - Set 'Origin domain to' your-subdomain.app.somleng.org - replacing your-subdomain with your Somleng subdomain. + Sign in to the Dashboard and from the side-navigation, click SIP Trunks.
- - Set 'Protocol' to HTTPS only + Click the icon to create a new SIP trunk.
- - 'HTTPS port' should be set to 443 + Under General, select Client credentials for the authentication mode.
- - Set 'Minimum origin SSL protocol' to TLSv1.2 + Set Max channels to the number of channels (or SIM cards) your have available + on + your VoIP Gateway.
-
- 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 + Under Outbound Dialing optionally configure Route prefixes, Dial string + prefix and select National dialing where appropriate. - - -
-
- Update the 'Default cache behavior' settings.
-
-
-
- - Set 'Compress objects automatically' to No. + 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. +
+ +- - Set 'Viewer protocol policy' to Redirect HTTP to HTTPS + Sign in to the Dashboard and from the side-navigation, click Accounts.
- - Set 'Allowed HTTP methods' to GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE + Click the icon to create a new account.
- - Set 'Restrict viewer access' to No + Enter a name for the account. - - -
-
- Update the 'Cache key and origin requests' settings
-
- - Select Cache policy and origin request policy (recommended) + Choose Create Account. -
-
- Under 'Cache policy', click Create policy
-
-
-
+
-
-
- - Set 'Name' to somleng-proxy - -
-
-
- - Set 'Minimum TTL' to 0 - -
- - Set 'Maximum TTL' to 1 - -
- - Set 'Default TTL' to 0 - -
-
-
- - Under 'Headers', select Include the following headers - -
-
- Select the following headers:
-
-
-
- - Authorization - -
- - Accept-Encoding - -
+ + 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. + +
-
- - - Set 'Query strings' to None - -
- - Set 'Cookies' to None - -
-
-
- - Deselect both Gzip and Brotli - -
- -
-
-
- 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 - -
-
+ + After you have created your account, the SID and Auth Token are shown on the next screen: +
-
+ -
-
- - Set 'Price class' to Use all edge locations (best performance) + Sign in to the Dashboard and from the side-navigation, click Phone Numbers.
- - Set 'Alternate domain name (CNAME)' to your-domain.example.com + Click the icon to create a new phone number.
- - Set 'Custom SSL certificate' to your certificate or click the link to Request certificate. + Enter the phone number including he country code in E.164 format.
- - Set security policy to TLSv1.2_2021 (recommended) or to the latest recommended - policy. + Link the phone number to the account by selecting the account created in the previous step. - - - -
- - Click Create distribution - -
- + Choose Create Phone number. + + -
- - Set 'Origin domain to' api.somleng.org - -
- - DO NOT set the X-Forwarded-Host header - -
- + Click the dropdown and choose + Configure. + +
- + Configure the phone number by entering a Voice URL that returns valid + TwiML for + Programmable Voice . + +
- + Configure other optional parameters for the phone number as necessary. + +
- + Choose Update Configuration. + +
- + GoIP + +
- + + General Configuration + + +
- + + Basic VoIP Configuration + + +
- + + Advanced VoIP Configuration + + +
- + + Call-In Configuration + + +
- + + Testing + + +
- + + Advanced Routing Configuration (Optional) + + +
- + + Additional Resources + + +
- + From the side-navigation, click Configurations -> Preferences. + +
- + Set IVR to Disable + +
- + Click Save Changes. + +
- - Sign in to the Dashboard and from the side-navigation, click Carrier Settings. - -
- - Click the icon to edit your settings. - -
- - Under custom domain, enter your dashboard and API hosts. - -
- - Choose Update Carrier Settings. - -
- + From the side-navigation, click Configurations -> Basic VoIP. + +
- + Choose your preferred configuration mode as described above from Config Mode. + +
- + Copy the Username from the Client Credentials section from + Step 1 + and paste it in the Authentication ID field. + +
- + Copy the Password from the Client Credentials section from + Step 1 + and paste it in the Password field. + +
- + Copy the Domain from the Client Credentials section from + Step 1 + and paste it in the SIP Registrar Server field. + +
- + Optionally fill in Routing Prefix to control the channel selection algorithm. + Please refer to the + GoIP User + Manual + for more details. + +
- + Click Save Changes. + +
+ + 3. Create a Phone Number +
+ ++ Create a new Phone Number and configure it for inbound + dialing. +
+- API Configuration (optional) -
+- Repeat the exact same process above to create a distribution for your custom API - domain, with the following modifications: -
-
-
+ + After you have created your phone number, you can configure it on the next screen: +
-
- - 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. -
++ 4. Configure your VoIP gateway +
--
- server {
- listen 443;
- server_name dashboard.example.com; # replace this with your dashboard domain
+
+ 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:
- ssl_certificate /path/to/your/fullchain.pem;
- ssl_certificate_key /path/to/your/privatekey.pem;
+
+
+
+ + GoIP Configuration +
- # 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 ++ Follow the instructions below to configure the GoIP gateway to connect to Somleng. +
- ssl_certificate /path/to/your/fullchain.pem; - ssl_certificate_key /path/to/your/privatekey.pem; +-
+
+ 1. General Configuration +
-- 2. Test your custom domain -
++ + 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. + +
-- 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. -
++ In order to configure the GoIP gateway for inbound dialing, we need to turn off the in-built + IVR. +
-- 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. -
++ 2. Basic VoIP Configuration +
--
-
+ The next step is to configure the GoIP gateway to register with Somleng. There are 3 different + modes of configuration depending on your + circumstances. Please refer to the + GoIP User + Manual + for more information about the different configuration modes and the channel selection + algorithms. +
-- 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. -
+| Config Mode | +Description | +
|---|---|
| Single Server Mode | +
+ Use this mode to associate all channels on your GoIP gateway to a single SIP Trunk on
+ Somleng.
+ + + This mode is best if you only have one group of SIM cards and you want to route evenly + between all of them. + + |
+
| Config by Line | +
+ Use this mode to associate a single channel on your GoIP gateway to a single SIP Trunk on
+ Somleng.
+ + + Note: This mode requires you so set a Routing Prefix for each channel. + + |
+
| Config by Group | +
+ Use this mode to associate a group of channels on your GoIP gateway to a single SIP trunk
+ on
+ Somleng.
+ + + This mode is useful if you want to route to a different group of SIM cards based on the + number prefix. + See Advanced Routing Configuration for more info. + + |
+
- 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. -
-+ + Note: If you choose Config by Line or Config by Group you'll + need to repeat the instructions above for each channel or group. + +
-+
+ - Client Gateway Configuration Guide -
++ 3. Advanced VoIP Configuration (Optional) +
-- 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. -
++ Configure DTMF Signaling under the Advance VoIP section. +
-- - 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. - -
+-
+
- + From the side-navigation, click Configurations -> Advance VoIP. + +
- + Ensure NAT Keep-alive is set to Enable. + +
- + Select None from Call OUT Auth Mode. + +
- + Select Outband from DTMF Signaling. + +
- + Select RFC 2833 from Outband DTMF Type. + +
- + Ensure RTP Payload Type is set to 101. + +
- + Click Save Changes. + +
- 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. -
++ 4. Call-In Configuration +
-- The network provider can also use Somleng to offer 3rd party access to the PSTN in their country via - their VoIP gateway. -
-+ Configure caller-id forward mode and VoIP forwarding number. +
-- Configuration Overview -
+-
+
- + From the side-navigation, click Configurations -> Call In. + +
- + Select Use Remote Party ID from CID Forward Mode. + +
- + Ensure Call In is set to Enable. + +
- + Fill in Forwarding to VoIP Number with the number you configured in + Step + 3. + +
- + Click Save Changes. + +
- - 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. - -
++ Note: Repeat this step for each channel you need to configure. +
-- Below is an overview of the steps required to configure a client gateway: -
+
+ -
-
- - - Create a SIP Trunk - to obtain your SIP credentials. - -
- - - Create an account - to obtain your Account SID and Auth Token for outbound dialing. - -
- - - Create a Phone Number - for inbound dialing. - -
- - - Configure your VoIP Gateway - to connect to Somleng. - -
+ 5. Testing +
-
-
- Note: Currently Somleng officially supports the following gateways:
-
+ Reboot, then test your configuration.
+
-
+
-
+
- + From the side-navigation, click Tools -> Reboot. + +
- + From the side-navigation, click Status -> General. + +
- + Under Call Status and Setting ensure that Login, Call In and Call + Out shows Y in each column. + +
- + Test an inbound call by making a call to one of the phone numbers you configured in + Step + 3. + +
- + Test an outbound call using the + Account API . + Use the credentials from the account you created in + + Step 2. + +
- 1. Create a SIP Trunk -
+
+ - Create a new SIP Trunk and configure it with client - credentials authentication. -
++ 6. Advanced Routing Configuration (Optional) +
--
-
- - Sign in to the Dashboard and from the side-navigation, click SIP Trunks. - -
- - Click the icon to create a new SIP trunk. - -
- - Under General, select Client credentials for the authentication mode. - -
- - Set Max channels to the number of channels (or SIM cards) your have available on - your VoIP Gateway. - -
- - 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. - -
- - Under Outbound Dialing optionally configure Route prefixes, Dial string - prefix and select National dialing where appropriate. - -
- - Choose Create SIP Trunk. - -
+ Let's say you have a GoIP-8 with 3 groups of SIM Cards from 3 different mobile operators. Assume + you have 4 SIM cards from Telco A, + 3 SIM cards from Telco B, and 1 SIM Card from Telco C and you want to route calls from Telco A + to + group 1, + Telco B to group 2 and Telco C to group 3 according to the table below. +
-
+ | No. of SIM cards | +Telco | +Prefixes | +Group | +Lines | +
|---|---|---|---|---|
| 4 | +Telco A | +85510, 85515, 85516 | +Group 1 | +Lines 1-4 | +
| 3 | +Telco B | +85531, 85571, 85597 | +Group 2 | +Lines 5-7 | +
| 1 | +Telco C | +85511, 85512, 85517 | +Group 3 | +Line 8 | +
- After you have created a SIP trunk you will see your client credentials on the next screen: -
++ In order to handle this situation complete the following steps. +
-
- -
+
-
+
+ Configure 3 separate SIP Trunks (one for each Telco) as per the instructions in + Step 1 of + the Client Configuration Guide. +
++ For each SIP trunk specify: +
-
+
- + Max channels. This should equal the number of SIM cards installed for the + telco. + +
- + Route prefixes. A comma separated list of route prefixes for the telco. + Must include the country code. + +
- + Dial string prefix. A unique numeric identifier for the group prepended + to + the dial string. This will be used by GoIP to identify the channel group. + +
- + Select National dialing. This will ensure that the national dialing + format + will be sent to your GoIP. + +
--- 2. Create an Account -
+
+
- - Create a new Account to obtain your Account SID and - Auth Token - for outbound dialing. -
+- +
++ Configure Basic VoIP configuration for each group created above, as per the instructions in + + Step + 2 of the GoIP Configuration Guide. +
+ ++ For each group specify: +
-
+
- + Authentication ID. This should match the Username + generated from the previous step. + +
- + Password. This should match the Password generated from + the previous step. + +
- + SIP Registrar Server. This should match the Domain + obtained from the previous step. + +
- + Routing Prefix: This should match the Dial string prefix + configured above. + +
-
-
- - Sign in to the Dashboard and from the side-navigation, click Accounts. - -
- - Click the icon to create a new account. - -
- - Enter a name for the account. - -
- - Choose Create Account. - -
+ - +
+ ++ Configure Call Out configuration for each channel. +
-- - 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. - -
++ For each channel, specify a Dial Plan to remove the routing prefix setup in + the previous step. This removes the prefix before calling out. +
-
+
+ - After you have created your account, the SID and Auth Token are shown on the next screen: -
-
-
+ 7. Additional Resources +
-- 3. Create a Phone Number -
++ Below is a list of additional resources for the GoIP Gateway. +
-- Create a new Phone Number and configure it for inbound - dialing. -
+-
+
- + GoIP User Manual + +
- + Latest + Firmware + . + +
- + Official + Website + . + +
-
-
- - Sign in to the Dashboard and from the side-navigation, click Phone Numbers. - -
- - Click the icon to create a new phone number. - -
- - Enter the phone number including he country code in E.164 format. - -
- - Link the phone number to the account by selecting the account created in the previous step. - -
- - Choose Create Phone number. - -
-
- After you have created your phone number, you can configure it on the next screen: -
++ SMS Gateway Configuration Guide +
-
+ + Setting up an SMS Gateway allows + independent entities + to provide programmable SMS through their own SMS infrastructure. +
--
-
- - Click the dropdown and choose - Configure. - -
- - Configure the phone number by entering a Voice URL that returns valid - TwiML for - Programmable Voice . - -
- - Configure other optional parameters for the phone number as necessary. - -
- - Choose Update Configuration. - -
+ SMS infrastructure can mean anything from an API connection to a provider that you manage, + a simple GSM Modem, or an SMPP connection to a carrier. +
-
- + + Note: Providing programmable SMS as an independent entity isn't restricted to carriers or + organizations. + Any individual can become an independent entity as long as they have access to their own SMS + infrastructure. + +
-- 4. Configure your VoIP gateway + How it works
+
+
- 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: + independent entities connect to Somleng via Somleng's SMS Gateway App installed on-premise, or on + the + cloud + infrastructure managed by the independent entity. +
--
-
- - GoIP - -
+ Customers can then use the + Account API + to send and receive SMS though the independent entity's SMS infrastructure.
- GoIP Configuration -
++ Configuration Overview +
- Follow the instructions below to configure the GoIP gateway to connect to Somleng. + Below is an overview of the steps required to configure an SMS gateway:
- - - General Configuration - + Create an SMS + Gateway +
- - - Basic VoIP Configuration - + Create an Account +
- - - Advanced VoIP Configuration - + Create and configure a + Phone Number +
- - - Call-In Configuration - + Install the + Somleng + SMS Gateway App +
- - - Testing - + Send an Outbound + Message +
- - - Advanced Routing Configuration (Optional) - + Receive an + Inbound Message +
- - - Additional Resources - + Additional Steps
- 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. - -
++ 1. Create an SMS Gateway +
- In order to configure the GoIP gateway for inbound dialing, we need to turn off the in-built IVR. + Create an SMS gateway via the Dashboard.
--
-
- - From the side-navigation, click Configurations -> Preferences. - -
- - Set IVR to Disable - -
- - Click Save Changes. - -
- - 2. Basic VoIP Configuration -
-- The next step is to configure the GoIP gateway to register with Somleng. There are 3 different - modes of configuration depending on your - circumstances. Please refer to the - GoIP User - Manual - for more information about the different configuration modes and the channel selection algorithms. -
- -| Config Mode | -Description | -
|---|---|
| Single Server Mode | -
- Use this mode to associate all channels on your GoIP gateway to a single SIP Trunk on
- Somleng.
- - - This mode is best if you only have one group of SIM cards and you want to route evenly - between all of them. - - |
-
| Config by Line | -
- Use this mode to associate a single channel on your GoIP gateway to a single SIP Trunk on
- Somleng.
- - - Note: This mode requires you so set a Routing Prefix for each channel. - - |
-
| Config by Group | -
- Use this mode to associate a group of channels on your GoIP gateway to a single SIP trunk on
- Somleng.
- - - This mode is useful if you want to route to a different group of SIM cards based on the - number prefix. - See Advanced Routing Configuration for more info. - - |
-
- - From the side-navigation, click Configurations -> Basic VoIP. - -
- - Choose your preferred configuration mode as described above from Config Mode. - -
- - Copy the Username from the Client Credentials section from - Step 1 - and paste it in the Authentication ID field. + Sign in to the Dashboard and from the side-navigation, click SMS Gateways under + Messaging.
- - Copy the Password from the Client Credentials section from - Step 1 - and paste it in the Password field. + Click the icon to create a new SMS Gateway.
- - Copy the Domain from the Client Credentials section from - Step 1 - and paste it in the SIP Registrar Server field. + Enter a name for your SMS Gateway.
- - Optionally fill in Routing Prefix to control the channel selection algorithm. - Please refer to the - GoIP User - Manual - for more details. + Enter the maximum number of channels your SMS gateway supports. Leave it blank for unlimited + channels.
- - Click Save Changes. + Choose Create SMS gateway.
- - Note: If you choose Config by Line or Config by Group you'll - need to repeat the instructions above for each channel or group. - + 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.
-
+
- 3. Advanced VoIP Configuration (Optional) -
++ 2. Create an Account +
- Configure DTMF Signaling under the Advance VoIP section. + Create an Account via the Dashboard. +
++ Note: You can skip this step if you already have a carrier account setup.
+
- - From the side-navigation, click Configurations -> Advance VoIP. - -
- - Ensure NAT Keep-alive is set to Enable. - -
- - Select None from Call OUT Auth Mode. - -
- - Select Outband from DTMF Signaling. + Sign in to the Dashboard and from the side-navigation, click Accounts.
- - Select RFC 2833 from Outband DTMF Type. + Click the icon to create a new account.
- - Ensure RTP Payload Type is set to 101. + Give the account a name.
- - Click Save Changes. + 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. +
-
+
- 4. Call-In Configuration -
++ 3. Create and configure a Phone Number +
- Configure caller-id forward mode and VoIP forwarding number. + Create a new Phone Number and configure it for inbound + messaging.
- - From the side-navigation, click Configurations -> Call In. + Sign in to the Dashboard and from the side-navigation, click Phone Numbers.
- - Select Use Remote Party ID from CID Forward Mode. + Click the icon to create a new phone number.
- - Ensure Call In is set to Enable. + Enter the phone number including he country code in E.164 format.
- - Fill in Forwarding to VoIP Number with the number you configured in - Step - 3. + Link the phone number to the account by selecting the account created in the previous step.
- - Click Save Changes. + Choose Create Phone number.
- Note: Repeat this step for each channel you need to configure. + After you have created your phone number, you can configure it on the next screen:
-
- - 5. Testing -
- -- Reboot, then test your configuration. -
+
- - From the side-navigation, click Tools -> Reboot. - -
- - From the side-navigation, click Status -> General. + Click the dropdown and choose + Configure.
- - Under Call Status and Setting ensure that Login, Call In and Call - Out shows Y in each column. + 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.
- - Test an inbound call by making a call to one of the phone numbers you configured in - Step - 3. + Choose GET from SMS method if you used the URL above.
- - Test an outbound call using the - Account API . - Use the credentials from the account you created in - - Step 2. + Choose Update Configuration.
- - 6. Advanced Routing Configuration (Optional) -
-- Let's say you have a GoIP-8 with 3 groups of SIM Cards from 3 different mobile operators. Assume - you have 4 SIM cards from Telco A, - 3 SIM cards from Telco B, and 1 SIM Card from Telco C and you want to route calls from Telco A to - group 1, - Telco B to group 2 and Telco C to group 3 according to the table below. + After you have configured your phone number you can review the configuration on the next screen:
-| No. of SIM cards | -Telco | -Prefixes | -Group | -Lines | -
|---|---|---|---|---|
| 4 | -Telco A | -85510, 85515, 85516 | -Group 1 | -Lines 1-4 | -
| 3 | -Telco B | -85531, 85571, 85597 | -Group 2 | -Lines 5-7 | -
| 1 | -Telco C | -85511, 85512, 85517 | -Group 3 | -Line 8 | -
+ The + Somleng SMS Gateway + App . + is as a gateway between Somleng and your SMS infrastructure. +
- In order to handle this situation complete the following steps. + 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.
--
-
-
-
- Configure 3 separate SIP Trunks (one for each Telco) as per the instructions in - Step 1 of - the Client Configuration Guide. -
-- For each SIP trunk specify: -
-
-
- - Max channels. This should equal the number of SIM cards installed for the - telco. - -
- - Route prefixes. A comma separated list of route prefixes for the telco. - Must include the country code. - -
- - Dial string prefix. A unique numeric identifier for the group prepended to - the dial string. This will be used by GoIP to identify the channel group. - -
- - Select National dialing. This will ensure that the national dialing format - will be sent to your GoIP. - -
+ Once the SMS Gateway app is configured and successfully connected to Somleng, you should see the + connection status show Connected + the Dashboard. +
-
-
+
+ - Configure Basic VoIP configuration for each group created above, as per the instructions in - Step - 2 of the GoIP Configuration Guide. -
++ 5. Send an Outbound Message +
-- For each group specify: -
-
-
- - Authentication ID. This should match the Username - generated from the previous step. - -
- - Password. This should match the Password generated from - the previous step. - -
- - SIP Registrar Server. This should match the Domain - obtained from the previous step. - -
- - Routing Prefix: This should match the Dial string prefix - configured above. - -
+ 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
+- Configure Call Out configuration for each channel. -
+ + Note: TheFrom parameter must match the phone number you created in
+ Step 3.
+
+
- - For each channel, specify a Dial Plan to remove the routing prefix setup in - the previous step. This removes the prefix before calling out. -
++ You should see the message appear in the Messages section of the Dashboard. +
-
-
- 7. Additional Resources -
++ 6. Receive an Inbound Message +
- Below is a list of additional resources for the GoIP Gateway. + In order to test an inbound SMS, simply send a message to the number you configured in + Step 3.
--
-
- - GoIP User Manual - -
- - Latest Firmware - . - -
- - Official Website - . - -
+
+ 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. +
-- SMS Gateway Configuration Guide -
++ If you don't see the message on the Dashboard, you can check the Error Logs + section + of the Dashboard. +
-- 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. -
++ 7. Additional Steps +
-- - 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. - -
++ If you need more control over which channels outbound SMS are delivered though, you can configure + one or more + Channel Groups. +
-- How it works -
++ 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. +
+
+ -
- Network providers connect to Somleng via Somleng's SMS Gateway App installed on-premise, or on the - cloud - infrastructure managed by the network provider. -
++ Installation Guide +
- Customers can then use the - Account API - to send and receive SMS though the network provider's SMS infrastructure. + This guide is intended to get you up and running with Somleng on your local machine. It is not + intended + for production. If you are just getting started with Somleng we recommend following the + Getting Started guide before + attempting to install Somleng on your local machine.
-- Configuration Overview + Prerequisites
-- Below is an overview of the steps required to configure an SMS gateway: -
-- - Create an SMS - Gateway + Install Docker and git on your local machine. +
+ Overview +
+ ++ Below is an overview of the steps required to complete this guide: +
+ -- 1. Create an SMS Gateway -
- -- Create an SMS gateway via the Dashboard. -
- --
-
-
- - Sign in to the Dashboard and from the side-navigation, click SMS Gateways under - Messaging. - -
- - Click the icon to create a new SMS Gateway. - -
- - Enter a name for your SMS Gateway. - -
- - Enter the maximum number of channels your SMS gateway supports. Leave it blank for unlimited - channels. - -
- - 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 + 1. Clone the somleng-project repository.
- Create an Account via the Dashboard. -
-- Note: You can skip this step if you already have a carrier account setup. -
- --
-
-
- - Sign in to the Dashboard and from the side-navigation, click Accounts. - -
- - Click the icon to create a new account. - -
- - Give the account a name. - -
- - 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. + Clone the somleng-project repository.
-
+ $ git clone https://github.com/somleng/somleng-project.git && cd somleng-project- 3. Create and configure a Phone Number + 2. Pull the latest Docker images.
-- Create a new Phone Number and configure it for inbound - messaging. -
- --
-
- - Sign in to the Dashboard and from the side-navigation, click Phone Numbers. - -
- - Click the icon to create a new phone number. - -
- - Enter the phone number including he country code in E.164 format. - -
- - Link the phone number to the account by selecting the account created in the previous step. - -
- - Choose Create Phone number. - -
- After you have created your phone number, you can configure it on the next screen: -
- -
-
- -
-
- - Click the dropdown and choose - Configure. - -
- - 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. - -
- - Choose GET from SMS method if you used the URL above. - -
- - Choose Update Configuration. - -
- After you have configured your phone number you can review the configuration on the next screen: -
- -
+ $ docker-compose pull- 4. Download and Install the Somleng SMS Gateway App + 3. Start Somleng.
-- 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. -
- -
+ $ docker-compose up- 5. Send an Outbound Message + 4. Seed the Database
-- You can use the - Account API to test sending an outbound SMS. +
$ docker-compose exec somleng bundle exec rails db:setup
-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
+
+
+Account SID: account-sid
+Auth Token: auth-token
+Inbound 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
-
-
- 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 + 5. Log in to the Dashboard
- If you need more control over which channels outbound SMS are delivered though, you can configure - one or more - Channel Groups. + 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.
- 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. + + 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. +
- -
- Installation Guide -
- -- This guide is intended to get you up and running with Somleng on your local machine. It is not intended - for production. If you are just getting started with Somleng we recommend following the - Getting Started guide before - attempting to install Somleng on your local machine. -
- -- Prerequisites -
- - - -- Overview -
- -- Below is an overview of the steps required to complete this guide: -
- --
-
- - Clone the somleng-project repository. - - -
- - Pull the latest Docker images. - -
- - Start Somleng. - - -
- - Seed the Database. - - -
- - Login to the Dashboard. - -
-
- 1. Clone the somleng-project repository. -
++ RTP and Symmetric Latching +
- Clone the somleng-project repository. + 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.
- -$ 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
-Inbound 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. Login 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. + 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.
- - 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. - + 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.
- -
- 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. -
+