TelegramApiServer Documentation

Telegram is an event-driven platform. You can retrieve updates (like new messages) using three primary methods:

1. Long Polling: Send a request to the getUpdates endpoint. Use limit and offset to manage the queue and timeout to hold the connection.
2. Webhooks: Redirect all updates to your own endpoint by calling setWebhook. The URL must be URL-encoded in the query string.
3. Websockets: Connect to the /events endpoint to receive all events as JSON-RPC 2.0 formatted objects. This is an efficient alternative to webhooks.

When using multiple sessions, you can subscribe to a specific session's events by appending the session name to the websocket path (e.g., ws://127.0.0.1:9503/events/session_name).

# Long Polling example
curl "127.0.0.1:9503/api/getUpdates?limit=3&offset=0&timeout=10.0" -g

# Webhook setup example
curl "127.0.0.1:9503/api/setWebhook?url=http%3A%2F%2Fexample.com%2Fsome_webhook" -g

You can send documents, videos, audio, and other media using methods like sendDocument or sendVideo. The server supports three upload modes:

• Stream upload: Send a file directly from your client using a multipart/form-data POST request.
• Remote URL: Provide a JSON object containing a RemoteUrl type and the target URL. The server will fetch it.
• Local file on server: Provide a JSON object containing a LocalUrl type and the file path relative to the server.

Note: For all methods, the peer field specifies the recipient (e.g., me).

# Stream upload from client
curl --location --request POST 'http://127.0.0.1:9503/api/sendDocument' -g \
-F peer=me \
-F caption=key \
-F file=@screenshot.png

# Remote URL upload
curl --location --request POST 'http://127.0.0.1:9503/api/sendVideo' \
--header 'Content-Type: application/json' \
--data-raw '{
    "peer": "me",
    "file": {
        "_": "RemoteUrl",
        "url": "https://domain.site/storage/video.mp4"
    },
    "parseMode": "HTML",
    "caption": "<b>caption text</b>"
}'

# Local file on server upload
curl --location --request POST 'http://127.0.0.1:9503/api/sendDocument' \
--header 'Content-Type: application/json' \
--data-raw '{
    "peer": "me",
    "file": {
        "_": "LocalUrl",
        "file": "faust.txt"
    },
    "parseMode":  "HTML",
    "caption": "<b>caption text</b>"
}'

Recommended: Separate Containers

It is highly recommended to run every session in a separate container to ensure stability. You can use a docker-compose.override.yml to add additional service instances, each with its own port mapping and -s (session) command argument.

Deprecated: Multiple sessions in one container

Running multiple sessions in a single instance is unstable; a crash in one session will crash all others.

If you must use one container, you can specify multiple sessions via CLI: php server.php --session=bot --session=users/xtrime

To target a specific session in an API call, include the session path in the URL:

• http://127.0.0.1:9503/api/bot/getSelf
• http://127.0.0.1:9503/api/users/xtrime/getSelf

Sessions are stored in the sessions/ directory. You can use glob syntax like --session=* to load all sessions.

# Example docker-compose.override.yml for multiple sessions
services:
    api-2:
        extends:
            file: docker-compose.base.yml
            service: base-api
        ports:
            - "127.0.0.1:9512:9503"
        command:
            - "-s=session-2"

You can apply unique settings (like proxies) to specific sessions using two methods:

1. Environment Files: Use the --env argument when starting the server to point to a specific .env file (e.g., php server.php --env=sessions/.env.session).
2. JSON Settings Files: Place a %sessionName%.settings.json file in the sessions/ folder. For example, session1.settings.json will apply to the session1 session.

System API methods for settings:

• saveSessionSettings: Save settings via query parameters.
• unlinkSessionSettings: Remove settings for a session.
• addSession: Provide settings as the second argument during session creation to ensure they persist after restart.

// Example session.settings.json for adding a proxy
{
    "connection": {
        "proxies": {
            "\\danog\\MadelineProto\\Stream\\Proxy\\SocksProxy": [
                {
                  "address": "127.0.0.1",
                  "port": 1234,
                  "username": "user",
                  "password": "pass"
                }
            ]
        }
    }
}