مدل ها

Chat

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

فیلد	نوع	توضیحات
chat_id	string	شناسه چت
chat_type	ChatTypeEnum	نوع چت (کاربر، گروه، کانال و …).
user_id	string	شناسه کاربر مقابل بات در چت‌های خصوصی است. (فقط در چت‌های خصوصی).
first_name	string	نام کاربر. (فقط در چت‌های خصوصی).
last_name	string	نام خانوادگی کاربر
title	string	عنوان گروه یا کانال (در چت‌های گروهی و کانال‌ها).
username	string	نام کاربری چت یا کاربر (در صورت تنظیم شدن).

توجه: بسته به نوع چت، برخی فیلدها ممکن است مقدار null داشته باشند.

File

نشان‌دهنده‌ی اطلاعات یک فایل است که در پیام‌ها استفاده می‌شود.

فیلد	نوع	توضیحات
file_id	string	شناسه فایل
file_name	string	نام فایل
size	string	حجم فایل (بر حسب بایت)

ForwardedFrom

اطلاعات مربوط به پیام‌های فوروارد شده (Forwarded) را نمایش می‌دهد. این مدل در فیلد forwarded_from داخل مدل Message قرار می‌گیرد و نشان می‌دهد پیام از چه نوع منبعی، از کجا و توسط چه کسی فوروارد شده است

فیلد	نوع	توضیحات
type_from	ForwardedFromEnum	نوع منبع فوروارد (کاربر، کانال یا بات).
message_id	string	شناسه پیام اصلی که فوروارد شده.
from_chat_id	string	شناسه چت مبدا که پیام از آن فوروارد شده.
from_sender_id	string	شناسه کاربری ارسال‌کننده‌ی اصلی پیام.

MessageTextUpdate

مدل MessageTextUpdate تغییرات متنی پیام‌ها را نمایش می‌دهد که در نتیجه تعامل کاربر با Inline Keypad رخ داده است. این مدل فقط در داده‌های ارسالی به وب‌هوک بات هنگام فعال شدن receiveInlineMessage بازگردانده می‌شود و برای اطلاع بات از پیام‌هایی است که متن آن‌ها به دنبال این تعامل تغییر کرده است.

فیلد	نوع	توضیحات
message_id	string	شناسه پیام که متن آن تغییر کرده است.
text	string	متن جدید پیام پس از به‌روزرسانی.

توجه: این مدل توسط کاربر مستقیماً فراخوانی نمی‌شود و تنها زمانی فعال می‌شود که کاربر روی Inline Keypad کلیک کند و سرور روبیکا یک درخواست POST حاوی شیء InlineMessage به وب‌هوک شما ارسال نماید.

Bot

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

فیلد	نوع	توضیحات
bot_id	string	شناسه یکتا بات
bot_title	string	عنوان نمایش‌داده‌شده در پروفایل بات
avatar	File	تصویر پروفایل بات
description	string	توضیحات بات
username	string	نام‌کاربری بات
start_message	string	پیامی که هنگام شروع مکالمه با بات به کاربر نشان داده می‌شود
share_url	string	لینک قابل اشتراک‌گذاری بات برای دعوت کاربران

BotCommand

مدل BotCommand برای تعریف دستورهای (Commands) قابل استفاده در بات به‌کار می‌رود. این دستورات همان مواردی هستند که کاربر می‌تواند با / در چت بات وارد کند و معمولاً در لیست دستورات پیشنهادی بات نمایش داده می‌شوند.

فیلد	نوع	توضیحات
command	string	نام دستور بدون / (مثلاً start)
description	string	توضیح کوتاه درباره عملکرد دستور

Sticker

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

فیلد	نوع	توضیحات
sticker_id	string	شناسه استیکر
file	File	اطلاعات فایل استیکر
emoji_character	string	اموجی مرتبط با استیکر

ContactMessage

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

فیلد	نوع	توضیحات
phone_number	string	شماره تلفن ارسال‌شده توسط کاربر.
first_name	string	نام شخص صاحب شماره.
last_name	string	نام خانوادگی شخص (در صورت موجود).

PollStatus

نشان‌دهنده‌ی وضعیت فعلی یک نظرسنجی (Poll) است.

