Documentation

1. Create a Customer Account.

In this step you create a new customer account (not to be confused with your carrier account) which will generate a set of credentials used to authenticate to the Verify API.

Perform the following steps:

1. Under the Accounts menu, click the icon to create a new account.
2. Give the account a name.
3. Choose a premium TTS voice (such as Polly.Joanna) from the default TTS Voice dropdown. This will be used by your verification service to determine the TTS provider (Basic or Polly) when sending verification codes via phone call.
4. Press Create Account.

2. Create a Verification Service.

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

Perform the following steps:

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

3. Create a SMS Gateway.

In this step you create a new SMS Gateway which will handle the delivery of verification codes via SMS.

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

Perform the following steps:

1. Under the Messaging menu, select SMS Gateways.
2. Click the icon to create a new SMS gateway.
3. Give your SMS Gateway a name.
4. Enter a Default sender. This will be used as the sender id when sending verification codes. A default sender can an E.164 number or short code.
5. Press Create SMS gateway.

4. Create a SIP Trunk.

In this step you create a new SIP Trunk which will handle the delivery of verification codes via phone call.

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

Perform the following steps:

1. Under the Voice menu, select SIP Trunks.
2. Click the icon to create a new SIP trunk.
3. Under Authentication mode, choose Client credentials.
4. Give your SIP Trunk a name.
5. Enter a Default sender. This will be used as the sender id when sending verification codes via phone call. A default sender can an E.164 number or short code.
6. Press Create SIP trunk.

5. Run the Somleng SMS Gateway Application.

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

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

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

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

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

After your SMS Gateway Application is running on your local machine you should see the connection status update to Connected. You can also view the connection status on your local machine by visiting http://localhost:3210 .

6. Register your softphone with the SIP Trunk.

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

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

To configure your softphone perform the following steps:

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

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

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

7. Start a new Verification Flow

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

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

Run the code below substituting the following:

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

// To run this code, download the Somleng.js helper library from:
// https://www.somleng.org/docs/twilio_api/#helper-libraries

// Then, find your Account SID and Auth Token from the Somleng console
// and set the following environment variables.
// const accountSid = process.env.SOMLENG_ACCOUNT_SID;
// const authToken = process.env.SOMLENG_AUTH_TOKEN;

const accountSid = "change-me";
const authToken = "change-me";
const verificationServiceSid = "change-me";
const to = "+15017122661";
const channel = "sms";
const client = require('somleng')(accountSid, authToken);

client.verify.v2.services(verificationServiceSid)
      .verifications
      .create({to: to, channel: channel})
      .then(verification => console.log(verification.sid));
                  

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

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

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

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

9. Resend the verification code via a call.

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

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

// To run this code, download the Somleng.js helper library from:
// https://www.somleng.org/docs/twilio_api/#helper-libraries

// Then, find your Account SID and Auth Token from the Somleng console
// and set the following environment variables.
// const accountSid = process.env.SOMLENG_ACCOUNT_SID;
// const authToken = process.env.SOMLENG_AUTH_TOKEN;

const accountSid = "change-me";
const authToken = "change-me";
const verificationServiceSid = "change-me";
const to = "+15017122661";
const channel = "call";
const client = require('somleng')(accountSid, authToken);

client.verify.v2.services(verificationServiceSid)
      .verifications
      .create({to: to, channel: channel})
      .then(verification => console.log(verification.sid));

10. Receive the verification via a call.

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

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

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

11. Complete the flow by confirming the verification code.

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

Run the code below, substituting the following:

1. Set accountSid and authToken from the account you created in Step 1.
2. Set verificationServiceSid from the verification service you created in Step 3.
3. Set verificationCode from the verification code received via SMS or call in Step 9 or Step 11.

// To run this code, download the Somleng.js helper library from:
// https://www.somleng.org/docs/twilio_api/#helper-libraries

// Then, find your Account SID and Auth Token from the Somleng console
// and set the following environment variables.
// const accountSid = process.env.SOMLENG_ACCOUNT_SID;
// const authToken = process.env.SOMLENG_AUTH_TOKEN;

const accountSid = "change-me";
const authToken = "change-me";
const verificationServiceSid = "change-me";
const to = "+15017122661";
const verificationCode = "change-me"
const client = require('somleng')(accountSid, authToken);

