Interaction with PBX
Integration with PBX systems occurs through SIP connections, which are jointly configured both on the PBX side and on the SIP.TG side.
To create a SIP connection on the SIP.TG side:
Below are specific settings for each type of SIP connection.
The table shows that each identifier has serious limitations that prevent it from being used in all scenarios. SIP.TG supports all types of identifiers and their combinations, and also allows you to set the priority of their use according to your needs.
Such a Caller ID in different situations can take all three types of identifiers, depending on which ones the user has:
In addition to Caller ID, the From field can also contain the caller’s name (Caller Name), the formation of which can also be controlled using similar rules, but in addition to the parameters listed above, there are two more:
Depending on whether the user has a Phone number and Username, one of the following will be used:
Most often, the interaction is arranged as follows:
- Launch the @siptg_bot and go to the
/gatewaysection. - Select the Telegram session you want to connect to the PBX, or create a new one using the “Connect” button (for more details, see Step-by-step session connection).
- Click one of the buttons to create a new SIP connection, corresponding to the connection type: ”🆕 PBX→SIP․TG”, ”🆕 SIP․TG→PBX” or ”🆕 IP⇿IP”.
Configuring SIP Connection to PBX
Most settings are displayed directly on the buttons as current values. To change these settings, simply click the corresponding button and enter a new value when prompted by the bot. However, some buttons work differently:- Worker: when clicked, a list of available Worker servers appears. Select the desired server from the list to see its detailed description and assign it.
- Checkmark buttons, such as “DTMF in”, “DTMF out”, “Redial”, “Lines”, “Message processing”, “Callback” and “Share subscription”, work as toggles. One click activates or deactivates the option.
- Connection protocol (UDP/TCP/TLS): each click switches to the next available protocol.
- Show account and Reset password: display connection parameters to SIP.TG that need to be specified on the PBX side.
Worker server
Worker server
Allows you to select the server that will connect to the PBX or telephony provider.There are 3 types of servers:
On a free subscription, only some of the public SIP.TG servers are available.
| Server type | Description | Symbol |
|---|---|---|
| Public SIP.TG servers | Main servers supported by SIP.TG | ✅ |
| Public servers of other users | Publicly available servers hosted by other users | 🌐 |
| Private servers | Your own servers, available only for your SIP accounts | 🔑 |
Audio codecs
Audio codecs
The choice of codecs affects the quality and compatibility of voice communication. Opus, alaw, mulaw, GSM and other codecs are supported.
DTMF transmission methods
DTMF transmission methods
DTMF is necessary for interacting with voice menus. Available methods are RFC2833 (recommended), INFO, and inband.
Number transformation rules
Number transformation rules
Allow you to set the number dialing format for compatibility with the PBX. More details in the Number transformation rules section.
Priority
Priority
Priority allows you to set the order of calling SIP accounts when making a Telegram → SIP call.The following rules apply:
- Accounts with the same priority are called simultaneously.
- The lower the priority, the earlier SIP accounts are called.
- Transition to the next priority occurs after unsuccessful dialing to all SIP accounts of the previous priority.
Caller ID and Caller Name
Caller ID and Caller Name
Rules for forming the caller ID and displayed caller name when making a call, which applies to both directions.For more details, see Types of caller identifiers.
PBX → SIP.TG
In this mode, your PBX registers on SIP.TG as a SIP client. You receive a SIP login and password from the bot and specify them in your PBX.This is the simplest connection method and is suitable for most systems (Asterisk, 3CX, FreePBX, etc.).
Screenshot with PBX→SIP.TG connection settings
Show account and Reset password
Show account and Reset password
Show the login, password, and connection address of the current SIP line, which needs to be registered on your PBX side.“Reset password” generates a new SIP password for this line in advance. After resetting, it will need to be updated on the PBX side.
Trusted IPs
Trusted IPs
A list of IP addresses and subnets from which connection to this account is allowed.
SIP.TG → PBX
Here, the SIP.TG Worker server registers on your PBX. In the bot, you set the parameters of your PBX: login, password, and address.Don’t forget to add SIP.TG IP addresses to the whitelist on your PBX. Current list: files.sip.tg/fw.txt.
Screenshot with SIP.TG→PBX connection settings
Login, Password, Domain and Proxy
Login, Password, Domain and Proxy
Basic connection parameters that need to be filled in to make connection to your PBX possible.“Proxy” should only be filled in if it differs from the “Domain”.
Number on the PBX
Number on the PBX
When a user clicks the call button 📞 in the Telegram app without sending any messages — this number will be used as the default number that will be sent to the PBX.
IP ⇿ IP
Both sides know each other’s IP address. Used in cases where registration is impossible or unnecessary (for example, static routing).Suitable for advanced users. Requires route configuration on the PBX side.
Screenshot with IP⇿IP connection settings
Address:port
Address:port
IP address and port of the opposite side (your PBX).For the connection to be established, on the PBX side, you also need to create a connection with a specific IP address of the SIP.TG server. For this, the IP address of the Worker server assigned to the SIP connection is used.The current IP address of the Worker server being used will be displayed in the message when you request a change to the current parameter.
Field:Value
Field:Value
If you want to use multiple SIP connections between the same IP addresses, this field allows you to set an additional SIP header for correct connection identification.The parameter is set as a pair
{SIP field name}:{SIP field value}, separated by a colon :.Number on the PBX
Number on the PBX
When a user clicks the call button 📞 in the Telegram app without sending any messages — this number will be used as the default number that will be sent to the PBX.
Types of caller identifiers
Each Telegram user can have up to three types of identifiers:- Phone number, on which the account is registered. It is always present, but by default is hidden by privacy settings for other users. With significant limitations, it’s possible to establish contact with a user by phone number.
- Username — this is a unique alphabetic username. By default, it doesn’t exist, many users set it up, but strictly speaking, it may be absent. Conversely, a user may have several collectible Usernames. You can establish contact with a user by Username, and the restrictions are much milder than for Phone number, but cloud PBXs often do not provide for the use of non-numeric caller identifiers.
- User ID — internal numeric identifier. Always present, never changes, but it’s impossible to establish contact with a user only by User ID — it can be used only after contact has been established by one of the other methods.
| Identifier type | Format | Contact possibility | Mandatory | Changeable | PBX support |
|---|---|---|---|---|---|
| Phone number | numeric | limited | yes | yes | yes |
| Username | alphabetic | yes | no | yes | limited |
| User ID | numeric | no | yes | no | yes |
Telegram → PBX
For each SIP connection, you can set rules for forming the Caller ID, which will be transmitted in theFrom field in the INVITE message for Telegram → PBX calls.
Caller ID formation rules consist of several lines, with one rule per line. Each rule is a template string, in which {phone}, {username}, and {userid} are allowed as template parameters. When forming the final Caller ID, the first rule is used, all template parameters of which contain values about the calling Telegram user.
Examples of Caller ID formation
Examples of Caller ID formation
- If the Phone number is not hidden — it will be used.
- Otherwise, if Username is set — the system will choose it.
- And only in the most exceptional case will User ID with prefix
0be used — this tag allows resolving ambiguity in the interpretation of the identifier type.
{name}— display name in UTF-8 (may cause problems on the PBX side due to emojis);{name_ascii}— display name converted to ASCII (safe option).
Example of Caller Name formation
Example of Caller Name formation
- either the Phone number with prefix
+, followed by the display name written in parentheses, - or the Username with prefix
@, followed by the display name written in parentheses, - or in the most extreme case — just the display name without extraneous characters.
PBX → Telegram
When receiving anINVITE request from the PBX side, the called identifier will be interpreted in full accordance with the same Caller ID parameter described above. However, the algorithm for determining the identifier type and cutting off prefixes and extraneous characters in it does not look so obvious.
Detailed rule processing algorithm
Detailed rule processing algorithm
As in the case of Telegram → PBX calls, rules are checked sequentially and the selection stops at the first one that satisfies the given criteria after transformations:
- All template parameters in the rule are replaced with their corresponding regular expressions:
{phone}→+?[1-9]\d*: a number that cannot start with0and optionally can start with the+symbol;{username}→@?[a-zA-Z]\w*: an alphanumeric string that can only start with a letter and optionally with a prefix@;{userid}→[1-9]\d*: a number that cannot start with0and cannot have prefixes.
- As a result of item 1, a complex regular expression is obtained, against which the received identifier from the INVITE URI is checked.
- As a result of satisfying the regular expression, although this is only theoretical, several types of identifiers may be recognized in the identifier at once. In this case, the first value will be selected in the specified order:
{userid},{username},{phone}.
CRM Integration
CRM integration is usually implemented not directly with SIP.TG, but through a PBX to which SIP.TG connects as a standard SIP trunk. The CRM itself “sees” calls and contacts thanks to the capabilities of the PBX. Separate modules or plugins specifically for SIP.TG in CRM, as a rule, do not need to be installed.
- A Telegram call comes to the SIP.TG Gateway (Telegram account).
- The SIP.TG Gateway converts the call to SIP and passes it to the PBX (via SIP trunk).
- The PBX, having the necessary module or plugin for CRM integration, recognizes the incoming call, displays the client card, logs the call, or performs other actions.
- At the end of the conversation, data about the call (for example, duration, result) is also saved in the CRM.
How does the PBX learn about the client's number?
How does the PBX learn about the client's number?
Almost any modern PBX can use SIP headers (CallerID, From, etc.) during an incoming or outgoing call to “pass through” data to the CRM module. When calling from Telegram through the SIP.TG Gateway to a SIP trunk, the caller’s identifier is transmitted (most often displayed as Telegram ID or username), and the logic in the PBX maps this identifier to CRM records.If your PBX can manage CallerID for outgoing calls (for example, “substitutes” the desired number), then the CRM can automatically record both the real phone number and Telegram contacts in the card. But there are many details for each CRM and PBX; in general, this is not directly regulated by SIP.TG.
How to initiate a call from CRM?
How to initiate a call from CRM?
If a CRM “knows how” to initiate a call (for example, to click on a number and call), it usually does this through the PBX, sends a Call API or AMI command there (Asterisk, 3CX, etc.). Then the PBX translates the request to the SIP.TG SIP trunk, and the Gateway calls Telegram. All this is again standard interaction “CRM → PBX → SIP trunk”, where SIP.TG simply performs the role of a telecom operator for Telegram.
Setup example
Setup example
- In the PBX, create an account (SIP trunk) with the credentials provided when setting up
/gatewayin @siptg_bot. - In the CRM, activate a ready-made plugin or module (for Asterisk, 3CX, FreePBX, Yate, etc.) or configure external requests to the PBX through its API.
- Check that the CRM receives events about calls (card pops up, logs are written) and, if necessary, connect deeper logic (call distribution, linking conversation recordings, automation).
- For outgoing calls from CRM — check that the PBX can form a call via the “SIP.TG” SIP trunk (usually a route or dialing rule for such a line is selected).
When additional configuration is needed
1
Extended SIP header fields
If your CRM forms or expects some specific headers (for example, X-CRM-ID), such situations are resolved by means of your PBX (AGI scripts in Asterisk, custom settings in 3CX, etc.). On the SIP.TG side, there is no way to directly influence arbitrary SIP headers.
2
Need a forwarded CallerID
In some cases, the CRM needs to see the original caller number in full (for example, to “link” to a specific client). If the call is from Telegram, then the number can be anything (or absent altogether), and here it depends on the logic of your PBX how to substitute CallerID. Sometimes an additional database of correspondence “Telegram ID → client phone” is added.
3
Enabling call recording in CRM
Call recording can be enabled both in the PBX itself and in the “Call recording” mode on the SIP.TG side (in the Softphone). If you want to store recordings specifically in the CRM, check if your PBX can transfer recording files there. From the point of view of SIP.TG, this is a “transparent” transmission of sound via SIP, and there are no additional settings for recording.
Additional tips
- Unified approach: all settings related to CRM are usually performed in your PBX interface. You perceive SIP.TG as a regular telecom operator (SIP trunk).
- Typical PBXs (Asterisk, 3CX, FreeSWITCH, Yate, Oktell, Panasonic, etc.) have plugins or REST interfaces for CRM integration. Study the PBX documentation: most likely, there is a ready-made example.
- Call reception and routing scenarios (IVR, operator queue, automatic forwarding) — all these are common PBX functions. The SIP.TG Gateway does not limit or complicate such scenarios: they work the same way as with other SIP trunks.
Don’t overcomplicate. To “befriend” CRM with Telegram calls, it’s enough to connect the SIP.TG Gateway to your PBX and use the standard CRM integration tools that are available in the PBX.If you encounter problems or errors, use the Troubleshooting section.