Telegram sessions storage

This module is a broker between SIP.tg platform and your Telegram account in SIP Gateway mode. It allows to locate your Telegram session data on your hardware and pass only white-listed operations with your Telegram account. This approach reaches two main goals:

• decreases risks of compromising your Telegram account: SIP.tg gets a limited access to your Telegram account;
• SIP.tg remains usable: management of SIP Gateway is made through @siptg_bot.

The storage uses TDLib library as a backend to communicate with Telegram platform and acts as TCP server for SIP.tg platform. It caches and resolves usernames and phone numbers into user_ids out of the box and optionally can backup all data into MySQL database. It also allows to connect to the Telegram session from multiple socket clients.

How to configure the storage

Update the software of your system. For example, on Ubuntu/Debian system use the following commands:

apt-get update
apt-get upgrade

Next, setup docker and download latest configs:

cd ~
wget get.docker.com -O - -o /dev/null | sudo sh
apt-get install docker-compose dnsutils git
git clone https://github.com/siptg/storage.git
cd storage

Get API_ID and API_HASH through API development tools and update them in storage/settings.json in section tdlib.

Get the cert.pem and key.pem from the @siptg_bot and push it to ssl directory inside storage.

Warning! The certificate which is given from the bot is valid for a limited time (365 days at the moment). In the case it expires, you get Certificate error while connecting to the storage and have to get the new one the same way. To check the expiration date use the following command:
openssl x509 -enddate -noout -in ssl/cert.pem

Next, verify and change if needed the storage's server port which will be used to connect to your storage from SIP.tg platform (see below). If you are is under the NAT, verify the port mapping at the NAT as well. Also don't forget to allow incoming connections for the specified port at your firewall if needed.

Next, run the storage by command:

docker-compose up -d

After that set the host's address:port in the bot and push Turn on button. You're done!

Default ports which are used by the storage

Port	Type	Area	Description	To change
50002*	TCP	all	Storage external	nginx/nginx.conf: stream→server→listen
23456	TCP	local	Storage internal	storage/settings.json: port nginx/nginx.conf: stream→server→proxy_pass

* — the port which you have to provide to the bot.

Managing the storage

Restart

Inside storage directory run:

docker-compose restart

Update

Inside storage directory run:

git pull
docker-compose pull && docker-compose up -d

Settings file

Settings file is located on storage/settings.json and has JSON format with the following options:

Option	Description	Default
logfile	If set, redirect stderr and stdout to the specified file. Please note: it requires to attach external volume from the docker-compose.yml, make an empty file with the given logfile name and update the storage first.	(not set)
debug_level	Main debug level: 0 - NONE: output only version info; 1 - FATAL: add errors which terminates the storages; 2 - ERROR: add general errors; 3 - WARNING: add attempts of disallowed RPC calls; 4 - INFO: general info about start/stop Telegram sessions; 5 - DEBUG: debug info about create/destroy internal structures; 6 - VERBOSE: output data of RPC/updates attempts.	4
terminate_delay	Delay (in seconds) before terminating Telegram session after the last socket client is disconnected	0
host	IP address or host where the server starts listening	localhost
port	Port where the server starts listening; 0 means a random port	0
offline	Include updates which were received while Telegram session was offline (applied only for first socket client)	false
tdlib	Section of TDLib settings
tdlib/api_id	App api_id from API development tools
tdlib/api_hash	App api_hash from API development tools
tdlib/path	Relative path where to save TDLib data. Make sure to match this value with the value from docker-compose.yml and follow to update steps to apply changes.
tdlib/debug_level	TDLib debug level: 0 - FATAL; 1 - ERROR; 2 - WARNING; 3 - INFO; 4 - DEBUG.	0
tdlib/proxy	Section of setting up connection to Telegram servers through proxy. Only one proxy server is supported at the moment.	(not set)
tdlib/proxy/type	Proxy type: socks5, http or mtproto
tdlib/proxy/host	Host of proxy server
tdlib/proxy/port	Port of proxy server
tdlib/proxy/username	Username to authenticate on proxy server (for socks5 and http types only; optional)	(not set)
tdlib/proxy/password	Password to authenticate on proxy server (for socks5 and http types only; optional)	(not set)
tdlib/proxy/http_only	Pass true, if the proxy supports only HTTP requests and doesn't support transparent TCP connections via HTTP CONNECT method (for http type only)	false
tdlib/proxy/secret	The proxy's secret in hexadecimal encoding (for mtproto type only)
allowed_updates	List of allowed update types; updateAuthorizationState and updateConnectionState are always allowed. See below for values which are used by SIP.tg platform.
allowed_requests	List of allowed RPC types. See below for values which are used by SIP.tg platform.
request_peers	Section which enumerates fields from RPC types which have to preprocess to resolve user_id by the given username or phone number. Key represents the type of RPC request, value -- the field name which contains username or phone number (can be single value or a list of values).
format_fields	Section which enumerates fields to preprocess given text into formattedText. Key represents the type name, value -- the field name which contains the text to preprocess.
format_markdown	Parse fields from format_fields as Markdown (if true) or as HTML (if false)	true
mysql	Section of MySQL connection settings. If not set, data is saved locally only.	(not set)
mysql/host	Host of MySQL server
mysql/port	Port of MySQL server	3306
mysql/user	User name to authenticate by MySQL server
mysql/password	Password to authenticate by MySQL server
mysql/database	Name of the database to store the data
mysql/charset	Default charset of string values	utf8
mysql/read_timeout	Timeout before reconnect to MySQL server on read; 0 means system default	0
mysql/debug	Debug output of MySQL communication	false
mysql/ssl	Section of setting up a secure SSL connection to MySQL server	(not set)
mysql/ssl/key	Relative path of SSL key file
mysql/ssl/cert	Relative path of SSL cert file
mysql/ssl/ca	Relative path of SSL ca file

Update and request types used by SIP.tg platform

Depending on the features you want to use, the list of allowed update and RPC request types can include one or multiple groups from the table:

Feature	allowed_updates	allowed_requests
Managing the session from @siptg_bot and REST API		setAuthenticationPhoneNumber, checkAuthenticationCode, checkAuthenticationPassword, recoverAuthenticationPassword, requestAuthenticationPasswordRecovery, checkAuthenticationBotToken, requestQrCodeAuthentication, setAuthenticationEmailAddress, checkAuthenticationEmailCode, getMe, logOut
Configure Telegram account from @siptg_bot and REST API		getActiveSessions, toggleSessionCanAcceptCalls, setUserPrivacySettingRules
Make voice calls (SIP→Telegram)	updateCall, updateNewCallSignalingData	getUser, createCall, discardCall, sendCallSignalingData, restoreCall
Receive voice calls (Telegram→SIP)	updateCall, updateNewCallSignalingData	receiveCall, acceptCall, discardCall, sendCallSignalingData, restoreCall
DTMF and Redial buttons		getInlineQueryResults, sendInlineQueryResultMessage, deleteMessages
Call to arbitrary numbers through PBX	updateNewMessage
Managing the session of a White Label bot		checkAuthenticationBotToken, logOut
Change settings via a White Label bot	updateNewMessage, updateNewCallbackQuery	sendMessage, editMessageText, editMessageReplyMarkup
Using a White Label bot for DTMF and Redial buttons	updateNewInlineQuery, updateNewInlineCallbackQuery	answerInlineQuery, editInlineMessageText, editInlineMessageReplyMarkup

Storing data in external MySQL database

To store data externally, create new database on your MySQL server and apply schema.sql to create requried tables inside. After that change (or add if not exists) section mysql in storage/settings.json file according to the instructions and restart the storage.