فیلد	نوع	توضیحات
state	PollStatusEnum	وضعیت فعلی نظرسنجی
selection_index	int	شماره گزینه انتخاب‌شده توسط کاربر؛ در صورت عدم انتخاب، مقدار -1 بازگردانده می‌شود.
percent_vote_options	list[int]	درصد رأی‌های هر گزینه در نظرسنجی.
total_vote	int	تعداد کل آراء نظرسنجی
show_total_votes	bool	آیا تعداد آرا باید به کاربر نمایش داده شود یا خیر.

Poll

مدل Poll برای نمایش اطلاعات یک نظرسنجی استفاده می‌شود، شامل سؤال نظرسنجی، گزینه‌ها و وضعیت فعلی رأی‌دهی.

فیلد	نوع	توضیحات
question	string	متن سؤال نظرسنجی.
options	list[string]	آرایه‌ای از گزینه‌های قابل رأی‌دهی
poll_status	PollStatus	وضعیت جاری نظرسنجی

Location

مدل Location نمایانگر مختصات جغرافیایی (GIS) است.

فیلد	نوع	توضیحات
longitude	string	طول جغرافیایی
latitude	string	عرض جغرافیایی

ButtonSelectionItem

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

فیلد	نوع	توضیحات
text	string	متن دکمه
image_url	string	آدرس تصویر مرتبط با گزینه (در صورت وجود).
type	ButtonSelectionTypeEnum	نوع نمایش دکمه

ButtonSelection

تنظیمات کامل یک دکمه‌ی انتخاب را پیام مشخص می‌کند. این مدل برای دکمه‌هایی با type = Selection به‌کار می‌رود و شامل داده‌های لیست گزینه‌ها، نحوه‌ی نمایش، انتخاب چندگانه و شناسه‌ی انتخاب است.

فیلد	نوع	توضیحات
selection_id	string	شناسه مربوط به لیست
search_type	ButtonSelectionSearchEnum	نحوه‌ی جستجو
get_type	ButtonSelectionGetEnum	نحوه‌ی دریافت آیتم‌ها (مثلاً آفلاین/سینک با سرور).
items	list[ButtonSelectionItem]	آرایه‌ای از ButtonSelectionItem ها
is_multi_selection	bool	تعیین می‌کند که کاربر می‌تواند چند گزینه انتخاب کند یا تنها یک گزینه.
columns_count	string	تعداد ستون‌هایی که آیتم‌ها در آن نمایش داده می‌شوند.
title	string	عنوان

ButtonCalendar

تنظیمات دکمه‌ی انتخاب تاریخ را پیام تعریف می‌کند.

فیلد	نوع	توضیحات
default_value	Optional[string]	مقدار پیش‌فرض تقویم. تاریخی که در ابتدا به کاربر نمایش داده می‌شود.
type	ButtonCalendarTypeEnum	نوع تقویم (تقویم شمسی یا میلادی).
min_year	string	حداقل سال قابل انتخاب در تقویم.
max_year	string	بیشینه سال قابل انتخاب در تقویم.
title	string	عنوان دکمه

ButtonNumberPicker

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

فیلد	نوع	توضیحات
min_value	string	حداقل مقدار قابل انتخاب.
max_value	string	بیشینه مقدار قابل انتخاب.
default_value	Optional[string]	مقدار پیشفرض
title	string	عنوان دکمه

ButtonStringPicker

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

فیلد	نوع	توضیحات
items	list[string]	آرایه‌ای از رشته‌ها — گزینه‌های قابل انتخاب.
default_value	Optional[string]	مقدار پیشفرض
title	Optional[string]	عنوان دکمه

ButtonTextbox

تنظیمات یک دکمه‌ی ورودی متن را پیام تعریف می‌کند

فیلد	نوع	توضیحات
type_line	ButtonTextboxTypeLineEnum	تعیین می‌کند ورودی متن به صورت تک‌خطی یا چندخطی باشد.
type_keypad	ButtonTextboxTypeKeypadEnum	نوع صفحه‌کلید نمایش داده‌شده برای ورودی متن (رشته‌ای یا عددی).
place_holder	Optional[string]	متن placeholder که در فیلد ورودی نمایش داده می‌شود.
title	Optional[string]	عنوان دکمه
default_value	Optional[string]	مقدار پیشفرض

ButtonLocation

