آموزش ساخت ربات ایتا؛ از دریافت توکن تا اجرای ربات روی هاست

آموزش ساخت ربات ایتا با رویکرد عملی

ساخت ربات ایتا زمانی نتیجه قابل استفاده می‌دهد که پیش از نوشتن کد، دقیقاً مشخص کنید ربات قرار است چه کاری انجام دهد: پاسخ‌گویی خودکار، ثبت سفارش، دریافت اطلاعات مشتری، ارسال اعلان، اتصال به سایت یا هدایت کاربر به اپراتور. رباتی که فقط چند پیام ثابت ارسال می‌کند معمولاً خیلی زود به بن‌بست می‌رسد؛ اما اگر از ابتدا جریان کاربر، داده‌های موردنیاز و پنل مدیریت را طراحی کنید، می‌تواند به بخشی از فرایند فروش یا پشتیبانی تبدیل شود.

در این راهنما یک نمونه پایه با پایتون می‌سازیم که پیام‌های دریافتی را دریافت، فرمان‌های مشخص را پردازش و پاسخ ارسال می‌کند. سپس ساختار آن را برای ربات فروش، ثبت درخواست و اتصال به وب‌سرویس توسعه می‌دهیم. برای سناریوی متمرکز بر ارسال زمان‌بندی‌شده نیز راهنمای آموزش ساخت ربات ایتا و ارسال خودکار پیام به کانال یا گروه می‌تواند مکمل این مقاله باشد.

پیش‌نیازها و نکته مهم درباره API ایتا

قبل از شروع، باید بررسی کنید که حساب، نوع ربات و دسترسی مدنظر شما در نسخه فعلی پلتفرم ایتا چه قابلیت‌هایی دارد. روش ایجاد ربات، آدرس API، نام متدها، نوع احراز هویت و محدودیت‌های ارسال پیام ممکن است در طول زمان تغییر کند. بنابراین توکن و آدرس‌های نهایی را فقط از مسیر رسمی یا مستندات معتبر همان زمان دریافت کنید و هرگز توکن را در کد عمومی، اسکرین‌شات یا مخزن Git منتشر نکنید.

• یک حساب ایتا برای ایجاد و مدیریت ربات
• توکن یا کلید دسترسی ربات از مسیر رسمی
• Python 3.10 یا جدیدتر
• سرور یا هاست دارای امکان اجرای دائمی پایتون برای محیط عملیاتی
• دامنه و گواهی SSL در صورت استفاده از وب‌هوک
• ویرایشگر کد، مانند VS Code، و دسترسی SSH برای استقرار

اگر قبلاً با معماری ربات‌های پیام‌رسان کار کرده‌اید، ساختار کلی برایتان آشناست: پلتفرم یک رویداد یا پیام جدید را در اختیار برنامه شما می‌گذارد، برنامه متن و شناسه گفتگو را بررسی می‌کند و با یک درخواست API پاسخ می‌دهد. با این حال، نام فیلدهای داده و جزئیات endpoint را نباید از تلگرام یا روبیکا کپی کنید. برای مقایسه الگوی طراحی در پیام‌رسان‌های دیگر، آموزش ساخت ربات تلگرام با Python و آموزش ساخت ربات روبیکا با پایتون و پیام شیشه‌ای (دکمه تعاملی) مفید هستند.

مرحله اول: طراحی سناریوی ربات پیش از کدنویسی

به‌جای شروع با فرمان‌های تصادفی، یک سناریوی کوچک و قابل تست تعریف کنید. فرض کنید هدف، ثبت درخواست مشتری برای خرید یک خدمت است. کاربر /start را ارسال می‌کند، ربات منو را نشان می‌دهد، کاربر گزینه ثبت درخواست را انتخاب می‌کند، نام و شماره تماس را وارد می‌نماید و ربات یک کد پیگیری بازمی‌گرداند. در نسخه بعدی می‌توانید درخواست را در دیتابیس ذخیره و به مدیر اعلان دهید.