client.verify.v2.services(verificationServiceSid)
      .verificationChecks
      .create({to: to, code: verificationCode})
      .then(verification_check => console.log(verification_check.status));

After you complete the flow you can view the Verification and the associated logs from the Dashboard.

1. Under the Verify menu, select Verifications.
2. Click on the verification you just created in the list.

🎉 Congratulations!

Congratulations! You have successfully completed the tutorial and built your own phone verification service!

What we learned:

1. Customer accounts (not to be confused with your carrier account) are used to manage access to the API. You can create as many customer accounts as you need.
2. A Verification Service is a set of common configurations used to create and check verifications. A verification service includes a Friendly name and a Code length.
3. An SMS Gateway is used to deliver SMS messages including verification codes.
4. A SIP Trunk is used to send voice calls including verification codes.
5. The Somleng SMS Gateway Application is a stand-alone application which runs on your local machine and communicates with the SMS Gateway. It allows you to take full control of the SMS delivery process.
6. The somleng-node helper library can be used to start and check verification flows from your application.

1. Create a new Chime Voice Connector

In this step you create and configure a new Voice Connector on Amazon Chime.

Perform the following steps:

1. Under Amazon Chime SDK, create a new Voice Connector.
2. Give the Voice connector a name.
3. Set Encryption to Disabled.
4. Press Create Voice Connector
5. Configure the termination settings
   1. On the Termination tab, set Termination status to Enabled.
   2. Under Allowed hosts list, add the following IP addresses:
      • 13.250.230.15/32
      • 52.4.242.134/32
      These are Somleng's public IP address documented here.
   3. Press Save.
6. Assign a phone number.
   1. On the Phone numbers tab, press Assign from inventory.
   2. Select a phone number from the list and press Assign from inventory.

2. Create a new Phone Number

In this step you create a new phone number on Somleng which matches the phone number you configured in Step 1 on Chime. This phone number will be used as the caller ID when routing calls through Chime.

In addition we'll assign this new number to the customer account that you created in the previous tutorial, so that you can use it can be used to send generic voice calls as well as verification calls.

Note: The phone number you create in this step must exactly match the phone number assigned in the previous step otherwise Chime will reject your calls.

Perform the following steps:

1. From the Somleng Dashboard, under the Phone Numbers menu, click the icon to create a new phone number.
2. Enter the same phone number that you configured in Step 1 on Chime.
3. Assign the phone number to the customer account that you created in the previous tutorial.
4. Press Create Phone number.

3. Configure a new SIP Trunk.

In this step you configure a new SIP Trunk on Somleng to point to the newly created Voice Connector in Step 1.

If you recall from the previous tutorial, we already created a SIP trunk to handle calls to our local softphone. In this step you'll create a new SIP trunk to handle the delivery of calls through Chime. You'll still keep the SIP trunk created in the previous tutorial to handle calls to your softphone.

In a real-world scenario this setup would be useful for routing calls through a different SIP trunk depending on the destination. For example you might want to handle domestic calls through your own VoIP gateway and international calls through Chime.

We can simulate this scenario in reverse, by configuring the new SIP trunk to only handle calls with a certain prefix. All other prefixes will be routed though the default SIP Trunk which points to your local softphone. This way you can test a a call destined to your real phone number, which will be routed though Chime and a call destined to an overseas number, which will be routed to your local softphone.

Perform the following steps:

1. From the Somleng Dashboard, under the Voice menu, select SIP Trunks.
2. Click the icon to create a new SIP trunk.
3. Under Authentication mode, choose IP address.
4. Give your SIP Trunk a name (e.g Amazon Chime).
5. Set the Outbound Dialing Host to the Outbound host name that was when you created the Chime Voice Connector in Step 1. The host should be of the form your-chime-host-id.voiceconnector.chime.aws
6. Under Route prefixes add the international dialing code (e.g. +855) for your real phone number. This will be used to correctly select this SIP trunk based on the destination number.
7. Enter the phone number you created in Step 2 as the Default sender.
8. Check Plus prefix. This send outbound calls using a plus (+) prefix is a requirement of Chime.
9. Press Create SIP trunk.

4. Test a call to your own number

In this step you'll test a call to your own phone number which should be routed though Chime.

Below is an example of how to use the Phone Calls API using the somleng-node helper library.