تنظیمات یک دکمه‌ی ورودی مکان را پیام تعریف می‌کند، شامل موقعیت‌های پیش‌فرض و نوع نمایش نقشه.

فیلد	نوع	توضیحات
default_pointer_location	Location	مختصات نقطه‌ی پیش‌فرض در نقشه.
default_map_location	Location	مختصات مرکز نقشه در نمای اولیه.
type	ButtonLocationTypeEnum	نوع تعامل نقشه (انتخاب یا مشاهده).
title	Optional[string]	عنوان دکمه

AuxData

برای نگهداری داده‌های کمکی مرتبط با پیام‌ها استفاده می‌شود و معمولاً در رویدادهای کلیک روی دکمه‌ها (در Update یا وب‌هوک) بازگردانده می‌شود

فیلد	نوع	توضیحات
start_id	string	شناسه‌ی شروع تعامل کاربر با بات که در صورت ورود کاربر از طریق لینک دارای پارامتر st مقداردهی می‌شود. این مقدار همان مقداری است که در لینک بات ارسال شده و در رویدادهای دریافتی Webhook از قابل دسترسی است.
button_id	string	شناسه دکمه‌ای که کاربر روی آن کلیک کرده است(در صورت وجود).

Button

مدل Button نمایانگر یک دکمه تعاملی در رابط کاربری پیام یا صفحه‌کلید بات است. دکمه‌ها می‌توانند در Inline Keypad (دکمه‌های شیشه‌ای زیر پیام) یا Chat Keypad (دکمه‌های کلید پایین پیام) نمایش داده شوند و برای ایجاد تعامل‌های مختلف (عملیات، انتخاب، ورودی کاربر، ارسال موقعیت و…) استفاده می‌شوند.

فیلد	نوع	توضیحات
id	string	شناسه دکمه
type	ButtonTypeEnum	نوع دکمه که مشخص می‌کند رفتار و شکل نمایش آن چگونه است.
button_text	string	متن نمایش‌داده‌شده روی دکمه.
button_selection	ButtonSelection	داده‌های مربوط به دکمه لیست انتخابی.
button_calendar	ButtonCalendar	داده‌های مربوط به دکمه تقویم.
button_number_picker	ButtonNumberPicker	داده‌های مربوط به دکمه انتخاب عدد.
button_string_picker	ButtonStringPicker	داده‌های مربوط به دکمه انتخاب رشته.
button_location	ButtonLocation	داده‌های مربوط به دکمه موقعیت.
button_textbox	ButtonTextbox	داده‌های مربوط به دکمه متن ورودی.

توجه: فیلدهای button_selection، button_calendar، button_number_picker، button_string_picker، button_location و button_textbox تنها زمانی پر می‌شوند که نوع دکمه (type) با همان مدل سازگار باشد.

ButtonTypeEnum

این Enum انواع مختلف رفتار و هدف دکمه را مشخص می‌کند.

فیلد	نوع	توضیحات
Simple	string	دکمه معمولی با متن ثابت.
Selection	string	دکمه‌ای برای نمایش لیست انتخابی.
Calendar	string	نمایش دکمه به صورت تقویم
NumberPicker	string	دکمه‌ای برای انتخاب عدد از محدودهٔ مشخص.
StringPicker	string	دکمه‌ای برای انتخاب مقدار از لیست رشته‌ها.
Location	string	دکمه‌ای برای اشتراک‌گذاری موقعیت مکانی.
CameraImage	string	دکمه‌ای برای گرفتن عکس با دوربین.
CameraVideo	string	دکمه‌ای برای گرفتن ویدئو با دوربین.
GalleryImage	string	دکمه‌ای برای انتخاب عکس از گالری.
GalleryVideo	string	دکمه‌ای برای انتخاب ویدئو از گالری.
File	string	دکمه‌ای برای انتخاب فایل.
Audio	string	دکمه‌ای برای انتخاب فایل صوتی.
RecordAudio	string	دکمه‌ای برای ضبط صدا.
Textbox	string	دکمه‌ای برای باز کردن ورودی متن.
Link	string	دکمه‌ای برای باز کردن لینک.
AskMyPhoneNumber	string	دکمه‌ای برای درخواست شماره تلفن کاربر.
AskMyLocation	string	دکمه‌ای برای درخواست موقعیت کاربر.
Barcode	string	دکمه‌ای برای اسکن بارکد.

