Telegram SIP Connector + Voximplant = Calls to Soft/Cellphones

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 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 (see slide 83), especially in India, Hong Kong, Ethiopia, Saudi Arabia, Russia, Iran, etc. and recently has reached 400 million monthly users.

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/.
2. Go the Applications section and create a sip application.
3. 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:
4. 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:

If everything is correct, a registered user will be marked green:

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:

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

Remember userbob, created at the very beginning? Well, you need to log in with its credentials to our webphone:

Type in usertelegram and click Call, then you'll receive an incoming call to all your devices where Telegram is opened.

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 incoming call interface. It doesn't make a lot of sense, but still.

Click the green button and the call will be forwarded to the webphone, where userbob is logged in.

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

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:

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.

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.