The Phone Calls API is different from the Verification API used in the previous tutorial. It allows you to send automated phone calls and control them using TwiML and requires the following parameters:

to

The phone number that will receive the call.

from

The phone number that will be used to make the call. This number must be assigned to the customer account you created in the previous tutorial, and must match the number created in Step 2.

twiml

TwiML instructions to control the call.

Run the code below substituting the following:

• Set accountSid and authToken from the account you created in the previous tutorial.
• Set to to the phone number which will receive the call.
• Set from to the number you configured in Step 2.
• Optionally update the twiml as you like.

// To run this code, download the Somleng.js helper library from:
// https://www.somleng.org/docs/twilio_api/#helper-libraries

// Then, find your Account SID and Auth Token from the Somleng console
// and set the following environment variables.
// const accountSid = process.env.SOMLENG_ACCOUNT_SID;
// const authToken = process.env.SOMLENG_AUTH_TOKEN;

const accountSid = "change-me";
const authToken = "change-me";
const to = "change-me"; // A phone number which will receive the call
const from = "change-me"; // This should exactly match the number configured in Step 2.
const twiml = "<Response><Say>Hello World from the Somleng Chime Tutorial! How are you today?</Say><Play>https://demo.twilio.com/docs/classic.mp3</Play></Response>"

const client = require('somleng')(accountSid, authToken);

client.calls
  .create({ to: to, from: from, twiml: twiml })
  .then(call => console.log(call.sid));

You should receive a phone call to your real phone number delivered through the SIP Trunk connected to Chime. Pick up the call and listen to the message. You should hear what you have entered in the TwiML instructions above.

Note: Instead of running this code, you could also re-run the Verification Flow as show in the previous tutorial. You should receive the verification code on your real phone number delivered through Chime.

5. Test a call to an international number

In this step you'll test a call to an international number (with a prefix different from your own number), which should be routed to your local softphone.

In order to complete this step, simply update the to parameter to a phone number which does not match the international prefix of your own number. This will result in the SIP trunk from the previous tutorial being selected and therefore the call should be routed to your local softphone.

Go ahead and run the code again from the previous step. Remember to replace the to parameter and keep the rest the same.

You should receive a phone call to your real phone number delivered through the SIP Trunk connected to your local softphone. Pick up the call and listen to the message. You should hear what you have entered in the TwiML instructions from the previous step.

🎉 Congratulations!

Congratulations! You have successfully completed the tutorial and connected Somleng to Chime.

What we learned:

1. How to connect Somleng to Amazon Chime.
2. A Phone number must be assigned to a customer account in order to use it in the Phone Calls API .
3. Multiple SIP Trunks can be configured to handle routing based on the destination phone number.
4. The Phone Calls API is different from the Verification API . It can be used to create outbound calls and control the call via TwiML instructions .

Prerequisites

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

Overview

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

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

1. Update your carrier settings.

In this step, you'll update your carrier settings and add a logo. In this tutorial we're using an imaginary company called Rocket Communications.

Perform the following steps:

1. Click on Carrier Settings from the main menu.
2. Upload your company's logo.
3. Optionally update other details about your company.
4. Press Update Carrier Settings.

2. Create a new Account for your customer.

In this step you create a new account for your customer. There are two types of accounts on Somleng namely: Carrier Managed and Customer Managed. As the name suggests, Customer Managed accounts are managed by the carrier's customer, who will get access to the Dashboard and can manage their own Account SID and Auth Token. Here we'll create a customer account for our imaginary customer Elvie Padberg from Klocko Block, but feel free to use your own customer details.

Perform the following steps:

1. Under the Accounts menu, click the icon to create a new account.
2. Give the account a name.
3. Under Owner, enter the customer's name and email address.
   Note: You cannot invite yourself as your own customer. You must use a different email address than the one you used to sign up for Somleng. However, in order to complete this tutorial you'll need to choose an email that you have access to, so you can explore the dashboard from the customer's perspective. If you only have one email address you can use the following trick: your-email+customer-email@your-domain.tld. For example, if your real email address is bob@example.com and your customer's name is Elive Padberg, enter bob+elvie.padberg@example.com.
4. Choose a premium TTS voice (such as Polly.Joanna) from the default TTS Voice dropdown. This will be used to determine the TTS provider (Basic or Polly) when sending phone calls.
5. Press Create Account.