KeypadRow

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

فیلد	نوع	توضیحات
buttons	list[Button]	آرایه‌ای از دکمه‌ها

نکته: ترتیب قرارگیری دکمه‌ها در آرایه، ترتیب نمایش افقی کلیدها را تعیین می‌کند.

Keypad

مدل Keypad مجموعه‌ای از ردیف‌های دکمه را تعریف می‌کند که می‌تواند در Keypad پیام (Inline یا Chat) نمایش داده شود.

فیلد	نوع	توضیحات
rows	list[KeypadRow]	آرایه‌ای از ردیف keypad ها
resize_keyboard	bool	تغییر اندازه و ارتفاع دکمه‌ها
one_time_keyboard	bool	بسته شدن خودکار کیبورد بعد از اولین انتخاب

MessageKeypadUpdate

مدل MessageKeypadUpdate برای به‌روزرسانی Inline Keypad پیام‌ها در پاسخ به رویداد کلیک کاربر روی Inline Keypad استفاده می‌شود. این مدل تنها در خروجی وب‌هوک receiveInlineMessage و به‌عنوان بخشی از پاسخ بات به پلتفرم بازگردانده می‌شود.

فیلد	نوع	توضیحات
message_id	string	شناسه‌ی پیام که Keypad آن تغییر یافته است.
inline_keypad	Keypad	Keypad جدید که باید جایگزین Keypad قبلی شود.

Message

مدل Message نمایانگر اطلاعات یک پیام در روبیکا است که می‌تواند شامل متن، فایل، موقعیت جغرافیایی، نظرسنجی.... و دیگر داده‌های مرتبط باشد. این مدل معمولاً در خروجی متدهای دریافت پیام (مانند getUpdates یا داده‌های وب‌هوک) و همچنین در پاسخ‌های بات استفاده می‌شود.

فیلد	نوع	توضیحات
message_id	string	شناسه پیام
text	string	متن پیام — اگر پیام متنی باشد.
time	int	زمان ارسال پیام به صورت timestamp.
is_edited	bool	نشان می‌دهد آیا پیام ویرایش شده است یا خیر.
sender_type	MessageSenderEnum	نوع فرستنده پیام
sender_id	string	شناسه فرستنده پیام
aux_data	AuxData	داده‌های کمکی مرتبط با پیام
file	File	اطلاعات فایل پیوست (اگر پیام شامل فایل باشد)
reply_to_message_id	string	شناسه پیام قبلی که این پیام در پاسخ به آن ارسال شده است.
forwarded_from	ForwardedFrom	اطلاعات اصلی پیام فوروارد شده (در صورت وجود).
forwarded_no_link	string	متنی که به‌جای لینک حساب کاربری فرستنده نمایش داده می‌شود، در صورتی که فرستنده اجازه لینک شدن به حساب خود را غیرفعال کرده باشد.
location	Location	موقعیت جغرافیایی ارسال‌شده (اگر پیام موقعیت داشته باشد).
sticker	Sticker	اطلاعات استیکر (در صورت وجود).
contact_message	ContactMessage	اطلاعات تماس اگر پیام حاوی Contact باشد.
poll	Poll	اطلاعات نظرسنجی اگر پیام شامل Poll باشد.

Update

نمایانگر رویدادی است که از سوی API یا وب‌هوک به بات می‌رسد و شامل داده‌های مرتبط با پیام‌ها و تغییرات آن‌ها می‌باشد.

فیلد	نوع	توضیحات
type	UpdateTypeEnum	نوع رویداد آپدیت (مثل پیام جدید، پیام ویرایش‌شده، حذف پیام و …).
chat_id	string	شناسه چت مرتبط با رویداد.
removed_message_id	Optional[string]	شناسه‌ی پیام حذف‌شده (در رویداد حذف پیام).
new_message	Message	پیام جدید در این رویداد (اگر نوع رویداد پیام جدید باشد).
updated_message	Optional[Message]	پیام ویرایش‌شده (در رویداد ویرایش پیام).

InlineMessage

داده‌های مربوط به کلیک کاربر روی Inline Keypad را در وب‌هوک receiveInlineMessage نمایش می‌دهد و شامل شناسه پیام و چت، داده‌های کمکی، متن و اطلاعات رسانه‌ای است.