1. ورودی‌ها را فهرست کنید: متن، شماره سفارش، نام، شماره تماس یا انتخاب منو.
2. خروجی‌ها را مشخص کنید: پیام خوش‌آمد، راهنما، تأیید ثبت و ارجاع به اپراتور.
3. وضعیت‌های مکالمه را طراحی کنید: شروع، انتظار نام، انتظار تماس، پایان.
4. خطاها را تعیین کنید: پیام خالی، فرمان ناشناخته، شماره نامعتبر و قطع ارتباط API.
5. داده‌ای را که باید نگهداری شود مشخص کنید: شناسه کاربر، وضعیت مکالمه، زمان و متن درخواست.

این طراحی مانع از تبدیل شدن فایل اصلی به مجموعه‌ای از شرط‌های نامرتب می‌شود. در پروژه‌های جدی، بهتر است منوی ربات، متن پیام‌ها و تنظیمات مدیر از پنل یا فایل پیکربندی مدیریت شوند؛ نه اینکه برای تغییر یک جمله مجبور به ویرایش و استقرار مجدد کد باشید.

مرحله دوم: ساخت محیط پروژه پایتون

یک پوشه برای پروژه بسازید و محیط مجازی ایجاد کنید. استفاده از محیط مجازی باعث می‌شود وابستگی‌های ربات با سایر برنامه‌های سرور تداخل نداشته باشد.

mkdir eitaa-bot
cd eitaa-bot
python -m venv .venv
source .venv/bin/activate
pip install requests python-dotenv

در ویندوز معمولاً دستور فعال‌سازی محیط مجازی به شکل زیر است:

.venv\Scripts\activate

ساختار اولیه پروژه را ساده اما منظم نگه دارید:

eitaa-bot/
├── app.py
├── config.py
├── .env
├── .gitignore
├── requirements.txt
└── logs/

فایل .env محل مناسب نگهداری متغیرهای محرمانه در محیط توسعه است. این فایل نباید وارد Git شود.

EITAA_BOT_TOKEN=توکن_دریافتی_از_مسیر_رسمی
EITAA_API_BASE=https://API_BASE_FROM_OFFICIAL_DOCUMENTATION
ADMIN_CHAT_ID=شناسه_مدیر

و محتوای حداقلی فایل .gitignore:

.venv/
.env
__pycache__/
logs/

مرحله سوم: تنظیمات امن و ارسال پیام

چون جزئیات API باید با مستندات رسمی تطبیق داده شود، در کد زیر عمداً endpoint و نام پارامترها به‌صورت قابل تنظیم نوشته شده‌اند. پیش از اجرا، مقدار EITAA_API_BASE و مسیر متد ارسال پیام را با مستندات نسخه فعال ربات خود جایگزین کنید. ساختار نمونه نشان می‌دهد چگونه توکن را از کد جدا و خطای شبکه را مدیریت کنید.

import os
from dotenv import load_dotenv

load_dotenv()

BOT_TOKEN = os.getenv("EITAA_BOT_TOKEN")
API_BASE = os.getenv("EITAA_API_BASE")
ADMIN_CHAT_ID = os.getenv("ADMIN_CHAT_ID")

if not BOT_TOKEN or not API_BASE:
    raise RuntimeError("متغیرهای EITAA_BOT_TOKEN و EITAA_API_BASE تنظیم نشده‌اند.")

در فایل app.py یک تابع مستقل برای ارسال پیام بسازید. اگر مستندات پلتفرم از قالب JSON استفاده می‌کند، نمونه زیر مناسب است؛ در غیر این صورت نوع درخواست و payload را مطابق همان مستندات تغییر دهید.

import logging
import requests
from config import BOT_TOKEN, API_BASE

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(levelname)s - %(message)s"
)


