Telegram SIP Connector + Voximplant = Calls to Soft/Cellphones
Tags: javascript, webdev, integration, calls
Published: 2020-04-29 10:34:43

I'm glad to meet each and every of you, fellow devs! My name is Nikita, I'm a lead technical writer at Voximplant. Recently, my colleague released a [great article here](https://dev.to/imaximova/how-we-used-jointjs-in-voximplant-kit-29b0) on how we got through yet another JS-related challenge. As of today, I'm going to show something that is maybe not so exciting, but still fun; I welcome you to a guide on how to use a SIP connector of a messenger app Telegram to enable it to initiate and accept phone calls. 

#What's the Buzz?
There's a SIP connector in a form of a bot in the Telegram ecosystem (@siptg). In the meanwhile, Voximplant is a communications platform. Do you know what it means? Correct, they are meant to be integrated.

For the sake of clarity, even though Telegram is not the most popular messenger worldwide, it's quite a favorite one amongst techies and/or people who concern about their privacy. It is [used globally](https://wearesocial.com/global-digital-report-2019) (see slide 83), especially in India, Hong Kong, Ethiopia, Saudi Arabia, Russia, Iran, etc. and recently has reached [400 million monthly users](https://telegram.org/blog/400-million).   

Without further ado, let's get practical and follow the steps below :)

#Registering a Softphone in Voximplant
The SIP connector can operate in two modes: softphone and gateway. We're going to consider the former, as it allows registering the bot as an inner user of your Voximplant application. This is why we have to create an application and users within it.
1. Log in to your account [https://manage.voximplant.com/](https://manage.voximplant.com/).
1. Go the [Applications](https://manage.voximplant.com/applications) section and create a *sip* application.
1. Being in the application, switch to the *Users* tab to create a *usertelegram* user. Don't forget to specify a password, we'll need it soon:<img src="https://dev-to-uploads.s3.amazonaws.com/i/ir10sisxrgknsl82y183.jpg" width="500">
1. Also, create a *userbob* user, we'll get back to it later.

>Please be aware that @siptg converts users' names to a lower case during outbound calls. This is why you have to name users exactly as it is shown in this tutorial. Otherwise, the telegram bot will be accepting inbound calls, but won't be establishing outbound calls.

Now let's configure the messenger side.

The softphone itself is represented by @siptg, whereas its settings are available at @siptg_bot-open it. Press *Start*, send the */tariff* command, and choose *Free* (it's suitable for testing purposes, even though it has some limitation, e.g., after 5 failed calls the softphone becomes temporarily blocked. The exact time of unblocking can be seen via the same command, */tariff*).

Next, send the */softphone* command and tap *New*. Here, sequentially specify the user's credentials and tap *Apply*. The *server* field consists of *sip.* + Voximplant account + *.voximplant.com*:
![](https://dev-to-uploads.s3.amazonaws.com/i/3ty91a6da9z45bsns76u.png)

If everything is correct, a registered user will be marked green:
![](https://dev-to-uploads.s3.amazonaws.com/i/8ejvx3amigxlt1pbt8aq.png)

Great! It's time to check if Telegram can accept...

#...inbound calls
To do so, we need to open the *sip* Voximplant application and create a JS scenario and a rule in it. The JS scenario is going to be simple: when a call from a *sip* application user lands in the cloud, the cloud calls the second user of the same application and connect them. It looks like this:
```javascript
VoxEngine.addEventListener(AppEvents.CallAlerting, e => {
   const inc = e.call
 
   const out = VoxEngine.callUser(e.destination, e.callerid)
 
   VoxEngine.easyProcess(inc, out)
})
```
Save the scenario with the name *callUser*. Being in the *sip* application, switch to the *Routing* tab to create a *call user rule* with the following settings (pay attention to the pattern):
<img src="https://dev-to-uploads.s3.amazonaws.com/i/xojpyuf1v2vrppv02tag.png" width="600">

Remember *userbob*, created at the very beginning? Well, you need to log in with its credentials to [our webphone](https://phone.voximplant.com/):
<img src="https://dev-to-uploads.s3.amazonaws.com/i/yjf69cyy817ukdst26ur.png" width="600">
Type in *usertelegram* and click *Call*, then you'll receive an incoming call to all your devices where Telegram is opened.
<img src="https://dev-to-uploads.s3.amazonaws.com/i/0k5gv8kcs5bkh0e8i6p0.png" width="600">

#Outbound Calls to Voximplant Users
The same scenario and the rule are applicable here, there is no need to create anything else.

>As mentioned before, Voximpalnt user names should be in lower case. If the name is *userBob*, when you pass it to the @siptg softphone, it will convert it to *userbob*, a non-existing user of your application. Thus, the call will fail.

Open @siptg, send the message "userbob" to it, and the bot will show you an <span style="color:red">incoming call interface</span>. It doesn't make a lot of sense, but still.
<img src="https://dev-to-uploads.s3.amazonaws.com/i/s7lhc7kut5ggr4jkzo50.png" width="300">
Click the green button and the call will be forwarded to the webphone, where *userbob* is logged in.
<img src="https://dev-to-uploads.s3.amazonaws.com/i/tozpsue1vgfi84dtzpmf.png" width="600">

#Outbound Calls to Mobile Numbers
To enable outbound calls to mobile numbers, you'll need:
* another scenario and a rule for it,
* a valid callback number (Caller ID). It could be your own number that you [verified in the Control panel](https://manage.voximplant.com/settings/caller_ids) or a number that is rented from Voximplant. __IMPORTANT: test numbers can't be used for this purpose.__

Go to the *sip* application and create a *callPSTN* scenario with the following code (look at line 4 where you need to substitute your callback number):
```javascript
VoxEngine.addEventListener(AppEvents.CallAlerting, e => {
   const inc = e.call
 
   const out = VoxEngine.callPSTN(e.destination, "real callback number")
 
   VoxEngine.easyProcess(inc, out)
})
```
Next, create a *call PSTN rule* with the default pattern:
<img src="https://dev-to-uploads.s3.amazonaws.com/i/p1vibwbksxsa9h3nmuno.png" width="600">
IMPORTANT: move this new rule to the bottom of the rule list. This way, the rule will have the lowest priority and will be executed only if a rule with the `user.*` pattern is not triggered.
<img src="https://dev-to-uploads.s3.amazonaws.com/i/4d0wwudtatgpp6ei0lh1.png" width="780">
Ok then, now you can send a target phone number to @siptg, it shows you an incoming call interface, you click the green button, and, finally, the call goes to the target number.

#Use the Force
Integration with a messenger can be beneficial for a business, since it's yet another way to reach your customers, to wit, an omnichannel approach. It's also applicable if Telegram serves as your corporate messenger. In general, it comes in handy when you use Telegram and a person you want to reach out to-doesn't. As a result, you both won't be changing your communication environment as a call is initiated from the messenger and is placed to a soft/cellphone.