فیلد	نوع	توضیحات
sender_id	string	شناسه کاربری که روی Inline Keypad کلیک کرده است.
text	string	متن پیام مرتبط (اگر وجود داشته باشد).
file	Optional[File]	فایل همراه پیام (اگر وجود داشته باشد).
location	Optional[Location]	موقعیت جغرافیایی (در صورت وجود).
aux_data	Optional[AuxData]	داده‌های کمکی مرتبط با کلیک دکمه.
message_id	string	شناسه پیام اصلی که InlineKeypad آن را نشان می‌دهد.
chat_id	string	شناسه چت مرتبط با پیام Inline.

Enums

---

ChatTypeEnum

فیلد	توضیحات
User	چت با کاربر
Bot	چت با ربات
Group	چت در گروه
Channel	چت در کانال

FileTypeEnum

فیلد	توضیحات
File	فایل‌های عمومی با حداکثر حجم 50 مگابایت.
Image	عکس با فرمت jpg، gif، png یا webp با حداکثر حجم 10 مگابایت.
Voice	پیام صوتی کوتاه با فرمت mp3.
Video	فیلم با فرمت mp4 با حداکثر حجم 50 مگابایت.
Music	آهنگ با فرمت mp3.
Gif	تصویر متحرک با فرمت mp4 که حتماً باید بدون صدا باشد.

ForwardedFromEnum

فیلد	توضیحات
User	پیام از یک کاربر فوروارد شده است.
Channel	پیام از یک کانال فوروارد شده است.
Bot	پیام از یک بات فوروارد شده است.

فیلد	توضیحات
Paid	پرداخت شده
NotPaid	پرداخت نشده

PollStatusEnum

فیلد	توضیحات
Open	نظرسنجی در حال اجرا و قابل رأی دادن است.
Closed	نظرسنجی پایان یافته و رأی‌دهی بسته است.

ButtonSelectionTypeEnum

فیلد	توضیحات
TextOnly	نمایش دکمه به صورت متن
TextImgThu	نمایش دکمه به صورت متن و عکس کوچک
TextImgBig	نمایش دکمه به صورت متن و عکس بزرگ

ButtonSelectionSearchEnum

فیلد	توضیحات
None	حالت پیشفرض
Local	جستجو در آیتم‌های لیست با استفاده از مقادیر ارسالی در فیلد items
Api	جستجو در آیتم‌های لیست از طریق Api

ButtonSelectionGetEnum

فیلد	توضیحات
Local	نمایش آیتم‌های لیست با استفاده از مقادیر ارسالی در فیلد items
Api	جستجو در آیتم‌های لیست از طریق Api

ButtonCalendarTypeEnum

فیلد	توضیحات
DatePersian	نمایش تقویم به فرمت شمسی
DateGregorian	نمایش تقویم به فرمت میلادی

ButtonTextboxTypeKeypadEnum

فیلد	نوع	توضیحات
String	string	امکان ارسال تمامی کاراکتر ها
Number	string	امکان ارسال کاراکترها عددی

ButtonTextboxTypeLineEnum

فیلد	نوع	توضیحات
SingleLine	string	نوشتن پیام متنی در یک سطر
MultiLine	string	نوشتن پیام متنی در چندین سطر

ButtonLocationTypeEnum

فیلد	توضیحات
Picker	به کاربر اجازه می‌دهد موقعیت را انتخاب کند (Picker).
View	موقعیت به صورت نمایشی نشان داده می‌شود (View).

MessageSenderEnum

فیلد	توضیحات
User	کاربر
Bot	بات

UpdateTypeEnum

فیلد	توضیحات
UpdatedMessage	ویرایش پیام
NewMessage	پیام جدید
RemovedMessage	حذف پیام
StartedBot	شروع بات
StoppedBot	توقف بات

ChatKeypadTypeEnum

فیلد	توضیحات
None	مقدار پیشفرض
New	اضافه کردن keypad جدید
Remove	حذف keypad

UpdateEndpointTypeEnum

فیلد	توضیحات
ReceiveUpdate	ReceiveUpdate
ReceiveInlineMessage	ReceiveInlineMessage
ReceiveQuery	ReceiveQuery
GetSelectionItem	GetSelectionItem
SearchSelectionItems	SearchSelectionItems