def send_message(chat_id, text):
    url = f"{API_BASE}/sendMessage"
    payload = {
        "token": BOT_TOKEN,
        "chat_id": chat_id,
        "text": text
    }

    try:
        response = requests.post(url, json=payload, timeout=15)
        response.raise_for_status()
        return response.json()
    except requests.RequestException as error:
        logging.exception("خطا در ارسال پیام: %s", error)
        return None

در یک پروژه واقعی، متن خطای کامل API را در لاگ خصوصی ذخیره کنید، اما آن را بدون بررسی برای کاربر ارسال نکنید. پاسخ خطا ممکن است شامل اطلاعات فنی یا شناسه‌های داخلی باشد.

مرحله چهارم: پردازش فرمان‌ها و پیام‌های کاربر

منطق ربات را در تابعی جدا از لایه ارتباط با API بنویسید. این جداسازی تست و توسعه را آسان می‌کند. نمونه زیر برای هر پیام ورودی، فرمان‌های ساده را تشخیص می‌دهد. شکل دقیق داده ورودی، مانند محل قرارگیری شناسه گفتگو و متن پیام، باید با payload واقعی ایتا هماهنگ شود.

from app import send_message


def handle_update(update):
    message = update.get("message", {})
    chat_id = message.get("chat", {}).get("id")
    text = (message.get("text") or "").strip()

    if not chat_id:
        return

    if text in ["/start", "شروع"]:
        send_message(
            chat_id,
            "سلام. به ربات خوش آمدید.\n"
            "برای ثبت درخواست، عبارت «ثبت درخواست» را ارسال کنید.\n"
            "برای دریافت راهنما، عبارت «راهنما» را بنویسید."
        )
    elif text == "راهنما":
        send_message(chat_id, "درخواست خود را به‌صورت متن ارسال کنید تا ثبت شود.")
    elif text == "ثبت درخواست":
        send_message(chat_id, "لطفاً نام و توضیح کوتاه نیاز خود را در یک پیام ارسال کنید.")
    elif text:
        send_message(chat_id, "پیام شما دریافت شد. کد پیگیری پس از ثبت درخواست ارسال می‌شود.")
    else:
        send_message(chat_id, "لطفاً یک پیام متنی ارسال کنید.")

این نسخه هنوز وضعیت مکالمه را ذخیره نمی‌کند. برای ربات فروش یا پشتیبانی، ذخیره وضعیت در Redis، SQLite، PostgreSQL یا یک سرویس دیتابیس ضروری است. نگهداری وضعیت در یک متغیر پایتون فقط برای تست کوتاه مناسب است، زیرا با ری‌استارت برنامه از بین می‌رود و در اجرای چندپردازشی هم قابل اعتماد نیست.

مرحله پنجم: انتخاب بین Long Polling و Webhook

Long Polling برای شروع و تست

در polling، برنامه شما در بازه‌های زمانی مشخص از API می‌پرسد آیا پیام جدیدی وجود دارد یا نه. راه‌اندازی آن در محیط توسعه ساده است، اما باید offset یا شناسه آخرین رویداد را درست نگهداری کنید تا یک پیام چند بار پردازش نشود. اگر API ایتا متد دریافت update ارائه می‌کند، منطق کلی به صورت زیر خواهد بود:

import time
import requests
from handler import handle_update
from config import BOT_TOKEN, API_BASE

last_offset = None

while True:
    params = {"token": BOT_TOKEN, "timeout": 25}
    if last_offset is not None:
        params["offset"] = last_offset

    try:
        response = requests.get(f"{API_BASE}/getUpdates", params=params, timeout=35)
        response.raise_for_status()
        data = response.json()

        for update in data.get("result", []):
            handle_update(update)
            last_offset = update.get("update_id", last_offset) + 1
    except requests.RequestException:
        time.sleep(5)

Webhook برای اجرای عملیاتی

در webhook، پلتفرم رویداد را به یک URL امن در سرور شما ارسال می‌کند. این روش برای رباتی که باید همیشه فعال باشد مناسب‌تر است. به دامنه دارای HTTPS، مسیر مشخص و اعتبارسنجی درخواست نیاز دارید. توکن را در URL قرار ندهید. اگر پلتفرم امضای درخواست، secret token یا IPهای معتبر ارائه می‌کند، حتماً آن‌ها را اعتبارسنجی کنید.

