رابط برنامه‌نویسی بات سروش‌پلاس

API بات یک رابط مبتنی بر HTTP است که برای توسعه دهندگانی که علاقه‌مند به ساخت بات برای سروش‌پلاس هستند طراحی شده است.

ایجاد بات

هر بات هنگام ایجاد از طریق splus.ir/botfather یک توکن احراز هویت منحصر به فرد دریافت می‌کند. توکن‌ها مشابه 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 است، اما ما در این سند فقط از <token> استفاده خواهیم کرد.

ارسال درخواست

تمام درخواست‌ها به API بات سروش‌پلاس باید از طریق HTTPS با این شکل ارائه شوند: https://api.splus.ir/bot<token>/METHOD_NAME

مثال:

https://api.splus.ir/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/getMe

ما از دو متد GET و POST و همچنین از چهار روش ارسال پارامتر در درخواست‌های API بات پشتیبانی می‌کنیم:

Url query string
application/x-www-form-urlencoded
application/json (به جز بارگذاری فایل‌ها)
multipart/form-data (استفاده در بارگذاری فایل‌ها)

پاسخ شامل یک شی JSON است که همیشه یک فیلد boolean به نام «OK» دارد و ممکن است یک فیلد رشته اختیاری به نام «description» برای توضیح نتیجه درخواست داشته باشد. اگر «ok» برابر با True باشد، درخواست موفقیت‌آمیز بوده و نتیجه پرس‌وجو را می‌توان در فیلد «result» یافت. در صورت ناموفق بودن، «OK» برابر با False است و خطا در «description» توضیح داده می‌شود. یک فیلد عدد صحیح 'error_code' نیز بازگردانده می‌شود، اما محتوای آن ممکن است در آینده تغییر کند. برخی خطاها ممکن است یک فیلد اختیاری به نام «پارامترهای» نوع ResponseParameters داشته باشند که می‌تواند به مدیریت خودکار خطا کمک کند.

هیچ حساسیتی نسبت به بزرگ یا کوچک بودن حروف در API بات سروش‌پلاس جود ندارد. همه درخواست‌ها باید با فرمت UTF-8 ایجاد شوند.

درخواست هنگام دریافت به‌روزرسانی‌ها

اگر از webhooks استفاده می‌کنید، می‌توانید هنگام ارسال پاسخ به وب‌هوک، درخواست را به API بات ارسال کنید. برای ارسال پارامترها، از نوع محتوای پاسخ application/json یا application/x-www-form-urlencoded یا multipart/form-data استفاده کنید. متدی را که باید فراخوانی شود، در پارامتر method درخواست مشخص کنید. امکان اطمینان از موفقیت چنین درخواستی یا دریافت نتیجه‌ی آن وجود ندارد.

دریافت به‌روزرسانی‌ها

برای دریافت به‌روزرسانی‌های بات، دو روش مجزا وجود دارد: استفاده از getUpdates یا webhooks. به‌روزرسانی‌های ورودی تا زمانی که بات آن‌ها را دریافت کند، روی سرور ذخیره می‌شوند؛ با این حال، این داده‌ها بیش از ۲۴ ساعت نگهداری نمی‌شوند.
فارغ از این‌که کدام روش را انتخاب کنید، در نهایت اشیای سریال‌شده‌ی Update را با فرمت JSON دریافت خواهید کرد.

Update

این object نشان‌دهنده‌ی یک به‌روزرسانی ورودی است.
در هر به‌روزرسانی، حداکثر یکی از فیلدهای اختیاری می‌تواند وجود داشته باشد.

فیلد	نوع	توضیحات
update_id	Integer	شناسه‌ی منحصربه‌فرد به‌روزرسانی. شناسه‌های به‌روزرسانی از یک عدد مثبت مشخص شروع می‌شوند و به‌ترتیب افزایش می‌یابند. این شناسه به‌ویژه هنگام استفاده از webhooks کاربرد دارد، زیرا به شما امکان می‌دهد به‌روزرسانی‌های تکراری را نادیده بگیرید یا در صورت به‌هم‌خوردن ترتیب آن‌ها، توالی صحیح به‌روزرسانی‌ها را بازیابی کنید. اگر حداقل یک هفته هیچ به‌روزرسانی جدیدی دریافت نشود، شناسه‌ی به‌روزرسانی بعدی به‌صورت تصادفی انتخاب می‌شود و لزوماً ادامه‌ی توالی قبلی نخواهد بود.
message	Message	Optional. پیام ورودی جدید از هر نوع، مانند متن، عکس، استیکر و غیره.
edited_message	Message	Optional. نسخه‌ی جدید پیامی که بات از آن مطلع است و ویرایش شده است. این به‌روزرسانی ممکن است در اثر تغییر فیلدهایی از پیام نیز ایجاد شود که در دسترس بات نیستند یا بات شما به‌طور مستقیم از آن‌ها استفاده نمی‌کند.
callback_query	CallbackQuery	Optional. درخواست Callback جدید.

getUpdates

از این متد برای دریافت به‌روزرسانی‌های ورودی با استفاده از Long Polling ستفاده کنید. این متد آرایه‌ای از اشیای Update را باز می‌گرداند.

پارامتر	نوع	الزامی	توضیحات
offset	Integer	Optional	شناسه‌ی اولین به‌روزرسانی‌ای که باید بازگردانده شود. این مقدار باید یک واحد بیشتر از بزرگ‌ترین update_id در میان به‌روزرسانی‌های دریافت‌شده‌ی قبلی باشد. به‌صورت پیش‌فرض، به‌روزرسانی‌ها از اولین مورد تأییدنشده بازگردانده می‌شوند. هر به‌روزرسانی زمانی تأییدشده محسوب می‌شود که getUpdates با مقدار offset بزرگ‌تر از update_id آن فراخوانی شود. همچنین می‌توانید از مقدار منفی برای offset استفاده کنید تا به‌روزرسانی‌ها از انتهای صف و از موقعیت -offset بازیابی شوند. در این حالت، تمام به‌روزرسانی‌های قبلی نادیده گرفته خواهند شد.
limit	Integer	Optional	حداکثر تعداد به‌روزرسانی‌هایی که باید بازیابی شوند. مقادیر بین ۱ تا ۱۰۰ پذیرفته می‌شوند و مقدار پیش‌فرض ۱۰۰ است.
timeout	Integer	Optional	مدت‌زمان Timeout برای Long Polling، برحسب ثانیه. مقدار پیش‌فرض ۰ است که به‌معنای استفاده از Polling کوتاه معمولی است. برای Long Polling باید مقداری مثبت تعیین شود؛ Polling کوتاه فقط برای اهداف آزمایشی توصیه می‌شود.
allowed_updates	Array of String	Optional	فهرستی JSON-سریال‌شده از انواع به‌روزرسانی‌هایی که می‌خواهید بات دریافت کند. برای مثال، می‌توانید ["message", "edited_channel_post", "callback_query"] را مشخص کنید تا فقط به‌روزرسانی‌های این نوع‌ها دریافت شوند. برای مشاهده‌ی فهرست کامل انواع موجود، به Update مراجعه کنید. برای دریافت همه‌ی انواع به‌روزرسانی به‌جز chat_member، message_reaction و message_reaction_count، یک فهرست خالی مشخص کنید؛ این رفتار پیش‌فرض است. اگر این پارامتر مشخص نشود، تنظیم قبلی حفظ خواهد شد. توجه داشته باشید که این پارامتر روی به‌روزرسانی‌هایی که پیش از فراخوانی getUpdates ایجاد شده‌اند تأثیری ندارد؛ بنابراین ممکن است برای مدت کوتاهی همچنان برخی به‌روزرسانی‌های ناخواسته را دریافت کنید.

یادداشت‌ها
۱. این روش اگر یک webhook خروجی راه‌اندازی شده باشد، کار نخواهد کرد.
۲. برای جلوگیری از دریافت به‌روزرسانی‌های تکراری، پس از هر پاسخ سرور offset را دوباره محاسبه کنید.

setWebhook

از این روش برای مشخص کردن یک URL و دریافت به‌روزرسانی‌های ورودی از طریق یک webhook خروجی استفاده کنید. هرگاه به‌روزرسانی برای بات انجام شود، یک درخواست HTTPS POST به URL مشخص شده ارسال می‌کنیم که شامل یک Update JSON-serialized است. در صورت ناموفق بودن درخواست (درخواستی با پاسخ HTTP کد وضعیت متفاوت از 2XY)، درخواست را تکرار می‌کنیم و پس از تعداد معقولی تلاش منصرف می‌شویم. True با موفقیت برمی گردد.

پارامتر	نوع	الزامی	توضیحات
url	String	Yes	HTTPS URL برای ارسال به‌روزرسانی‌ها. از یک رشته خالی برای حذف ادغام وب‌هوک استفاده کنید.
certificate	InputFile	Optional	گواهی کلید عمومی خود را بارگذاری کنید تا گواهی ریشه در حال استفاده قابل بررسی باشد. برای جزئیات به راهنمای خودامضا ما مراجعه کنید.
ip_address	String	Optional	آدرس IP ثابتی که برای ارسال درخواست‌های وب‌هوک استفاده می‌شود به جای آدرس IP که از طریق DNS حل می‌شود
max_connections	Integer	Optional	حداکثر تعداد مجاز اتصال HTTPS همزمان به وب‌هوک برای تحویل به‌روزرسانی، ۱ تا ۱۰۰ است. پیش‌فرض روی 40 است. از مقادیر پایین‌تر برای محدود کردن بار روی سرور بات خود استفاده کنید و مقادیر بالاتر را برای افزایش توان عملیاتی بات خود افزایش دهید.
allowed_updates	Array of String	Optional	یک فهرست JSON-SERIALIZED شده از انواع به‌روزرسانی‌هایی که می‌خواهید بات شما دریافت کند. برای مثال، مشخص کنید ["message", "edited_channel_post", "callback_query"] فقط به‌روزرسانی‌های این نوع‌ها را دریافت کند. برای فهرست کامل انواع به‌روزرسانی‌های موجود به Update مراجعه کنید. یک فهرست خالی برای دریافت همه انواع به‌روزرسانی به جز chat_member، message_reaction و message_reaction_count(پیش‌فرض) مشخص کنید. اگر مشخص نشده باشد، تنظیم قبلی استفاده خواهد شد. لطفاً توجه داشته باشید که این پارامتر بر به‌روزرسانی‌هایی که قبل از فراخوانی به setWebhook ایجاد شده اند تأثیر نمی‌گذارد، بنابراین ممکن است به‌روزرسانی‌های ناخواسته برای مدت کوتاهی دریافت شوند.
drop_pending_updates	Boolean	Optional	True را برای حذف تمام به‌روزرسانی‌های معلق ارسال کنید

یادداشت‌ها
۱. تا زمانی که وب‌هوک خروجی راه‌اندازی شده باشد، نمی‌توانید با استفاده از getUpdates به‌روزرسانی دریافت کنید.
۲. برای استفاده از گواهی self-signed، باید گواهی کلید عمومی خود را با استفاده از پارامتر certificate بارگذاری کنید. لطفاً به‌صورت InputFile بارگذاری کنید، ارسال Sring کار نخواهد کرد.
۳. پورت‌هایی که در حال حاضر پشتیبانی می‌شوندبرای webhooks: ۴۴۳، ۸۰، ۸۸، ۸۴۴۳.

اگر در راه‌اندازی وب‌هوک‌ها مشکلی دارید، لطفاً این راهنمای فوق العاده وب‌هوک‌ها را بررسی کنید.

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

https://example.com/webhook/<BOT_TOKEN>

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

deleteWebhook

از این روش برای حذف ادغام وب‌هوک استفاده کنید اگر تصمیم گرفتید به آن برگردید getUpdates. با موفقیت True را برمی گرداند.

پارامتر	نوع	الزامی	توضیحات
drop_pending_updates	Boolean	Optional	True را برای حذف تمام به‌روزرسانی‌های معلق ارسال کنید

getWebhookInfo

از این روش برای دریافت وضعیت فعلی webhook استفاده کنید. هیچ پارامتری نیاز ندارد. در صورت موفقیت، یک شیء WebhookInfo برمی گردد. اگر بات از getUpdates استفاده کند، شیئی با فیلد url خالی برمی گرداند.

WebhookInfo

وضعیت فعلی یک وب‌هوک را توصیف می‌کند.

فیلد	نوع	توضیحات
url	String	آدرس وب‌هوک ممکن است خالی باشد اگر webhook تنظیم نشده باشد
has_custom_certificate	Boolean	True اگر گواهی سفارشی برای بررسی‌های گواهی وب‌هوک ارائه شده باشد
pending_update_count	Integer	تعداد به‌روزرسانی‌های منتظر تحویل
ip_address	String	Optional. آدرس IP وب‌هوک که در حال حاضر استفاده می‌شود
last_error_date	Integer	Optional. زمان یونیکس برای آخرین خطایی که هنگام تلاش برای ارائه به‌روزرسانی از طریق وب‌هوک رخ داد
last_error_message	String	Optional. پیام خطا در قالب قابل‌خواندن انسانی برای آخرین خطایی که هنگام تلاش برای ارائه به‌روزرسانی از طریق وب‌هوک رخ داده است
max_connections	Integer	Optional. حداکثر تعداد مجاز اتصال HTTPS همزمان به وب‌هوک برای تحویل به‌روزرسانی
allowed_updates	Array of String	Optional. فهرستی از انواع به‌روزرسانی‌هایی که بات به آن‌ها مشترک است. به‌طور پیش‌فرض به همه نوع به‌روزرسانی‌ها به جز chat_member، message_reaction و message_reaction_count است.

انواع موجود