3. Log in to the Dashboard as if you are the customer.

In this step, you'll log in to the Dashboard as if you are the customer. To do this you'll first need to log out of your carrier account, then click the customer invitation link from your email.

Note: In a real-world scenario you would never log in to the customer's account. The goal of this step is to understand the customer's experience.

Perform the following steps:

1. Click on your avatar in the top right corner and select Logout from the dropdown.
2. Check your email. You should have received a customer invitation email when completing the previous step.
3. Follow the link in the email and set your password.
4. Setup two factor authentication (2FA).

You should now be viewing the dashboard from the customer's perspective.

4. Explore the Dashboard and API docs from the customer's perspective.

In this step, feel free to click around and explore the Dashboard from the customer's perspective.

Notice the following:

• Your company's logo appears in the top left of the Dashboard.
• The customer can manage their own Account SID and Auth Token.
• The customer cannot view or manage any carrier resources such as SIP Trunks, SMS Gateways etc.
• The customer can only see resources (e.g. Phone Calls, Messages etc) that belong to their account.
• The API docs are branded with your company's name and logo.

5. Use the API and Dashboard from the customer's perspective.

In this step, you'll explore using the Verify API from the customer's perspective.

Perform the following steps:

1. Under the Verify menu, select Services.
2. Click the icon to create a new verification service.
3. Give your verification service a friendly name.
4. Press Create Verification service.

Make sure your softphone is still registered with the SIP trunk that you created in the first tutorial.

Then, run the code below substituting the following:

• Set accountSid and authToken from the values shown on the Account Settings page.
• Set verificationServiceSid from the verification service you just created.

// To run this code, download the Somleng.js helper library from:
// https://www.somleng.org/docs/twilio_api/#helper-libraries

// Then, find your Account SID and Auth Token from the Somleng console
// and set the following environment variables.
// const accountSid = process.env.SOMLENG_ACCOUNT_SID;
// const authToken = process.env.SOMLENG_AUTH_TOKEN;

const accountSid = "change-me";
const authToken = "change-me";
const verificationServiceSid = "change-me";
const to = "+15017122661";
const channel = "call";
const client = require('somleng')(accountSid, authToken);

client.verify.v2.services(verificationServiceSid)
      .verifications
      .create({to: to, channel: channel})
      .then(verification => console.log(verification.sid));

You can now view the verification from the customer's perspective from the Verify menu on the Dashboard.

If you completed the first tutorial, and your softphone is still connected, then you should receive the verification call.

Note: In this step we demonstrated that your customers can use the Verify API, which is connected to your SIP infrastructure. In a real-world scenario you would connect your SIP trunk to a VoIP Gateway, Amazon Chime or your own SIP Infrastructure.

Prerequisites

1. Complete the Verify tutorial.
2. Complete the Chime tutorial.
3. Sign up for a free Retell AI trial account.
4. Install Node.js and ngrok .

Overview

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

1. Obtain your Retell AI credentials.
2. Run the retell_server.js application.
3. Confirm you have completed the previous tutorials.
4. Talk with the AI.

1. Obtain your Retell AI credentials

1. Login to your Retell AI account, select API Keys from the menu and copy your API key.
2. Select Agents from the menu, select and Agent and copy the Agent ID as shown below.

2. Run the retell_server.js application

1. Download retell_server.js and package.json from the Somleng SWITCH testing repository
2. Install the required packages with npm

   npm install

3. Run retell_server.js replacing RETELL_AI_API_KEY and RETELL_AI_AGENT_ID with the values from Step 1. After running this command you should see the server running on localhost:3000.

   node retell_server.js --api_key RETELL_AI_API_KEY --agent_id RETELL_AI_AGENT_ID --port 3000

4. In another terminal window run the following command to expose the server to the internet.

   ngrok http 3000

5. Note the forwarding URL: It should look something like this: https://eb3c-229-14-127-42.ngrok-free.app

3. Confirm you have completed the previous tutorials

Ensure you have completed the Verify and Chime tutorials. You will need to have configured a Somleng customer account, a SIP trunk which is connected to Chime, and a phone number to continue.

4. Talk with the AI

In this step we'll create an outbound call to your number. After you answer the call, Somleng will request TwiML instructions from the ngrok URL obtained from Step 2. Ngrok will forward the request to the retell_server.js application which will connect your call to Retell AI.

