How to configure the Gateway
on the side PBX
Configuration on the side of PBX (or telephony module CRM) is made after connecting the session to the desired telegram account on the side @siptg_bot and choosing how to communicate with PBX.
The configuration on the PBX side consists of two basic steps:
Unlike standard phone numbers, one of three values (user-id, username, account phone number) can come as a Caller-ID when you call from Telegram, and when you make outgoing calls, you must comply with a number of Telegram restrictions to protect against spam.
You can test the passage of calls on the free rate, but it has a number of restrictions on calls. You can remove restrictions for 1 week by connecting tariff Trial for 100 rubles. After testing the system to use it you need to connect one of the paid tariffs.
See also features of the Gateway configuration with different CRM systems.
The configuration on the PBX side consists of two basic steps:
- Connecting a SIP trunk
- Configuring call routing
Unlike standard phone numbers, one of three values (user-id, username, account phone number) can come as a Caller-ID when you call from Telegram, and when you make outgoing calls, you must comply with a number of Telegram restrictions to protect against spam.
You can test the passage of calls on the free rate, but it has a number of restrictions on calls. You can remove restrictions for 1 week by connecting tariff Trial for 100 rubles. After testing the system to use it you need to connect one of the paid tariffs.
See also features of the Gateway configuration with different CRM systems.
Step 1: Connecting a SIP trunk
SIP trunk is a line for receiving and making calls, with the help of trunks, standard numbers for telephony are connected to PBX . In the case of Telegram-gateway, the number for receiving and making calls will be a Telegram account, to which Telegram users call, and on whose behalf they can call back.
All modern SIP-PBX have the ability to independently connect numbers (trunks). In the case of some virtual PBX to connect a new trunk you may need to send a corresponding request to the support service, but in general it is a simple standard procedure.
Depending on the specific PBX and the used method of communication with SIP.TG servers (which is selected in the bot, one of three) trunk connection procedure is different.
With the registration method PBX->SIP. PBX TG (the simplest and the most often used) you have to specify standard parameters (server, login, password) on the side of PBX . You must get the parameters in @siptg_bot under /gateway when you choose the corresponding registration method.
With the SIP.TG->PBX registration method you must get SIP account data (address PBX, login, password), which you can specify in @siptg_bot under /gateway to connect the trunk.
If you are using IP-IP communication method on @siptg_bot side you should specify address PBX, number to call on PBX side (and optionally field:value), then make call from PBX to address and port received from @siptg_bot in section /gateway for corresponding communication method.
Sometimes you might need to explicitly specify in @siptg_bot for the appropriate communication method the Worker-server used (in the desired country, or your own), the communication protocol (UDP, TCP, TLS), the set of codecs used, DTMF signaling method.
See @siptg_bot instructions for details.
--
After successful connection trunk in PBX interface and bot should be marked as active and ready to work. After basic call routing is set up, the first test calls can be made.
All modern SIP-PBX have the ability to independently connect numbers (trunks). In the case of some virtual PBX to connect a new trunk you may need to send a corresponding request to the support service, but in general it is a simple standard procedure.
Depending on the specific PBX and the used method of communication with SIP.TG servers (which is selected in the bot, one of three) trunk connection procedure is different.
With the registration method PBX->SIP. PBX TG (the simplest and the most often used) you have to specify standard parameters (server, login, password) on the side of PBX . You must get the parameters in @siptg_bot under /gateway when you choose the corresponding registration method.
With the SIP.TG->PBX registration method you must get SIP account data (address PBX, login, password), which you can specify in @siptg_bot under /gateway to connect the trunk.
If you are using IP-IP communication method on @siptg_bot side you should specify address PBX, number to call on PBX side (and optionally field:value), then make call from PBX to address and port received from @siptg_bot in section /gateway for corresponding communication method.
Sometimes you might need to explicitly specify in @siptg_bot for the appropriate communication method the Worker-server used (in the desired country, or your own), the communication protocol (UDP, TCP, TLS), the set of codecs used, DTMF signaling method.
See @siptg_bot instructions for details.
--
After successful connection trunk in PBX interface and bot should be marked as active and ready to work. After basic call routing is set up, the first test calls can be made.
Firewall settings on the side PBX
If you use Firewall to protect your PBX, make sure that the actual addresses of our Worker-servers that connect to PBX are in the white list.
All IP-addresses of our servers are listed in the file:
https://www.sip.tg/fw.txt
Sometimes the Worker-server network is updated, we inform about it in the news channel @siptg_news (we recommend that administrators subscribe to it).
All IP-addresses of our servers are listed in the file:
https://www.sip.tg/fw.txt
Sometimes the Worker-server network is updated, we inform about it in the news channel @siptg_news (we recommend that administrators subscribe to it).
About the infrastructure of Worker Servers
The infrastructure of SIP.TG Worker-servers is secure, the servers can be scaled quickly if necessary, and are located in different geographic areas.
If necessary, a specific Worker-server can be specified for all linked SIP-accounts, including those located on your own servers.
To use your own Worker-server (or several), install and configure the appropriate module, then specify it in the connection settings (on free plans this option is NOTavailable
IP blocking PBX for wrong passwords
Specify your connection details to the SIP.TG servers carefully. We have password protection activated, so the IP address PBX can be blocked for an arbitrary period of time if it connects to the SIP.TG servers without the registration option enabled, with the wrong username or password, from an untrusted IP, and so on.
Step 2: Setting up call routing
Incoming and outgoing calls from Telegram users are the same between the Gateway and PBX , regardless of how the Gateway connects to PBX.
For incoming calls from a Telegram user to the Gateway account at PBX the number and name of the caller is transmitted, while for outgoing calls just specify the user number in one of the allowed formats (userid, username, phone).
For incoming calls from a Telegram user to the Gateway account at PBX the number and name of the caller is transmitted, while for outgoing calls just specify the user number in one of the allowed formats (userid, username, phone).
Incoming calls to PBX from Telegram
After connecting a SIP trunk for calls, don't forget to specify which of PBX users (employees) will receive incoming calls from it.
After configuring the recipient of incoming calls you can make a test call to the connected to the Gateway Telegram account to make sure that incoming calls go through.
Important! The test call is better to make from the device where the Gateway account is not connected. The call will come both to PBX and to all devices with connected Telegram-gateway account.
If there is a delay on getting off the phone at PBX , you can receive a call from the Telegram application, but then through PBX such call will not come.
To make calls only to PBX disable reception of calls on other devices with connected gateway account. This is done in settings of Telegram for the Gateway account(☰ → Settings → Notification and Sounds → Calls → Accept calls on this Device).
Any available functions PBX for voice calls are applicable to calls through the Gateway: call recording, call transfer and call hold, voice menu, call to the group, soufling and etc.
Pay attention to what Caller-ID the incoming call will come with, it corresponds to the settings set on the side of @siptg_bot (user-id, username or account phone number + used prefix or suffix).
The Caller-Name field, which can contain one or more available values about the calling telegram user (name, username, Phone), is also transmitted to PBX from the Gateway.
More about configuring the values of transmitted Caller-ID and Caller-Name (step 5)
After connecting a SIP trunk for calls, don't forget to specify which of PBX users (employees) will receive incoming calls from it.
After configuring the recipient of incoming calls you can make a test call to the connected to the Gateway Telegram account to make sure that incoming calls go through.
Important! The test call is better to make from the device where the Gateway account is not connected. The call will come both to PBX and to all devices with connected Telegram-gateway account.
If there is a delay on getting off the phone at PBX , you can receive a call from the Telegram application, but then through PBX such call will not come.
To make calls only to PBX disable reception of calls on other devices with connected gateway account. This is done in settings of Telegram for the Gateway account(☰ → Settings → Notification and Sounds → Calls → Accept calls on this Device).
Any available functions PBX for voice calls are applicable to calls through the Gateway: call recording, call transfer and call hold, voice menu, call to the group, soufling and etc.
Pay attention to what Caller-ID the incoming call will come with, it corresponds to the settings set on the side of @siptg_bot (user-id, username or account phone number + used prefix or suffix).
The Caller-Name field, which can contain one or more available values about the calling telegram user (name, username, Phone), is also transmitted to PBX from the Gateway.
More about configuring the values of transmitted Caller-ID and Caller-Name (step 5)
Outgoing calls from PBX to Telegram
To make outgoing calls through the connected line Gateway (trunk to telegram) in the settings PBX usually need to explicitly specify which of the users PBX (employees) has the appropriate right.
Depending on the system used, PBX users may be able to explicitly select the outgoing line for the call in their softphones (work terminals), or the line selection can only take place automatically based on the prefix or suffix for the number of the called user.
One of three values can be used as the user number to call them on Telegram:
To make outgoing calls through the connected line Gateway (trunk to telegram) in the settings PBX usually need to explicitly specify which of the users PBX (employees) has the appropriate right.
Depending on the system used, PBX users may be able to explicitly select the outgoing line for the call in their softphones (work terminals), or the line selection can only take place automatically based on the prefix or suffix for the number of the called user.
One of three values can be used as the user number to call them on Telegram:
- internal user-id of the user (usually used with a prefix of * or 0, or other attribute, has an arbitrary length, from 5 to 20 digits, has all users)
- user's phone number linked to the Telegram account (10 digits, can be hidden by privacy settings)
- username in Telegram (no @ symbol at the beginning, only Latin letters and numbers, may not be set, supported by some PBX)
We recommend using user-id as the Caller-ID and number of the called party with a prefix of 0 or *, it is the most universal way. But remember that the user-id cannot be used to call the user first, if there has not yet been a mutual correspondence with him. If you still need to call a user outside your contact list, then use his phone number (if it's not hidden) or username (if your PBX allows it).
Pro prefix before Caller-ID (user-id or phone number) . To distinguish between telegram users numbers (user-id or account phone number) from regular phone numbers in logs PBX and/or CRM systems, it is convenient to set them a prefix on the side of @siptg_bot when configuring communication with PBX (we recommend using the symbol * or 0). If you set a prefix for Caller-ID, it is important to save it in the number of the called user when making an outgoing call to Telegram through the connected Gateway line.
The easiest way to test outgoing calls to Telegram is to make an answer call to an incoming call (it is important that the prefix before the number matches, if it was set).
Be especially careful when calling strangers. Any user can complain about spam if your call is unexpected. If a significant number of complaints are received, the Gateway account may be temporarily restricted or blocked by Telegram algorithms.
Pro prefix before Caller-ID (user-id or phone number) . To distinguish between telegram users numbers (user-id or account phone number) from regular phone numbers in logs PBX and/or CRM systems, it is convenient to set them a prefix on the side of @siptg_bot when configuring communication with PBX (we recommend using the symbol * or 0). If you set a prefix for Caller-ID, it is important to save it in the number of the called user when making an outgoing call to Telegram through the connected Gateway line.
The easiest way to test outgoing calls to Telegram is to make an answer call to an incoming call (it is important that the prefix before the number matches, if it was set).
Be especially careful when calling strangers. Any user can complain about spam if your call is unexpected. If a significant number of complaints are received, the Gateway account may be temporarily restricted or blocked by Telegram algorithms.
Telegram restrictions on outgoing calls
If there has not been any correspondence with the user yet, you can call him first only by his username (may not be set for the account), or by the account phone number (may be hidden by privacy settings).
The number of calls per day to users who were not yet in your contact list is very limited (several dozen calls per day).
If the intensity of calls is too high, you can get a temporary ban on calls from Telegram (lasting about 24 hours).
You can call a user-id only if there was already some prior mutual correspondence with him, or the user was the first to make a call to the Gateway account.
Telegram users can prohibit in their settings incoming voice calls from accounts that are not on their contact list (or any calls at all).
The number of calls per day to users who were not yet in your contact list is very limited (several dozen calls per day).
If the intensity of calls is too high, you can get a temporary ban on calls from Telegram (lasting about 24 hours).
You can call a user-id only if there was already some prior mutual correspondence with him, or the user was the first to make a call to the Gateway account.
Telegram users can prohibit in their settings incoming voice calls from accounts that are not on their contact list (or any calls at all).
Delayed calls on Telegram
You may experience delays when calling an offline user. This is due to a feature of Telegram described below.
Cellular operators have no trouble determining whether the user is online or not. Telegram works harder. The user gets the status "Online" if three conditions are met: the application is running, is active, and the phone itself is unlocked. Otherwise, the user is considered offline.
Push technology helps force the user to come online. He receives a notification of an incoming Telegram call and at that moment gets online status, even if he's not logged into the app. This approach helps the app save battery power significantly.
The time between a call and receiving a Push notification is not regulated. If the phone is not online, the user may not receive a notification at all. Therefore, the timeout definition depends on the gateway usage tasks and has to be configured on the side of your virtual PBX.
The current timeout value is 15 seconds.
Cellular operators have no trouble determining whether the user is online or not. Telegram works harder. The user gets the status "Online" if three conditions are met: the application is running, is active, and the phone itself is unlocked. Otherwise, the user is considered offline.
Push technology helps force the user to come online. He receives a notification of an incoming Telegram call and at that moment gets online status, even if he's not logged into the app. This approach helps the app save battery power significantly.
The time between a call and receiving a Push notification is not regulated. If the phone is not online, the user may not receive a notification at all. Therefore, the timeout definition depends on the gateway usage tasks and has to be configured on the side of your virtual PBX.
The current timeout value is 15 seconds.
About protecting Telegram from flood calls
When there is a heavy load on Telegram servers, flood protection may trigger. For this purpose, an artificial restriction on the use of all or some Telegram API calls is introduced.
If the delay is limited to 5 seconds, this request to the API is repeated automatically. Otherwise the request ends with an error, which is transmitted to SIP as code 503 Service Unavailable.
According to RFC 3261 the Retry-After header will also be transmitted, containing the value in seconds after which the request can be sent again.
If the delay is limited to 5 seconds, this request to the API is repeated automatically. Otherwise the request ends with an error, which is transmitted to SIP as code 503 Service Unavailable.
According to RFC 3261 the Retry-After header will also be transmitted, containing the value in seconds after which the request can be sent again.
If incoming calls to the Gateway account are immediately dropped
Most often this happens because the test call is made from the same device where the gateway account is connected. The call can not be received, as the call is already outgoing from the same device, and therefore the call is dropped.
To avoid this happening, you can prohibit receiving calls in the settings of the Gateway account on the device from which the test calls are made.
This setting is done in the settings of the Telegram application here:
☰ → Settings → Notification and Sounds → Calls → Accept calls on this Device
To avoid this happening, you can prohibit receiving calls in the settings of the Gateway account on the device from which the test calls are made.
This setting is done in the settings of the Telegram application here:
☰ → Settings → Notification and Sounds → Calls → Accept calls on this Device
See also
How to set up Gateway mode to receive and make calls through the company's single Telegram account
What users see when calling a single Telegram account via SIP.TG, the set of functions available to them (DTMF, Autoanswer, Line selection, Call back button, specifying the internal number and calling via Callback)
Limitations and specifics of making voice calls in Telegram via the SIP.TG Gateway
Features of SIP.TG Gateway integration for Telegram-calls with CRM systems, receiving incoming and making outgoing calls to Telegram users via PBX
Payment options for the SIP.TG gateway for transferring calls between Telegram and SIP telephony
Purpose, benefits, installation and configuration of own Worker servers for SIP.TG
Purpose, benefits, installation and configuration of your own Telegram Session Store for SIP.TG
The crux of the problem with the tg2sip library (libtgvoip) with Telegram clients on Android and the proposed solution from SIP.TG
We use cookies to ensure the best user experience.
Okay, I don't mind.
We're on Telegram
Support
users
users
Public
group
group
News
and updates
and updates
Account
for calls
for calls
Bot
to set up
to set up
