Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/OPENNOVA2026/telegram-connector/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through obtaining Telegram API credentials, building and running the service with Docker, completing the two-step sign-in flow, and making your first channel and message requests. By the end you will have a running Telegram Connector instance, an authenticated session, and a list of your Telegram channels returned from the API.
1

Obtain Telegram API credentials

Navigate to https://my.telegram.org/apps and log in with the phone number associated with your Telegram account. Create a new application — Telegram will issue an api_id (integer) and an api_hash (string) that identify your client to the MTProto network.
Keep your api_hash secret. It acts as a password for your Telegram API application — anyone who holds it can impersonate your client.
2

Create your .env file

In the root of the project, create a .env file with your credentials and S3 session storage configuration:
# Telegram API credentials (required)
API_ID=12345678
API_HASH=your_api_hash_here

# AWS S3 — required for session persistence
AWS_REGION=us-east-1
AWS_ACCESS_KEY=your_access_key_id
AWS_SECRET_KEY=your_secret_access_key
AWS_S3_SESSION_BUCKET=nova-persistent-sessions-bucket

# Optional: override the S3 endpoint (e.g. for LocalStack)
# AWS_S3_ENDPOINT=http://localhost:4566

# Optional: logical name used in the S3 key path (defaults to teleapp)
# SESSION=teleapp

# Optional: deployment environment label (defaults to local)
# ENVIRONMENT=local

# Optional: enable Sentry error monitoring
# SENTRY_DSN=https://your-dsn@sentry.io/123
The service calls S3 on every startup and shutdown to load and persist the Telethon session. The AWS credentials are therefore required for the service to start successfully. See Configuration → Environment for the full variable reference.
3

Build the Docker image

From the project root, build the production image:
docker build -t telegram-connector .
The Dockerfile uses a multi-stage build: a builder stage installs dependencies with Poetry, and the prod stage copies only the installed packages and application source into a minimal python:3.10.16-slim-bullseye image.
4

Run the container

Start the container with the environment file and a volume mount:
docker run --rm --name telegram-connector -it -p 5004:5000 -v .:/app telegram-connector
  • -p 5004:5000 maps port 5004 on your host to the container’s internal port 5000, where Uvicorn is listening.
  • -v .:/app mounts your project directory into the container so that your .env file is picked up at runtime.
The service starts and immediately tries to load an existing session from S3. If no session exists yet it initialises a fresh StringSession and waits for sign-in.
5

Sign in — send your phone number

POST to /sign_in with only your phone number (in E.164 format):
curl -X POST http://localhost:5004/sign_in \
  -H 'Content-Type: application/json' \
  -d '{"phone": "+1234567890"}'
The service returns HTTP 206 Partial Content. This means Telegram has dispatched a one-time code to your Telegram app (or via SMS). Do not include a password field in this first request.
6

Sign in — submit the code

Open your Telegram app, note the code you received, and send it as the password field:
curl -X POST http://localhost:5004/sign_in \
  -H 'Content-Type: application/json' \
  -d '{"phone": "+1234567890", "password": "12345"}'
The password field carries the code Telegram sent to your app — it is not your account password. A successful authentication returns HTTP 200 and the session is immediately persisted to S3 via SessionManager.
7

Verify authorization

Confirm the session is active:
curl http://localhost:5004/is_user_authorized
Expected response:
{"data": true}
If this returns false, repeat the sign-in steps — the session was not established correctly.
8

List your channels

Fetch all channels the authenticated user belongs to:
curl http://localhost:5004/channels
Example response (trimmed to one channel):
{
  "data": [
    {
      "id": 1234567890,
      "title": "Example Channel",
      "username": "example_channel",
      "participants_count": 4821
    }
  ]
}
Each object in data is the raw Telethon Channel dict. You can use the username values here as identifiers when joining or leaving channels via POST /channels and DELETE /channels.

​
Next Steps

API Reference

Explore full request and response schemas for every endpoint, including sign-in, channel management, and message retrieval.

Configuration

Review all environment variables — AWS credentials, Sentry DSN, session name, and more.

Session Persistence

Understand how Telethon StringSessions are serialised and stored in S3 so your authentication survives container restarts.

Deployment

Learn about the production and development Docker targets, environment-specific configuration, and container best practices.

Build docs developers (and LLMs) love

Get started for freeTalk to us