تمام انواع مورد استفاده در پاسخ‌های API بات به‌صورت شیء‌های JSON نمایش داده می‌شوند.

استفاده از اعداد صحیح علامت‌دار ۳۲ بیتی برای ذخیره همه فیلدهای صحیح ایمن است مگر اینکه خلاف آن ذکر شده باشد.

فیلدهای اختیاری در صورت نامربوط بودن ممکن است بازگردانده نشوند.

User

این شیء نمایانگر یک کاربر یا بات سروش‌پلاس است.

فیلد	نوع	توضیحات
id	Integer	شناسه یکتا برای این کاربر یا بات. این عدد ممکن است بیش از ۳۲ بیت مهم داشته باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن دچار مشکل یا نقص‌های بی صدا شوند. اما حداکثر ۵۲ بیت معنادار دارد، بنابراین عدد صحیح ۶۴ بیتی یا نوع شناور با دقت دوبرابر برای ذخیره این شناسه ایمن است.
is_bot	Boolean	True اگر این کاربر بات باشد
first_name	String	نام کوچک کاربر یا بات
last_name	String	Optional. نام خانوادگی کاربر یا بات
username	String	Optional. نام کاربری کاربر یا بات
language_code	String	Optional. تگ زبان IETF زبان کاربر
can_join_groups	Boolean	Optional. True، اگر بات بتواند به گروه‌ها دعوت شود. فقط در getMe بازگردانده می‌شود.
can_read_all_group_messages	Boolean	Optional. True، اگر حالت حریم خصوصی برای بات غیرفعال شده باشد. فقط در getMe بازگردانده شده است.
supports_inline_queries	Boolean	Optional. True، اگر بات از کوئری‌های inline پشتیبانی کند. فقط در سال getMe بازگردانده شده است.

Chat

این شیء نمایانگر یک چت است.

فیلد	نوع	توضیحات
id	Integer	شناسه منحصر به فرد برای این چت. این عدد ممکن است بیش از ۳۲ بیت معنادار داشته باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن دچار مشکل یا نقص‌های بی صدا شوند. اما حداکثر ۵۲ بیت معنادار دارد، بنابراین عدد صحیح ۶۴ بیتی علامت‌دار یا نوع شناور با دقت دوگانه برای ذخیره این شناسه ایمن است.
type	String	نوع چت می‌تواند «private»، «group»، «supergroup» یا «channel» باشد.
title	String	Optional. عنوان، برای سوپرگروپ‌ها، کانال‌ها و گروه‌های چت
username	String	Optional. نام کاربری، برای گفتگوهای خصوصی، سوپرگروپ‌ها و کانال‌ها در صورت امکان
first_name	String	Optional. اسم کوچک طرف مقابل در یک چت خصوصی
last_name	String	Optional. نام خانوادگی طرف مقابل در یک چت خصوصی
photo	ChatPhoto	Optional. عکس چت
bio	String	Optional. بیوگرافی طرف مقابل در یک چت خصوصی
description	String	Optional. توضیحات، برای گروه‌ها، سوپرگروپ‌ها و گفتگوهای کانال
invite_link	String	Optional. لینک اصلی دعوت برای گروه‌ها، سوپرگروپ‌ها و گفتگوهای کانال
pinned_message	Message	Optional. جدیدترین پیام پین شده (بر اساس تاریخ ارسال)
permissions	ChatPermissions	Optional. مجوزهای پیش‌فرض اعضای چت، برای گروه‌ها و سوپرگروپ‌ها
slow_mode_delay	Integer	Optional. برای ابرگروه‌ها، حداقل تأخیر مجاز بین پیام‌های متوالی ارسال شده توسط هر کاربر بدون امتیاز؛ بر حسب چند ثانیه
message_auto_delete_time	Integer	Optional. زمانی که پس از آن تمام پیام‌های ارسال شده به چت به‌طور خودکار حذف می‌شوند؛ در عرض چند ثانیه
has_protected_content	True	Optional. True، اگر پیام‌های چت قابل انتقال به گفتگوهای دیگر نباشند
sticker_set_name	String	Optional. برای ابرگروه‌ها، نام مجموعه تگ‌های گروه
can_set_sticker_set	True	Optional. True، اگر بات بتواند مجموعه تگ گروه را تغییر دهد
linked_chat_id	Integer	Optional. شناسه یکتا برای چت مرتبط شده، یعنی شناسه گروه بحث برای یک کانال و بالعکس؛ برای ابرگروه‌ها و گفتگوهای کانال. این شناسه ممکن است بزرگ‌تر از ۳۲ بیت باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن مشکل یا نقص‌های بی صدا داشته باشند. اما این شناسه کوچکتر از ۵۲ بیت است، بنابراین عدد صحیح ۶۴ بیتی علامت‌دار یا نوع شناور با دقت دوبرابر برای ذخیره این شناسه ایمن است.
location	ChatLocation	Optional. برای ابرگروه‌ها، مکانی که ابرگروه به آن متصل است
all_members_are_administrators	Boolean	Optional. True اگر همه اعضا مدیر باشند (گروه‌های قدیمی)

Message

این شیء نمایانگر یک پیام است.

فیلد	نوع	توضیحات
message_id	Integer	شناسه پیام منحصر به فرد در این چت؛ ۰ برای پیام‌های زودگذر. در موارد خاص (مثلاً پیامی که شامل ویدیویی است که به یک چت بزرگ ارسال شده است)، سرور ممکن است به‌طور خودکار پیام را زمان‌بندی کند و بلافاصله ارسال نکند. در چنین مواردی، این فیلد صفر خواهد بود و پیام مربوطه تا زمانی که واقعاً ارسال نشود، غیرقابل استفاده خواهد بود.
from	User	Optional. فرستنده پیام؛ ممکن است برای پیام‌های ارسال شده به کانال‌ها خالی باشد. برای سازگاری با نسخه‌های قبلی، اگر پیام به نمایندگی از چت ارسال شده باشد، فیلد شامل کاربر فرستنده جعلی در گفتگوهای غیرکاناله است.
date	Integer	تاریخ ارسال پیام به زمان یونیکس. همیشه عدد مثبت است که نشان دهنده تاریخ معتبر است.
chat	Chat	چتی که پیام متعلق به آن است
forward_from	User	Optional. برای پیام‌های فوروارد شده، فرستنده پیام اصلی
forward_from_chat	Chat	Optional. برای پیام‌های فوروارد شده از چت دیگر، اطلاعات چت اصلی
forward_from_message_id	Integer	Optional. برای پیام‌های فوروارد شده از چت دیگر، شناسه پیام اصلی
forward_signature	String	Optional. برای پیام‌های فوروارد شده دارای امضا، امضای کاربر ارسال‌کننده
forward_sender_name	String	Optional. نام فرستنده برای پیام‌های فوروارد شده از کاربرانی که افزودن لینک حساب را مجاز نمی‌دانند
forward_date	Integer	Optional. برای پیام‌های فوروارد شده، تاریخ ارسال پیام اصلی به وقت یونیکس
reply_to_message	Message	Optional. برای پاسخ‌ها در همان رشته چت و پیام، پیام اصلی. توجه داشته باشید که شیء Message در این فیلد حتی اگر خود پاسخ باشد، فیلدهای reply_to_message بیشتری نخواهد داشت. اگر پیام پاسخی به یک پیام زودگذر باشد، این فیلد ممکن است حذف شود.
via_bot	User	Optional. بات که پیام از طریق آن ارسال شد
edit_date	Integer	Optional. تاریخ آخرین ویرایش پیام در زمان یونیکس
has_protected_content	True	Optional. True، اگر پیام قابل ارسال نباشد
media_group_id	String	Optional. شناسه منحصر به فرد داخل این چت گروه پیام رسانه ای که این پیام به آن تعلق دارد
text	String	Optional. برای پیامک‌ها، متن واقعی UTF-8 پیام
entities	Array of MessageEntity	Optional. برای پیامک‌ها، موجودیت‌های ویژه مانند نام‌های کاربری، URL ها، دستورات بات و غیره که در متن ظاهر می‌شوند
animation	Animation	Optional. پیام یک انیمیشن است، اطلاعاتی درباره انیمیشن. برای سازگاری به گذشته، وقتی این فیلد تنظیم شود، فیلد document نیز تنظیم خواهد شد.
audio	Audio	Optional. پیام یک فایل صوتی است، اطلاعاتی درباره فایل
document	Document	Optional. پیام یک فایل عمومی است، اطلاعاتی درباره فایل
photo	Array of PhotoSize	Optional. پیام یک عکس است، اندازه‌های موجود عکس
sticker	Sticker	Optional. پیام یک استیکر است، اطلاعات درباره استیکر
video	Video	Optional. پیام یک ویدیو است، اطلاعاتی درباره ویدئو
video_note	VideoNote	Optional. پیام یک یادداشت ویدیویی است، اطلاعاتی درباره پیام ویدیویی
voice	Voice	Optional. پیام یک پیام صوتی است، اطلاعات مربوط به فایل
caption	String	Optional. کپشن برای انیمیشن، صدا، سند، رسانه پولی، عکس، ویدئو یا صدا
caption_entities	Array of MessageEntity	Optional. برای پیام‌هایی با کپشن، موجودیت‌های ویژه مانند نام‌های کاربری، URL ها، دستورات بات و غیره که در کپشن ظاهر می‌شوند
contact	Contact	Optional. پیام یک مخاطب مشترک است، اطلاعات مربوط به مخاطب
dice	Dice	Optional. پیام یک تاس با مقدار تصادفی است
location	Location	Optional. پیام یک مکان مشترک است، اطلاعاتی درباره مکان
new_chat_title	String	Optional. عنوان چت به این مقدار تغییر کرد
new_chat_photo	Array of PhotoSize	Optional. عکس چت به این مقدار تغییر کرد
pinned_message	MaybeInaccessibleMessageMessage	Optional. پیام مشخص شده پین شد. توجه داشته باشید که شیء Message در این فیلد حتی اگر خود یک پاسخ باشد، فیلدهای reply_to_message بیشتری نخواهد داشت.
reply_markup	InlineKeyboardMarkup	Optional. inline keyboard متصل به پیام. login_url دکمه‌ها به‌صورت دکمه‌های معمولی url نمایش داده می‌شوند.

MessageId

این شیء نمایانگر یک شناسه پیام منحصر به فرد است.

فیلد	نوع	توضیحات
message_id	Integer	شناسه پیام منحصر به فرد. در موارد خاص (مثلاً پیامی که شامل ویدیویی است که به یک چت بزرگ ارسال می‌شود)، سرور ممکن است به‌طور خودکار پیام را زمان‌بندی کند و بلافاصله ارسال نکند. در چنین مواردی، این فیلد صفر خواهد بود و پیام مربوطه تا زمانی که واقعاً ارسال نشود، غیرقابل استفاده خواهد بود.

MessageEntity

این شیء نمایانگر یک موجودیت خاص در یک پیام متنی است. برای مثال، هشتگ‌ها، نام‌های کاربری، URL ها و غیره.