Run the following code:

// To run this code, download the Somleng.js helper library from:
// https://www.somleng.org/docs/twilio_api/#helper-libraries

// Then, find your Account SID and Auth Token from the Somleng console
// and set the following environment variables.
// const accountSid = process.env.SOMLENG_ACCOUNT_SID;
// const authToken = process.env.SOMLENG_AUTH_TOKEN;

const accountSid = "change-me"; // Replace with the accountSid obtained when completing the Verify tutorial.
const authToken = "change-me"; // Replace with the authToken obtained when completing the Verify tutorial.
const to = "change-me"; // A phone number which will receive the call.
const from = "change-me"; // This should exactly match the number obtained from the Chime tutorial.
const url = "change-me"; // Replace with the ngrok URL obtained from step 2.

const client = require('somleng')(accountSid, authToken);

client.calls
  .create({ to: to, from: from, url: `${url}/connect` })
  .then(call => console.log(call.sid));

🎉 Congratulations!

Congratulations! You have successfully completed the tutorial and connected Somleng with Retell AI.

What we learned:

1. Retell AI works with Somleng out of the box. This makes it possible to replace Twilio with Somleng for your existing workflows.
2. You can replace Chime with your own infrastructure or voice termination provider.
3. You can also replace Retell AI with Vocode to have a complete solution built on open source software.

Import Phone Numbers

In order to bulk import phone numbers, you can upload a CSV file from the Dashboard. Somleng requires a CSV file in the following format:

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

Column Header	Required/Optional	Content	Possible Values	Example
number	Required	The phone number or short code	E.164 formatted number or short code. e.g. +12505550199 or 77730	12505550199
type	Required	The type of phone number	One of either local, mobile, toll_free, short_code, or alphanumeric_sender_id	local
visibility	Optional	The visibility of the phone number	One of either private, public, or disabled defaults to public for phone numbers with a price or private for phone numbers without one. true	public
country	Optional	The country of the phone number	Optional ISO 3166-1 alpha-2 country code. If not provided, will try to resolve from the phone number	CA
price	Optional	The monthly price you want to charge for the phone number	A positive value in the billing currency of the carrier	1.15
region	Optional	The state or province abbreviation of this phone number's location	Optional ISO 3166-2 subdivision code	ON
locality	Optional	The locality or city of this phone number's location	The name of a city or locality	Toronto
lata	Optional	The local access and transport area (LATA). Applicable only for phone numbers from the US and Canada.	LATA code	888
rate_center	Optional	The Rate center of this phone number. Applicable only for phone numbers from the US and Canada.	Rate center name	NEWTORONTO
latitude	Optional	The latitude of this phone number's location. Applicable only for phone numbers from the US and Canada.	Latitude	43.6008
longitude	Optional	The longitude of this phone number's location. Applicable only for phone numbers from the US and Canada.	Longitude	-79.5053
meta_*	Optional	Custom metadata. The column name must start with meta_. E.g. meta_my_custom_field	The value for the custom field: E.g. My custom value	My custom value
marked_for_deletion	Optional	Marks the phone number for deletion	true	true

Sample CSV for creating phone numbers

number,type,visibility,country,price,region,locality,lata,rate_center,latitude,longitude,meta_my_custom_field,meta_another_custom_field
+12505550199,local,public,CA,1.15,ON,Toronto,888,NEWTORONTO,43.6008,-79.5053,My custom value,Another custom value

Sample CSV for deleting phone numbers

number,marked_for_deletion
+12505550199,true

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.

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>

<Response>
<Say language="en-US" voice="Polly.Joanna">Hello. I am Joanna and I speak American English!</Say>
</Response>

SMS Gateways

SMS Gateways are used by Somleng for SMS origination and termination. Configuring an SMS Gateway allows you to fully control your own SMS infrastructure.

When you configure an SMS gateway on the Dashboard, you receive a Device Token which uniquely identifies your SMS Gateway. You'll then need to install the Somleng SMS Gateway App on your on-premise or cloud infrastructure. Normally, you'll only need to configure a single SMS Gateway, however if you require multiple SMS gateways, you'll need to run an instance of the for each one. Once the app is running on your local infrastructure and connected to Somleng, the SMS Gateway will show Connected on the Dashboard.