from flask import Flask, request, jsonify
from handler import handle_update

app = Flask(__name__)

@app.post("/webhook/eitaa")
def eitaa_webhook():
    update = request.get_json(silent=True)
    if not update:
        return jsonify({"ok": False}), 400

    handle_update(update)
    return jsonify({"ok": True}), 200

if __name__ == "__main__":
    app.run(host="127.0.0.1", port=5000)

برای اجرای وب‌هوک، Flask را مستقیم در اینترنت عمومی قرار ندهید. آن را پشت Nginx یا reverse proxy اجرا کنید و با Gunicorn یا سرویس مشابه مدیریت نمایید. اگر پروژه به زیرساخت بدون سرور نیاز دارد، الگوی اجرای وب‌هوک در آموزش ساخت ربات تلگرام با Cloudflare Workers بدون نیاز به هاست (راهنمای کامل ۲۰۲۶) به درک معماری event-driven کمک می‌کند، هرچند endpoint و سازوکار ایتا باید جداگانه بررسی شود.

مرحله ششم: ثبت درخواست در دیتابیس و اعلان به مدیر

یک ربات کاربردی نباید فقط بگوید «پیام شما دریافت شد». باید پیام را با شناسه کاربر، زمان، وضعیت و کد پیگیری ذخیره کند. در نسخه ابتدایی می‌توانید از SQLite استفاده کنید؛ اما برای ترافیک بالاتر، چند اپراتور یا اتصال به سایت، PostgreSQL گزینه مناسب‌تری است.

import sqlite3
from datetime import datetime


def save_request(chat_id, text):
    connection = sqlite3.connect("bot.db")
    cursor = connection.cursor()
    cursor.execute("""
        CREATE TABLE IF NOT EXISTS requests (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            chat_id TEXT NOT NULL,
            message TEXT NOT NULL,
            status TEXT NOT NULL,
            created_at TEXT NOT NULL
        )
    """)
    cursor.execute(
        "INSERT INTO requests (chat_id, message, status, created_at) VALUES (?, ?, ?, ?)",
        (str(chat_id), text, "new", datetime.utcnow().isoformat())
    )
    request_id = cursor.lastrowid
    connection.commit()
    connection.close()
    return request_id

پس از ذخیره، کد پیگیری را به کاربر بدهید و خلاصه درخواست را برای مدیر ارسال کنید. در مرحله بعد، مدیر می‌تواند از یک پنل وب وضعیت درخواست را به «در حال بررسی»، «تکمیل‌شده» یا «نیازمند تماس» تغییر دهد. این همان نقطه‌ای است که ربات از یک پاسخ‌گوی ساده به اتوماسیون فروش و پشتیبانی تبدیل می‌شود.

استقرار روی هاست و اجرای دائمی

برای رباتی که باید ۲۴ ساعته کار کند، اجرای دستی با ترمینال کافی نیست. روی سرور لینوکسی، سرویس systemd انتخاب رایجی است. ابتدا وابستگی‌ها را ثبت کنید:

pip freeze > requirements.txt

سپس فایل سرویس بسازید. مسیرها را با مسیر واقعی کاربر و پروژه خود جایگزین کنید.

[Unit]
Description=Eitaa Bot Service
After=network.target

[Service]
User=ubuntu
WorkingDirectory=/home/ubuntu/eitaa-bot
EnvironmentFile=/home/ubuntu/eitaa-bot/.env
ExecStart=/home/ubuntu/eitaa-bot/.venv/bin/python /home/ubuntu/eitaa-bot/polling.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

بعد از ذخیره فایل در مسیر مناسب systemd، سرویس را فعال و لاگ‌ها را بررسی کنید:

sudo systemctl daemon-reload
sudo systemctl enable eitaa-bot
sudo systemctl start eitaa-bot
sudo systemctl status eitaa-bot
journalctl -u eitaa-bot -f