فیلد	نوع	توضیحات
type	String	نوع موجودیت. در حال حاضر، می‌تواند به‌صورت «mention» (@username)، «hashtag» (#hashtag یا#hashtag@chatusername)، «cashtag» ($USD یا$USD@chatusername)، «bot_command» (/start@jobs_bot)، «url» (https://example.com)، «email» (name@example.com)، «phone_number» (+98-912-345-6789)، «bold» (متن پررنگ) باشد، "italic" (italic text)، "underline" (متن زیرخط دار)، "strikethrough" (متن خط خورده )، "spoiler" (پیام اسپویل)،"code" (رشته مونوویید)، "pre" (بلوک مونوویید)، "text_link" (برای آدرس‌های متنی قابل‌کلیک)، "text_mention" (برای کاربران بدون نام کاربری)
offset	Integer	جابجایی در واحدهای کد UTF-16 تا ابتدای موجودیت
length	Integer	طول موجودیت در واحدهای کد UTF-16
url	String	Optional. فقط برای «text_link» آدرس اینترنتی که پس از ضربه زدن کاربر روی متن باز می‌شود
user	User	Optional. فقط برای «text_mention»، کاربر مذکور
language	String	Optional. فقط برای "pre"، زبان برنامه‌نویسی متن موجودیت

PhotoSize

این شیء نمایانگر یک اندازه از یک عکس یا یک تصویر Thumbnail file/sticker است.

فیلد	نوع	توضیحات
file_id	String	شناسه این فایل که می‌تواند برای دانلود یا استفاده مجدد از فایل استفاده شود
file_unique_id	String	شناسه یکتا برای این فایل که قرار است در طول زمان و برای بات‌های مختلف یکسان باشد. نمی‌توان از آن برای دانلود یا استفاده مجدد فایل استفاده کرد.
width	Integer	عرض عکس
height	Integer	ارتفاع عکس
file_size	Integer	Optional. اندازه فایل بر حسب بایت

Animation

این شیء نمایانگر یک فایل انیمیشن (GIF یا ویدئوی AVC H.264/MPEG-4 بدون صدا) است.

فیلد	نوع	توضیحات
file_id	String	شناسه این فایل که می‌تواند برای دانلود یا استفاده مجدد از فایل استفاده شود
file_unique_id	String	شناسه یکتا برای این فایل که قرار است در طول زمان و برای بات‌های مختلف یکسان باشد. نمی‌توان از آن برای دانلود یا استفاده مجدد فایل استفاده کرد.
width	Integer	عرض ویدئو طبق تعریف فرستنده
height	Integer	ارتفاع ویدیو طبق تعریف فرستنده
duration	Integer	مدت زمان ویدیو بر حسب ثانیه طبق تعریف فرستنده
thumb	PhotoSize	Optional. تصویر کوچک انیمیشن طبق تعریف فرستنده
file_name	String	Optional. نام فایل انیمیشن اصلی طبق تعریف فرستنده
mime_type	String	Optional. نوع MIME فایل طبق تعریف فرستنده
file_size	Integer	Optional. اندازه فایل بر حسب بایت. می‌تواند بزرگ‌تر از 2^31 باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن دچار مشکل یا نقص‌های بی صدا شوند. اما حداکثر 52 بیت معنادار دارد، بنابراین عدد صحیح 64 بیتی علامت‌دار یا نوع شناور با دقت دوگانه برای ذخیره این مقدار ایمن است.

Audio

این شیء نمایانگر یک فایل صوتی است که توسط کلاینت‌های سروش‌پلاس به عنوان موسیقی در نظر گرفته می‌شود.

فیلد	نوع	توضیحات
file_id	String	شناسه این فایل که می‌تواند برای دانلود یا استفاده مجدد از فایل استفاده شود
file_unique_id	String	شناسه یکتا برای این فایل که قرار است در طول زمان و برای بات‌های مختلف یکسان باشد. نمی‌توان از آن برای دانلود یا استفاده مجدد فایل استفاده کرد.
duration	Integer	مدت زمان صدا بر حسب ثانیه طبق تعریف فرستنده
performer	String	Optional. اجراکننده صدا طبق تعریف فرستنده یا تگ‌های صوتی
title	String	Optional. عنوان فایل صوتی طبق تعریف فرستنده یا تگ‌های صوتی
file_name	String	Optional. نام فایل اصلی طبق تعریف فرستنده
mime_type	String	Optional. نوع MIME فایل طبق تعریف فرستنده
file_size	Integer	Optional. اندازه فایل بر حسب بایت. می‌تواند بزرگ‌تر از 2^31 باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن دچار مشکل یا نقص‌های بی صدا شوند. اما حداکثر 52 بیت معنادار دارد، بنابراین عدد صحیح 64 بیتی علامت‌دار یا نوع شناور با دقت دوگانه برای ذخیره این مقدار ایمن است.
thumb	PhotoSize	Optional. تصویر Thumbnail جلد آلبومی که فایل موسیقی به آن تعلق دارد

Document

این شیء نمایانگر یک فایل عمومی است (برخلاف فایل‌های photos، پیام صوتی و صوتی).

فیلد	نوع	توضیحات
file_id	String	شناسه این فایل که می‌تواند برای دانلود یا استفاده مجدد از فایل استفاده شود
file_unique_id	String	شناسه یکتا برای این فایل که قرار است در طول زمان و برای بات‌های مختلف یکسان باشد. نمی‌توان از آن برای دانلود یا استفاده مجدد فایل استفاده کرد.
thumb	PhotoSize	Optional. تصویر Thumbnail سند طبق تعریف فرستنده
file_name	String	Optional. نام فایل اصلی طبق تعریف فرستنده
mime_type	String	Optional. نوع MIME فایل طبق تعریف فرستنده
file_size	Integer	Optional. اندازه فایل بر حسب بایت. می‌تواند بزرگ‌تر از 2^31 باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن دچار مشکل یا نقص‌های بی صدا شوند. اما حداکثر 52 بیت معنادار دارد، بنابراین عدد صحیح 64 بیتی علامت‌دار یا نوع شناور با دقت دوگانه برای ذخیره این مقدار ایمن است.

Video

این شیء نمایانگر یک فایل ویدیویی است.

فیلد	نوع	توضیحات
file_id	String	شناسه این فایل که می‌تواند برای دانلود یا استفاده مجدد از فایل استفاده شود
file_unique_id	String	شناسه یکتا برای این فایل که قرار است در طول زمان و برای بات‌های مختلف یکسان باشد. نمی‌توان از آن برای دانلود یا استفاده مجدد فایل استفاده کرد.
width	Integer	عرض ویدئو طبق تعریف فرستنده
height	Integer	ارتفاع ویدیو طبق تعریف فرستنده
duration	Integer	مدت زمان ویدیو بر حسب ثانیه طبق تعریف فرستنده
thumb	PhotoSize	Optional. تصویر Thumbnail ویدئو
file_name	String	Optional. نام فایل اصلی طبق تعریف فرستنده
mime_type	String	Optional. نوع MIME فایل طبق تعریف فرستنده
file_size	Integer	Optional. اندازه فایل بر حسب بایت. می‌تواند بزرگ‌تر از 2^31 باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن دچار مشکل یا نقص‌های بی صدا شوند. اما حداکثر 52 بیت معنادار دارد، بنابراین عدد صحیح 64 بیتی علامت‌دار یا نوع شناور با دقت دوگانه برای ذخیره این مقدار ایمن است.

VideoNote

این شیء نمایانگر یک پیام ویدیویی است.

فیلد	نوع	توضیحات
file_id	String	شناسه این فایل که می‌تواند برای دانلود یا استفاده مجدد از فایل استفاده شود
file_unique_id	String	شناسه یکتا برای این فایل که قرار است در طول زمان و برای بات‌های مختلف یکسان باشد. نمی‌توان از آن برای دانلود یا استفاده مجدد فایل استفاده کرد.
length	Integer	عرض و ارتفاع ویدئو (قطر پیام ویدیویی) طبق تعریف فرستنده
duration	Integer	مدت زمان ویدیو بر حسب ثانیه طبق تعریف فرستنده
thumb	PhotoSize	Optional. تصویر Thumbnail ویدئو
file_size	Integer	Optional. اندازه فایل بر حسب بایت

Voice

این شیء نمایانگر یک پیام صوتی است.

فیلد	نوع	توضیحات
file_id	String	شناسه این فایل که می‌تواند برای دانلود یا استفاده مجدد از فایل استفاده شود
file_unique_id	String	شناسه یکتا برای این فایل که قرار است در طول زمان و برای بات‌های مختلف یکسان باشد. نمی‌توان از آن برای دانلود یا استفاده مجدد فایل استفاده کرد.
duration	Integer	مدت زمان صدا بر حسب ثانیه طبق تعریف فرستنده
mime_type	String	Optional. نوع MIME فایل طبق تعریف فرستنده
file_size	Integer	Optional. اندازه فایل بر حسب بایت. می‌تواند بزرگ‌تر از 2^31 باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن دچار مشکل یا نقص‌های بی صدا شوند. اما حداکثر 52 بیت معنادار دارد، بنابراین عدد صحیح 64 بیتی علامت‌دار یا نوع شناور با دقت دوگانه برای ذخیره این مقدار ایمن است.

Contact

این شیء نمایانگر یک مخاطب تلفنی است.

فیلد	نوع	توضیحات
phone_number	String	شماره تلفن مخاطب
first_name	String	نام کوچک تماس
last_name	String	Optional. نام خانوادگی تماس
user_id	Integer	Optional. شناسه کاربری Contact در سروش‌پلاس. این عدد ممکن است بیش از ۳۲ بیت مهم داشته باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن دچار مشکل یا نقص‌های بی صدا شوند. اما حداکثر ۵۲ بیت معنادار دارد، بنابراین عدد صحیح ۶۴ بیتی یا نوع شناور با دقت دوگانه برای ذخیره این شناسه ایمن است.
vcard	String	Optional. اطلاعات اضافی درباره تماس به‌صورت یک vCard

Dice

این شیء نمایانگر یک ایموجی متحرک است که مقدار تصادفی را نمایش می‌دهد.

فیلد	نوع	توضیحات
emoji	String	ایموجی ای که انیمیشن پرتاب تاس بر اساس آن ساخته شده است
value	Integer	ارزش تاس، ۱ تا ۶ برای ایموجی‌های پایه «»، «» و «»، ۱ تا ۵ برای ایموجی‌های پایه «» و «» و ۱ تا ۶۴ برای ایموجی پایه «»

Location

این شیء نمایانگر یک نقطه روی نقشه است.

فیلد	نوع	توضیحات
latitude	Float	عرض جغرافیایی که توسط فرستنده تعریف شده است
longitude	Float	طول جغرافیایی که توسط فرستنده تعریف شده است

UserProfilePhotos

این شیء نمایانگر عکس‌های پروفایل کاربر است.

فیلد	نوع	توضیحات
total_count	Integer	تعداد کل عکس‌های پروفایل کاربر هدف
photos	Array of Array of PhotoSize	عکس‌های پروفایل درخواستی (در حداکثر ۴ سایز)

File

این شیء نمایانگر فایلی است که آماده دانلود است. فایل را می‌توان از طریق لینک https://api.splus.ir/file/bot<token>/<file_path> دانلود کرد. تضمین شده است که لینک حداقل به مدت ۱ ساعت معتبر خواهد بود. وقتی لینک منقضی می‌شود، می‌توان با فراخوانی getFile پیوند جدید درخواست کرد.

حداکثر حجم فایل برای دانلود ۲۰ مگابایت است

فیلد	نوع	توضیحات
file_id	String	شناسه این فایل که می‌تواند برای دانلود یا استفاده مجدد از فایل استفاده شود
file_unique_id	String	شناسه یکتا برای این فایل که قرار است در طول زمان و برای بات‌های مختلف یکسان باشد. نمی‌توان از آن برای دانلود یا استفاده مجدد فایل استفاده کرد.
file_size	Integer	Optional. اندازه فایل بر حسب بایت. می‌تواند بزرگ‌تر از 2^31 باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن دچار مشکل یا نقص‌های بی صدا شوند. اما حداکثر 52 بیت معنادار دارد، بنابراین عدد صحیح 64 بیتی علامت‌دار یا نوع شناور با دقت دوگانه برای ذخیره این مقدار ایمن است.
file_path	String	Optional. مسیر file. از https://api.splus.ir/file/bot<token>/<file_path> برای گرفتن فایل استفاده کن.

ReplyKeyboardMarkup

این شیء نمایانگر یک صفحه‌کلید سفارشی با گزینه‌های پاسخ است.

فیلد	نوع	توضیحات
keyboard	Array of Array of KeyboardButton	آرایه ای از ردیف‌های دکمه‌ها، هر کدام با آرایه ای از KeyboardButton شیء نمایش داده می‌شوند
resize_keyboard	Boolean	Optional. از کلاینت‌ها می‌خواهد صفحه‌کلید را به‌صورت عمودی تغییر اندازه دهند تا تناسب بهینه داشته باشد (مثلاً اگر فقط دو ردیف دکمه وجود داشته باشد، صفحه‌کلید را کوچکتر کنند). پیش‌فرض False است که در این صورت کیبورد سفارشی همیشه هم ارتفاع کیبورد استاندارد اپ است.
one_time_keyboard	Boolean	Optional. از کلاینت‌ها می‌خواهد پس از استفاده، صفحه‌کلید را مخفی کنند. صفحه‌کلید همچنان در دسترس خواهد بود، اما کلاینت‌ها به‌طور خودکار صفحه‌کلید حروف معمولی را در چت نمایش می‌دهند - کاربر می‌تواند دکمه ویژه ای را در فیلد ورودی فشار دهد تا دوباره صفحه‌کلید سفارشی را ببیند. پیش‌فرض روی False است.
input_field_placeholder	String	Optional. موقتی که هنگام فعال بودن صفحه‌کلید در فیلد ورودی نمایش داده می‌شود؛ ۱ تا ۶۴ کاراکتر

KeyboardButton

این شیء نمایانگر یک دکمه از صفحه‌کلید پاسخ است. حداکثر باید یکی از فیلدها به جز text برای مشخص کردن نوع دکمه استفاده شود. برای دکمه‌های ساده متنی، می‌توان به جای این شیء از String برای مشخص کردن متن دکمه استفاده کرد.

فیلد	نوع	توضیحات
text	String	متن دکمه. اگر هیچ یک از فیلدها به جز text، icon_custom_emoji_id و style استفاده نشوند، هنگام فشار دادن دکمه به‌صورت پیام ارسال می‌شود.
request_contact	Boolean	Optional. اگر True، شماره تلفن کاربر هنگام فشار دادن دکمه به عنوان مخاطب ارسال خواهد شد. فقط در گفتگوهای خصوصی در دسترس است.
request_location*	Boolean	Optional. اگر True، موقعیت فعلی کاربر هنگام فشار دادن دکمه ارسال خواهد شد. فقط در گفتگوهای خصوصی در دسترس است.

ReplyKeyboardRemove

پس از دریافت پیامی با این شیء، کلاینت‌های سروش‌پلاس صفحه‌کلید سفارشی فعلی را حذف کرده و صفحه‌کلید حرفی پیش‌فرض را نمایش می‌دهند. به‌طور پیش‌فرض، صفحه‌کلیدهای سفارشی تا زمانی که بات صفحه‌کلید جدیدی ارسال کند، نمایش داده می‌شوند. استثنایی برای صفحه‌کلیدهای یک بار مصرف که بلافاصله پس از فشار دادن یک دکمه توسط کاربر پنهان می‌شوند (مشاهده: ReplyKeyboardMarkup).

فیلد	نوع	توضیحات
remove_keyboard	True	از کلاینت‌ها می‌خواهد صفحه‌کلید سفارشی را حذف کنند (کاربر نمی‌تواند این صفحه‌کلید را فراخوانی کند؛ اگر می‌خواهید صفحه‌کلید را از دید پنهان کنید اما در دسترس نگه دارید، از one_time_keyboard در ReplyKeyboardMarkup استفاده کنید)

InlineKeyboardMarkup

این شیء نمایانگر یک inline keyboard است که درست کنار پیامی که به آن تعلق دارد ظاهر می‌شود.

فیلد	نوع	توضیحات
inline_keyboard	Array of Array of InlineKeyboardButton	آرایه ای از ردیف‌های دکمه‌ها، هر کدام با آرایه ای از InlineKeyboardButton شیء نمایش داده می‌شوند

InlineKeyboardButton

این شیء نمایانگر یک دکمه از یک inline keyboard است. دقیقاً یکی از فیلدها به جز text باید برای مشخص کردن نوع دکمه استفاده شود.

فیلد	نوع	توضیحات
text	String	متن تگ روی دکمه
url	String	Optional. HTTP که هنگام فشار دادن دکمه باز می‌شود
callback_data	String	Optional. داده‌هایی که باید در یک پرس وجوی callback به بات ارسال شوند، زمانی که دکمه فشرده می‌شود، بین ۱ تا ۶۴ بایت

CallbackQuery

این شیء نمایانگر یک پرس و جوی فراخوانی ورودی از یک دکمه فراخوانی در یک صفحه‌کلید inline است. اگر دکمه ای که پرس وجوی را ایجاد کرده به پیامی که توسط بات ارسال شده متصل شده باشد، فیلد message وجود خواهد داشت. اگر دکمه به پیامی که از طریق بات ارسال شده متصل شده باشد (در حالت inline )، inline_message_id فیلد حضور خواهد داشت. دقیقاً یکی از فیلدهای data یا game_short_name وجود خواهد داشت.

فیلد	نوع	توضیحات
id	String	شناسه یکتا برای این پرس‌وجو
from	User	فرستنده
message	MaybeInaccessibleMessageMessage	Optional. پیامی که توسط بات با دکمه تماس برگشتی ارسال شده و پرسش را آغاز کرده است
data	String	Optional. داده‌های مرتبط با دکمه callback. توجه داشته باشید که پیام منشأ پرس‌وجو نمی‌تواند هیچ دکمه فراخوانی با این داده‌ها داشته باشد.

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

ForceReply (به‌زودی)

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

فیلد	نوع	توضیحات
force_reply	True	رابط پاسخ را به کاربر نشان می‌دهد، انگار که او به‌صورت دستی پیام بات را انتخاب کرده و روی «پاسخ» ضربه زده است.
input_field_placeholder	String	Optional. موقتی که در فیلد ورودی هنگام فعال بودن پاسخ نمایش داده می‌شود؛ ۱ تا ۶۴ کاراکتر
selective	Boolean	Optional. اگر می‌خواهید پاسخ را فقط از کاربران خاص اجباری کنید، از این پارامتر استفاده کنید. اهداف: ۱) کاربرانی که در text شیء Message@mentioned هستند؛ ۲) اگر پیام بات پاسخ به پیامی در همان موضوع چت و انجمن باشد، فرستنده پیام اصلی است.

