⚡ AutoHub API

Authentication

Method	How to send	Example
X-API-Key header Recommended	HTTP header	X-API-Key: your_api_key_here
Authorization header	Bearer token	Authorization: Bearer your_api_key_here
Query parameter	URL param	?api_key=your_api_key_here

API keys are issued by an admin. Each key is tied to a specific user account and inherits that account's permissions.

Quick Start

Copy# 1. Verify your key and see available endpoints
curl -s "https://tgautomation.org/api/v1/system-info" \
  -H "X-API-Key: YOUR_KEY" | python -m json.tool

# 2. List your accounts
curl -s "https://tgautomation.org/api/v1/accounts" \
  -H "X-API-Key: YOUR_KEY"

# 3. Send a broadcast NOW
curl -s -X POST "https://tgautomation.org/api/v1/broadcast" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "YOUR_ACCOUNT_ID",
    "target_keys": ["@channel1", "@channel2"],
    "message": "Hello from the API!",
    "schedule_type": "now"
  }'

All Endpoints

V1 Endpoints

GET /api/v1/system-info

Returns system information and a summary of all available endpoints.

Copycurl "{base}/api/v1/system-info" -H "X-API-Key: KEY"

GET /api/v1/accounts

Returns all Telegram and WhatsApp accounts owned by the API key's user.

Copycurl "{base}/api/v1/accounts" -H "X-API-Key: KEY"

# Response
{
  "success": true,
  "accounts": [
    {
      "id": "abc123",
      "name": "My Account",
      "phone": "+1234567890",
      "platform": "telegram",
      "connected": true,
      "status": "connected"
    }
  ],
  "count": 1
}

GET /api/v1/groups

Returns all groups, channels and contacts available to the user. Supports optional filtering.

Query Param	Values	Description
platform	telegram, whatsapp	Filter by platform
account_id	account ID	Show only groups scanned by this account

Copycurl "https://tgautomation.org/api/v1/groups?platform=telegram" -H "X-API-Key: KEY"

GET /api/v1/templates

Returns all message templates owned by the user.

Copycurl "https://tgautomation.org/api/v1/templates" -H "X-API-Key: KEY"

# Response
{
  "success": true,
  "templates": [
    {
      "id": "tpl-uuid",
      "name": "Promo Message",
      "content": "Hello! Check our latest offer..."
    }
  ],
  "count": 1
}

GET /api/v1/broadcasts

Returns all broadcast schedules owned by the user.

Query Param	Values	Description
platform	telegram, whatsapp	Filter by platform
enabled	true, false	Filter by enabled status

Copycurl "https://tgautomation.org/api/v1/broadcasts?platform=telegram&enabled=true" -H "X-API-Key: KEY"

POST /api/v1/broadcast

Create a broadcast. Set schedule_type to now to send immediately, or interval/daily for recurring.

Field	Type	Required	Description
account_id	string	Yes	ID of the Telegram or WhatsApp account to send from
target_keys	array	Yes	Array of group/channel IDs or @usernames (max 50)
message	string	One of	Custom message text (max 4096 chars)
template_id	string	One of	ID of a saved template to use
schedule_type	string	No	now (default), interval, or daily
interval_minutes	integer	No	Minutes between runs (for interval type)
daily_time	string	No	Time in HH:MM format (for daily type)
platform	string	No	auto (default — detected from account), telegram, or whatsapp
name	string	No	Display name for the schedule

Copy# Send now
curl -X POST "https://tgautomation.org/api/v1/broadcast" \
  -H "X-API-Key: KEY" -H "Content-Type: application/json" \
  -d '{
    "account_id": "abc123",
    "target_keys": ["@channel1", "-1001234567890"],
    "message": "Hello from AutoHub!",
    "schedule_type": "now"
  }'

# Schedule recurring (every 2 hours)
curl -X POST "https://tgautomation.org/api/v1/broadcast" \
  -H "X-API-Key: KEY" -H "Content-Type: application/json" \
  -d '{
    "account_id": "abc123",
    "target_keys": ["@channel1"],
    "template_id": "tpl-uuid",
    "schedule_type": "interval",
    "interval_minutes": 120,
    "name": "My 2hr Campaign"
  }'

# Response
{
  "success": true,
  "schedule_id": "uuid",
  "platform": "telegram",
  "message": "Broadcast triggered for telegram."
}

GET /api/v1/broadcast/{id}

Get status and details for a specific broadcast schedule.

Copycurl "https://tgautomation.org/api/v1/broadcast/SCHEDULE_ID" -H "X-API-Key: KEY"

POST /api/v1/broadcast/{id}/run

Trigger an existing broadcast schedule to run immediately (regardless of its scheduled time).

Copycurl -X POST "https://tgautomation.org/api/v1/broadcast/SCHEDULE_ID/run" -H "X-API-Key: KEY"

DELETE /api/v1/broadcast/{id}