اگر هدف شما پیاده‌سازی ربات‌های چندپیام‌رسان با سناریوی یکسان است، از همان ابتدا لایه «منطق کسب‌وکار» را از لایه API جدا کنید. نمونه‌های مرتبط با معماری و سناریونویسی را در آموزش ساخت سورس ربات روبیکا؛ از طراحی سناریو تا اجرا روی هاست نیز می‌توانید بررسی کنید.

خطاهای رایج و روش عیب‌یابی

• توکن نامعتبر یا منقضی: مقدار متغیر محیطی را بررسی کنید، فاصله ابتدا و انتهای توکن را حذف کنید و در صورت نیاز توکن جدید بسازید.
• ربات پیام را دریافت نمی‌کند: وضعیت webhook یا polling، دسترسی ربات به گفتگو و ساختار payload ورودی را بررسی کنید.
• ارسال پیام با خطای ۴۰۰ یا ۴۰۱: نام فیلدهای API، شناسه گفتگو، روش ارسال توکن و endpoint را با مستندات رسمی تطبیق دهید.
• پردازش تکراری سفارش: شناسه یکتای update را ذخیره کنید و قبل از ثبت، بررسی کنید قبلاً پردازش نشده باشد.
• قطع شدن ربات پس از خروج SSH: برنامه را با systemd، Supervisor یا سازوکار مدیریت فرایند اجرا کنید؛ screen راه‌حل عملیاتی پایدار نیست.
• افشای اطلاعات کاربران: لاگ‌ها را محدود کنید، داده حساس را رمزنگاری یا ماسک کنید و دسترسی دیتابیس را فقط به سرویس لازم بدهید.

چک‌لیست تحویل ربات ایتا

1. سناریوی کاربر و پیام‌های خطا مستند شده‌اند.
2. توکن در متغیر محیطی نگهداری می‌شود و در سورس قرار ندارد.
3. ارسال و دریافت پیام در یک گفتگوی آزمایشی تست شده است.
4. درخواست‌ها با شناسه و زمان در دیتابیس ذخیره می‌شوند.
5. خطاهای API و خطاهای برنامه در لاگ قابل پیگیری هستند.
6. ربات بعد از ری‌استارت سرور به‌صورت خودکار بالا می‌آید.
7. بکاپ دیتابیس، راهنمای نصب و اطلاعات استقرار در مستندات تحویل وجود دارد.
8. برای تغییر منو، متن‌ها و اپراتورها مسیر مدیریتی مشخص شده است.

اگر ربات شما قرار است فروش، پرداخت، تحویل فایل، صدور دسترسی یا اتصال به سایت را انجام دهد، مرحله بعد طراحی پنل مدیریت و API یکپارچه است. در چنین پروژه‌ای، ربات فقط یک کانال گفتگو است و منبع اصلی داده باید یک بک‌اند قابل توسعه باشد. برای بررسی راهکارهای اجرایی در پیام‌رسان‌های داخلی می‌توانید صفحه ربات روبیکا و ایتا را ببینید.

جمع‌بندی

ساخت ربات ایتا با دریافت توکن و ارسال یک پیام آغاز می‌شود، اما ربات قابل تحویل به طراحی سناریو، مدیریت امن تنظیمات، ذخیره‌سازی داده، لاگ‌گیری، استقرار پایدار و تست خطا نیاز دارد. ابتدا نسخه کوچک و قابل تست بسازید، سپس ثبت درخواست، اعلان مدیر، پنل مدیریت و اتصال به سایت را مرحله‌به‌مرحله اضافه کنید. این مسیر هم نگهداری پروژه را ساده‌تر می‌کند و هم مانع از بازنویسی پرهزینه ربات پس از افزایش کاربران می‌شود.

مطالب مرتبط

• آموزش ساخت ربات بله از صفر تا صد (۲۰۲۶) | راهنمای گام‌به‌گام