مثال: یک بات نظرسنجی برای گروه‌ها در حالت حریم خصوصی اجرا می‌شود (فقط دستورات را دریافت می‌کند، به پیام‌ها و اشاره‌ها پاسخ می‌دهد). دو روش برای ایجاد نظرسنجی جدید می‌تواند وجود داشته باشد:

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

ChatPhoto

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

فیلد	نوع	توضیحات
small_file_id	String	شناسه فایل عکس چت کوچک (160x160). این file_id فقط برای دانلود عکس قابل استفاده است و تا زمانی که عکس تغییر نکرده باشد.
small_file_unique_id	String	شناسه فایل منحصر به فرد برای عکس چت کوچک (160x160) که قرار است در طول زمان و برای بات‌های مختلف یکسان باشد. نمی‌توان از آن برای دانلود یا استفاده مجدد فایل استفاده کرد.
big_file_id	String	شناسه فایل عکس چت بزرگ (640x640). این file_id فقط برای دانلود عکس قابل استفاده است و فقط تا زمانی که عکس تغییر نکند.
big_file_unique_id	String	شناسه فایل منحصر به فرد برای عکس چت بزرگ (640x640) که قرار است در طول زمان و برای بات‌های مختلف یکسان باشد. نمی‌توان از آن برای دانلود یا استفاده مجدد فایل استفاده کرد.

BotCommand*

این شیء نمایانگر یک فرمان بات است.

فیلد	نوع	توضیحات
command	String	متن فرمان؛ ۱ تا ۳۲ کاراکتر. فقط می‌تواند شامل حروف کوچک انگلیسی، ارقام و زیرخط‌ها باشد.
description	String	توضیح فرماندهی؛ ۱ تا ۲۵۶ کاراکتر

BotCommandScope

این شیء نمایانگر دامنه‌ای است که دستورات بات روی آن اعمال می‌شوند. در حال حاضر، ۳ دامنه زیر پشتیبانی می‌شوند:

BotCommandScopeDefault
BotCommandScopeAllPrivateChats
BotCommandScopeChat

تعیین فهرست فرمان‌ها

الگوریتم زیر برای تعیین فهرست دستورات برای کاربر خاصی که منوی بات را مشاهده می‌کند، استفاده می‌شود. اولین فهرست دستورات که تنظیم می‌شود بازگردانده می‌شود:

دستورات در چت با بات

botCommandScopeChat +language_code
botCommandScopeChat
botCommandScopeAllPrivateChats +language_code
botCommandScopeAllPrivateChats
botCommandScopeDefault +language_code
botCommandScopeDefault

فرمان‌ها در گفتگوهای گروهی و سوپرگروپ

botCommandScopeChat +language_code
botCommandScopeChat
botCommandScopeDefault +language_code
botCommandScopeDefault

BotCommandScopeDefault

نمایانگر scope پیش‌فرض دستورات بات است. دستورات پیش‌فرض زمانی استفاده می‌شوند که هیچ دستوری با دامنه باریک‌تر برای کاربر مشخص نشده باشد.

فیلد	نوع	توضیحات
type	String	نوع تلسکوپ باید default

BotCommandScopeAllPrivateChats

نمایانگر scope دستورات بات است و تمام گفتگوهای خصوصی را پوشش می‌دهد.

فیلد	نوع	توضیحات
type	String	نوع تلسکوپ باید all_private_chats

BotCommandScopeChat

نمایانگر scope دستورات بات است که یک چت خاص را پوشش می‌دهد.

فیلد	نوع	توضیحات
type	String	نوع تلسکوپ باید chat
chat_id	Integer or String	شناسه منحصر به فرد برای چت یا نام کاربری در قالب @username. پیام‌های مستقیم کانال‌ها، گفتگوها و گفتگوهای کانال پشتیبانی نمی‌شوند.

ResponseParameters

توضیح می‌دهد چرا یک درخواست ناموفق بود.

فیلد	نوع	توضیحات
retry_after	Integer	Optional. در صورت عبور از محدودیت، تعداد ثانیه‌های باقی مانده برای انتظار قبل از درخواست می‌تواند تکرار شود

InputMedia

این شیء نمایانگر محتوای یک پیام رسانه ای است که باید ارسال شود. باید یکی از

InputMediaAnimation
InputMediaAudio
InputMediaDocument
InputMediaLivePhoto
InputMediaPhoto
InputMediaVideo

InputMediaAnimation

یک فایل انیمیشن (GIF یا ویدیوی H.264/MPEG-4 AVC بدون صدا) که باید ارسال شود را نمایش می‌دهد.

فیلد	نوع	توضیحات
type	String	نوع رسانه باید animation
media	String	فایل برای ارسال. یک file_id ارسال کنید تا فایلی که روی سرورهای سروش‌پلاس وجود دارد ارسال شود (توصیه می‌شود)، یک آدرس آدرس HTTPارسال کنید تا سروش‌پلاس بتواند فایلی را از اینترنت دریافت کند، یا «attach://<file_attach_name>» را برای بارگذاری فایل جدید با استفاده از داده‌های multipart/form-data تحت نام <file_attach_name> ارسال کنید. اطلاعات بیشتر درباره ارسال فایل‌ها »
caption	String	Optional. کپشن انیمیشنی که قرار است ارسال شود، ۰ تا ۱۰۲۴ کاراکتر پس از Entities Parsing
parse_mode	String	Optional. حالت Entities Parsingدر کپشن انیمیشن. برای جزئیات بیشتر به گزینه‌های قالب‌بندی مراجعه کنید.
caption_entities	Array of MessageEntity	Optional. فهرست موجودیت‌های ویژه‌ای که در کپشن ظاهر می‌شوند و می‌توان آن‌ها را به جای parse_mode مشخص کرد
width	Integer	Optional. عرض انیمیشن
height	Integer	Optional. ارتفاع انیمیشن
duration	Integer	Optional. مدت زمان انیمیشن به ثانیه

InputMediaAudio

نمایانگر یک فایل صوتی است که باید به عنوان موسیقی برای ارسال در نظر گرفته شود.

فیلد	نوع	توضیحات
type	String	نوع رسانه باید audio
media	String	فایل برای ارسال. یک file_id ارسال کنید تا فایلی که روی سرورهای سروش‌پلاس وجود دارد ارسال شود (توصیه می‌شود)، یک آدرس آدرس HTTP ارسال کنید تا سروش‌پلاس بتواند فایلی را از اینترنت دریافت کند، یا «attach://<file_attach_name>» را برای بارگذاری فایل جدید با استفاده از داده‌های multipart/form-data تحت نام <file_attach_name> ارسال کنید. اطلاعات بیشتر درباره ارسال فایل‌ها »
caption	String	Optional. کپشن صوتی که باید ارسال شود، ۰ تا ۱۰۲۴ کاراکتر پس از Entities Parsing
parse_mode	String	Optional. حالت برای Entities Parsingدر کپشن صوتی. برای جزئیات بیشتر به گزینه‌های قالب‌بندی مراجعه کنید.
caption_entities	Array of MessageEntity	Optional. فهرست موجودیت‌های ویژه ای که در کپشن ظاهر می‌شوند و می‌توان آن‌ها را به جای parse_mode مشخص کرد
duration	Integer	Optional. مدت زمان صدا بر حسب ثانیه
performer	String	Optional. اجراکننده صدا
title	String	Optional. عنوان فایل صوتی

InputMediaDocument

نمایانگر یک فایل عمومی برای ارسال است.

فیلد	نوع	توضیحات
type	String	نوع رسانه باید document
media	String	فایل برای ارسال. یک file_id ارسال کنید تا فایلی که روی سرورهای سروش‌پلاس وجود دارد ارسال شود (توصیه می‌شود)، یک آدرس آدرس HTTP ارسال کنید تا سروش‌پلاس بتواند فایلی را از اینترنت دریافت کند، یا «attach://<file_attach_name>» را برای بارگذاری فایل جدید با استفاده از داده‌های multipart/form-data تحت نام <file_attach_name> ارسال کنید. اطلاعات بیشتر درباره ارسال فایل‌ها »
caption	String	Optional. کپشن سند برای ارسال، ۰ تا ۱۰۲۴ کاراکتر پس از Entities Parsing
parse_mode	String	Optional. حالت Entities Parsingدر کپشن سند. برای جزئیات بیشتر به گزینه‌های قالب‌بندی مراجعه کنید.
caption_entities	Array of MessageEntity	Optional. فهرست موجودیت‌های ویژه ای که در کپشن ظاهر می‌شوند و می‌توان آن‌ها را به جای parse_mode مشخص کرد
disable_content_type_detection	Boolean	Optional. تشخیص خودکار نوع محتوای سمت سرور را برای فایل‌هایی که با استفاده از داده‌های چندبخشی یا فرم بارگذاری شده اند غیرفعال می‌کند. همیشه True اگر سند به عنوان بخشی از یک آلبوم ارسال شود.

InputMediaPhoto

نمایانگر عکسی است که باید ارسال شود.

فیلد	نوع	توضیحات
type	String	نوع رسانه باید photo
media	String	فایل برای ارسال. یک file_id ارسال کنید تا فایلی که روی سرورهای سروش‌پلاس وجود دارد ارسال شود (توصیه می‌شود)، یک آدرس آدرس HTTP ارسال کنید تا سروش‌پلاس بتواند فایلی را از اینترنت دریافت کند، یا «attach://<file_attach_name>» را برای بارگذاری فایل جدید با استفاده از داده‌های multipart/form-data تحت نام <file_attach_name> ارسال کنید. اطلاعات بیشتر درباره ارسال فایل‌ها »
caption	String	Optional. کپشن عکس برای ارسال، ۰ تا ۱۰۲۴ کاراکتر پس از Entities Parsing
parse_mode	String	Optional. حالت برای Entities Parsingدر کپشن عکس. برای جزئیات بیشتر به گزینه‌های قالب‌بندی مراجعه کنید.
caption_entities	Array of MessageEntity	Optional. فهرست موجودیت‌های ویژه ای که در کپشن ظاهر می‌شوند و می‌توان آن‌ها را به جای parse_mode مشخص کرد

InputMediaVideo

نمایانگر ویدیویی است که باید ارسال شود.

فیلد	نوع	توضیحات
type	String	نوع رسانه باید video
media	String	فایل برای ارسال. یک file_id ارسال کنید تا فایلی که روی سرورهای سروش‌پلاس وجود دارد ارسال شود (توصیه می‌شود)، یک آدرس آدرس HTTP ارسال کنید تا سروش‌پلاس بتواند فایلی را از اینترنت دریافت کند، یا «attach://<file_attach_name>» را برای بارگذاری فایل جدید با استفاده از داده‌های multipart/form-data تحت نام <file_attach_name> ارسال کنید. اطلاعات بیشتر درباره ارسال فایل‌ها »
caption	String	Optional. کپشن ویدیویی که قرار است ارسال شود، ۰ تا ۱۰۲۴ کاراکتر پس از Entities Parsing
parse_mode	String	Optional. حالت Entities Parsingدر کپشن ویدیو. برای جزئیات بیشتر به گزینه‌های قالب‌بندی مراجعه کنید.
caption_entities	Array of MessageEntity	Optional. فهرست موجودیت‌های ویژه ای که در کپشن ظاهر می‌شوند و می‌توان آن‌ها را به جای parse_mode مشخص کرد
width	Integer	Optional. عرض ویدئو
height	Integer	Optional. ارتفاع ویدئو
duration	Integer	Optional. مدت زمان ویدیو به ثانیه
supports_streaming	Boolean	Optional. اگر ویدیوی آپلود شده برای استریم مناسب است، True را رد کنید