To configure an SMS Gateway:

1. Sign in to the Dashboard and from the side-navigation, click SMS Gateways under Messaging.
2. Click the icon to create a new SMS Gateway.
3. Enter a name for your SMS Gateway.
4. Enter the maximum number of channels your SMS gateway supports. Leave it blank for unlimited channels.
5. Choose Create SMS gateway.

After you create your SMS Gateway you'll see your Device Token on the next screen.

Channel Groups

An SMS gateway channel group allows you control which channels are used by your SMS Gateway to terminate outbound messages. This is mainly used by independent entities who connect via a GSM Gateway.

For example let's assume your GSM Gateway has 4 available channels. Now, let's assume you insert 2 SIM cards belong to a carrier called "Smart", 1 SIM card belonging to a carrier called "Metfone", and another SIM card belonging to a carrier called "Cellcard".

Channel groups allow you to specify which messages will be routed through the "Smart" SIM cards, which messages will be routed through the "Metfone" SIM cards and which messages will be routed through the "Cellcard" SIM cards.

To configure a Channel Group:

1. Sign in to the Dashboard and from the side-navigation, click Channel Groups under Messaging.
2. Click the icon to create a new Channel Group.
3. Enter a name for your Channel Group.
4. Assign the channel group to an SMS Gateway.
5. Specify a comma separated list of prefixes (including the country code) for the Channel Group. This list is used to match the channel group by the destination number of an outbound message.
6. Select the channels that you want to associate with the channel group. The available channels are derived from the maximum number of channels you specified on your SMS Gateway.
7. Choose Create Channel group.

After you have created your Channel Group you can see the configuration details.

Messaging Services

Messaging services allow you to apply messaging configuration to of a group of phone numbers, rather than having to configure each one individually.

To configure an Messaging Service:

1. Sign in to the Dashboard and from the side-navigation, click Messaging Services under Messaging.
2. Click the icon to create a new Messaging Service.
3. Enter a name for your Messaging Service.
4. Choose Next.
5. Add phone numbers to your Messaging Service by selecting them from the Sender Pool. Note these phone numbers must already be assigned to the account you selected above.
6. Choose the default behavior for inbound messages received by the numbers in the pool. You can either:
   • Defer to sender's webhook (Default). This will fallback to configuration for the individual phone number.
   • Drop the message. Your application will ignore inbound messages. You won't be charged for them and they won't show up on the dashboard.
   • Send a webhook. Invoke a HTTP webhook for all incoming messages in the sender pool.
7. If you chose Send a webhook in the previous step you must enter a Inbound Request URL and Inbound request method to request for incoming messages.
8. Optionally configure a Status Callback URL for all outbound messages in the sender pool.
9. Configure Smart encoding for outbound messages. If this is turned on Smart encoding will apply to all outbound messages in the number pool.
10. Choose Create Messaging service.

After you have configured your messaging service you can see the configuration details.

1. Create a SIP Trunk

Create a new SIP Trunk and configure it with client credentials authentication.

1. Sign in to the Dashboard and from the side-navigation, click SIP Trunks.
2. Click the icon to create a new SIP trunk.
3. Under General, select Client credentials for the authentication mode.
4. Set Max channels to the number of channels (or SIM cards) your have available on your VoIP Gateway.
5. Under Inbound Dialing select the default country code of the caller. This should match the country code you use later when you create a phone number.
6. Under Outbound Dialing optionally configure Route prefixes, Dial string prefix and select National dialing where appropriate.
7. Choose Create SIP Trunk.

After you have created a SIP trunk you will see your client credentials on the next screen:

2. Create an Account

Create a new Account to obtain your Account SID and Auth Token for outbound dialing.

1. Sign in to the Dashboard and from the side-navigation, click Accounts.
2. Click the icon to create a new account.
3. Enter a name for the account.
4. Choose Create Account.

Note: You don't need explicity associate the account with the SIP trunk you created in the previous step. Somleng will automatically select the SIP trunk when a call is created or received.

After you have created your account, the SID and Auth Token are shown on the next screen:

3. Create a Phone Number

Create a new Phone Number and configure it for inbound dialing.

