تطوير البوتات

مرجع Bot API

جمعنا هنا كل الطرق التي تقبلها واجهة HTTP Bot API في Pabal، والكائنات التي تتبادلها، والأخطاء، دون استثناء. وهي متوافقة مع Bot API الخاصة بـ Telegram.

تستخدم واجهة HTTP Bot API في Pabal صيغة العناوين والطلبات والاستجابات والأخطاء نفسها المستخدمة في Telegram Bot API. ولا يذكر هذا المستند إلا ما يقبله Pabal فعلاً، والطرق غير المذكورة هنا تعيد 404 Not Found: method not found. وإن كانت هذه أول مرة لك، فابدأ بـدرس إنشاء بوت.

إرسال الطلبات

https://pabal.me/bot<token>/<method>

• فعل HTTP: يعمل GET وPOST كلاهما.
• المعاملات تُرسل بإحدى أربع طرق — سلسلة الاستعلام (?chat_id=1&text=hi)، وapplication/x-www-form-urlencoded، وapplication/json، وmultipart/form-data عند رفع الملفات. ويمكنك المزج بينها.
• المعاملات التي هي كائنات (reply_markup، commands، allowed_updates) تُمرَّر كما هي كائناتٍ ومصفوفاتٍ في جسم JSON، وكسلسلة JSON في النموذج أو سلسلة الاستعلام.
• أسماء الطرق لا تميّز بين الأحرف الكبيرة والصغيرة (sendMessage = sendmessage).
• حجم الجسم حتى 12MB (وإذا تجاوزه فالنتيجة 413).
• تنزيل الملفات له عنوان منفصل: https://pabal.me/file/bot<token>/<file_path> (getFile).

الاستجابات والأخطاء

الاستجابة دائماً بصيغة JSON. عند النجاح تصل HTTP 200 مع result، وعند الفشل تصل حالة HTTP المعنية مع error_code مطابق لها، وdescription يقرؤه البشر.

{"ok": true, "result": { … }}

{"ok": false, "error_code": 400, "description": "Bad Request: chat not found"}

لا يفرض Pabal حالياً حداً لمعدل الطلبات كلها، لكن لطرق الصوت حدوداً في الساعة، فقد يصلك 429 Too Many Requests: retry after N (المكالمات الصوتية). اكتب شيفرتك بحيث إذا استلمت 429 انتظرت parameters.retry_after ثانية ثم أعادت الإرسال.

استلام التحديثات

استخدم إحدى الطريقتين، إذ لا يمكن استخدامهما معاً.

getUpdates

POST/bot<token>/getUpdates

تجلب التحديثات المنتظرة (الاستطلاع الطويل). وإذا كان webhook مضبوطاً فالنتيجة 409.

القيمة المعادة: Array of Update

setWebhook

POST/bot<token>/setWebhook

لاستلام التحديثات على عنوان HTTPS. والشرح المفصّل في مستند Webhook.

القيمة المعادة: True

deleteWebhook

POST/bot<token>/deleteWebhook

تحذف webhook وتعود إلى getUpdates. وتنجح حتى لو لم يكن هناك webhook.

القيمة المعادة: True

getWebhookInfo

GET/bot<token>/getWebhookInfo

حالة webhook. بلا معاملات. وإذا لم يكن هناك webhook فإن url سلسلة فارغة.

القيمة المعادة: WebhookInfo

الطرق

getMe

GET/bot<token>/getMe

تُستخدم للتحقق من صحة الرمز المميّز. بلا معاملات.

القيمة المعادة: User — ويُضاف للبوت can_join_groups (true)، وcan_read_all_group_messages (true)، وsupports_inline_queries (false)، وcan_connect_to_business (false)، وhas_main_web_app (false).

sendMessage

POST/bot<token>/sendMessage

القيمة المعادة: الرسالة المرسلة Message