InputFile

این شیء نمایانگر محتوای فایلی است که قرار است بارگذاری شود. باید با استفاده از داده‌های multipart/form-data به روشی که معمولا فایل‌ها از طریق مرورگر بارگذاری می‌شوند، ارسال شود.

ارسال فایل‌ها

سه روش برای ارسال فایل‌ها وجود دارد (عکس، استیکر، صدا، رسانه و غیره):

اگر فایل قبلا جایی روی سرورهای سروش‌پلاس ذخیره شده باشد، نیازی به بارگذاری مجدد آن نیست: هر شیء فایل یک فیلد file_id دارد، کافی است این file_id را به عنوان پارامتر ارسال کنید به جای بارگذاری. هیچ محدودیتی برای فایل‌هایی که به این روش ارسال می‌شوند وجود ندارد.
فایل را با استفاده از داده‌های multipart/form-data به روش معمول که فایل‌ها از طریق مرورگر بارگذاری می‌شوند، ارسال کنید. حداکثر ۱۰ مگابایت برای عکس‌ها، ۵۰ مگابایت برای فایل‌های دیگر.

ارسال توسط file_id

امکان تغییر نوع فایل هنگام ارسال مجدد توسط file_id وجود ندارد. مثلاً یک video نمی‌تواند به‌صورت عکس ارسال شود، photo را نمی‌توان به‌صورت سند ارسال کرد و غیره.
امکان ارسال مجدد تصاویر thumbnail وجود ندارد.
ارسال مجدد عکس توسط file_id تمام sizes را ارسال می‌کند.
file_id برای هر بات منحصر به فرد است و نمی‌توان آن را از یک بات به بات دیگر منتقل کرد.
file_id یک فایل را به‌طور یکتا شناسایی می‌کند، اما فایل حتی برای همان بات می‌تواند file_ids معتبر متفاوتی داشته باشد.

روش‌های موجود

تمام متدهای API بات حساس به حروف بزرگ نیستند. ما از متدهای GET و POST پشتیبانی می‌کنیم. برای عبور پارامترها در درخواست‌های API بات از رشته جستجوی URL یا application/json یا application/x-www-form-urlencoded یا multipart/form-data استفاده کنید.
در صورت فراخوانی موفق، یک شیء JSON-که شامل نتیجه باشد بازگردانده می‌شود.

getMe

یک روش ساده برای آزمایش توکن احراز هویت بات شما. هیچ پارامتری نیاز ندارد. اطلاعات پایه درباره بات را به‌صورت یک شیء User بازمی گرداند.

logOut

از این روش برای خروج از سرور API بات ابری قبل از راه‌اندازی بات به‌صورت محلی استفاده کنید. قبل از اجرای محلی باید بات را خارج کنید، در غیر این صورت تضمینی وجود ندارد که بات به‌روزرسانی دریافت کند. پس از تماس موفق، می‌توانید بلافاصله روی سرور محلی وارد شوید، اما تا ۱۰ دقیقه نمی‌توانید دوباره وارد سرور API بات ابری شوید. True را پس از موفقیت برمی گرداند. نیازی به پارامترها ندارد.

close

از این روش برای بستن نمونه بات قبل از انتقال آن از یک سرور محلی به سرور دیگر استفاده کنید. قبل از فراخوانی این متد باید webhook را حذف کنید تا مطمئن شوید بات پس از راه‌اندازی مجدد سرور دوباره اجرا نمی‌شود. این روش در ۱۰ دقیقه اول پس از راه‌اندازی بات خطای ۴۲۹ را بازمی گرداند. True را هنگام موفقیت برمی گرداند. نیازی به پارامترها ندارد.

sendMessage

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

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چت هدف یا نام کاربری در قالب @username
text	String	Yes	متن پیام ارسالی، 1-4096 کاراکتر پس از Entities Parsing
parse_mode	String	Optional	حالت برای Entities Parsingدر متن پیام. برای جزئیات بیشتر به گزینه‌های قالب‌بندی مراجعه کنید.
entities	Array of MessageEntity	Optional	فهرستی JSON-SERIALIZED شده از موجودیت‌های ویژه که در متن پیام ظاهر می‌شوند و می‌توان آن‌ها را به جای parse_mode مشخص کرد.
reply_markup	InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply	Optional	گزینه‌های رابط کاربری اضافی. یک شیء سریال سازی شده JSON برای صفحه‌کلید inline ، ReplyMarkup ، دستورالعمل حذف صفحه‌کلید پاسخ یا اجبار پاسخ از کاربر.
disable_web_page_preview	Boolean	Optional	پیش‌نمایش لینک‌ها در این پیام را غیرفعال می‌کند
reply_to_message_id	Integer	Optional	اگر پیام پاسخ باشد، شناسه پیام اصلی
allow_sending_without_reply	Boolean	Optional	True اگر پیام حتی در صورت پیدا نشدن پیام پاسخ‌داده‌شده ارسال شود

گزینه‌های قالب‌بندی

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

توجه داشته باشید که کلاینت‌های سروش‌پلاس قبل از باز کردن لینک inline («این لینک را باز کنید؟» همراه با آدرس کامل URL) هشدار به کاربر نمایش می‌دهند.

موجودیت‌های پیام می‌توانند تو در تو باشند، به شرطی که محدودیت‌های زیر رعایت شوند:
- اگر دو موجودیت کاراکتر مشترک داشته باشند، یکی از آن‌ها کاملاً درون دیگری قرار دارد.
-bold، italic، underline، strikethrough و spoiler موجودیت می‌توانند شامل و بخشی از هر موجودیت دیگری باشند، به جز pre و code.
- همه موجودات دیگر نمی‌توانند یکدیگر را نگه دارند.

می‌توانید فهرست زبان‌های برنامه‌نویسی و نشانه‌گذاری که برجسته‌سازی نحو آن‌ها پشتیبانی می‌شود را در libprisma#supported-languages پیدا کنید.

قالب‌بندی موجودیت تاریخ-زمان

قالب‌بندی موجودیت تاریخ-زمان توسط یک رشته قالب مشخص می‌شود که باید به عبارت منظم زیر پایبند باشد:r|w?[dD]?[tT]?.

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

r: زمان را نسبت به زمان فعلی نمایش می‌دهد. نمی‌توان آن را با هیچ کاراکتر کنترلی دیگری ترکیب کرد.
w: روز هفته را به زبان بومی شده کاربر نمایش می‌دهد.
d: تاریخ را به‌صورت کوتاه نمایش می‌دهد (مثلاً «17.03.22»).
D: تاریخ را به‌صورت طولانی نمایش می‌دهد (مثلاً «۱۷ مارس ۲۰۲۲»).
t: زمان را به‌صورت کوتاه نمایش می‌دهد (مثلاً «۲۲:۴۵»).
T: زمان را به‌صورت طولانی نمایش می‌دهد (مثلاً «۲۲:۴۵:۰۰»).

سبک MarkdownV2

برای استفاده از این حالت، MarkdownV2 را در فیلد parse_mode ارسال کنید. از syntax زیر در پیام خود استفاده کنید:

*bold \*text*
_italic \*text_
__underline__
~strikethrough~
||spoiler||
*bold _italic bold ~italic bold strikethrough ||italic bold strikethrough spoiler||~ __underline italic bold___ bold*
[inline URL](http://www.example.com/)
`inline fixed-width code`
```
pre-formatted fixed-width code block
```
```python
pre-formatted fixed-width code block written in the Python programming language
```
>Block quotation started
>Block quotation continued
>Block quotation continued
>Block quotation continued
>The last line of the block quotation
**>The expandable block quotation started right after the previous block quotation
>It is separated from the previous block quotation by an empty bold entity
>Expandable block quotation continued
>Hidden by default part of the expandable block quotation started
>Expandable block quotation continued
>The last line of the expandable block quotation with the expandability mark||

لطفاً توجه داشته باشید:

● هر کاراکتر با کد ASCII بین ۱ تا ۱۲۶ را می‌توان با قرار دادن کاراکتر Escape یعنی \ قبل از آن، از قواعد نشانه‌گذاری خارج کرد. در این حالت، کاراکتر موردنظر به‌عنوان یک کاراکتر معمولی در نظر گرفته می‌شود و بخشی از Markup نخواهد بود. بنابراین، برای نمایش خودِ کاراکتر \ نیز معمولاً باید آن را Escape کرده و به‌صورت \\ بنویسید.

● درون موجودیت‌های pre و code، تمام کاراکترهای ` و \ باید با قرار دادن \ قبل از آن‌ها Escape شوند.

● در بخش (...) مربوط به لینک‌های Inline و تعریف Custom Emoji، کاراکترهای ) و \ باید با قرار دادن \ قبل از آن‌ها Escape شوند.

● در سایر بخش‌های متن، کاراکترهای _، *، [، ]، (، )، ~، `، >، #، +، -، =، |، {، }، . و ! باید با قرار دادن \ قبل از آن‌ها Escape شوند.

● در صورت وجود ابهام بین موجودیت‌های italic و underline، توالی __ همواره به‌صورت حریصانه و از چپ به راست، به‌عنوان شروع یا پایان یک موجودیت underline در نظر گرفته می‌شود. بنابراین، در چنین شرایطی باید ساختار متن را به‌گونه‌ای تنظیم کنید که مرز بین این دو نوع قالب‌بندی به‌صورت صریح مشخص باشد.

سبک HTML

برای استفاده از این حالت، HTML را در فیلد parse_mode پاس دهید. تگ‌‌های زیر در حال حاضر پشتیبانی می‌شوند:

<b>bold</b>, <strong>bold</strong>
<i>italic</i>, <em>italic</em>
<u>underline</u>, <ins>underline</ins>
<s>strikethrough</s>, <strike>strikethrough</strike>, <del>strikethrough</del>
<b>bold <i>italic bold <s>italic bold strikethrough italic bold strikethrough spoiler</s> <u>underline italic bold</u></i> bold</b>
<a href="http://www.example.com/">inline URL</a>
<code>inline fixed-width code</code>
<pre>pre-formatted fixed-width code block</pre>
<pre><code class="language-python">pre-formatted fixed-width code block written in the Python programming language</code></pre>
<blockquote>Block quotation started
Block quotation continued
The last line of the block quotation</blockquote>
<blockquote expandable>Expandable block quotation started
Expandable block quotation continued
Expandable block quotation continued
Hidden by default part of the block quotation started
Expandable block quotation continued
The last line of the block quotation</blockquote>

لطفاً توجه داشته باشید:

● در حال حاضر فقط تگ‌های ذکرشده در بالا پشتیبانی می‌شوند.

● تمام کاراکترهای <، > و & که بخشی از یک تگ یا HTML Entity نیستند، باید با Entity متناظر جایگزین شوند: < با <، > با > و & با &.

● تمام HTML Entityهای عددی پشتیبانی می‌شوند.

● در حال حاضر API فقط از HTML Entityهای نام‌گذاری‌شده‌ی <، >، & " پشتیبانی می‌کند.

● برای مشخص‌کردن زبان برنامه‌نویسی در یک موجودیت pre، از تگ‌های pre و code به‌صورت تو‌در‌تو استفاده کنید.

● برای تگ مستقل code نمی‌توان زبان برنامه‌نویسی مشخص کرد.

سبک Markdown

این یک حالت قدیمی است که برای سازگاری با نسخه‌های قبلی حفظ شده است. برای استفاده از این حالت، Markdown را در فیلد parse_mode ارسال کنید. از نحو زیر در پیام خود استفاده کنید:

*bold text*
_italic text_
[inline URL](http://www.example.com/)
`inline fixed-width code`
```
pre-formatted fixed-width code block
```
```python
pre-formatted fixed-width code block written in the Python programming language
```

لطفاً توجه داشته باشید:

موجودیت‌ها نباید تو در تو باشند، به جای آن از حالت تجزیه MarkdownV2 استفاده کنید.
هیچ راهی برای مشخص کردن «underline»، «strikethrough»، «spoiler»، «blockquote»، «expandable_blockquote»، «custom_emoji» و «date_time» وجود ندارد، به جای آن از حالت تجزیه MarkdownV2 استفاده کنید.
برای فرار از شخصیت‌های '_'، '*'، '''، '[' خارج از یک موجود، شخصیت '\' را قبل از آن‌ها قرار دهید.
فرار از داخل موجودیت‌ها مجاز نیست، بنابراین ابتدا باید موجودیت بسته و دوباره باز شود: برای snake_case ایتالیک از _snake_\__case_ و برای بولد 2*2=4 از*2*\**2=4*استفاده کنید.

forwardMessage

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

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چت هدف قالب @username
from_chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چتی که پیام اصلی در آن ارسال شده است (قالب @username)
message_id	Integer	Yes	شناسه پیام در چت مشخص شده در from_chat_id

copyMessage

یک poll آزمون فقط زمانی قابل کپی است که مقدار فیلد correct_option_ids برای بات شناخته شده باشد. این روش مشابه روش forwardMessage است، اما پیام کپی شده لینکی به پیام اصلی ندارد. MessageId پیام ارسال شده را هنگام موفقیت بازمی گرداند.

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چت هدف در قالب @username
from_chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چتی که پیام اصلی در آن ارسال شده است (یا نام کاربری بات در قالب @username
message_id	Integer	Yes	شناسه پیام در چت مشخص شده در from_chat_id
caption	String	Optional	کپشن جدید برای رسانه، ۰ تا ۱۰۲۴ کاراکتر پس از تجزیه موجودیت. اگر مشخص نشده باشد، کپشن اصلی حفظ می‌شود.
parse_mode	String	Optional	حالت Entities Parsingدر کپشن جدید. برای جزئیات بیشتر گزینه‌های قالب‌بندی را ببینید.
caption_entities	Array of MessageEntity	Optional	یک فهرست JSON سریالی از موجودیت‌های ویژه که در کپشن جدید ظاهر می‌شوند و می‌توان آن‌ها را به جای parse_mode مشخص کرد.
reply_markup	InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply	Optional	گزینه‌های رابط کاربری اضافی. یک شیء سریال سازی شده JSON برای صفحه‌کلید inline ، ReplyMarkup ، دستورالعمل حذف صفحه‌کلید پاسخ یا اجبار پاسخ از کاربر.

sendPhoto

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

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چت هدف قالب @username
photo	InputFile or String	Yes	عکس برای ارسال. یک file_id را به‌صورت رشته ارسال کنید تا عکسی که روی سرورهای سروش‌پلاس موجود است ارسال شود (توصیه می‌شود)، یک آدرس HTTP را به‌صورت رشته ای برای سروش‌پلاس ارسال کنید تا عکس را از اینترنت دریافت کند، یا عکس جدیدی با استفاده از داده‌های multipart/form-data آپلود کنید. اندازه عکس باید حداکثر ۱۰ مگابایت باشد. عرض و ارتفاع عکس نباید در مجموع از ۱۰۰۰۰ مگابایت تجاوز کند. نسبت عرض و ارتفاع باید حداکثر ۲۰ باشد. اطلاعات بیشتر درباره ارسال فایل‌ها »
caption	String	Optional	کپشن عکس (ممکن است هنگام ارسال مجدد عکس‌ها توسط file_id نیز استفاده شود)، ۰ تا ۱۰۲۴ کاراکتر پس از Entities Parsing
parse_mode	String	Optional	حالت برای Entities Parsing در کپشن عکس. برای جزئیات بیشتر به گزینه‌های قالب‌بندی مراجعه کنید.
caption_entities	Array of MessageEntity	Optional	یک فهرست JSON-SERIALIZEDاز موجودیت‌های ویژه که در کپشن ظاهر می‌شوند و می‌توان آن‌ها را به جای parse_mode مشخص کرد
reply_markup	InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply	Optional	گزینه‌های رابط کاربری اضافی. یک شیء سریال سازی شده JSON برای صفحه‌کلید inline ، ReplyMarkup ، دستورالعمل حذف صفحه‌کلید پاسخ یا اجبار پاسخ از کاربر.

sendAudio

از این روش برای ارسال فایل‌های صوتی استفاده کنید، اگر می‌خواهید کلاینت‌های سروش‌پلاس آن‌ها را در پخش کننده موسیقی نمایش دهند. صدای شما باید در فرمت. MP3 یا. M4A باشد. در صورت موفقیت، Message ارسال شده بازگردانده می‌شود. بات‌ها در حال حاضر می‌توانند فایل‌های صوتی تا ۵۰ مگابایت ارسال کنند، این محدودیت ممکن است در آینده تغییر کند.

برای ارسال پیام صوتی، به جای آن از روش sendVoice استفاده کنید.

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چت هدف در قالب @username
audio	InputFile or String	Yes	فایل صوتی برای ارسال. یک file_id به‌صورت رشته ارسال کنید تا فایل صوتی موجود روی سرورهای سروش‌پلاس ارسال شود (توصیه می‌شود)، یک آدرس HTTP را به‌صورت رشته ارسال کنید تا سروش‌پلاس فایل صوتی را از اینترنت دریافت کند، یا فایل جدیدی با استفاده از داده‌های multipart/form-data آپلود کنید. اطلاعات بیشتر درباره ارسال فایل‌ها »
caption	String	Optional	کپشن صوتی، ۰-۱۰۲۴ کاراکتر پس از Entities Parsing
parse_mode	String	Optional	حالت برای Entities Parsing در کپشن صوتی. برای جزئیات بیشتر به گزینه‌های قالب‌بندی مراجعه کنید.
caption_entities	Array of MessageEntity	Optional	یک فهرست JSON-SERIALIZEDاز موجودیت‌های ویژه که در کپشن ظاهر می‌شوند و می‌توان آن‌ها را به جای parse_mode مشخص کرد
duration	Integer	Optional	مدت زمان صدا بر حسب ثانیه
performer	String	Optional	performer
title	String	Optional	نام Track
thumb	InputFile	Optional	تصویر Thumbnail فایل ارسال شده؛ اگر تولید تصویر Thumbnail فایل در سمت سرور پشتیبانی شود، می‌تواند نادیده گرفته شود. تصویر Thumbnail باید در قالب JPEG و کمتر از ۲۰۰ kB حجم داشته باشد. عرض و ارتفاع تصویر Thumbnail نباید از ۳۲۰ کیلوبایت تجاوز کند. اگر فایل با استفاده از داده‌های multipart/form-data بارگذاری نشده باشد، نادیده گرفته می‌شود. تصاویر Thumbnail قابل استفاده مجدد نیستند و فقط به‌صورت فایل جدید بارگذاری می‌شوند، بنابراین اگر تصویر Thumbnail با استفاده از داده‌های multipart/form-data تحت <file_attach_name> بارگذاری شده باشد، می‌توانید «attach://<file_attach_name>» را منتقل کنید. اطلاعات بیشتر درباره ارسال فایل‌ها »
reply_markup	InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply	Optional	گزینه‌های رابط کاربری اضافی. یک شیء سریال سازی شده JSON برای صفحه‌کلید inline ، ReplyMarkup ، دستورالعمل حذف صفحه‌کلید پاسخ یا اجبار پاسخ از کاربر.

sendDocument

از این روش برای ارسال فایل‌های عمومی استفاده کنید. در صورت موفقیت، Message ارسال شده بازگردانده می‌شود. بات‌ها در حال حاضر می‌توانند فایل‌هایی با هر نوع تا ۵۰ مگابایت حجم ارسال کنند، این محدودیت ممکن است در آینده تغییر کند.

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چت هدف قالب @username
document	InputFile or String	Yes	فایل برای ارسال. ارسال فایل file_id به‌صورت رشته برای ارسال فایلی که روی سرورهای سروش‌پلاس وجود دارد (توصیه می‌شود)، ارسال یک آدرس HTTP به‌صورت رشته برای دریافت فایل از اینترنت، یا بارگذاری فایل جدید با استفاده از داده‌های multipart/form-data. اطلاعات بیشتر درباره ارسال فایل‌ها »
thumb	InputFile	Optional	تصویر Thumbnail فایل ارسال شده؛ اگر تولید تصویر Thumbnail فایل در سمت سرور پشتیبانی شود، می‌تواند نادیده گرفته شود. تصویر Thumbnail باید در قالب JPEG و کمتر از ۲۰۰ kB حجم داشته باشد. عرض و ارتفاع تصویر Thumbnail نباید از ۳۲۰ کیلوبایت تجاوز کند. اگر فایل با استفاده از داده‌های multipart/form-data بارگذاری نشده باشد، نادیده گرفته می‌شود. تصاویر Thumbnail قابل استفاده مجدد نیستند و فقط به‌صورت فایل جدید بارگذاری می‌شوند، بنابراین اگر تصویر Thumbnail با استفاده از داده‌های multipart/form-data تحت <file_attach_name> بارگذاری شده باشد، می‌توانید «attach://<file_attach_name>» را منتقل کنید. اطلاعات بیشتر درباره ارسال فایل‌ها »
caption	String	Optional	عنوان سند (ممکن است هنگام ارسال مجدد اسناد توسط file_id نیز استفاده شود)، ۰ تا ۱۰۲۴ کاراکتر پس از Entities Parsing
parse_mode	String	Optional	حالت Entities Parsingدر کپشن سند. برای جزئیات بیشتر به گزینه‌های قالب‌بندی مراجعه کنید.
caption_entities	Array of MessageEntity	Optional	یک فهرست JSON-SERIALIZEDاز موجودیت‌های ویژه که در کپشن ظاهر می‌شوند و می‌توان آن‌ها را به جای parse_mode مشخص کرد
disable_content_type_detection	Boolean	Optional	تشخیص خودکار نوع محتوا در سمت سرور برای فایل‌هایی که با استفاده از داده‌های multipart/form-data شده اند را غیرفعال می‌کند
reply_markup	InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply	Optional	گزینه‌های رابط کاربری اضافی. یک شیء سریال سازی شده JSON برای صفحه‌کلید inline ، ReplyMarkup ، دستورالعمل حذف صفحه‌کلید پاسخ یا اجبار پاسخ از کاربر.

sendVideo

از این روش برای ارسال فایل‌های ویدیویی استفاده کنید، کلاینت‌های سروش‌پلاس از ویدیوهای MPEG4 پشتیبانی می‌کنند (فرمت‌های دیگر ممکن است به‌صورت Document ارسال شوند). در صورت موفقیت، Message ارسال شده بازگردانده می‌شود. بات‌ها در حال حاضر می‌توانند فایل‌های ویدیویی تا ۵۰ مگابایت ارسال کنند، این محدودیت ممکن است در آینده تغییر کند.

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چت هدف قالب @username
video	InputFile or String	Yes	ویدیو برای ارسال. ارسال یک file_id به‌صورت رشته برای ارسال ویدیویی که روی سرورهای سروش‌پلاس وجود دارد (توصیه می‌شود)، ارسال یک آدرس HTTP به‌صورت رشته برای سروش‌پلاس جهت دریافت ویدیو از اینترنت، یا بارگذاری ویدیوی جدید با استفاده از داده‌های multipart/form-data. اطلاعات بیشتر درباره ارسال فایل‌ها »
duration	Integer	Optional	مدت زمان ویدئوی ارسال شده بر حسب ثانیه
width	Integer	Optional	عرض ویدئو
height	Integer	Optional	ارتفاع ویدئو
thumb	InputFile	Optional	تصویر Thumbnail فایل ارسال شده؛ اگر تولید تصویر Thumbnail فایل در سمت سرور پشتیبانی شود، می‌تواند نادیده گرفته شود. تصویر Thumbnail باید در قالب JPEG و کمتر از ۲۰۰ kB حجم داشته باشد. عرض و ارتفاع تصویر Thumbnail نباید از ۳۲۰ کیلوبایت تجاوز کند. اگر فایل با استفاده از داده‌های multipart/form-data بارگذاری نشده باشد، نادیده گرفته می‌شود. تصاویر Thumbnail قابل استفاده مجدد نیستند و فقط به‌صورت فایل جدید بارگذاری می‌شوند، بنابراین اگر تصویر Thumbnail با استفاده از داده‌های multipart/form-data تحت <file_attach_name> بارگذاری شده باشد، می‌توانید «attach://<file_attach_name>» را منتقل کنید. اطلاعات بیشتر درباره ارسال فایل‌ها »
caption	String	Optional	کپشن ویدیو (ممکن است هنگام ارسال مجدد ویدیوها توسط file_id نیز استفاده شود)، ۰ تا ۱۰۲۴ کاراکتر پس از Entities Parsing
parse_mode	String	Optional	حالت Entities Parsingدر کپشن ویدیو. برای جزئیات بیشتر به گزینه‌های قالب‌بندی مراجعه کنید.
caption_entities	Array of MessageEntity	Optional	یک فهرست JSON-SERIALIZEDاز موجودیت‌های ویژه که در کپشن ظاهر می‌شوند و می‌توان آن‌ها را به جای parse_mode مشخص کرد
supports_streaming	Boolean	Optional	اگر ویدیوی آپلود شده برای استریم مناسب است، True را رد کنید
reply_markup	InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply	Optional	گزینه‌های رابط کاربری اضافی. یک شیء سریال سازی شده JSON برای صفحه‌کلید inline ، ReplyMarkup ، دستورالعمل حذف صفحه‌کلید پاسخ یا اجبار پاسخ از کاربر.

sendAnimation

از این روش برای ارسال فایل‌های انیمیشن (GIF یا ویدئوی H.264/MPEG-4 AVC بدون صدا) استفاده کنید. در صورت موفقیت، Message ارسال شده بازگردانده می‌شود. بات‌ها در حال حاضر می‌توانند فایل‌های انیمیشنی تا ۵۰ مگابایت ارسال کنند، این محدودیت ممکن است در آینده تغییر کند.

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چت هدف قالب @username
animation	InputFile or String	Yes	انیمیشن برای ارسال. ارسال یک file_id به‌صورت رشته برای ارسال انیمیشنی که روی سرورهای سروش‌پلاس وجود دارد (توصیه می‌شود)، ارسال یک آدرس اینترنتی HTTP به‌صورت رشته برای سروش‌پلاس جهت دریافت انیمیشن از اینترنت، یا آپلود انیمیشن جدید با استفاده از داده‌های multipart/form-data‌ها. اطلاعات بیشتر درباره ارسال فایل‌ها »
duration	Integer	Optional	مدت زمان انیمیشن ارسال شده بر حسب ثانیه
width	Integer	Optional	عرض انیمیشن
height	Integer	Optional	ارتفاع انیمیشن
thumb	InputFile	Optional	تصویر Thumbnail فایل ارسال شده؛ اگر تولید تصویر Thumbnail فایل در سمت سرور پشتیبانی شود، می‌تواند نادیده گرفته شود. تصویر Thumbnail باید در قالب JPEG و کمتر از ۲۰۰ kB حجم داشته باشد. عرض و ارتفاع تصویر Thumbnail نباید از ۳۲۰ کیلوبایت تجاوز کند. اگر فایل با استفاده از داده‌های multipart/form-data بارگذاری نشده باشد، نادیده گرفته می‌شود. تصاویر Thumbnail قابل استفاده مجدد نیستند و فقط به‌صورت فایل جدید بارگذاری می‌شوند، بنابراین اگر تصویر Thumbnail با استفاده از داده‌های multipart/form-data تحت <file_attach_name> بارگذاری شده باشد، می‌توانید «attach://<file_attach_name>» را منتقل کنید. اطلاعات بیشتر درباره ارسال فایل‌ها »
caption	String	Optional	کپشن انیمیشن (ممکن است هنگام بازارسال انیمیشن توسط file_id نیز استفاده شود)، ۰ تا ۱۰۲۴ کاراکتر پس از Entities Parsing
parse_mode	String	Optional	حالت برای Entities Parsingدر کپشن انیمیشن. برای جزئیات بیشتر گزینه‌های قالب‌بندی را ببینید.
caption_entities	Array of MessageEntity	Optional	یک فهرست JSON-SERIALIZEDاز موجودیت‌های ویژه که در کپشن ظاهر می‌شوند و می‌توان آن‌ها را به جای parse_mode مشخص کرد
reply_markup	InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply	Optional	گزینه‌های رابط کاربری اضافی. یک شیء سریال سازی شده JSON برای صفحه‌کلید inline ، ReplyMarkup ، دستورالعمل حذف صفحه‌کلید پاسخ یا اجبار پاسخ از کاربر.

sendVoice

از این روش برای ارسال فایل‌های صوتی استفاده کنید، اگر می‌خواهید کلاینت‌های سروش‌پلاس فایل را به‌صورت پیام صوتی قابل پخش نمایش دهند. برای اینکه این کار انجام شود، صدای شما باید در فایل. OGG کدگذاری شده با OPUS، یا به فرمت. MP3 یا در قالب باشد. M4A (فرمت‌های دیگر ممکن است به‌صورت Audio یا Document ارسال شوند). در صورت موفقیت، Message ارسال شده بازگردانده می‌شود. بات‌ها در حال حاضر می‌توانند پیام صوتی تا اندازه ۵۰ مگابایت ارسال کنند، این محدودیت ممکن است در آینده تغییر کند.

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چت هدف قالب @username
voice	InputFile or String	Yes	فایل صوتی برای ارسال. ارسال یک file_id به‌صورت رشته برای ارسال فایلی که روی سرورهای سروش‌پلاس وجود دارد (توصیه می‌شود)، ارسال یک آدرس HTTP به‌صورت رشته برای سروش‌پلاس جهت دریافت فایل از اینترنت، یا آپلود فایل جدید با استفاده از داده‌های multipart/form-data‌ها. اطلاعات بیشتر درباره ارسال فایل‌ها »
caption	String	Optional	توضیح پیام صوتی، ۰ تا ۱۰۲۴ کاراکتر پس از Entities Parsing
parse_mode	String	Optional	حالت برای Entities Parsingدر توضیح پیام صوتی. برای جزئیات بیشتر به گزینه‌های قالب‌بندی مراجعه کنید.
caption_entities	Array of MessageEntity	Optional	یک فهرست JSON-SERIALIZED از موجودیت‌های ویژه که در کپشن ظاهر می‌شوند و می‌توان آن‌ها را به جای parse_mode مشخص کرد
duration	Integer	Optional	مدت زمان پیام صوتی به ثانیه
reply_markup	InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply	Optional	گزینه‌های رابط کاربری اضافی. یک شیء سریال سازی شده JSON برای صفحه‌کلید inline ، ReplyMarkup ، دستورالعمل حذف صفحه‌کلید پاسخ یا اجبار پاسخ از کاربر.

sendVideoNote

از نسخه ۴.۰، کلاینت‌های سروش‌پلاس از ویدیوهای MPEG4 مربعی گرد تا ۱ دقیقه پشتیبانی می‌کنند. از این روش برای ارسال پیام‌های ویدیویی استفاده کنید. در صورت موفقیت، Message ارسال شده بازگردانده می‌شود.

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چت هدف قالب @username
video_note	InputFile or String	Yes	یادداشت ویدیویی برای ارسال. یک file_id به‌صورت رشته ارسال کنید تا یادداشت ویدیویی موجود روی سرورهای سروش‌پلاس ارسال شود (توصیه می‌شود) یا ویدیوی جدیدی با استفاده از داده‌های multipart/form-data آپلود کنید. اطلاعات بیشتر درباره ارسال فایل‌ها ». ارسال یادداشت‌های ویدیویی از طریق URL در حال حاضر پشتیبانی نمی‌شود.
duration	Integer	Optional	مدت زمان ویدئوی ارسال شده بر حسب ثانیه
length	Integer	Optional	عرض و ارتفاع ویدئو، یعنی قطر پیام ویدیویی
thumb	InputFile	Optional	تصویر Thumbnail فایل ارسال شده؛ اگر تولید تصویر Thumbnail فایل در سمت سرور پشتیبانی شود، می‌تواند نادیده گرفته شود. تصویر Thumbnail باید در قالب JPEG و کمتر از ۲۰۰ kB حجم داشته باشد. عرض و ارتفاع تصویر Thumbnail نباید از ۳۲۰ کیلوبایت تجاوز کند. اگر فایل با استفاده از داده‌های multipart/form-data بارگذاری نشده باشد، نادیده گرفته می‌شود. تصاویر Thumbnail قابل استفاده مجدد نیستند و فقط به‌صورت فایل جدید بارگذاری می‌شوند، بنابراین اگر تصویر Thumbnail با استفاده از داده‌های multipart/form-data تحت <file_attach_name> بارگذاری شده باشد، می‌توانید «attach://<file_attach_name>» را منتقل کنید. اطلاعات بیشتر درباره ارسال فایل‌ها »
reply_markup	InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply	Optional	گزینه‌های رابط کاربری اضافی. یک شیء سریال سازی شده JSON برای صفحه‌کلید inline ، ReplyMarkup ، دستورالعمل حذف صفحه‌کلید پاسخ یا اجبار پاسخ از کاربر.

sendMediaGroup

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

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چت هدف قالب @username
media	Array of InputMediaAudio, InputMediaDocument, InputMediaLivePhoto, InputMediaPhoto and InputMediaVideo	Yes	یک آرایه JSON-SERIALIZED شده که پیام‌های ارسالی را توصیف می‌کند، باید شامل ۲ تا ۱۰ مورد باشد

sendLocation

از این روش برای ارسال نقطه روی نقشه استفاده کنید. در صورت موفقیت، Message ارسال شده بازگردانده می‌شود.

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چت هدف قالب @username
latitude	Float	Yes	عرض جغرافیایی محل
longitude	Float	Yes	طول جغرافیایی محل
horizontal_accuracy	Float	Optional	شعاع عدم قطعیت برای مکان، که بر حسب متر اندازه گیری می‌شود؛ 0-1500
reply_markup	InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply	Optional	گزینه‌های رابط کاربری اضافی. یک شیء سریال سازی شده JSON برای صفحه‌کلید inline ، ReplyMarkup ، دستورالعمل حذف صفحه‌کلید پاسخ یا اجبار پاسخ از کاربر.

sendContact

از این روش برای ارسال مخاطبین تلفنی استفاده کنید. در صورت موفقیت، Message ارسال شده بازگردانده می‌شود.

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چت هدف قالب @username
phone_number	String	Yes	شماره تلفن مخاطب
first_name	String	Yes	نام کوچک تماس
last_name	String	Optional	نام خانوادگی تماس
vcard	String	Optional	داده‌های اضافی درباره تماس به‌صورت vCard، 0-2048 بایت
reply_markup	InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply	Optional	گزینه‌های رابط کاربری اضافی. یک شیء سریال سازی شده JSON برای صفحه‌کلید inline ، ReplyMarkup ، دستورالعمل حذف صفحه‌کلید پاسخ یا اجبار پاسخ از کاربر.

sendDice

از این روش برای ارسال یک ایموجی متحرک استفاده کنید که مقدار تصادفی نمایش می‌دهد. در صورت موفقیت، Message ارسال شده بازگردانده می‌شود.

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چت هدف قالب @username
emoji	String	Optional	ایموجی ای که انیمیشن پرتاب تاس بر اساس آن است. در حال حاضر، باید یکی از «»، «»، «» یا «» باشد. تاس‌ها می‌توانند مقادیر ۱ تا ۶ برای «»، «» و «» داشته باشند، مقادیر ۱ تا ۵ برای «» و «» و مقادیر ۱ تا ۶۴ برای «». پیش‌فرض به «».
reply_markup	InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply	Optional	گزینه‌های رابط کاربری اضافی. یک شیء سریال سازی شده JSON برای صفحه‌کلید inline ، ReplyMarkup ، دستورالعمل حذف صفحه‌کلید پاسخ یا اجبار پاسخ از کاربر.

sendChatAction (به‌زودی)

این روش را زمانی استفاده کنید که باید به کاربر اطلاع دهید که اتفاقی در سمت بات در حال رخ دادن است. وضعیت برای ۵ ثانیه یا کمتر تنظیم می‌شود (وقتی پیامی از بات شما می‌رسد، کلاینت‌های سروش‌پلاس وضعیت تایپ آن را پاک می‌کنند). با موفقیت True را برمی گرداند.

مثال:ImageBot نیاز دارد تا درخواست را پردازش کرده و تصویر را بارگذاری کند. به جای ارسال پیامک با مضمون «در حال بازیابی تصویر، لطفاً صبر کنید...»، بات ممکن است از sendChatAction با action=upload_photo استفاده کند. کاربر وضعیت «ارسال عکس» را برای بات مشاهده خواهد کرد.

ما توصیه می‌کنیم فقط زمانی از این روش استفاده کنید که پاسخ بات زمان قابل توجهی برای رسیدن داشته باشد.

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چت هدف در قالب @username. گفتگوهای کانال و پیام‌های مستقیم کانال پشتیبانی نمی‌شوند.
action	String	Yes	نوع عملی برای پخش. بسته به اینکه کاربر قرار است چه چیزی دریافت کند، یکی را انتخاب کنید:typing برای پیامک، upload_photo برای photos، record_video یا upload_video برای videos، record_voice یا upload_voice برای یادداشت‌های صوتی، upload_document برای فایل‌های عمومی، choose_sticker برای stickers، find_location برای داده‌های موقعیت، record_video_note یا upload_video_note برای یادداشت‌های ویدیویی.

getUserProfilePhotos (به‌زودی)

از این روش برای دریافت فهرستی از عکس‌های پروفایل برای کاربر استفاده کنید. یک شیء UserProfilePhotos را برمی گرداند.

پارامتر	نوع	الزامی	توضیحات
user_id	Integer	Yes	شناسه منحصر به فرد کاربر هدف
offset	Integer	Optional	شماره متوالی اولین عکسی که بازگردانده می‌شود. به‌طور پیش‌فرض، همه عکس‌ها بازگردانده می‌شوند.
limit	Integer	Optional	تعداد عکس‌هایی که باید بازیابی شوند را محدود می‌کند. مقادیر بین ۱ تا ۱۰۰ پذیرفته می‌شوند. پیش‌فرض روی ۱۰۰ است.

getFile

از این روش برای به دست آوردن اطلاعات پایه درباره یک فایل و آماده سازی آن برای دانلود استفاده کنید. در حال حاضر، بات‌ها می‌توانند فایل‌هایی با اندازه تا ۲۰ مگابایت دانلود کنند. در صورت موفقیت، یک شیء File بازگردانده می‌شود. سپس فایل را می‌توان از طریق لینک https://api.splus.ir/file/bot<token>/<file_path> دانلود کرد که <file_path> از پاسخ گرفته می‌شود. تضمین شده است که لینک حداقل به مدت ۱ ساعت معتبر خواهد بود. وقتی لینک منقضی می‌شود، می‌توان با تماس مجدد getFile درخواست لینک جدید کرد.

پارامتر	نوع	الزامی	توضیحات
file_id	String	Yes	شناسه فایل برای دریافت اطلاعات درباره

توجه: این تابع ممکن است نام فایل و نوع MIME اصلی را حفظ نکند. هنگام دریافت شیء فایل، باید نوع و نام MIME فایل (در صورت وجود) را ذخیره کنید.

pinChatMessage (به‌زودی)

از این روش برای افزودن پیام به فهرست پیام‌های سنجاق شده در چت استفاده کنید. در گفتگوهای خصوصی می‌توانند پین شوند. True را پس از موفقیت بازمی گرداند.

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چت هدف یا نام کاربری کانال هدف در قالب @username
message_id	Integer	Yes	شناسه پیامی که باید پین شود

unpinChatMessage (به‌زودی)

از این روش برای حذف پیام از فهرست پیام‌های سنجاق شده در چت استفاده کنید. در گفتگوهای خصوصی همه پیام‌ها می‌توانند از حالت پین خارج شوند. True را پس از موفقیت بازمی گرداند.

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چت هدف در قالب @username
message_id	Integer	Optional	شناسه پیام برای باز کردن پین. اگر مشخص شده business_connection_id لازم است. اگر مشخص نشده باشد، آخرین پیام سنجاق شده (بر اساس تاریخ ارسال) از پین خارج خواهد شد.

getChat (به‌زودی)

از این روش برای به دست آوردن اطلاعات به روز درباره چت استفاده کنید. یک شیء ChatFullInfo را هنگام موفقیت بازمی گرداند.

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چت هدف در قالب @username

answerCallbackQuery

از این روش برای ارسال پاسخ به callback queries که از inline keyboards ارسال می‌شوند استفاده کنید. پاسخ به‌صورت اعلان در بالای صفحه چت یا به‌صورت هشدار به کاربر نمایش داده می‌شود. در صورت موفقیت، True بازگردانده می‌شود.

پارامتر	نوع	الزامی	توضیحات
callback_query_id	String	Yes	شناسه یکتا برای پاسخ به پرس‌وجو
text	String	Optional	متن اعلان. اگر مشخص نشود، هیچ چیزی به کاربر نشان داده نمی‌شود، از صفر تا ۲۰۰ کاراکتر.
show_alert	Boolean	Optional	اگر True شود، به جای اعلان در بالای صفحه چت، یک هشدار توسط کلاینت نمایش داده می‌شود. پیش‌فرض روی False است.
url	String	Optional	آدرسی که توسط کلاینت کاربر باز خواهد شد.
cache_time	Integer	Optional	حداکثر مدت زمانی که نتیجه پرس وجوی callback می‌تواند در سمت کلاینت کش شود.

setMyCommands

از این روش برای تغییر فهرست دستورات بات استفاده کنید. برای جزئیات بیشتر درباره دستورات بات به این دفترچه مراجعه کنید. True را هنگام موفقیت برمی گرداند.

پارامتر	نوع	الزامی	توضیحات
commands	Array of BotCommand	Yes	یک فهرست JSON-SERIALIZED شده از دستورات بات که باید به عنوان فهرست دستورات بات تنظیم شود. حداکثر می‌توان ۱۰۰ فرمان مشخص کرد.
scope	BotCommandScope	Optional	یک شیء JSON-SERIALIZED سازی شده که دامنه کاربرانی را که دستورات مرتبط با آن‌ها هستند توصیف می‌کند. پیش‌فرض روی BotCommandScopeDefault است.
language_code	String	Optional	یک کد زبانی دو حرفی ISO 639-1. اگر خالی باشد، دستورات به همه کاربران از محدوده داده شده اعمال می‌شود، زیرا برای زبان آن‌ها هیچ دستور اختصاصی وجود ندارد.

deleteMyCommands

از این روش برای حذف فهرست دستورات بات برای دامنه داده شده و زبان کاربر استفاده کنید. پس از حذف کردن، دستورات سطح بالاتر به کاربران تحت تأثیر نمایش داده می‌شوند. True را هنگام موفقیت بازمی گرداند.

پارامتر	نوع	الزامی	توضیحات
scope	BotCommandScope	Optional	یک شیء JSON-SERIALIZED سازی شده که دامنه کاربرانی را که دستورات مرتبط با آن‌ها هستند توصیف می‌کند. پیش‌فرض روی BotCommandScopeDefault است.
language_code	String	Optional	یک کد زبانی دو حرفی ISO 639-1. اگر خالی باشد، دستورات به همه کاربران از محدوده داده شده اعمال می‌شود، زیرا برای زبان آن‌ها هیچ دستور اختصاصی وجود ندارد.

getMyCommands

از این روش برای به دست آوردن فهرست فعلی دستورات بات برای دامنه و زبان کاربری داده شده استفاده کنید. یک آرایه از BotCommand شیء را بازمی گرداند. اگر دستورات تنظیم نشده باشند، یک لیست خالی بازگردانده می‌شود.

پارامتر	نوع	الزامی	توضیحات
scope	BotCommandScope	Optional	یک شیء JSON-SERIALIZED شده، که دامنه کاربران را توصیف می‌کند. پیش‌فرض روی BotCommandScopeDefault است.
language_code	String	Optional	یک کد زبانی دو حرفی ISO 639-1 یا یک رشته خالی

به‌روزرسانی پیام‌ها

روش‌های زیر به شما اجازه می‌دهند پیام موجود در تاریخچه پیام را تغییر دهید به جای اینکه پیام جدیدی با نتیجه یک اقدام ارسال کنید. این روش بیشتر برای پیام‌هایی با صفحه‌کلید inline و استفاده از درخواست‌های callback مفید است، اما همچنین می‌تواند به کاهش شلوغی گفتگوها با بات‌های چت معمولی کمک کند.

لطفاً توجه داشته باشید که در حال حاضر فقط امکان ویرایش پیام‌ها بدون reply_markup یا با کیبوردهای inline وجود دارد.

editMessageText

از این روش برای ویرایش پیام‌های متنی استفاده کنید. در صورت موفقیت، اگر پیام ویرایش شده پیام inline نباشد، Message ویرایش شده بازگردانده می‌شود، در غیر این صورت True بازگردانده می‌شود.

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Optional	اگر مشخص نشده inline_message_id لازم است. شناسه منحصر به فرد برای چت هدف قالب @username.
message_id	Integer	Optional	اگر مشخص نشده inline_message_id الزامی است. شناسه پیام برای ویرایش.
text	String	Optional	متن جدید پیام، 1-4096 کاراکتر پس از تجزیه موجودیت؛
parse_mode	String	Optional	حالت برای Entities Parsingدر متن پیام. برای جزئیات بیشتر به گزینه‌های قالب‌بندی مراجعه کنید.
entities	Array of MessageEntity	Optional	فهرستی JSON-SERIALIZED شده از special entities که در متن پیام ظاهر می‌شوند و می‌توان آن‌ها را به جای parse_mode مشخص کرد.
reply_markup	InlineKeyboardMarkup	Optional	یک شیء JSON-SERIALIZED شده برای inline keyboard
disable_web_page_preview	Boolean	Optional	پیش‌نمایش لینک‌ها در این پیام را غیرفعال می‌کند

editMessageCaption

از این روش برای ویرایش کپشن پیام‌ها استفاده کنید. در صورت موفقیت، اگر پیام ویرایش شده پیام inline نباشد، Message ویرایش شده بازگردانده می‌شود، در غیر این صورت True بازگردانده می‌شود.

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Optional	اگر مشخص نشده inline_message_id لازم است. شناسه منحصر به فرد برای چت هدف قالب @username.
message_id	Integer	Optional	اگر مشخص نشده inline_message_id الزامی است. شناسه پیام برای ویرایش.
caption	String	Optional	کپشن جدید پیام، ۰ تا ۱۰۲۴ کاراکتر پس از Entities Parsing
parse_mode	String	Optional	حالت Entities Parsingدر کپشن پیام. برای جزئیات بیشتر به گزینه‌های قالب‌بندی مراجعه کنید.
caption_entities	Array of MessageEntity	Optional	یک فهرست JSON-SERIALIZEDاز موجودیت‌های ویژه که در کپشن ظاهر می‌شوند و می‌توان آن‌ها را به جای parse_mode مشخص کرد
reply_markup	InlineKeyboardMarkup	Optional	یک شیء JSON-SERIALIZED شده برای inline keyboard

editMessageMedia

از این روش برای ویرایش انیمیشن، صدا، سند، عکس زنده، عکس یا ویدئو یا جایگزینی متن با یک رسانه استفاده کنید. اگر پیامی بخشی از آلبوم پیام باشد، فقط می‌توان آن را به صوت آلبوم‌های صوتی، فقط به سند برای آلبوم‌های سند و به عکس، عکس زنده یا ویدئو ویرایش کرد. وقتی پیام inline ویرایش می‌شود، فایل جدیدی قابل بارگذاری نیست؛ از فایل بارگذاری شده قبلی از طریق file_id آن استفاده کنید. در صورت موفقیت، اگر پیام ویرایش شده پیام inline نباشد، Message ویرایش شده بازگردانده می‌شود، در غیر این صورت True بازگردانده می‌شود.

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Optional	اگر مشخص نشده inline_message_id لازم است. شناسه منحصر به فرد برای چت هدف قالب @username.
message_id	Integer	Optional	اگر مشخص نشده inline_message_id الزامی است. شناسه پیام برای ویرایش.
media	InputMedia	Yes	یک شیء JSON-SERIALIZED شده برای محتوای رسانه‌های جدید پیام
reply_markup	InlineKeyboardMarkup	Optional	یک شیء JSON-SERIALIZED سازی شده برای یک inline keyboard جدید

editMessageReplyMarkup

از این روش برای ویرایش فقط نشانه‌گذاری پاسخ پیام‌ها استفاده کنید. در صورت موفقیت، اگر پیام ویرایش شده پیام inline نباشد، Message ویرایش شده بازگردانده می‌شود، در غیر این صورت True بازگردانده می‌شود.

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Optional	اگر مشخص نشده inline_message_id لازم است. شناسه منحصر به فرد برای چت هدف قالب @username.
message_id	Integer	Optional	اگر مشخص نشده inline_message_id الزامی است. شناسه پیام برای ویرایش.
reply_markup	InlineKeyboardMarkup	Optional	یک شیء JSON-SERIALIZED شده برای inline keyboard

deleteMessage

از این روش برای حذف یک پیام با محدودیت‌های زیر استفاده کنید:
- یک پیام فقط در صورتی قابل حذف است که کمتر از ۴۸ ساعت پیش ارسال شده باشد.
- بات‌ها می‌توانند پیام‌های ورودی را در گفتگوهای خصوصی حذف کنند.
بازگشت True با موفقیت.

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چت هدف قالب @username
message_id	Integer	Yes	شناسه پیام برای حذف

استیکرها

روش‌ها و اشیای زیر به بات شما اجازه می‌دهد استیکرها و مجموعه‌های استیکر را مدیریت کند.

Sticker

این شیء نمایانگر یک استیکر است.

فیلد	نوع	توضیحات
file_id	String	شناسه این فایل که می‌تواند برای دانلود یا استفاده مجدد از فایل استفاده شود
file_unique_id	String	شناسه یکتا برای این فایل که قرار است در طول زمان و برای بات‌های مختلف یکسان باشد. نمی‌توان از آن برای دانلود یا استفاده مجدد فایل استفاده کرد.
width	Integer	عرض استیکر
height	Integer	ارتفاع استیکر
is_animated	Boolean	True اگر استیکر انیمیشن باشد
is_video	Boolean	True اگر استیکر یک استیکر ویدئویی باشد
thumb	PhotoSize	Optional. تصویر کوچک استیکر در قالب. WEBP یا. JPG
emoji	String	Optional. ایموجی مرتبط با استیکر
set_name	String	Optional. نام مجموعه استیکر که استیکر به آن تعلق دارد
mask_position	MaskPosition	Optional. برای استیکرهای ماسک، محل قرار دادن ماسک
file_size	Integer	Optional. اندازه فایل بر حسب بایت

StickerSet

این شیء نمایانگر یک مجموعه استیکر است.

فیلد	نوع	توضیحات
name	String	نام مجموعه استیکر
title	String	عنوان مجموعه استیکر
stickers	Array of Sticker	فهرست تمام استیکرهای مجموعه
thumb	PhotoSize	Optional. تصویر Thumbnail مجموعه استیکر در. وب،. TGS، یا. فرمت WEBM

MaskPosition

این شیء موقعیت روی سطوح را توصیف می‌کند که ماسک باید به‌طور پیش‌فرض در آن قرار گیرد.

فیلد	نوع	توضیحات
point	String	بخشی از صورت که ماسک باید نسبت به آن قرار گیرد. یکی از «forehead»، «eyes»، «mouth» یا «chin».
x_shift	Float	شیفت با محوری X که به عرض ماسک مقیاس شده بر اساس اندازه صورت، از چپ به راست اندازه گیری می‌شود. برای مثال، انتخاب -1.0 ماسک را درست در سمت چپ موقعیت پیش‌فرض ماسک قرار می‌دهد.
y_shift	Float	شیفت توسط محور Y که بر حسب ارتفاع ماسک مقیاس شده بر اساس اندازه صورت، از بالا به پایین اندازه گیری می‌شود. برای مثال، نسخه 1.0 ماسک را درست زیر موقعیت پیش‌فرض ماسک قرار می‌دهد.
scale	Float	ضریب مقیاس پذیری ماسک. برای مثال، ۲.۰ یعنی اندازه دو برابر.

sendSticker

از این روش برای ارسال استاتیک استفاده کنید. WEBP، انیمیشنی. TGS یا ویدیو. استیکرهای WEBM. پس از موفقیت، Message ارسال شده بازگردانده می‌شود.

پارامتر	نوع	الزامی	توضیحات
chat_id	Integer or String	Yes	شناسه منحصر به فرد برای چت هدف قالب @username
sticker	InputFile or String	Yes	استیکر برای ارسال. یک file_id به‌صورت رشته ارسال کنید تا فایلی که روی سرورهای سروش‌پلاس وجود دارد ارسال شود (توصیه می‌شود)، یک آدرس HTTP را به‌صورت رشته برای سروش‌پلاس ارسال کنید تا استیکر. WEBP از اینترنت دریافت کند، یا یک استیکر جدید. WEBP،. TGS یا. استیکر WEBM با استفاده از داده‌های multipart/form-data آپلود شود. اطلاعات بیشتر درباره ارسال فایل‌ها ». استیکرهای ویدیویی و متحرک را نمی‌توان از طریق آدرس HTTP ارسال کرد.
reply_markup	InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply	Optional	گزینه‌های رابط کاربری اضافی. یک شیء سریال سازی شده JSON برای صفحه‌کلید inline ، ReplyMarkup ، دستورالعمل حذف صفحه‌کلید پاسخ یا اجبار پاسخ از کاربر.

getStickerSet (به‌زودی)

از این روش برای به دست آوردن مجموعه استیکر استفاده کنید. در صورت موفقیت، یک شیء StickerSet بازگردانده می‌شود.

پارامتر	نوع	الزامی	توضیحات
name	String	Yes	نام مجموعه استیکرها