Permanently delete and cancel a broadcast schedule.

Copycurl -X DELETE "https://tgautomation.org/api/v1/broadcast/SCHEDULE_ID" -H "X-API-Key: KEY"

Scan & Search Endpoints

POST /api/v1/scan

Scan a Telegram account to discover its chats, groups, channels, and contacts. Results are stored and retrievable via GET /api/v1/scan/results.

Body Field	Required	Description
account_id	Yes	Telegram account ID to scan (from /api/v1/accounts)
max_age_days	No	Only include chats active within N days (0 = no filter)
since_ts	No	Unix timestamp — only include chats active after this

Copycurl -X POST "https://tgautomation.org/api/v1/scan" \
  -H "X-API-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "ACCOUNT_ID", "max_age_days": 30}'

# Response
{
  "success": true,
  "account_id": "ACCOUNT_ID",
  "channels": [ {"id": -100123, "title": "Crypto News", "members": 5000} ],
  "groups":   [ {"id": -100456, "title": "Trading Signals", "members": 200} ],
  "contacts": [ {"id": 789, "name": "John", "username": "john_doe"} ],
  "total": 87
}

GET /api/v1/scan/results

Retrieve the stored results from the last scan (dashboard scan or API scan).

Query Param	Description
account_id	Filter to results from a specific account
type	Filter by type: groups, channels, contacts (default: all)

Copycurl "https://tgautomation.org/api/v1/scan/results?type=groups" -H "X-API-Key: KEY"

# Also supports POST with JSON body:
curl -X POST "https://tgautomation.org/api/v1/scan/results" \
  -H "X-API-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "ACCOUNT_ID", "type": "groups"}'

POST /api/v1/scan/messages

Search for messages matching a keyword/phrase across all chats on a Telegram account. Equivalent to the dashboard "Scan Messages" feature.

Body Field	Required	Description
account_id	Yes	Telegram account ID to search with
query	Yes	Keyword or phrase to search for
target_type	No	groups, channels, contacts, or all (default: all)
per_chat_limit	No	Max messages per chat (default: 8)
max_chats	No	Max chats to search (default: 60)
lookback_days	No	How many days back to search (0 = unlimited)
since_ts	No	Unix timestamp lower bound
until_ts	No	Unix timestamp upper bound

Copycurl -X POST "https://tgautomation.org/api/v1/scan/messages" \
  -H "X-API-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "ACCOUNT_ID", "query": "buy crypto", "lookback_days": 7}'

# Response
{
  "success": true,
  "account_id": "ACCOUNT_ID",
  "query": "buy crypto",
  "results": [
    {"chat_id": -100123, "chat_title": "Crypto Group", "message_id": 555,
      "text": "I want to buy crypto", "from_user": "alice", "date": 1700000000}
  ],
  "total": 23,
  "chats_searched": 60
}

POST /api/v1/scan/search-reply

Search group chats for messages containing keywords and automatically send a reply to those senders. Equivalent to the dashboard "Keyword Auto-Reply" feature.

Body Field	Required	Description
account_id	Yes	Telegram account ID to use
keywords	Yes	Comma-separated keywords to match
reply_text	Yes	Message to send to matched users
target_type	No	groups, channels, contacts, or all (default: all)
max_chats	No	Max chats to scan (default: 120)
per_chat_limit	No	Max messages per chat (default: 120)

Copycurl -X POST "https://tgautomation.org/api/v1/scan/search-reply" \
  -H "X-API-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "ACCOUNT_ID", "keywords": "buy,interested,price", "reply_text": "Hi! Check our offer at t.me/mychannel"}'

# Response
{
  "success": true,
  "account_id": "ACCOUNT_ID",
  "keywords": "buy,interested,price",
  "replied_to": 14,
  "details": [ {"user": "alice", "chat": "Trading Group", "matched_text": "what is the price?"} ]
}

POST /api/v1/scan/discover

Discover new Telegram groups and channels using AI-powered multi-source search (DuckDuckGo, Bing, TGStat, SearcheeBot). Equivalent to the dashboard "Discover Groups" feature.

Body Field	Required	Description
account_id	Yes	Telegram account ID to use for discovery
keywords	No	Search terms (e.g. "crypto trading signals")
category	No	Category hint (e.g. finance, tech, marketing)
min_members	No	Minimum member count filter (default: 0)
include_channels	No	Include channels in results (default: false)
only_new	No	Skip already-scanned groups (default: true)
max_results	No	Max groups to return (default: 40)
use_tgstat	No	Search via TGStat (default: true)
use_web	No	Search via DuckDuckGo/Bing (default: true)
use_searchee	No	Search via SearcheeBot (default: true)

Copycurl -X POST "https://tgautomation.org/api/v1/scan/discover" \
  -H "X-API-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "ACCOUNT_ID", "keywords": "crypto trading", "min_members": 500, "max_results": 50}'