1. Sign in to the Dashboard and from the side-navigation, click Phone Numbers.
2. Click the icon to create a new phone number.
3. Enter the phone number including he country code in E.164 format.
4. Link the phone number to the account by selecting the account created in the previous step.
5. Choose Create Phone number.

After you have created your phone number, you can configure it on the next screen:

1. Click the dropdown and choose Configure.
2. Configure the phone number by entering a Voice URL that returns valid TwiML for Programmable Voice .
3. Configure other optional parameters for the phone number as necessary.
4. Choose Update Configuration.

4. Configure your VoIP gateway

After you have completed the previous steps, you can now configure you VoIP gateway to connect to Somleng. Below is the configuration instructions for the following VoIP gateways:

• GoIP

GoIP Configuration

Follow the instructions below to configure the GoIP gateway to connect to Somleng.

1. General Configuration
2. Basic VoIP Configuration
3. Advanced VoIP Configuration
4. Call-In Configuration
5. Testing
6. Advanced Routing Configuration (Optional)
7. Additional Resources

1. Create an SMS Gateway

Create an SMS gateway via the Dashboard.

1. Sign in to the Dashboard and from the side-navigation, click SMS Gateways under Messaging.
2. Click the icon to create a new SMS Gateway.
3. Enter a name for your SMS Gateway.
4. Enter the maximum number of channels your SMS gateway supports. Leave it blank for unlimited channels.
5. Choose Create SMS gateway.

After you create your SMS Gateway you'll see your Device Token on the next screen. You'll need this later in Step 4 when you install the SMS Gateway App.

2. Create an Account

Create an Account via the Dashboard.

Note: You can skip this step if you already have a carrier account setup.

1. Sign in to the Dashboard and from the side-navigation, click Accounts.
2. Click the icon to create a new account.
3. Give the account a name.
4. Choose Create Account.

You'll need to reference this account when you configure a Phone Number in Step 3 and when testing an outbound message in Step 5.

3. Create and configure a Phone Number

Create a new Phone Number and configure it for inbound messaging.

1. Sign in to the Dashboard and from the side-navigation, click Phone Numbers.
2. Click the icon to create a new phone number.
3. Enter the phone number including he country code in E.164 format.
4. Link the phone number to the account by selecting the account created in the previous step.
5. Choose Create Phone number.

After you have created your phone number, you can configure it on the next screen:

1. Click the dropdown and choose Configure.
2. Under Messaging enter an SMS URL that returns valid TwiML for Programmable SMS . This will configure the phone number to handle inbound messages. You can use the following URL: https://tinyurl.com/demo-sms which returns valid TwiML.
3. Choose GET from SMS method if you used the URL above.
4. Choose Update Configuration.

After you have configured your phone number you can review the configuration on the next screen:

4. Download and Install the Somleng SMS Gateway App

The Somleng SMS Gateway App . is as a gateway between Somleng and your SMS infrastructure.

Detailed instructions on how to install, configure and deploy the app can be found on the Somleng SMS Gateway Github repository . You'll need the Device Token from Step 1. to connect the SMS Gateway App to Somleng.

Once the SMS Gateway app is configured and successfully connected to Somleng, you should see the connection status show Connected the Dashboard.

5. Send an Outbound Message

You can use the Account API to test sending an outbound SMS. Replacing the ACCOUNT-SID and AUTH-TOKEN with the information from the account you created in Step 2 you can use the following code to send an SMS:

curl 'https://api.somleng.org/2010-04-01/Accounts/ACCOUNT-SID/Messages.json' -X POST \
--data-urlencode 'To=+855715100860' \
--data-urlencode 'From=+85568308531' \
--data-urlencode 'Body=Hello from Somleng' \
-u ACCOUNT-SID:AUTH-TOKEN

Note: The From parameter must match the phone number you created in Step 3.

You should see the message appear in the Messages section of the Dashboard.

6. Receive an Inbound Message

In order to test an inbound SMS, simply send a message to the number you configured in Step 3.

If you have configured your phone number correctly you should see the message appear in the Messages section of the Dashboard as shown in Step 5.

If you don't see the message on the Dashboard, you can check the Error Logs section of the Dashboard.

7. Additional Steps

If you need more control over which channels outbound SMS are delivered though, you can configure one or more Channel Groups.

Instead of configuring each phone number individually, like we did in Step 3, you can configure a Messaging Service with shared configuration and apply it to multiple phone numbers.