TelegramApiServer Save

Fast, simple, async php telegram api server: MadelineProto + Amp HTTP Server

Project README


Fast, simple, async php telegram api server: MadelineProto and Amp Http Server


  • Fast async Amp Http Server
  • Full access to telegram api: bot and user
  • Multiple sessions
  • Stream media (view files in a browser)
  • Upload media
  • Websocket endpoints for events and logs
  • MadelineProto optimized settings to reduce memory consumption

Architecture Example Architecture Example



  1. git clone TelegramApiServer
  2. cd TelegramApiServer
  3. Start container: docker-compose up
    Folder will be linked inside container to store all necessary data: sessions, env, db.


  1. Requirements:

  2. git clone TelegramApiServer

  3. cd TelegramApiServer

  4. composer install -o --no-dev

  5. php server.php

First start

  1. Ctrl + C to stop TelegramApiServer if running.
  2. Get app_id and app_hash at Only one app_id needed for any amount of users and bots.
  3. Fill app_id and app_hash in .env.docker or .env.
  4. Start TelegramApiServer in cli:
    • docker:
      1. Start: docker-compose up
      2. Start new shell and connect to docker container: bash bin/
      3. Start another instance with different port inside new shell: php server.php -p=9500 -s=session --docker -e=.env.docker
    • manual:
      1. php server.php --session=session
  5. Authorize your session:
    1. Chose account type: user (u) or bot (b)
    2. Follow instructions
  6. Wait 10-30 seconds until authorization is end and exit with Ctrl + C.
  7. Run TAS in screen, tmux, supervisor (see below) or docker.


  1. Run server/parser

    usage: php server.php [--help] [-a=|--address=] [-p=|--port=9503] [-s=|--session=]  [-e=|--env=.env] [--docker]
            --help      Show this message
        -a  --address   Server ip (optional) (default:
                        To listen external connections use and fill IP_WHITELIST in .env
        -p  --port      Server port (optional) (default: 9503)
        -s  --session   Name for session file (optional)
                        Multiple sessions can be specified: "--session=user --session=bot"
                        Each session is stored in `sessions/{$session}.madeline`. 
                        Nested folders supported.
                        See README for more examples.
        -e  --env       .env file name. (default: .env). 
                        Helpful when need multiple instances with different settings
            --docker    Apply some settings for docker: add docker network to whitelist.
    Also some options can be set in .env file (see .env.example)
  2. Access Telegram API with simple GET/POST requests.

    Regular and application/json POST supported. Its recommended to use http_build_query, when using GET requests.


    • All methods from MadelineProto supported: Methods List

    • Url: http://%address%:%port%/api[/%session%]/%class%.%method%/?%param%=%val%

    • Important: api available only from ip in whitelist. By default it is: You can add a client IP in .env file to IP_WHITELIST (separate with a comma)

      In docker version by default api available only from localhost ( To allow connections from the internet, need to change ports in docker-compose.yml to 9503:9503 and recreate the container: docker-compose up -d. This is very insecure, because this will open TAS port to anyone from the internet. Only protection is the IP_WHITELIST, and there are no warranties that it will secure your accounts.

    • If method is inside class (messages, contacts and etc.) use '.' to separate class from method:

    • If method requires array of values, use any name of array, for example 'data': ?data[peer][email protected]&data[message]=Hello!. Order of parameters does't matter in this case.

    • If method requires one or multiple separate parameters (not inside array) then pass parameters with any names but in strict order:[email protected] or[email protected] works the same


    • get_info about channel/user:[email protected]
    • get_info about currect account:
    • repost:[from_peer][email protected]&data[to_peer][email protected]&data[id]=1234
    • get messages from channel/user:[peer][email protected]&data[limit]=10
    • get messages with text in HTML:[peer][email protected]&data[limit]=10
    • search:[q]=Hello%20World&data[limit]=10
    • sendMessage:[peer][email protected]&data[message]=Hello!
    • copy message from one channel to another (not repost):[from_peer][email protected]&data[to_peer][email protected]&data[id][0]=1

Run in background

  • Docker: docker-compose up -d Docker will monitor and restart containers.
  • Manual:
    1. Use supervisor to monitor and restart swoole/amphp servers.
    2. apt-get install supervisor
    3. Put config file in /etc/supervisor/conf.d/telegram_api_server.conf. Example:
    command=/usr/bin/php /home/admin/web/ --session=*
    1. Load new config: supervisorctl update
    2. View/control processes: supervisorctl


  • git pull or git fetch && git reset --hard origin/master
  • composer install -o --no-dev
  • Compare .env.docker or .env with corresponding .env.example. Update if needed.
  • Docker:
    • docker-compose pull
    • docker-compose down
    • docker-compose up
  • Manual: supervisorctl restart telegram_api_server

Advanced features

Uploading files.

There are few options to upload and send media files:

  • Custom method sendMedia supports upload from form:

    curl "[peer]=xtrime&data[message]=Hello" -g \
    -F "[email protected]/Users/xtrime/Downloads/test.txt"
  • use custom uploadMediaForm method and then pass result to messages.sendMedia:

    1. curl "" -g -F "[email protected]/Users/xtrime/Downloads/test.txt" Method supports application/x-www-form-urlencoded and multipart/form-data.

    2. Send result from uploadMediaForm to messages.sendMedia or sendMedia:

    curl --location --request POST '' \
    --header 'Content-Type: application/json' \
    --data-raw '{
            "peer": "@xtrime",
            "media": {
                "_": "inputMediaUploadedDocument",
                "file": {
                    "_": "inputFile",
                    "id": 1164670976363200575,
                    "parts": 1,
                    "name": "test.txt",
                    "mime_type": "text/plain",
                    "md5_checksum": ""
                "attributes": [
                        "_": "documentAttributeFilename",
                        "file_name": "test.txt"
  • See other options:

Downloading files

curl --location --request POST '' \
--header 'Content-Type: application/json' \
--data-raw '{
    "media": {
        "_": "messageMediaDocument",
        "document": {
            "_": "document",
            "id": 5470079466401169993,
            "access_hash": -6754208767885394084,
            "file_reference": {
                "_": "bytes",
                "bytes": "AkKdqJkAACnyXshwzMhdzeC5RkdVZeh58sAB/UU="
            "date": 1551713685,
            "mime_type": "video/mp4",
            "size": 400967,
            "dc_id": 2,
            "attributes": [
                    "_": "documentAttributeFilename",
                    "file_name": "одолдол.mp4"

Also see:

Multiple sessions support

When running multiple sessions, need to define which session to use for request. Each session stored in sessions/{$session}.madeline. Nested folders supported. Examples:

  • php server.php --session=bot --session=users/xtrime --session=users/user1
  • sessions file paths are: sessions/bot.madeline, sessions/users/xtrime.madeline and sessions/users/user1.madeline
  • glob syntax for sessions:
    • --session=* to use all sessions/*.madeline files (in subfolders too).
    • --session=users/* --session=bots/* to use all session files from sessions/bots and sessions/users folders.

Different settings for sessions

  • Use --env argument to define the relative path to env file. Example: php server.php --env=.env, php server.php --env=sessions/.env.session
    This is helpful to define unique settings for different instances of TelegramApiServer.
    You can start multiple instances of TelegramApiServer with different sessions on different ports with their own settings.

  • Another way to manage settings - put %sessionName%.settings.json in sessions folder. Example of session.settings.json to add proxy for the one session:

        "connection_settings": {
            "all": {
                "proxy": "\\SocksProxy",
                "proxy_extra": {
                    "address": "",
                    "port": 1234,
                    "username": "user",
                    "password": "pass"

    Methods to work with settings files:

  • Provide settings as second argument when adding session:[app_info][app_id]=xxx&&settings[app_info][app_hash]=xxx These settings will be saved into json file and will apply after the restart.

Session management


  • Session list:
  • Adding session:
  • Removing session (session file will remain): Due to madelineProto issue its instance still might be in memory and continue working even after the remove.
  • Remove session file: Don`t forget to logout and call removeSession first!
  • Close TelegramApiServer (end process):

Full list of system methods available in SystemApiExtensions class

Authorizing session remotely

If there is no authorization in session, or session file is blank, authorization required:


  •, %2B - is urlencoded "+" sign
  • (optional)
  • (optional)



Save new session to file immediately:

Also, session can be authorized in cli/shell on server start.


EventHandler updates (webhooks).

Connect to ws:// to get all events in json. This is efficient alternative for webhooks. Each event is json object in json-rpc 2.0 format. Example:

When using multiple sessions, name of session can be added to path of websocket endpoint: This endpoint will send events only from users/xtrime session: ws://

PHP websocket client example: websocket-events.php

php examples/websocket-events.php --url=ws://


Connect to ws://[/%level%] to get logs in real time.

%level% is optional parameter to filter logs. If filter is specified, then only messages with equal or greater level will be send. This endpoint will send only alert and emergency logs: ws://

Available levels: debug, info, notice, warning, error, critical, alert, emergency.

PHP websocket client example: websocket-events.php

php examples/websocket-events.php --url=ws://

Custom methods

TelegramApiServer extends madelineProto with some handful methods.
Full list of custom methods and their parameters available in ApiExtensions class

  • getHistory - same as messages.getHistory, but all params exept peer is optional.
  • getHistoryHtml - message entities converted to html
  • formatMessage - converts entities to html
  • copyMessages - copy message from one peer to onother. Like forwardMessages, but without the link to original.
  • getMedia - download media to stream/browser
  • getMediaPreview - download media preview to stream/browser
  • uploadMediaForm - upload document from POST request.


Open Source Agenda is not affiliated with "TelegramApiServer" Project. README Source: xtrime-ru/TelegramApiServer
Open Issues
Last Commit
1 month ago

Open Source Agenda Badge

Open Source Agenda Rating