# Response
{
  "success": true,
  "account_id": "ACCOUNT_ID",
  "groups": [
    {"title": "Crypto Signals", "username": "cryptosignals", "members": 12000, "link": "t.me/cryptosignals", "relevance_score": 0.92}
  ],
  "total": 38
}

Profile Management Endpoints

GET /api/v1/accounts/{id}/profile

Get the full Telegram profile for an account including name, username, bio, and photo status.

Copycurl "{base}/api/v1/accounts/ACCOUNT_ID/profile" -H "X-API-Key: KEY"

Response:

{"success": true, "ok": true, "profile": {"id": 123456, "first_name": "John", "last_name": "Doe", "username": "johndoe", "phone": "+1234567890", "about": "Bio text here", "photo": true}}

PUT /api/v1/accounts/{id}/profile

Update Telegram profile fields. All fields optional but at least one required.

Body Field	Required	Description
first_name	No	First name (1-64 chars)
last_name	No	Last name (0-64 chars, empty to clear)
about	No	Bio/about text (0-70 chars, empty to clear)

Copycurl -X PUT "{base}/api/v1/accounts/ACCOUNT_ID/profile" \
  -H "X-API-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Muhammad", "last_name": "Khan", "about": "Founder @ 2ndCall"}'

PUT /api/v1/accounts/{id}/username

Set or change the Telegram @username for an account.

Body Field	Required	Description
username	Yes	New username (5-32 chars, a-z/0-9/_, without @). Empty string to remove.

Copycurl -X PUT "{base}/api/v1/accounts/ACCOUNT_ID/username" \
  -H "X-API-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "MK_2ndcall"}'

POST /api/v1/accounts/{id}/photo

Upload and set a profile photo. Accepts multipart file upload or JSON with server-side path.

Option 1: File upload

Copycurl -X POST "{base}/api/v1/accounts/ACCOUNT_ID/photo" \
  -H "X-API-Key: KEY" \
  -F "photo=@profile.jpg"

Option 2: Server path

Copycurl -X POST "{base}/api/v1/accounts/ACCOUNT_ID/photo" \
  -H "X-API-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{"photo_path": "/path/to/photo.jpg"}'

DELETE /api/v1/accounts/{id}/photo

Delete all profile photos for a Telegram account.

Copycurl -X DELETE "{base}/api/v1/accounts/ACCOUNT_ID/photo" -H "X-API-Key: KEY"

Legacy Session-Compatible Endpoints

GET /api/accounts

Returns raw Telegram account objects for the authenticated user. Admins see all accounts.

Copycurl "https://tgautomation.org/api/accounts" -H "X-API-Key: KEY"

GET /api/templates   POST

List and create message templates.

Copy# List
curl "https://tgautomation.org/api/templates" -H "X-API-Key: KEY"

# Create
curl -X POST "https://tgautomation.org/api/templates" \
  -H "X-API-Key: KEY" -H "Content-Type: application/json" \
  -d '{"name":"My Template","content":"Hello {{name}}!"}'

GET /api/schedules   POST

List and create Telegram broadcast schedules (legacy dashboard format). Prefer /api/v1/broadcast for new integrations.

Copycurl "https://tgautomation.org/api/schedules" -H "X-API-Key: KEY"

GET /api/status

Returns a summary of connected accounts and active automations for the user.

Copycurl "https://tgautomation.org/api/status" -H "X-API-Key: KEY"

Error Responses

HTTP Status	Error	Meaning
401	{"error":"unauthorized"}	Missing or invalid API key
401	{"error":"Invalid or missing API key"}	API key not found or expired
403	{"error":"forbidden"}	Authenticated but not authorized (e.g., accessing another user's data)
400	{"error":"..."}	Bad request — missing or invalid parameter
404	{"error":"not found"}	Resource does not exist
500	{"error":"..."}	Internal server error

Limits

Limit	Value
Max targets per broadcast	50
Max message length	4096 characters
Supported platforms	telegram, whatsapp
Schedule types	now, interval, daily

Python Example

Copyimport requests

BASE = "https://tgautomation.org"
API_KEY = "your_api_key_here"
HEADERS = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

# Get accounts
accts = requests.get(f"{BASE}/api/v1/accounts", headers=HEADERS).json()
account_id = accts["accounts"][0]["id"]

# Get groups
groups = requests.get(f"{BASE}/api/v1/groups?platform=telegram", headers=HEADERS).json()
targets = [g["key"] for g in groups["groups"][:5]]

# Send broadcast
resp = requests.post(f"{BASE}/api/v1/broadcast", headers=HEADERS, json={
    "account_id": account_id,
    "target_keys": targets,
    "message": "Hello from Python!",
    "schedule_type": "now",
})
print(resp.json())

Analytics API

Auto-Reply Engine

Welcome / Goodbye Messages

Anti-Spam Module

A/B Testing

Drip Campaigns

Contact CRM

Webhooks

Reports / Export