Home

Awesome

TelegramApiServer

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

Features

Architecture Example Architecture Example

Installation

git clone https://github.com/xtrime-ru/TelegramApiServer.git TelegramApiServer
cd TelegramApiServer
cp .env.docker.example .env.docker
docker compose pull

Authorization

Please only use old and valid accounts. All new accounts will be banned by telegram. If your account was banned read this: https://docs.madelineproto.xyz/docs/LOGIN.html#getting-permission-to-use-the-telegram-api

  1. Get app_id and app_hash at my.telegram.org. Only one app_id needed for any amount of users and bots.
  2. Fill app_id and app_hash in .env.docker.
  3. Start TelegramApiServer in cli: 1. Start container interactively: docker compose run --rm api 2. If you need to start multiple sessions, create docker-compose.override.yml. Add additional containers there. Use unique ports and session names in command.
  4. Authorize your session:
    1. After promt, fill your phone number, or bot hash.
    2. You will receive telegram code. Type it in. If you're not receiving code - your server IP or hosting may be blocked by telegram. Try another server or change server IP.
    3. If you have 2fa enabled - enter 2fa passord.
  5. Wait 10-30 seconds until session is started. You will see logs: 
    TelegramApiServer ready. 
Number of sessions: 1.
  6. Exit with Ctrl + C
  7. Run container in background docker compose up -d.

Update

Security

Please be careful with settings, otherwise you can expose your telegram session and lose control. Default settings allow to access API only from localhost/127.0.0.1.

.env settings:

docker-compose.yml:

Usage

Access Telegram API with simple GET/POST requests. Regular and application/json POST supported. It's recommended to use http_build_query, when using GET requests.

Rules:

Examples:

Advanced features

Get events/updates

Telegram is event driven platform. For example: every time your account receives a message you immediately get an update. There are multiple ways of getting updates in TelegramApiServer / MadelineProto:

  1. Websocket
  2. Long Polling:
    send request to getUpdates endpoint
    curl "127.0.0.1:9503/api/getUpdates?data[limit]=3&data[offset]=0&data[timeout]=10.0" -g
  3. Webhook: Redirect all updates to your endpoint, just like bot api!
    curl "127.0.0.1:9503/api/setWebhook?url=http%3A%2F%2Fexample.com%2Fsome_webhook" -g
    Example uses urlencoded url in query.

Uploading files.

There are few options to upload and send media files:

Downloading files

curl --location --request POST '127.0.0.1:9503/api/downloadToResponse' \
--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: https://docs.madelineproto.xyz/docs/FILES.html#downloading-files

Multiple sessions support

Its recommended to run every session in separate container.

To add more containers create docker-compose.override.yml file. Docker will automatically merge it with default docker-compose file.

Example of docker-compose.override.yml with two additional containers/sessions (3 in total):

services:
    api-2:
        extends:
            file: docker-compose.base.yml
            service: base-api
        ports:
            - "127.0.0.1:9512:9503"
        command:
            - "-s=session-2"
    api-3:
        extends:
            file: docker-compose.base.yml
            service: base-api
        ports:
            - "127.0.0.1:9513:9503"
        command:
            - "-s=session-3"

Multiple sessions in one container (deprecated)

WARNING: running multiple sessions in one instance/container is unstable. Crash/error in one session will crash all of them.

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

Different settings for sessions

Session management

Examples:

Full list of system methods available in SystemApiExtensions class

Authorizing session remotely

WARNING: it is recomended to use interactive mode to authorize sessions! If there is no authorization in session, or session file is blank, authorization required:

User:

Bot:

Save new session to file immediately: http://127.0.0.1:9503/api/bot/serialize

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

Websocket

EventHandler updates (webhooks).

Connect to ws://127.0.0.1:9503/events 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://127.0.0.1:9503/events/users/xtrime

PHP websocket client example: websocket-events.php

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

Logs.

Connect to ws://127.0.0.1:9503/log[/%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://127.0.0.1:9503/log/alert

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

PHP websocket client example: websocket-events.php

php examples/websocket-events.php --url=ws://127.0.0.1:9503/log

Custom methods

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

Contacts