الرسائل عبر Telegram

18.1 البوت: حساب تقوده اللوحة – בוט ויצירתו (Bots and BotFather)

البوت (בוט) هو حساب في Telegram يكتب فيه برنامج بدلا من إنسان. ولأن اللوحة هي التي تبدأ كل اتصال، فلا نحتاج إلى عنوان عام ولا إلى تغيير في الموجّه: الطلب الخارج يمر كما يمر طلب الهاتف.

ننشئ البوت من الهاتف، دون أي برمجة:

1. نفتح في Telegram المحادثة مع @BotFather، وهو البوت الرسمي لإدارة البوتات.
2. نرسل الأمر /newbot. يسألنا عن اسم للعرض، ثم عن اسم مستخدم يجب أن ينتهي بـbot.
3. يردّ علينا بالرمز. ننسخه فورا إلى secrets.py، ولا نلصقه في أي مكان آخر.
4. نفتح المحادثة مع البوت الجديد ونضغط Start، ثم نرسل له أي رسالة.

18.2 الرمز كلمة مرور – הטוקן הוא סיסמה

من يملك الرمز يملك البوت: يقرأ ما يصله من رسائل، ويرسل باسمه، ويأمر لوحتنا بما يشاء. لا يوجد اسم مستخدم ولا سؤال إضافي، فالرمز وحده يكفي. لذلك نعامله كما نعامل كلمة مرور WiFi: مكانه الوحيد سطر في secrets.py.

WIFI_SSID = "my-network"
WIFI_PASS = "my-password"
TELEGRAM_TOKEN = "123:TEST"

• البرنامج يستورد الاسم فقط: from secrets import TELEGRAM_TOKEN. فنستطيع مشاركة البرنامج كله دون أن نشارك الرمز.
• الملف secrets.py لا يذهب إلى GitHub ولا إلى مجلد مشترك ولا إلى صورة شاشة ترسل إلى صديق.
• الرمز جزء من عنوان الطلب. فإذا طبعنا العنوان للفحص، صار الرمز مكتوبا في السجل. لذلك لا نطبع API أبدا.

ماذا نفعل إذا تسرّب الرمز؟ بهذا الترتيب:

1. نلغي الرمز فورا عند BotFather: نرسل الأمر /token ونختار البوت، فيعطينا رمزا جديدا. وتوثيق Telegram يذكر هذا الأمر للرمز المتسرّب، وفي قائمة أوامر BotFather نجد أيضا /revoke.
2. نضع الرمز الجديد في secrets.py على كل لوحة تستعمله.
3. نفحص أن الرمز القديم لم يعد يعمل: طلب به يجب أن يُرفض.
4. نبحث عن مصدر التسرّب ونغلقه. وإذا كان الرمز قد دخل مستودع شيفرة، فهو باقٍ في تاريخه حتى بعد حذف السطر.

18.3 إرسال رسالة – שליחת הודעה (sendMessage)

كل أوامر البوت طلبات HTTPS إلى عنوان واحد الشكل: https://api.telegram.org/bot<TOKEN>/METHOD. والرد نص JSON فيه الحقل ok، ومعه result عند النجاح أو description عند الفشل.

import time
import network
import requests
from secrets import WIFI_SSID, WIFI_PASS, TELEGRAM_TOKEN

CHAT = 555
API = "https://api.telegram.org/bot" + TELEGRAM_TOKEN

wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.disconnect()
wlan.connect(WIFI_SSID, WIFI_PASS)
while not wlan.isconnected():
    time.sleep(0.5)

r = requests.post(API + "/sendMessage",
                  json={"chat_id": CHAT, "text": "board is up"})
reply = r.json()
if reply["ok"]:
    print(r.status_code, reply["ok"], reply["result"]["message_id"])
else:
    print(r.status_code, reply["description"])
r.close()

200 True 7
[http_sent]
POST https://api.telegram.org/bot123:TEST/sendMessage {'text': 'board is up', 'chat_id': 555}

نرسل البيانات بالمعامل json=، فتتولى المكتبة تحويلها إلى نص JSON، ولا نحتاج إلى ترميز المسافات في العنوان. ولا ننسى r.close(): من دونه يبقى الاتصال مفتوحا والذاكرة محجوزة.

والآن نرى ما يحدث بعد إلغاء الرمز. الخادم يردّ بالرمز 401، فيعرف البرنامج أن الرمز غير صالح:

from secrets import TELEGRAM_TOKEN
from tgbot import Bot

bot = Bot(TELEGRAM_TOKEN)
code = bot.send(555, "still working?")
print("status", code)
if code == 401:
    print("token rejected: put the new one in secrets.py")

status 401
token rejected: put the new one in secrets.py

18.4 استقبال الأوامر – קבלת פקודות (getUpdates)

الخادم لا يستطيع الاتصال باللوحة، فهو يحتفظ بكل رسالة حتى تسأل عنها. كل رسالة تصل هي تحديث (עדכון) له رقم update_id، والسؤال المتكرر اسمه الاستطلاع (תשאול). لنكتب أبسط برنامج ممكن:

import time
import requests
from secrets import TELEGRAM_TOKEN

API = "https://api.telegram.org/bot" + TELEGRAM_TOKEN

for i in range(3):
    r = requests.get(API + "/getUpdates")
    data = r.json()
    r.close()
    if not data["ok"]:
        print(data["description"])
        break
    for u in data["result"]:
        print("poll", i, u["update_id"], u["message"]["text"])
    time.sleep(5)

poll 0 100 /on
poll 1 100 /on
poll 2 100 /on

السبب أن الخادم لا يعرف أننا عالجنا الرسالة. نخبره بذلك بالمعامل offset:

import time
import requests
from secrets import TELEGRAM_TOKEN

API = "https://api.telegram.org/bot" + TELEGRAM_TOKEN
offset = 0

for i in range(3):
    r = requests.get("%s/getUpdates?offset=%d" % (API, offset))
    data = r.json()
    r.close()
    if not data["ok"]:
        print(data["description"])
        break
    print("poll", i, "new:", len(data["result"]))
    for u in data["result"]:
        offset = u["update_id"] + 1
        m = u["message"]
        print(" ", m["chat"]["id"], m["text"])
    time.sleep(5)

poll 0 new: 2
  555 /on
  555 /light
poll 1 new: 1
  555 /off
poll 2 new: 0

18.5 بوت يقرأ حسّاسا ويشغّل ثنائيا – בוט שמחזיר קריאת חיישן ומפעיל נורית

نجمع الطلبات في مكتبة صغيرة، فيبقى البرنامج الرئيسي واضحا. وهي تأخذ الرمز من البرنامج، ولا تعرف قيمته:

# tgbot.py - a small Telegram bot client over HTTPS.
# The token comes from secrets.py. Never print self.api: it holds the token.
# (c) 2026 Fahed Ghanem - MIT License - fahed-lab.com
import time

import requests


class Bot:
    def __init__(self, token):
        self.api = "https://api.telegram.org/bot" + token
        self.offset = 0

    def send(self, chat, text):
        r = requests.post(self.api + "/sendMessage",
                          json={"chat_id": chat, "text": text})
        code = r.status_code
        r.close()
        return code

    def updates(self):
        url = "%s/getUpdates?offset=%d" % (self.api, self.offset)
        r = requests.get(url)
        code = r.status_code
        data = r.json()
        r.close()
        if code != 200:
            raise OSError(code)
        found = []
        for u in data["result"]:
            self.offset = u["update_id"] + 1
            m = u.get("message")
            if m and "text" in m:
                found.append((m["chat"]["id"], m["text"]))
        return found

import time
from machine import Pin
import board
from convert import to_percent
from secrets import TELEGRAM_TOKEN
from tgbot import Bot
import wifi

MY_CHAT = 555
POLL_S = 10

led = Pin(board.LED, Pin.OUT)
ldr = board.analog_in(board.LDR)
bot = Bot(TELEGRAM_TOKEN)


def answer(cmd):
    if cmd == "/light":
        return "light %d %%" % to_percent(ldr.read_u16())
    if cmd == "/on":
        led.on()
        return "LED on"
    if cmd == "/off":
        led.off()
        return "LED off"
    return "use /light /on /off"


wifi.connect()
while True:
    try:
        for chat, text in bot.updates():
            if chat != MY_CHAT:
                print("ignored", chat, text)
                continue
            reply = answer(text)
            print(text, "->", reply, "| led", led.value())
            bot.send(chat, reply)
    except OSError as e:
        print("network error", e)
    time.sleep(POLL_S)

/light -> light 40 % | led 0
/on -> LED on | led 1
ignored 999 /off
/light -> light 70 % | led 1
hello -> use /light /on /off | led 1
network error -202
network error -202
...

18.6 كم مرة نسأل؟ – לא לבקש בכל שנייה (Polling Rate)

كل طلب HTTPS في مكتبة requests يفتح اتصالا جديدا، مع مصافحة تشفير تستهلك زمنا وذاكرة، وخلالها لا يفعل البرنامج شيئا آخر. ولذلك لا نسأل في كل ثانية.

• لأمر ينتظره إنسان يكفي ما بين 5 و10 ثوانٍ. ولتنبيه يأتي من اللوحة لا نحتاج إلى الاستطلاع أصلا: نرسل عند الحدث فقط.
• حسب توثيق Telegram: لا نرسل أكثر من رسالة واحدة في الثانية إلى المحادثة نفسها. ومن يتجاوز ذلك باستمرار يتلقّى خطأ بالرمز 429.
• في getUpdates معامل اسمه timeout يجعل الخادم يُبقي الطلب مفتوحا حتى تصل رسالة. هذا يوفّر طلبات، لكن اللوحة تبقى محجوبة طوال الانتظار. سنرى في الفصل 19 لماذا يهمّنا هذا.

أهمّ أفكار الفصل:

• اللوحة هي التي تبدأ الاتصال، ولذلك يعمل البوت من خلف الموجّه دون أي إعداد.
• الرمز كلمة مرور: مكانه secrets.py، ولا يُطبع ولا يُشارَك. وإذا تسرّب نلغيه عند BotFather أولا.
• الإرسال طلب sendMessage، والاستقبال استطلاع بالأمر getUpdates.
• من دون offset = آخر رقم + 1 تعود الرسالة نفسها في كل مرة.
• البوت يفحص معرّف المحادثة قبل أن ينفّذ أي أمر.
• الاستطلاع كل بضع ثوانٍ يكفي، وانقطاع الشبكة يُعالَج ولا يوقف البرنامج.

أوامر الفصل:

قاموس المصطلحات – מילון מונחים:

أسئلة للتمرين:

ALLOWED = (555, 777)

for chat, text in bot.updates():
    if chat not in ALLOWED:
        continue
    bot.send(chat, answer(text))

import time
import board
from convert import to_percent
from secrets import TELEGRAM_TOKEN
from tgbot import Bot

MY_CHAT = 555
ldr = board.analog_in(board.LDR)
bot = Bot(TELEGRAM_TOKEN)
dark = False

while True:
    level = to_percent(ldr.read_u16())
    if level < 20 and not dark:
        dark = True
        bot.send(MY_CHAT, "it is dark: %d %%" % level)
    elif level > 30:
        dark = False
    time.sleep(10)