للإرسال إلى شخص يجب أن يكون هو من بدأ المحادثة مع البوت (403 Forbidden: bot can't initiate conversation with a user). وللإرسال إلى مجموعة يجب أن يكون البوت عضواً فيها.

sendPhoto

POST/bot<token>/sendPhoto

القيمة المعادة: الرسالة المرسلة Message (مع file_id جديد في photo)

sendDocument

POST/bot<token>/sendDocument

القيمة المعادة: الرسالة المرسلة Message (مع file_id جديد في document)

يُستنتج النوع (mime_type) من امتداد اسم الملف. والملفات المرسلة من جهة التطبيق تصل إلى 2GB، أما ما يرفعه البوت أو ينزّله عبر HTTP فحدّه 20MB كما في Telegram.

sendLocation

POST/bot<token>/sendLocation

القيمة المعادة: الرسالة المرسلة Message (مع Location في location)

sendVenue

POST/bot<token>/sendVenue

القيمة المعادة: الرسالة المرسلة Message (مع Venue في venue، والنقطة نفسها في location)

بدون title أو address تكون النتيجة 400 Bad Request: title and address are required.

sendContact

POST/bot<token>/sendContact

القيمة المعادة: الرسالة المرسلة Message (مع Contact في contact)

بطاقة جهة الاتصال التي يرسلها بوت لا تحمل user_id أبداً، حتى لو كان الرقم لحساب في Pabal — فالبوت ليست له جهات اتصال، ولو مُلئ هذا الحقل لاستطاع البوت أن يعرف صاحب أي رقم بإرسال بطاقة لكل رقم. وبدون phone_number أو first_name تكون النتيجة 400 Bad Request: phone_number and first_name are required.

editMessageLiveLocation

POST/bot<token>/editMessageLiveLocation

القيمة المعادة: الرسالة المعدّلة Message

الموقع المباشر الذي انتهى بالفعل — بإيقافه أو بانقضاء مدته — لا يمكن تحديث موضعه ولا إحياؤه بتمديد مدته (400 Bad Request: message can't be edited). والأمر نفسه للرسالة التي ليست موقعاً مباشراً.

الحركة التي تأتي بعد أقل من 10 ثوانٍ من آخر حركة طُبِّقت، أو التي تقل عن 10 أمتار، يتجاوزها الخادم دون حفظها. أما الإيقاف وتغيير المدة أو نصف قطر التنبيه فتُطبَّق دائماً. وعند تجاوز حركة ما، تُظهر الرسالة Message المعادة آخر موضع طُبِّق، لذا لا بأس بإرسال حركة كل بضع ثوانٍ.

stopMessageLiveLocation

POST/bot<token>/stopMessageLiveLocation

المعاملات: chat_id، وmessage_id، وreply_markup (اختياري). يوقف الموقع المباشر عند آخر موضع له. تُختصر مدة المشاركة إلى الوقت الذي مضى فعلاً، فتعرضه كل التطبيقات موقعاً منتهياً. وإذا كان قد أُوقف أو انتهى من قبل فالنتيجة 400 Bad Request: message is not modified: …. القيمة المعادة: الرسالة المعدّلة Message.

editMessageText

POST/bot<token>/editMessageText

القيمة المعادة: الرسالة المعدّلة Message. ينعكس التعديل فوراً في التطبيق، والرسائل التي يعدّلها الأشخاص تصل إلى البوت على شكل edited_message.

إذا كان النص والأزرار مطابقين لما سبق فالنتيجة 400 Bad Request: message is not modified: …، وإذا حاولت تعديل رسالة غيرك فالنتيجة 400 Bad Request: message can't be edited.

editMessageCaption

POST/bot<token>/editMessageCaption

المعاملات: chat_id، وmessage_id، وcaption (من 0 إلى 1,024 حرفاً، وحذفه يمسح الوصف)، وreply_markup. القيمة المعادة: الرسالة المعدّلة Message.

editMessageReplyMarkup

POST/bot<token>/editMessageReplyMarkup

تُبقي النص كما هو وتغيّر الأزرار فقط. المعاملات: chat_id، وmessage_id، وreply_markup (حذفه يمسح الأزرار). القيمة المعادة: الرسالة المعدّلة Message.

deleteMessage

POST/bot<token>/deleteMessage

المعاملات: chat_id، وmessage_id. تحذف الرسالة من طرفي المحادثة. وإذا لم تكن الرسالة موجودة فالنتيجة 400 Bad Request: message to delete not found. القيمة المعادة: True.

answerCallbackQuery

POST/bot<token>/answerCallbackQuery

ترد على زر ضغطه شخص (CallbackQuery). ويمكنك الرد خلال 10 ثوانٍ ومرة واحدة فقط.

القيمة المعادة: True. وإذا تأخرت كثيراً أو كنت قد رددت من قبل فالنتيجة 400 Bad Request: query is too old and response timeout expired or query ID is invalid.

sendChatAction

POST/bot<token>/sendChatAction

تُقبل للتوافق وتعيد True، لكنها لا تُظهر بعدُ «يكتب الآن…» في التطبيق.

getChat

GET/bot<token>/getChat?chat_id=…

المعامل: chat_id (رقم). إذا كان شخصاً فذلك الشخص، وإذا كانت مجموعة فلا يشمل إلا المجموعات التي البوت عضو فيها. القيمة المعادة: Chat. وإذا لم تكن موجودة أو لم يكن مسموحاً برؤيتها فالنتيجة 400 Bad Request: chat not found.

getFile

GET/bot<token>/getFile?file_id=…

تحصل بواسطة file_id لصورة مستلمة على مسار تنزيلها. القيمة المعادة: File. ثم تنزّلها من هذا العنوان.

https://pabal.me/file/bot<token>/<file_path>

وfile_id هو أيضاً إذن بالحصول على تلك الصورة. وإذا كانت القيمة خاطئة فالنتيجة 400 Bad Request: wrong file identifier/HTTP URL specified.

setMyCommands

POST/bot<token>/setMyCommands

القيمة المعادة: True. وإذا خالفت القائمة القواعد فلا يُحفظ شيء: 400 Bad Request: BOT_COMMAND_INVALID (أمر)، BOT_COMMAND_DESCRIPTION_INVALID (وصف فارغ أو يتجاوز 256 حرفاً)، BOT_COMMANDS_TOO_MUCH (أكثر من 100).

getMyCommands

GET/bot<token>/getMyCommands

المعامل: language_code (اختياري). القيمة المعادة: Array of BotCommand.

deleteMyCommands

POST/bot<token>/deleteMyCommands

المعامل: language_code (اختياري). تُفرغ تلك القائمة. القيمة المعادة: True.

logOut · close

في Telegram تُستخدم هاتان الطريقتان عند الانتقال إلى خادم Bot API محلي. وبما أنه لا يوجد في Pabal مكان يُنتقل إليه، فهما تُقبلان فقط وتعيدان True. ولإبطال الرمز المميّز استخدم الأمر /revoke لدى BotFather.

الكائنات

تعني اختياري بجانب الحقل أنه قد لا يكون موجوداً. أما حقول Telegram الأخرى غير المذكورة هنا فلا يرسلها Pabal.

Update

تحديث جديد واحد. يحتوي على update_id وواحد من الحقول أدناه.

User

Chat

Message

MessageEntity

يستخرجها الخادم من النص تلقائياً ويضيفها. أما كيانات التنسيق مثل الغامق والمائل فغير موجودة بعد.

PhotoSize

Document

Location

الموقع المباشر الذي يشاركه شخص ما يصل من جديد على شكل edited_message في كل مرة يطبّق فيها الخادم حركة.

Venue

Contact

File

CallbackQuery

InlineKeyboardMarkup

inline_keyboard: Array of Array of InlineKeyboardButton — المصفوفة الخارجية هي الصفوف، والداخلية هي أزرار الصف الواحد. والحد الأقصى 100 صف و100 زر في الرسالة الواحدة.

InlineKeyboardButton

الأنواع الأخرى مثل switch_inline_query وweb_app وlogin_url وpay غير متاحة بعد (400).

ReplyKeyboardMarkup

KeyboardButton

سلسلة نصية واحدة، أو كائن فيه text والحقلان الاختياريان request_contact (إرسال جهة اتصالي) وrequest_location (إرسال موقعي، Boolean).

ReplyKeyboardRemove

{"remove_keyboard": true} — يُخفي لوحة الأزرار. وselective اختياري.

ForceReply

{"force_reply": true} — يفتح التطبيق حقل الإدخال في وضع الرد على هذه الرسالة. وselective وinput_field_placeholder اختياريان.

BotCommand

WebhookInfo

المكالمات الصوتية

هذه طرق خاصة بـ Pabal وحده. البوت الصوتي بوت يرد فيه نموذج صوتي بالذكاء الاصطناعي عندما يتصل به شخص من التطبيق، وبهذه الطرق تضبط إعدادات ذلك النموذج وتتعامل مع المكالمات. وما يجب تفعيله وطريقة التفعيل والأمثلة في دليل البوتات الصوتية. والطرق موجودة حتى على الخوادم التي عُطّل فيها الصوت، فيمكنك قراءة الإعدادات، لكن إذا كان الصوت معطّلاً أو لم يسمح المشغّل للبوت بعد فلا يمكن تغيير أي إعداد سوى التعطيل والحذف (403 VOICE_NOT_AVAILABLE).

setVoiceCallSettings

POST/bot<token>/setVoiceCallSettings

تغيّر إعدادات الصوت للبوت. لا يتغيّر إلا ما أرسلته، ويُفحص الكل ثم يُكتب مرة واحدة أو يُرفض كله. ولكل بوت 30 مرة في الساعة (محسوبة مع @BotFather).

القيمة المعادة: True

getVoiceCallSettings

GET/bot<token>/getVoiceCallSettings

بلا معاملات. الإعدادات الحالية، وهل يستطيع البوت الآن استقبال المكالمات (available، unavailable_reason)، وحدود الخادم، وقوائم الأصوات واللغات، ووجهة استعلامات الأدوات ونص المحادثة، وحالة مفتاح المالك ووضع الصوت الخام وخوادم MCP. ولا تظهر المفاتيح والأسرار، بل بصماتها فقط. والحقول موضّحة في البوتات الصوتية — عرض الإعدادات الحالية.

القيمة المعادة: VoiceCallSettings (كائن)

endVoiceCall

POST/bot<token>/endVoiceCall

القيمة المعادة: True. وإذا لم تكن مكالمة جارية لهذا البوت فالنتيجة 400 VOICE_CALL_NOT_FOUND.

sendVoiceCallContext

POST/bot<token>/sendVoiceCallContext

القيمة المعادة: True. قبل الاتصال VOICE_CALL_NOT_ACTIVE، ولمكالمات الصوت الخام VOICE_CONTEXT_NOT_SUPPORTED، وللنص الطويل جداً VOICE_CONTEXT_TOO_LONG، وإذا تجاوزت 10 ملاحظات في الدقيقة للمكالمة الواحدة 429.

getVoiceCallUsage

GET/bot<token>/getVoiceCallUsage

القيمة المعادة: period، from_date، to_date، calls، seconds، missed، refused (busy·budget·unavailable)، platform_seconds، own_key_seconds، remaining_seconds_today (bot·owner)، وoutbound (today·limits) لبوت فعّل الاتصال ولو مرة — وحدود الأيام وفق المنطقة الزمنية للخادم

startVoiceCall

POST/bot<token>/startVoiceCall

يتصل البوت بشخص. لا يستطيع ذلك إلا بوت فعّل مالكه الميزة في @BotFather وراجعه المشغّل، ولا يتصل إلا بمن أذِن لذلك البوت. والردود وطريقة فحص الطلبات في البوتات الصوتية — الاتصال.

القيمة المعادة: {"voice_call_id": "…"} — تعني فقط أن الطلب استُلم؛ أما هل رنّ وهل ردّ أحد فيصل في تحديثات voice_call. والرفض: 403 VOICE_OUTBOUND_OFF: <reason>، و403 USER_UNAVAILABLE (المحتوى نفسه دائماً)، و429، و503 VOICE_UNAVAILABLE. ولا يمكن استدعاؤها من رد الـwebhook.

answerVoiceCallToolQuery

POST/bot<token>/answerVoiceCallToolQuery

القيمة المعادة: True. الرد الأول هو الأخير. وإذا تأخرت فالنتيجة 400 TOOL_QUERY_EXPIRED: answered|timeout|cancelled|call_ended|unreachable، وللمعرّف المجهول TOOL_QUERY_ID_INVALID، وإذا رُفض الرد TOOL_RESULT_EMPTY·TOOL_RESULT_INVALID·TOOL_RESULT_TOO_LONG·TOOL_ERROR_TOO_LONG·TOOL_RESULT_REFUSED: <code>. ويمكنك أيضاً الرد على POST استعلام الأداة الوارد عبر webhook في جسم الاستجابة.

setVoiceCallApiKey · deleteVoiceCallApiKey

POST/bot<token>/setVoiceCallApiKey

القيمة المعادة: True — ولا يُحفظ المفتاح إلا بعد اجتياز جلسة الاختبار في البوابة. API_KEY_INVALID، API_KEY_NO_REALTIME_ACCESS، 503 API_KEY_CHECK_UNAVAILABLE (لا يُحفظ)، 403 VOICE_OWN_KEY_NOT_AVAILABLE (هذا الخادم لا يقبل مفاتيح المالكين). وdeleteVoiceCallApiKey بلا معاملات ويعيد دائماً True. ولا يمكن استدعاء أيٍّ من الطريقتين عبر bots.sendCustomRequest، ولا يمكن استدعاء setVoiceCallApiKey عبر استجابة webhook أيضاً. والتفاصيل في مفتاح النموذج الخاص بالمالك.

طرق خوادم MCP

تُرسل auth والأسرار في جسم الطلب فقط. وعلى خادم عُطّلت فيه MCP تكون النتيجة 403 VOICE_NOT_AVAILABLE: MCP tools are not available on this server. والتفاصيل في البوتات الصوتية — خوادم MCP.

لاستلام تحديثات الصوت

voice_call وvoice_call_tool_query وvoice_call_transcript لا تصل إلا إذا طُلبت بأسمائها — اكتبها في allowed_updates الخاصة بـ getUpdates أو setWebhook. ولا تصل بالقائمة الفارغة، وما يقع قبل طلبها لا يُحفظ. وتصل استعلامات الأدوات في طلب POST منفصل إذا كان هناك webhook، وإذا استدعيت getUpdates خلال آخر 15 ثانية فإنها تأتي في مقدمة getUpdates التالي.

VoiceCall

لا يوجد في VoiceCall حقل يبيّن هل اختار المتصل الاحتفاظ بالمحادثة. وهذا مقصود — فذلك النص ملك المتصل ولا يصل إلى البوت. لذا على الخادم الذي فُعّل فيه الاحتفاظ بالمحادثة ينتظر ended المدة نفسها في كل المكالمات غير الصوت الخام، ويكون رقم الرسالة التالية لسجل المكالمة أكبر من رقم السجل بـ 31 على الأقل في كل المكالمات (لأن الأرقام محجوزة مسبقاً).

VoiceCallToolQuery

VoiceCallTranscript

لا يصل إلا عبر HTTP Bot API. والمكالمة كاملة في transcript الخاص بـ voice_call المنتهية.

وضع الصوت الخام (mode=stream)

في وضع الصوت الخام يذهب صوت المكالمة إلى خادم مالك البوت بدلاً من نموذج الذكاء الاصطناعي في Pabal. عندما ترسل إلى setVoiceCallSettings القيم mode=stream وstream_url=wss://… وstream_secret=… (من 32 إلى 128 حرف ASCII قابل للطباعة، في جسم الطلب فقط)، تحاول بوابة Pabal الاتصال بذلك العنوان مرة واحدة (فحص تجريبي)، وإذا نجحت يُفعَّل الوضع. ويلزم لذلك قبول شروط مالكي البوتات، وإصدار من التطبيق يتضمن نافذة تأكيد الصوت الخام. والإعداد ونتائج الفحص والأمثلة في البوتات الصوتية — وضع الصوت الخام.

• الاتصال: TLS 1.2 فأعلى، وشهادة عامة تطابق الاسم الوارد في URL، والبروتوكول الفرعي pabal.voice.v1، بلا ضغط، والرسالة الواحدة حتى 64KiB · والنصية حتى 4KiB، بلا إعادة توجيه.
• التوقيع: X-Pabal-Voice-Signature: t=…,nonce=…,call=…,v1=HMAC-SHA256(stream_secret, "pabal-voice-stream/1\n<t>\n<nonce>\n<call>\n<host>\n<path?query>"). وhost هو مضيف URL الذي أبلغت به. تحقّق من 300 ثانية · وnonce لمرة واحدة · والمقارنة بالبايتات · وتطابق start.call_id مع call (التفاصيل).
• الصوت: الرسائل النصية أحداث JSON، والثنائية PCM16 little-endian · أحادي القناة · 24 kHz. وصوت المتصل قطع طولها 20 ms (960 بايت).
• Pabal ← البوت: start (مرة واحدة) · live (انتهى إعلان الذكاء الاصطناعي) · الصوت · mark · cleared · buffer_full · stop (← إغلاق 1000).
• البوت ← Pabal: ready (خلال 3 ثوانٍ بعد start، وقبل أي شيء) · الصوت (بعد live) · clear · mark · hangup.

وشكل كل رسالة مفصّل في الجدول في البوتات الصوتية — المواصفة.

أخطاء طرق الصوت

جُمعت رموز أخطاء طرق الصوت ومعانيها في البوتات الصوتية — الأخطاء. وتأتي أخطاء 403 بالشكل Forbidden: <code>: <description> (VOICE_RULES_NOT_ACCEPTED، VOICE_NOT_AVAILABLE، VOICE_SUSPENDED، VOICE_OWNER_TERMS_NOT_ACCEPTED، VOICE_OWN_KEY_NOT_AVAILABLE، VOICE_STREAM_NOT_AVAILABLE، VOICE_OUTBOUND_OFF)، أما USER_UNAVAILABLE فيكون دائماً Forbidden: USER_UNAVAILABLE تماماً بلا وصف، وعند تجاوز الحد في الساعة تكون النتيجة 429 مع retry_after.

الاختلافات عن Telegram Bot API

• أنواع التحديثات: لا يصل إلا message وedited_message وcallback_query، وأنواع البوتات الصوتية الخاصة بـ Pabal (voice_call، voice_call_tool_query، voice_call_transcript). ولا توجد منشورات القنوات، ولا الاستعلامات المضمّنة، ولا المدفوعات، ولا الاستطلاعات، ولا تغييرات الأعضاء (my_chat_member) وما شابهها.
• التنسيق: يُتجاهل parse_mode وentities ويُرسل النص كما هو. ولا يُعرض تلقائياً إلا الأوامر والإشارات وعناوين URL والوسوم.
• أنواع المحادثات: المحادثات الفردية والمجموعات العادية فقط. ولا توجد قنوات ولا مجموعات خارقة ولا مواضيع منتديات.
• الوسائط: الصور والملفات (sendDocument) والمواقع والمواقع المباشرة والأماكن وجهات الاتصال فقط. ولا توجد رسائل تُشغَّل بوصفها فيديو أو صوتاً، ولا ملصقات، ولا ألبومات (sendMediaGroup)، ولا استطلاعات، ولا الإرسال عبر URL. والحدّ الأقصى للرفع والتنزيل عبر HTTP هو 20MB.
• المواقع: تنبيه الاقتراب للموقع المباشر (proximity_alert_radius) يُحفظ فقط ولا يُرسَل. والحركات التي تقع خلال 10 ثوانٍ أو 10 أمتار تُتجاوز دون تطبيق، وبطاقة جهة الاتصال التي يرسلها بوت لا تحمل user_id.
• البوتات في المجموعات: لا يوجد وضع خصوصية، فيستلم البوت كل رسائل المجموعة.
• قائمة الانتظار: التحديثات التي لم تُجلب تُحفظ في الذاكرة حتى آخر 1,000 تحديث لكل بوت، وتضيع عند إعادة تشغيل الخادم (بينما يحتفظ بها Telegram مدة 24 ساعة).
• Webhook: يُرسل تحديثاً واحداً في كل مرة بالترتيب (وmax_connections تُحفظ فقط)، ولا تُقبل الشهادات الموقّعة ذاتياً، ولا قيود على المنفذ.
• المعرّفات: معرّفات المستخدمين والرسائل والملفات لا معنى لها إلا داخل هذا الخادم. ولعدم وجود قنوات ومجموعات خارقة، لا توجد كذلك معرّفات بالشكل -100….
• الطرق غير الموجودة: ما ليس في القائمة أعلاه (forwardMessage، copyMessage، sendVideo، sendPoll، getChatMember، banChatMember، answerInlineQuery …) يعيد 404 Not Found: method not found.