# API Documentation Source: https://www.sip.tg/api-external # Catalog of Service Providers and Integrators Source: https://www.sip.tg/en/catalog SIP.TG services are not standalone — they require interaction with external service providers, and setup can be complex and have specifics. Here you can select service providers for your needs and find a specialist who will help implement them. For convenience, you can choose a country and filter offers by tags. | Tag | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------- | | Partner | Provides SIP.TG services under their own brand | | Integrator | Implements SIP.TG solutions turnkey, integrating them with existing telephony and CRM systems | | Payments | Helps pay for SIP.TG services and prepare financial documents | | Individuals | Works with end consumers (individuals) | | PBX | Developer of PBX solutions compatible with SIP.TG | | Telecom | Provider of IP telephony services where you can buy a virtual number and order international calling services | | Bitrix24
amoCRM | Specializes in integration with the specified CRM systems |
Tags:
Country:
If your services are compatible with SIP.TG, you work on telephony service implementations, are interested in partnership, and want to be listed in the catalog, contact us on Telegram: [@siptg\_support](https://t.me/siptg_support). # SIP.TG Documentation Source: https://www.sip.tg/en/docs Welcome to the updated documentation for the **SIP.TG** service. Here you will find the most up-to-date information on how to connect and use the capabilities of SIP.TG: from basic operations with the **Gateway** and **Softphone** to deploying your own **Worker** modules and **Telegram Session Storage**. ## Main Sections Use Telegram as a full-featured SIP client. Supports call recording, codec configuration. Receive and make calls from Telegram via SIP PBX. Multi-line support and flexible Caller ID settings. Subscriptions, limit changes, auto-renewal, various payment methods. Worker module, Session Storage, managing third-party accounts. ## How to Get Help 1. We have a public group [@siptg\_public](https://t.me/siptg_public) where users help each other. 2. If you need a turn-key implementation or special conditions — contact service providers from our [catalog](/en/catalog) for assistance. 3. Support via [@siptg\_support](https://t.me/siptg_support) depends on your monthly SIP.TG service spend: * AI-powered support — for monthly spend under **150 EUR**; * Support by SIP.TG specialists — for monthly spend starting from **150 EUR**. We usually don't send news updates to our users. Subscribe to our channel [@siptg\_news\_en](https://t.me/siptg_news_en) to stay informed about news and announcements. Thank you for using SIP.TG! # Worker and Storage Modules Source: https://www.sip.tg/en/docs/additional/modules The SIP.TG platform provides the ability to run **your own** server modules: * **Worker** — responsible for processing/converting voice data (SIP ↔ Telegram). * **Session Storage** (Storage) — stores keys and access data for Telegram accounts. These modules can be hosted on your own server in a Docker container, with a dedicated IP address and guaranteed availability. Below is a description of how this works and what steps are needed for setup. ## Worker Servers Worker processes and converts audio streams from SIP to Telegram format and vice versa in real time. ### Why it is needed * **Performance guarantee**: you choose the equipment yourself, scale it to the needed load. * **Minimal delay**: you can place the Worker as close as possible to your PBX to reduce RTT. * **Confidentiality**: voice streams are not transmitted to SIP.TG public servers — you process audio data yourself. * **Access to private networks**: if desired, the Worker can operate in a local (restricted) network and receive SIP traffic directly from the PBX. ### System Requirements * **Docker CE** and **Docker Compose** on a Linux server (e.g., Ubuntu 22.04). * Dedicated IP address (or TCP port forwarding) for connection from SIP.TG. * Approximate performance: 1 call ≈ 2.5% CPU on one AMD Ryzen 5 1400 core, \~1 MB RAM when using G.711 (A-law). ### Setting Up Your Own Worker 1. In the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) bot, execute the `/workers` command and click . 2. You will be sent 2 files: a private key and a certificate for secure connection with the SIP.TG platform. 3. Save them and do not share with third parties. 1. Install OS updates (if necessary). 2. Install Docker and Docker Compose. 3. Clone or download the Worker configuration template (see [GitHub](https://github.com/siptg/worker)). 4. Copy the certificates obtained from the bot to the server and specify paths to them in Docker/Worker settings. 5. If necessary, edit parameters in `docker-compose.yml` or in the corresponding configurations (SIP port, RTP range, etc.). 1. Start the Docker service: ```bash theme={null} docker-compose up -d ``` 2. Make sure the Worker container has successfully started and is listening on the specified ports. 3. Check the container logs (command `docker-compose logs`) if errors occur. 1. In the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) bot, return to `/workers`, select the created Worker and click . 2. Enter the external address and port through which your server is accessible. 3. Click for SIP.TG to check the connection. If everything is normal, the Worker will switch to "Online" status. ### Public or Personal Mode After enabling the Worker, you can specify: * **Personal** (icon 🔑) — only the owner and administered Gateway sessions can use the Worker. * **Public** (icon 🌐) — the Worker will be available to all SIP.TG users. ### Limitations for User Workers * Connections of type **PBX→SIP.TG** on a user Worker are prohibited by default. * In case of failure/unavailability of the Worker for more than 30 minutes, the platform may disconnect the associated SIP accounts. ## Telegram Session Storage Storage — a server on which keys and login data for Telegram accounts are stored. Without it, Telegram sessions live in the SIP.TG "cloud", but if desired, you can store everything on your side. ### What Sessions Storage provides * **Full control**: confidentiality of access to Telegram accounts, all keys are stored on your server. * **Unlimited number of accounts** (subject to your subscription) in one storage. * **Flexible configuration**: restriction on commands and events. ### System Requirements * Docker CE / Docker Compose (Linux). * Dedicated IP address (or TCP port forwarding) for connection from SIP.TG. * The module uses the TDLib library, so 1-2 GB of RAM is sufficient (but depends on the number of Telegram accounts). ### Setting Up Your Own Storage 1. In the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) bot, execute the `/storage` command and click . 2. The bot will send a private key and certificate. Save them to your server. 1. Install and configure Docker / Docker Compose. 2. Clone the storage configuration template (see [GitHub](https://github.com/siptg/storage)). 3. Place the certificates in the appropriate directories (as specified in `docker-compose.yml`). 4. If necessary, edit the configuration files (TCP port, database, etc.). 1. Execute in the folder with the configuration: ```bash theme={null} docker-compose up -d ``` 2. Check the container logs (`docker-compose logs`) for errors. 3. Make sure the specified TCP port is accessible externally. 1. Return to `/storage` in the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) bot, select your storage and click . 2. Specify the external address and port through which the SIP.TG platform can connect. 3. Click to check availability. If everything is OK, the storage will be Online. ### Using the Storage * When creating a new Telegram session (in the bot section `/gateway`), choose **your** Storage. * It is **impossible** to transfer an already created session to another storage, however, you can recreate the session without deleting SIP connections. ## Frequently Asked Questions The SIP.TG platform periodically checks the connection. If the server doesn't respond for more than 30 minutes, the Worker/Storage will switch to "Disabled" status. All SIP accounts working through this Worker will become inactive. The storage will stop servicing requests. You can resume operation by restoring server availability and re-enabling the module in the bot. Yes. These modules are independent. You can store Telegram sessions in the SIP.TG cloud but process SIP streams on your Worker. Or vice versa: use public Worker servers but store sessions on your side. The main task is to keep Docker containers operational, update software (Worker/Storage image) as new versions are released, and monitor network availability. If you don't have your own DevOps specialist, it's easier to use SIP.TG public resources. * All connections between the SIP.TG platform and your modules are encrypted using certificates. * By default, Docker images based on Ubuntu are used. All additional dependencies are pre-installed. * See license and terms of use in GitHub repositories. Change the Worker mode to "Public". Then any SIP.TG user can assign your Worker to themselves. You can also keep the Worker "Personal", but use it only with some of your SIP accounts in the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs). For full operation of Worker and Storage, a stable connection with the SIP.TG platform (Manager) is required. Make sure your server can access the internet without blockages and that ports are not filtered by the firewall. # Gateway features overview Source: https://www.sip.tg/en/docs/gateway To use the Gateway, you must have your own Telegram account for this purpose. SIP.TG does not register Telegram accounts for its users. **Gateway** is a mode that allows you to connect your Telegram account to a phone PBX (office or cloud-based) to forward voice calls **to** and **from** Telegram. This means any call to your Telegram account is handled by the PBX, and for outbound calls from the PBX, the same Telegram account can be used as the “caller number”. **When it's useful**: if you have a sales or support team working via PBX and want to make and receive calls through a Telegram account (not a bot) — to stay closer to your audience in the messenger. ### Key Use Cases * **Business Telegram account** — use a single company Telegram account that can receive many simultaneous calls via PBX. * **Support and sales** — route Telegram calls through your PBX to a call center, specific employee, or team. * **Outbound calling** — agents make calls from the company’s “Telegram number” instead of their personal ones. * **Any CRM integration** — if it works with your PBX, it works with your CRM module, auto-dialer, or analytics. ## How It Works 1. Connect your Telegram account in the `/gateway` section of the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) (this creates a virtual “SIP.TG → Telegram” device). 2. Configure the connection method with your PBX (PBX→SIP.TG, SIP.TG→PBX, or IP⇿IP). 3. For incoming calls, a user "rings" your Telegram account — but the call is routed to your PBX. 4. For outgoing calls, your PBX connects to the Telegram account, which then initiates a call to the target Telegram user. See [PBX SIP connection setup](/en/docs/gateway/pbx#general) for more on the three connection methods. ## General Setup Flow * Choose a Telegram account that will be used to receive and make calls. You can either create a new account for the Gateway or use an existing one. * Make sure in Telegram privacy settings that calls are allowed from everyone (or at least from the users you need). * Go to [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) and run the `/gateway` command. * Click and select the session storage where the access key for the Telegram account will be saved. * Enter the phone number of the Telegram account and wait for the verification code from Telegram’s official service. * Once authorized, a virtual "gateway session" will be created. * Choose your connection method: PBX→SIP.TG, SIP.TG→PBX, or IP⇿IP. * For PBX→SIP.TG: get the SIP login and password from the bot and enter them in your PBX settings as an external SIP trunk. * For SIP.TG→PBX: enter your PBX SIP account credentials (login, password, server address) in the bot. * For IP⇿IP: provide your PBX IP address and confirm with a test call if needed. * Check that the trunk is registered in your PBX (or that the IP-to-IP connection is active). * Make a test incoming call to the Telegram account and ensure it reaches the PBX. * Try making an outbound call from the PBX to Telegram. * Set up routing rules (IVR, voice menu) inside the PBX as needed. ## Next Steps * [Telegram Integration](/en/docs/gateway/telegram) — defining roles, linking SIP.TG with your Telegram account, privacy, P2P, blocking other devices, message handling. * [PBX Integration](/en/docs/gateway/pbx) — choosing and configuring the connection method (PBX→SIP.TG, SIP.TG→PBX, IP⇿IP); subscriber ID types and dialing behavior. * [Troubleshooting](/en/docs/gateway/problems) — if something goes wrong. The Gateway is a powerful tool for integrating Telegram with traditional telephony. For help, see [How to Get Help](/en/docs#help). # Interaction with PBX Source: https://www.sip.tg/en/docs/gateway/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: 1. Launch the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) and go to the `/gateway` section. 2. Select the Telegram session you want to connect to the PBX, or create a new one using the button (for more details, see [Step-by-step session connection](/en/docs/gateway/telegram#steps)). 3. Click one of the buttons to create a new SIP connection, corresponding to the connection type: , or . ## 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 "", "", "", "", "", "" and "", work as toggles. One click activates or deactivates the option. * **Connection protocol (UDP/TCP/TLS)**: each click switches to the next available protocol. * and : display connection parameters to SIP.TG that need to be specified on the PBX side. Allows you to select the server that will connect to the PBX or telephony provider. There are 3 types of servers: | 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 | 🔑 | On a free subscription, only some of the public SIP.TG servers are available. The choice of codecs affects the quality and compatibility of voice communication. Opus, alaw, mulaw, GSM and other codecs are supported. DTMF is necessary for interacting with voice menus. Available methods are RFC2833 (recommended), INFO, and inband. Allow you to set the number dialing format for compatibility with the PBX. More details in the [Outgoing dialing rules](/en/docs/softphone/settings#dialing-rules) section. Priority allows you to set the order of calling SIP accounts when making a Telegram → SIP call. The following rules apply: 1. Accounts with the same priority are called simultaneously. 2. The lower the priority, the earlier SIP accounts are called. 3. Transition to the next priority occurs after unsuccessful dialing to all SIP accounts of the previous priority. 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](#callerid). Below are specific settings for each type of SIP connection. ### 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.). Show the login, password, and connection address of the current SIP line, which needs to be registered on your PBX side. generates a new SIP password for this line in advance. After resetting, it will need to be updated on the PBX side. 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](https://files.sip.tg/fw.txt). Basic connection parameters that need to be filled in to make connection to your PBX possible. should only be filled in if it differs from . 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. 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. 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 `:`. 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 | 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. ### Telegram → PBX For each SIP connection, you can set rules for forming the Caller ID, which will be transmitted in the `From` 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. ``` {phone} {username} 0userid ``` Such a Caller ID in different situations can take all three types of identifiers, depending on which ones the user has: * 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 `0` be used — this tag allows resolving ambiguity in the interpretation of the identifier type. ``` {phone} {username} ``` Here, the behavior is similar to Example 1, with the only difference that if the user has neither a Phone number nor a Username, such a call will be prohibited and will not reach the PBX. ``` {phone} {username} anonymous ``` And this example differs from the first two in that if the user does not have a Phone number and Username, the call will still reach the PBX, but with the number `anonymous`. 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: * `{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). ``` +{phone} ({name_ascii}) @{username} ({name_ascii}) {name_ascii} ``` Depending on whether the user has a Phone number and Username, one of the following will be used: * 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 an `INVITE` 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. 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: 1. All template parameters in the rule are replaced with their corresponding regular expressions: * `{phone}` → `+?[1-9]\d*`: a number that cannot start with `0` and 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 with `0` and cannot have prefixes. 2. As a result of item 1, a complex regular expression is obtained, against which the received identifier from the INVITE URI is checked. 3. 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}`. This ensures bidirectionality of Caller ID formation rules and consistency of identifier formats for both call directions. ## 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. Most often, the interaction is arranged as follows: 1. A Telegram call comes to the SIP.TG Gateway (Telegram account). 2. The SIP.TG Gateway converts the call to SIP and passes it to the PBX (via SIP trunk). 3. 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. 4. At the end of the conversation, data about the call (for example, duration, result) is also saved in the CRM. 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. 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. 1. In the PBX, create an account (SIP trunk) with the credentials provided when setting up `/gateway` in [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs). 2. 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. 3. 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). 4. 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 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. 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. 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](/en/docs/gateway/problems) section. # Troubleshooting Source: https://www.sip.tg/en/docs/gateway/problems Below are possible errors that may occur when using the **Gateway** (PBX→Telegram mode) — both during registration (PBX→SIP.TG) and at the moment of call establishment (SIP→Telegram or Telegram→SIP). Some of them appear in PBX logs, some — as a displayed code when trying to call a Telegram account. Not all errors are frequently encountered in real operation, but it's useful to know about them for diagnostic purposes. For reference: * **Manager** — the controlling component of SIP.TG, responsible for connecting to Worker servers and Session Storages. * **Worker** — the working component that processes calls, RTP traffic, and performs SIP signaling. If you're just getting started with the Gateway, we also recommend checking out these articles: * [Interaction with Telegram](/en/docs/gateway/telegram) — how to authorize a Telegram account for calls. * [Interaction with PBX](/en/docs/gateway/pbx) — detailed description of SIP connection options. * [Subscriptions Overview](/en/docs/subscriptions/pricing) — to ensure your "Gateway" subscription covers the required number of lines. ## Frequently Asked Questions When setting up the Gateway, the Telegram account forwards incoming calls to the PBX.\ If a person is on the list of allowed callers, the call will be directed to the PBX, and on the device where this account is open, you can also manually answer the call.\ It's usually recommended to disable call reception on other devices so that everything goes through the PBX. Yes, in the "Gateway" subscription, you can pay for multiple Telegram accounts. The first account costs 15 EUR/month, each additional one costs 150 EUR/month. The Gateway can process incoming messages if you enable the option in the gateway settings. This enables auto-reply, Callback mode, and message processing by an external bot.\ For more details, see [SIP.TG Session Settings](/en/docs/gateway/telegram#session-settings). In your Telegram session settings, disable the following options: , , , and . For more details, see [SIP.TG Session Settings](/en/docs/gateway/telegram#session-settings). The entire SIP.TG infrastructure is distributed across multiple data centers. Nevertheless, for mission-critical systems, you might consider your own Worker servers. It's recommended to create a separate work account for the company — so that your personal Telegram doesn't mix with business calls. It's important that this account is always online (or store the session in the SIP.TG Cloud Storage). Telegram may limit or completely block your gateway Telegram account. We do not recommend this activity and we do not transfer a subscription to another Telegram account in case of blocking. However, if you want to preserve the subscription, we have a solution: 1. Activate the "Gateway" subscription for an Administrator (see [Roles of session and administrator accounts](/en/docs/gateway/telegram)) with the option ≥ 1. 2. From the administrator, create a new Telegram session linked to the account used for calls. 3. Enable the option for the created session. 4. If the calling Telegram account gets blocked, Disconnect the session via the session settings in the `/gateway` section **while keeping the current settings**, and Connect a new Telegram account there. Yes, but this means that everyone will be using the same Telegram account, and incoming calls will come to all devices simultaneously. As soon as one person answers, the call will be dropped for the others. This is normal Gateway behavior: the PBX sees that the call has already been accepted. A CANCEL is sent to other clients. If you want each employee to have their own Telegram account, use multiple gateway subscriptions. A Telegram account is created based on a phone number. Usually, you take any SIM card, register it with Telegram, and then the number may not be used for traditional operator voice calls. The main thing is not to lose access to this number for Telegram recovery. Our SIP stack is based on Yate, where the default UDP port range is 16384-32768. ## General Issues * Check that the Telegram account is active and not blocked by the messenger. * Make sure that in Telegram privacy settings, calls from everyone are allowed. As with the Softphone, this is most often a question of codecs or network restrictions. * Try specifying a specific codec (`alaw` or `mulaw`). * Make sure that UDP traffic is allowed. * Make sure that in the SIP account settings (Gateway), the method RFC2833 or INFO is selected, compatible with your PBX. * Try switching the codec, sometimes inband DTMF and high compression don't work well together. ## Common SIP Errors Such responses may appear both during calls and during simple SIP trunk registration. The code below is sent by the SIP.TG server to your PBX. **Essence:** Standard response when using SIP Digest Auth. The PBX sends an INVITE or REGISTER without a complete set of authorization data, and the SIP.TG server requests authorization.\ If error 401 appears repeatedly many times in a row, it means that either the password/login is incorrect, or Digest Auth support is disabled on the PBX side. **What to do:** * Make sure that the login/password from [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) (section `/gateway`) is correctly entered in your PBX settings. * Check that SIP authorization mode (Digest Auth) is enabled in the PBX itself. * If necessary, change the password in `/gateway` and enter it again. **Essence:** "Gateway" subscription limitation. This means that the Telegram account has no paid lines for Gateway mode, the subscription has expired, or the resource volume is exceeded. **What to do:** * In the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) with the command `/subscriptions`, check if the "Gateway" plan is active and if there are enough lines. * If the subscription period has expired or additional lines are needed, arrange for renewal / extension of the subscription (see [Subscription Overview](/en/docs/subscriptions/pricing)). * Make sure that the specific Telegram account is actually linked to the right subscription (when paying for multiple accounts). **Essence:** Internal error on the SIP.TG side related to the database. Such cases are extremely rare. **What to do:** * Usually temporary in nature and is automatically resolved. * Try again, if the error occurs regularly, seek help. For more details, see [How to Get Help](/en/docs#help). **Essence:** The Worker cannot connect to the SIP.TG Manager server due to an internal network problem. Your PBX will see this as a `503 No response from Manager` response. **What to do:** * As a rule, these are short-term failures. Try waiting 1-2 minutes and repeat the call. * If the problem persists, you can switch the SIP trunk to another Worker server (see [Interaction with PBX](/en/docs/gateway/pbx)). ## Errors during PBX → SIP.TG registration Here are responses that may come when your PBX tries to register with the SIP.TG Worker server (connection with the PBX→SIP.TG type). All errors listed below usually have code 403 or 404. **Essence:** The PBX correctly tries to authenticate, but the specified password does not match what SIP.TG expects. **What to do:** * Check the password in the `/gateway` section of [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) and compare with what is entered on the PBX. * If necessary, change the password in the bot (the "Change password" button) and enter the new one on the PBX side. * Make sure that the login (username) also does not contain typos. **Essence:** The password is correct, but your IP address is not in the list of allowed addresses for this SIP connection. **What to do:** * In [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs), section `/gateway`, open the settings of the corresponding SIP connection and: * Add your IP address to the trusted list. * Or clear the list to allow connections from any IP (but observe security measures). * If your external IP changes in your network, take this into account when configuring (perhaps it's worth completely disabling ACL). **Essence:** The Telegram account to which the binding is going is inactive (authorization has been lost). As a result, SIP.TG refuses to register the trunk, as there is no real Telegram connection. **What to do:** * In [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) in the `/gateway` section, reconnect the Telegram account (authorize the phone number). * If the Telegram account has been deleted, you will have to assign another phone number for the Gateway. * For more details, see [Interaction with Telegram](/en/docs/gateway/telegram). **Essence:** The storage where the Telegram session is saved (cloud or your own Sessions storage) is currently turned off or unavailable. Consequently, there is no possibility to work with the Telegram session. **What to do:** * If you use the SIP.TG cloud storage, check the status in `/gateway`. Usually such failures are short-lived. * If you have your own Session Storage, make sure it is running and available. If necessary, switch to the SIP.TG cloud. **Essence:** The selected Worker server is disabled on the SIP.TG side or is in the process of updating/restarting. The server cannot accept PBX→SIP.TG registration. **What to do:** * In the bot's `/gateway` section, check the Worker settings. If the server is disabled, select another one or wait until it becomes active again. * If this is your [own Worker](/en/docs/additional/modules#worker), start/restart it. **Essence:** The Worker server configuration does not provide for connections with the "PBX→SIP.TG" type. For example, the server is only configured for "SIP.TG→PBX" or "IP⇿IP". **What to do:** * In [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs), double-check the connection type (PBX→SIP.TG) and select an appropriate Worker. * Create another type of SIP connection ("SIP.TG→PBX" or "IP⇿IP"). **Essence:** Access to the used Telegram session has been revoked or no longer belongs to you. For example, the administrator who created the session has been deprived of rights, and you cannot use this session. **What to do:** * Create your own Gateway session. In the bot's `/gateway` section, connect the Telegram number that you control. * Make sure that the administrator who previously created the session did not take away your access. **Essence:** The login specified in the SIP request does not exist or has already been deleted. The SIP.TG server does not find such an "account". **What to do:** * Double-check the login/username that you received in the `/gateway` section. * If this record was previously deleted, create a new one. * Make sure that your PBX has exactly the login that was issued by the bot (without extra characters or spaces). ## Errors when calling SIP → Telegram These errors occur when your PBX is already registered (or IP-to-IP), and during an outgoing call to Telegram, the SIP.TG server returns a code if it cannot correctly call the Telegram account. **Essence:** The Telegram user has restricted the circle of people who can call them (e.g., only contacts or users with premium subscription), and your gateway account is not on this list. **What to do:** * Ask the called user to configure call permission: "Settings → Privacy → Voice Calls" → "All users" or add your gateway account to "Always allow". * Or use an account that is actually in the target user's contacts. **Essence:** SIP.TG could not find the Telegram account by the transmitted identifier (number, user\_id, username). Telegram may return such a response if: * The number is indeed not registered in Telegram. * The username does not exist or has been released. * The profile is unavailable due to restrictions. * Your gateway account searches for a phone number too frequently. **What to do:** * Make sure you are using the correct identifier (if using a phone — it should be a real Telegram number). * If it happens often, check if you made a mistake in the format. It might be better to use the internal user\_id. **Essence:** You are sending an INVITE without a prior PBX→SIP.TG registration, while the Worker requires a full REGISTER. **What to do:** * Enable "Registration" mode on your PBX side (register the PBX→SIP.TG trunk). For more details, see [Interaction with PBX](/en/docs/gateway/pbx). **Essence:** The Telegram server did not respond in time, or the SIP.TG request hung when accessing Telegram. This happens during overload or Telegram anti-spam filter, when there are many outgoing calls in a short time. **What to do:** * Reduce the intensity of outgoing calls. * Wait and try again if it was a temporary failure. **Essence:** SIP.TG is trying to call a user by their internal user\_id, with which there is no explicit confirmed contact. Telegram rejects such "anonymous" calls. **What to do:** * Usually you need to either call by a confirmed number or username, or have the user add you to contacts or write to you first. **Essence:** Any other internal error on the Telegram side. Sometimes this designates unexpected failures during audio channel processing, internal overload, etc. **What to do:** * Check the stability of the network, repeat the call. * If the error appears regularly on the same number, seek help. For more details, see [How to Get Help](/en/docs#help). **Essence:** The SIP.TG Worker server received an INVITE, but there is no active session for the needed account. That is, the PBX could have sent an INVITE without waiting for a response to REGISTER. **What to do:** * Make sure that the PBX→SIP.TG trunk is successfully registered and the Worker sees an active account. * Sometimes it helps to restart the trunk on the PBX. If necessary, see [Interaction with PBX](/en/docs/gateway/pbx). **Essence:** The Telegram session is actually disconnected. It's possible that in the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs), the session is displayed, but it's not actually authorized. **What to do:** * Double-check the session status in `/gateway`, if necessary, re-authorize the Telegram number. * If the error occurs frequently, try switching to another Worker or restarting the account. **Essence:** SIP.TG has lost connection with the Telegram session storage, so it cannot find out the current status or create a call. **What to do:** * If you use cloud storage, wait for recovery (usually a minute or two). * If your own Session Storage, check the logs and status of the module. **Essence:** This is Telegram's anti-spam protection, when too many outgoing calls occur in a short period, especially to unfamiliar numbers. **What to do:** * Reduce the dialing speed (on the PBX side or your script). * Use several different Telegram accounts to distribute the load. * Wait for the specified time "retry after N", then try again. **Essence:** The Worker was recently restarted or is being updated, and has not yet completed initialization. As a result, calls are rejected at the SIP level. **What to do:** * Wait 1-2 minutes and try the call again. * Or in [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs), select another Worker server for your connection. ## Errors when calling Telegram → SIP Here we consider situations when a real user tries to call the Gateway account from the Telegram application, and the Worker tries to transfer the call to your PBX. If the PBX returns an error, or if an error occurs on the SIP.TG side, the user may see an error in the chat with the Gateway account. In this section, we only list those errors that may occur on the SIP.TG side. **Essence:** The SIP.TG Gateway is also activated on the caller's account. The service blocks such an attempt (Telegram→SIP) to prevent looping or unforeseen call loops. **What to do:** * If you really need to receive calls from an account that is also a gateway, it's better to use a different mode for it (e.g., [Softphone](/en/docs/softphone)) or another Telegram account without Gateway. **Essence:** During an incoming call from Telegram, the Worker could not reach your PBX. This can happen if the PBX→SIP.TG trunk is down, or if you have IP-to-IP, but the required port is not responding. **What to do:** * Make sure that the PBX is registered (with PBX→SIP.TG) or that the IP-to-IP connection is active. * Check that SIP/UDP packets are not blocked in your firewall, and that you have opened RTP ports. * For more details, see [Interaction with PBX](/en/docs/gateway/pbx). **Essence:** The Worker server is currently unavailable for call transfer (network problems or restart), and the call is rejected with code 503. **What to do:** * Wait for some time or switch the Gateway account to another Worker (the bot's `/gateway` section). * If it's your own Worker server, check its logs and restart if necessary. If none of the listed solutions helps, seek assistance. For more details, see [How to Get Help](/en/docs#help). # Interaction with Telegram Source: https://www.sip.tg/en/docs/gateway/telegram For the **Gateway** mode to work, you need to connect a regular Telegram account through which calls will pass. **Two roles** are involved in this process: the session and the administrator. ## Session and Administrator Account Roles * **Session account** — a Telegram account that will be used as a source and receiver of calls. Connected as a **virtual device** to SIP.TG. * **Administrator account** — a Telegram account that interacts with [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) and manages the session: connects the session, can change settings, connect SIP-PBX, and receive error notifications. The same Telegram account can be used in both roles. However, in a corporate environment, it is recommended to separate them. ## Step-by-Step Session Connection Choose a Telegram account that will be used as a gateway. Make sure it is not used for personal calls or correspondence. Go to [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) and execute the `/gateway` command. Click the button. Specify where the session will be stored: * — simple, fast, and secure. * **Own storage** — for companies with increased privacy requirements. For more details, see [Telegram Session Storage](/en/docs/additional/modules#storage). Enter the phone number of the selected Telegram account. A code will be sent to it from the official Telegram account, which needs to be entered into the bot for authorization. If two-factor authentication (2FA) is enabled on the account, a secure recovery process will be initiated: Telegram will send an email to the linked email for password reset. This is done to avoid transmitting your password in plain text. ## Applying Telegram Settings to the Account Immediately after connecting the session, the bot will offer to apply recommended settings. They enhance the reliability and convenience of receiving calls: * — eliminates conflicts when a call arrives simultaneously in multiple places. Allows using the Telegram session as a channel only for calls, and other devices — for correspondence. * — important, as by default calls from unknown numbers are blocked by Telegram settings and will not reach the PBX. * — if supported, allows Telegram to transmit audio directly, without forwarding through servers, improving call quality and reducing delays. * — reduces the risk of receiving unnecessary notifications unrelated to call tasks. Some Telegram parameters can only be changed 24 hours after connecting the account. If you get an error — try again later. ## SIP.TG Session Settings These parameters enable or disable the use of the DTMF keypad in different call directions: * — used for incoming Telegram calls (Telegram → SIP direction); * — used for outgoing calls to Telegram from your PBX (SIP → Telegram direction). The DTMF keypad allows: * interacting with the PBX voice menu (IVR); * entering internal numbers; * displaying information about the calling employee when calling a Telegram user. The keypad is activated by swiping up during a conversation. Supported transmission modes (RFC2833, inband, SIP INFO) are changed in the SIP connection settings and should be coordinated with the PBX settings. Enables or disables the and buttons for Telegram users who interact with the gateway account. The buttons appear in the chat after the call ends. Clicking the button initiates a call to the internal number in the PBX that was used during the previous conversation, allowing to connect the user with a specific employee or department. The number is sent to the PBX without applying number transformation rules. The button works approximately the same with the only difference that before initiating the call, it displays the connected lines through which a call can be made. The number is sent to the PBX after applying the number transformation rules of the selected SIP account. Enables or disables the ability to react to text messages coming to the session's Telegram account. When enabled, additional functions open up: * — after sending any message to the chat, the user will receive an incoming call from the gateway with subsequent connection to the number sent in the message (or the default number; behavior is configured in the SIP line settings). * — if a suitable SIP account for calling is not found for the message, it can be processed through an external inline-bot. * — a predefined template is sent for each message, for example: > This account is for calls only. For correspondence, use @support\_bot. These functions can be enabled separately and the behavior can be configured depending on the situation. * / — allows removing administrator rights from the current account or assigning another Telegram user as administrator (see [Session and Administrator Account Roles](#roles)). * — extend the administrator's subscription to this session (see [Session and Administrator Account Roles](#roles) and [Additional sessions](/en/docs/subscriptions/pricing#gateway)). * — completely remove the virtual device, reset the session, and optionally clear SIP connection parameters. ### Inline-bot You can connect your own inline-bot that will be used to process incoming messages. This is especially useful in cases where the message cannot be matched with a phone number or a call is not required. The inline-bot can: * respond with a template; * collect requests; * integrate with external systems such as Helpdesk, CRM, etc. Additionally, you can set the format of the inline-request that will be passed to the bot. This allows structuring the user's request for more accurate processing. # Softphon features overview Source: https://www.sip.tg/en/docs/softphone To use the Softphone, you need a **SIP account** from a VoIP provider or PBX. SIP.TG is not a telecom operator, does not offer telephony services on its behalf, and does not register SIP accounts for users. **Softphone** allows you to use the Telegram app as a SIP client. You can connect to any VoIP provider or office PBX using SIP credentials. Incoming and outgoing calls go through Telegram — you receive them right inside your favorite messenger. **When it’s useful**: when you want to replace traditional softphones (Zoiper, MicroSIP, etc.) and manage all your voice communication within Telegram, without juggling multiple apps. ### Key Use Cases * **Personal use**: make and receive IP calls in Telegram even abroad (saving on roaming fees). * **Remote work**: call centers, support, and sales teams can connect corporate SIP numbers directly in Telegram. * **Unified workspace**: combine messaging and SIP telephony in a single app. ## How It Works 1. In the `/softphone` section of the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs), create a **SIP account** (enter login, password, and SIP server address). 2. SIP.TG registers on the SIP server using one of its Worker servers. 3. Incoming calls to the SIP account are forwarded to Telegram (a special account [@siptg](https://t.me/siptg) “calls” you in chat). 4. Outgoing calls are made by sending a phone number in chat with [@siptg](https://t.me/siptg) or by tapping the "Redial" button. Your Telegram account remains fully functional for regular calls and chats. The Softphone simply adds SIP call support. ## Next Steps * [Softphone Setup](/en/docs/softphone/settings) — how to configure a SIP account, enable call recording, and link an account to a specific user. * [How to Use](/en/docs/softphone/usage) — how to make and receive calls, use IVR menus, and control recording during a call. * [Troubleshooting](/en/docs/softphone/problems) — most common issues and how to resolve them. We hope the Softphone makes your voice communication more convenient. For help, see [How to Get Help](/en/docs#help). # Troubleshooting Source: https://www.sip.tg/en/docs/softphone/problems For the correct operation of the Softphone in Telegram, you need to: * Have an active **Softphone** subscription in the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs). * Make sure that in Telegram privacy settings, voice calls are allowed from "Everyone" or at least from **@siptg**. * Correctly specify the SIP server address (with the necessary port if it's non-standard), login, and password in the bot. * If necessary, configure audio codecs and "Dialing Rules" so that they meet the requirements of your PBX or SIP provider. ## Frequently Asked Questions **Softphone** — is when you use Telegram as a SIP client (linking to any SIP operator). **Gateway** — is when you connect a Telegram account to a PBX so that Telegram calls are processed by the PBX. Yes. Voice stream through Telegram is an internet channel, it doesn't interfere with your GSM calls. When creating an account, activate the checkbox. Available on a paid subscription (5 EUR/month per account). If necessary, you can select a separate channel/chat where audio files will be saved. Yes. In the `/softphone` section of the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) bot, open the SIP account and click . In the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) bot, open the settings of the desired account, click and select your colleague's Telegram profile. Now all incoming calls will go to them, and you will remain the Owner. Yes, if your "Softphone" subscription allows the required number of accounts. You can create several SIP accounts. For outgoing calls, a request to select an account will appear before each call. If you have a non-standard port on the operator or PBX side, specify it in the or field with a colon (for example: `sip.example.com:5062`). For the standard 5060, it's not necessary to specify. ## Problems and Debugging Below is an expanded list of problems that our users have encountered. **Symptoms** * No information about the incoming call appears in Telegram. **Possible causes** * Voice calls are prohibited at the level of your Telegram account. * The SIP account is being used in parallel on another device (in another Softphone, in a widget for calls through the browser, etc.). * The connection between your Telegram account and our **@siptg** was lost. **Solution** 1. Check the settings in Telegram: make sure that in the "Privacy and Security → "Voice Calls" section, the "Everyone" option is selected. 2. Update the SIP account password on the SIP provider or PBX side, and specify the new password for the account in the `/softphone` section of the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs). 3. Open the chat with [@siptg](https://t.me/siptg?text=👋) and send any message. **Symptoms** * When an incoming (or Callback) call arrives, the user doesn't have time to answer it, and in the **@siptg** chat it's shown with the status "Rejected call". * As a result, all incoming calls are automatically rejected on all devices linked to the Telegram account. * SIP log shows the error `486 User declined the call`. **Possible causes** * On one of the devices, the Telegram application is "stuck" in an active call state, although there are no signs of an active call. * During an incoming call, you're talking through another application or via mobile connection, and Telegram doesn't have access to the device's microphone. * You're trying to make a test call to yourself. For example, while making a call via mobile connection (thereby blocking the microphone), the call comes in through Telegram, and due to the other active call, the new Telegram call is rejected. **Solution** 1. Identify the problematic device: each of your devices must be disconnected from the internet in turn until the incoming calls stop dropping. After that, the problematic device needs to be restarted or the Telegram application should be completely unloaded from memory on it. 2. Make a test call involving two different devices, and ensure that your Telegram account is not used on the second device. 3. If the problem repeats, collect logs from the problematic device for further analysis and troubleshooting. See [Getting Log Files from Telegram](https://telegra.ph/Telegram-App-Logs-11-02) for details. When you send a number to the chat, the bot tries to call you back (callback). If you don't accept the incoming call in Telegram, the outgoing call won't happen. **What to do**: * Enable call notifications in Telegram. * Check that calls are allowed from **@siptg**. * Confirm the incoming call within 60 seconds. This is most often related to codec incompatibility or UDP traffic blocking. **Solution** 1. In the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) bot in the `/softphone` section, select the SIP account, click and set a short list, for example: `opus,alaw,mulaw`. If necessary, specify a specific audio codec (for example, only `alaw` or `mulaw`). 2. If the call is coming from abroad or through mobile internet, try another Worker server. This is due to the free subscription. To remove the restriction — activate the Softphone subscription. See more at [Subscriptions Overview](/en/docs/subscriptions/pricing). This is most often due to an unstable internet connection between the Telegram user and our server. **Solution** 1. Allow peer-to-peer calls in Telegram settings: ☰ → Settings → Privacy and Security → Calls → Peer-to-peer → Always Allow → Add Users → **@siptg** 2. Change the connection type and device; try calling from your computer via Wi-Fi. 3. In the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) bot in the `/softphone` section, select the SIP account, click **Worker** and choose another server that is closer in geographical location. **Symptoms** * During an outgoing or incoming call, the subscriber can't be heard, or the sound suddenly disappears. * The call drops within 5-10 seconds. **Possible causes** * Unsuitable or conflicting audio codec. * The provider or PBX doesn't accept the current set of codecs, or Telegram doesn't have time to negotiate the audio stream parameters. * Incorrect RTP settings or errors in voice packet transmission. **Solution** 1. In the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) bot in the `/softphone` section, select the SIP account, click and set a short list, for example: `opus,alaw,mulaw`. If necessary, specify a specific audio codec (for example, only `alaw` or `mulaw`). 2. Check the Worker server and firewall settings. **Symptoms** * When trying to make an outgoing call, the bot reports that there are no available lines. * Possibly, a code error appears in the logs indicating line unavailability. **Possible causes** * Incorrectly configured "Dialing Rules" that exclude correct numbers. * Exceeded the number of active SIP accounts allowed by the subscription. * Errors in SIP account parameters (incorrect login, server, or password). **Solution** 1. Check the current rules: in the `/softphone` section of the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) select the SIP account. To reset the dialing rules, click and enter the value `=`. 2. Make sure that the total number of SIP accounts corresponds to the paid subscription. 3. Try to restart the SIP account: in the `/softphone` section of the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) click and then . **Symptoms** * The bot reports that the limits of unsuccessful calls have been exceeded or that the current SIP account is not allowed by the tariff. * Calls don't go through due to exceeding established limits. **Possible causes** * The user has independently activated a SIP account without linking it to the administrated subscription. * Internal limitations of the tariff plan have been exceeded (for example, the number of unsuccessful attempts). * SIP accounts are incorrectly distributed or activated. **Solution** 1. Check that the SIP account is enabled and linked in the `/softphone` section of the bot. 2. Compare the number of active accounts with the data in the `/subscriptions` section. 3. If the account was activated independently, contact support to reconfigure it for administration. **Symptoms** * When I try to call, an error appears that the account is not started and the call does not start. * In the `/softphone` section, the account is marked with the ⚠️ icon, and in the settings, the Domain / Proxy / Template fields have such an icon. **Possible causes** * Temporary outage in the SIP.TG infrastructure: no communication between Manager and Worker servers. * Temporary outage on the side of the telephony provider or PBX: no communication between Worker and PBX/provider servers. **Solution** 1. Change the Worker server to a different one in the `/softphone` section of the bot. 2. Wait for the connection to be restored. Usually errors of this type are recovered automatically after a short time. **Symptoms** * When enabling a SIP account, the error "Invalid parameters (params)" appears. The account remains not connected. **Possible causes** * Required connection parameters are not specified: , , and . * The selected **Settings Template** doesn't contain a preset value for and for connection. **Solution** 1. Set the correct value for the and parameters (if it's different), and re-enable the SIP account. **Symptoms** * When enabling a SIP account, after some waiting the error "Time out (timeout)" appears. The account remains not connected. **Possible causes** * Incorrect SIP server address specified. * Firewall is active on the SIP server. * SIP server accepts requests on a non-standard port. * The server's DNS name returns an incorrect IP address or multiple IP addresses. * The server's DNS name returns an IPv6 address, but the SIP server is running only on IPv4. **Solution** 1. Set the correct value for the and parameters (if it's different), and re-enable the SIP account. 2. For , specify the IP address explicitly, leaving pointing to the DNS name. 3. Check the receipt of SIP packets using the `sngrep` or `tcpdump` utilities. 4. Check the Firewall rules. Set up automatic updates of the whitelist IP addresses from the file `https://files.sip.tg/fw.txt`. **Symptoms** * Call recording only works if it's enabled manually during each call. * Call recording stops after 15 seconds. **Possible causes** * The setting is not enabled in the SIP account settings. * When paying for the "Softphone" subscription, the "Call Recording" option was not added. **Solution** 1. Check the status of the SIP account settings. See [Configuring the Softphone](/en/docs/softphone/settings) for details. 2. Add the "Call Recording" option in the subscription settings. See [Softphone Subscription](/en/docs/subscriptions/pricing#softphone) for details. **Symptoms** * In the `/softphone` section of the bot, there are no buttons with account settings (, , , , Worker, , , ). There are only and buttons. **Possible causes** * You are a User of the SIP account, but not the Owner. **Solution** 1. Contact the owner of the SIP account with a request to change your settings. See [Owner and User roles for SIP account](/en/docs/softphone/settings#roles) for more details. * **403 Forbidden**: incorrect password/login, or the provider has blocked you. * **404 Not Found**: incorrect SIP domain or subscriber number not found. * **408 Request Timeout**: the provider is not responding, try another Worker or check the firewall. * **503 Service Unavailable**: the operator is experiencing temporary problems or Telegram limits have been exceeded (Too Many Requests). * **603 Declined**: the call is rejected by the operator or the called party. * **Telegram limitations with mass calls**:\ With a large number of outgoing calls, the system may issue `503 Too Many Requests` or `408 Timeout of waiting RPC result` errors. The solution is to reduce the speed of dialing. * **Problems with DTMF**:\ If button presses are not recognized when interacting with the voice menu (IVR), change the DTMF transmission method in the settings (for example, switch from `inband` to `RFC2833` or `INFO`). * **Problems with registration on the Worker server**:\ Sometimes SIP registration doesn't occur because the Worker server doesn't respond or the IP address isn't on the "whitelist". The solution is to check network settings and add the necessary IPs to the whitelist. * **Conflicts when independently updating settings**:\ If users independently change SIP account parameters (for example, audio codecs, dialing rules), this can lead to errors in mass management. Centralized administration through a common "admin" account is recommended. If the described actions didn't help, ask for assistance. See [How to Get Help](/en/docs#help) for details. # Softphone Setup Source: https://www.sip.tg/en/docs/softphone/settings ## Owner and user roles of SIP account **SIP account Owner** — a Telegram user who creates a SIP account in the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) bot. The owner has full control over creating, deleting, and changing SIP account settings, and can also assign accounts to other users. **SIP account User** — a person to whom the owner has assigned a SIP account. They can use the account to make and receive calls, but cannot change the settings of the account itself. The subscription for the softphone must be activated to the Telegram account of the **Owner**. The user's subscription has no effect on SIP accounts that belong to other owners! ## Principle of interaction with settings buttons Most settings are displayed directly on the buttons in the form of current values. To change these settings, simply press the corresponding button and enter a new value as requested by the bot. However, some buttons work differently: * **Worker**: when pressed, a list of available Worker servers appears. Select the desired server from the list to assign it. * **Buttons with checkboxes**: such as "Call Recording", work as toggles. One press activates or deactivates the option. * : when pressed for the first time, an additional button for selecting a chat will appear. By pressing this button, you will see a list of chats and channels available for selection. Choose a suitable chat for call recordings to be saved there. * : when pressed for the first time, an additional button for selecting a user will appear. By pressing this button, you can select another Telegram user to whom this SIP account will be assigned. * **Connection protocol (UDP/TCP/TLS)**: each press switches to the next available protocol. ## Step by step setup * Launch the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) bot. * Go to the `/softphone` section. * Press the button to create a new SIP account. * Enter the login and password received from your IP telephony provider or SIP PBX. Don't use your login and password simultaneously in multiple programs (widgets, other softphones, or telephones). This can result in lost incoming calls and is due to the nature of the SIP protocol. You must create a separate SIP account in your PBX for each program (device). * Specify the domain (SIP server address). * If necessary, specify a separate Registrar Proxy (registration server). * Prepared settings of the IP telephony operator can also be selected from the catalog, which is accessible via the button. * Select the transport protocol: UDP, TCP, or TLS. * Select and configure audio codecs supported by your provider. * Configure the DTMF signal transmission method (RFC2833, INFO, inband). * Set rules for transforming numbers for outgoing calls. * Check in the SIP provider/PBX account that the account is registered. * Try an outgoing call (send a number to the [@siptg](https://t.me/siptg) chat). * If everything is well, try an incoming call (to the SIP account number). * For authorization errors or problems, see [Troubleshooting](/en/docs/softphone/problems). * If necessary, so that calls go not to you but to another employee, assign a Telegram user to this SIP account (button ). * Now all calls will go to the employee, and you will receive notifications if there is a problem with the SIP account. * : enable the option and select a chat for storing recordings. * : for changing the format of the dialed number (for example, +7 → 8). Some settings take effect after pressing the button, or after 5 minutes. After completing the steps, the account will become active and ready to work. ## Available settings The choice of codecs affects the quality and compatibility of voice communication. Opus, alaw, mulaw, GSM, and other codecs are supported. DTMF is necessary for interacting with voice menus. Available methods are RFC2833 (recommended), INFO, and inband. You can activate or deactivate automatic call recording, and also select a separate chat or channel for saving audio recordings. Allows assigning SIP accounts to other Telegram users, giving them the ability to use accounts for calls without access to settings. Allows you to select the server that will connect to the PBX or telephony provider. There are 4 types of servers: | Server type | Description | Designation | | ----------------------------------- | ------------------------------------------------------------------------- | ----------- | | SIP.TG public servers | Main servers supported by SIP.TG | ✅ | | Public servers of other users | Publicly available servers hosted by other users | 🌐 | | Public servers of telecom providers | Available with some Settings Templates, provided by third-party providers | 📡 | | Private servers | Your own servers, available only for your SIP accounts | 🔑 | On a free subscription, only some of the SIP.TG public servers are available. Allow transforming the number for an outgoing call before sending it to the SIP provider or PBX, as well as removing unsuitable SIP accounts from the line selection request for a call (for example, if you prefer to make calls to different countries through different SIP accounts). See the detailed description in the [Transforming outgoing numbers](#dialing-rules) section. ## Transforming outgoing numbers Sometimes for outgoing calls, it's necessary to automatically change the dialed number to meet the requirements of the SIP provider or PBX (for example, replace the first "8" with "+7" or remove spaces and brackets). In SIP.TG, this is configured using **Transformation Rules** in the SIP account settings. If your provider accepts numbers in any format or you're using a ready-made **Settings Template**, dialing rules are most likely not needed. Before making changes, check the requirements for the number format with your SIP provider or within the PBX. There are 2 types of rules: * **Rules with "="** — replacing part of the number.\ If the left part of the rule (regular expression) is found, it's replaced with the right part. * **Rules without "="** — filter (mask).\ If the number doesn't match the regular expression, the rule interrupts processing, and the call is not made. All rules are separated by spaces and applied in sequence. As soon as the number stops matching even one filter rule (without "="), the use of the SIP account for calling that number is not allowed. Each replacement rule (with the "=" sign) changes the number before it's checked by the following filter rules. ### Editing rules in the bot 1. In the [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs) bot, go to the `/softphone` section. 2. Select the desired SIP account, press the button. 3. Enter one or more rules, separating them with spaces. 4. Confirm the changes. 5. Check with a test call that the numbers are transformed correctly. All rules work on the "left to right" principle. Note that adding too many filters or ambiguous replacements can lead to unexpected results. For complex scenarios, test with a couple of real numbers. ### Examples Let's consider the task: we dial numbers like "8 (926) 123-45-67", but the provider requires "7XXXXXXXXXX". Suppose we need to remove all non-digit symbols and turn the prefix 8 into 7. Here are two rules (written with a space): ```text theme={null} [^+*#\w]= ^8=7 ``` **The first** removes all characters except digits, letters, plus, and some special characters (\*, #, \_).\ **The second** replaces the first digit 8 with 7. Now if the user enters `8 (926) 123-45-67`, after the first rule the string will become `89261234567`, and after the second — `79261234567`. If you need to allow outgoing calls only to Russian mobile numbers (starting with 79 and then 9 digits), use a filter rule: ```text theme={null} ^79\d{9}$ ``` Without the "=" sign. If the number doesn't match `^79\d{9}$`, the SIP account won't be used. Sometimes you need to discard everything if the user accidentally entered an invalid number. You can use a replacement rule to empty: ```text theme={null} .*= ``` This will cause any number to be replaced with an empty string. If an empty string doesn't suit the operator, the call won't happen. If you encounter problems or errors, see [Troubleshooting](/en/docs/softphone/problems). # How to Use Source: https://www.sip.tg/en/docs/softphone/usage By using **Softphone**, you transform Telegram into a full-fledged SIP client. After you've added and configured a SIP account via [@siptg\_bot](https://t.me/siptg_bot?start=utm_docs), you can immediately start making calls through it using Telegram. To use Softphone, you need to activate a subscription with the ☎️ "Softphone" label — or use the **Free subscription**, which includes a limited number of calls. For more details, see [Subscriptions Overview](/en/docs/subscriptions/pricing). ## Making Calls After setting up a SIP account, simply send the number you want to call to the [@siptg](https://t.me/siptg) account chat. The number can contain not only digits but also letters, if supported by your PBX. The number is subject to customizable transformation rules that allow you to clean it of unnecessary characters, set prefixes, and more. For details, see [Outgoing Number Transformation](/en/docs/softphone/settings#dialing-rules). If you have the **Callback** mode active, immediately after sending the number, you will receive an incoming call from the **@siptg** account. After answering it, a connection with the dialed number will begin. If Callback is disabled — you need to manually press 📞 in the chat with **@siptg**. Send the phone number or SIP address you want to call to the **@siptg** chat. If you have multiple connected SIP accounts, you will be prompted to select a line for the call. If using Callback mode, you'll receive an incoming call from **@siptg**. Answer it — and the connection will be established. If Callback is disabled — after sending the number, press 📞 in the chat with **@siptg** to start the call. During your first call, Telegram may request permission to receive calls from the **@siptg** account. Allow calls for all or add **@siptg** to exceptions. ## Incoming Calls Incoming calls appear as regular Telegram calls from the **@siptg** account. You can accept the call from the notification menu or directly from Telegram. The name and number of the caller (if transmitted by your PBX) come as a separate text message in the chat with @siptg **at the moment of the incoming call**. You can pull down the notification shade to see the information before answering. To see additional information about the caller at the moment of an incoming call, enable Telegram notifications for the chat with **@siptg**. ## Call Recording If you have paid for call recording as part of your subscription, you can enable automatic recording of all calls for each SIP account separately. This is configured when editing the SIP account in the bot. There, you can also choose where to send the recordings: to a personal chat, channel, or group. For more details, see the [Softphone Settings](/en/docs/softphone/settings) page. A subscription with call recording activates the recording capability **for all accounts**, but enabling automatic recording is done **separately for each account**. ### Manual Recording During a Call If your subscription does not include recording, you can manually record **a call fragment up to 15 seconds long** — the recording button is available during the conversation. If recording is paid for, but **automatic recording is disabled**, you can manually start and stop recording at any time — **without duration limitations**. The recorded files are sent to the chat immediately after the recording is completed. The recording control button is located under the DTMF keypad. To see it, during a call, swipe up or left on the screen and open the chat with **@siptg**. If you are a **SIP account user**, and the account owner has enabled automatic recording and specified a separate chat for saving, you will see that the conversation is being recorded, but **you cannot stop the recording**. ## Reconnecting to call Below the DTMF keypad, there is another button — . It lets you reconnect to the same call from your another device without interrupting the conversation (for example, you can move a call from your laptop to your phone). It works as follows: 1. When you press the button, your call is ended, and your interlocutor is put on hold. 2. The interlocutor hears repeating reconnection tones, and you receive an incoming call (if Callback mode is enabled) or are prompted to make an outgoing call to **@siptg**. 3. If you answer or call back within 60 seconds, the conversation is resumed. Otherwise, the call is terminated. ### Connection recovering If your connection is suddenly lost during a call (for example, your phone battery dies), the call will automatically switch to reconnection mode. Your interlocutor will hear repeating reconnection tones, and you will be able to continue the conversation from another device within 60 seconds. If a [second parallel call](#second-call) was active during reconnection, it will be dropped. Only the active interlocutor you were talking to at the moment the call was interrupted will be put on hold. ## DTMF Keypad During a conversation, you can use the DTMF keypad to interact with voice menus (IVR) or enter extension numbers. It appears in the chat with **@siptg** during a call and disappears after it ends. DTMF transmission methods (RFC2833, INFO, inband) are selected in the SIP account settings. For more details, see [Softphone Settings](/en/docs/softphone/settings). ## Second Parallel Call During an active conversation, you can accept a second incoming call or make a second outgoing call: * If another **incoming** call arrives during a conversation, you will hear periodic beeps. * To make a second **outgoing** call without ending the current one, simply send the number for the second call as a regular message in the **@siptg** chat. In both cases, a new message with action buttons will appear in the **@siptg** chat: * — ends your current conversation and connects your interlocutors with each other; * — puts the current conversation on hold, and connect you to the new call; * — rejects the second incoming call. When you have two active conversations, you can continue to switch between interlocutors several times using the button, or press the button to connect the interlocutors with each other and disconnect yourself. Another button will also appear, — it terminates the current conversation and returns you to the second interlocutor, who was on hold during this time. ## Android Phone Book