{ "openapi": "3.1.0", "info": { "title": "Vispa Bot Platform API", "version": "2.0.0", "description": "Authenticated bot messaging for independently opted-in private chat members. UTF-8 byte limits apply. Invoke each method at its dedicated /v2/ path on the public bot API host." }, "servers": [ { "url": "https://bots.vispaco.net", "description": "Canonical public bot API host." } ], "paths": { "/v2/getMe": { "post": { "operationId": "getMe", "summary": "مشخصات ربات", "description": "اعتبار توکن و مشخصات ربات فعلی را بررسی می‌کند. ", "tags": [ "identity" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getMeRequest" } } } }, "responses": { "200": { "description": "شیء شامل id، is_bot، username، display_name و description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getMeResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/getChat": { "post": { "operationId": "getChat", "summary": "اطلاعات گفت‌وگو", "description": "اطلاعات گفت‌وگو و وضعیت عضویت همین کاربر در همین ربات را برمی‌گرداند. این متد مجوز ارسال ایجاد نمی‌کند؛ فقط عضویت موجود را می‌خواند.", "tags": [ "identity" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getChatRequest" } } } }, "responses": { "200": { "description": "شیء شامل id، type=private، status، started_at و stopped_at.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getChatResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/getChatMember": { "post": { "operationId": "getChatMember", "summary": "وضعیت عضویت", "description": "اطلاعات گفت‌وگو و وضعیت عضویت همین کاربر در همین ربات را برمی‌گرداند. این متد مجوز ارسال ایجاد نمی‌کند؛ فقط عضویت موجود را می‌خواند.", "tags": [ "identity" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getChatMemberRequest" } } } }, "responses": { "200": { "description": "شیء شامل id، type=private، status، started_at و stopped_at.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getChatMemberResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/getUpdates": { "post": { "operationId": "getUpdates", "summary": "دریافت رویداد با polling", "description": "رویدادهای تأییدنشده را به ترتیب update_id برمی‌گرداند؛ این متد long polling نیست. تا پیش از تأیید ممکن است رویداد دوباره برگردد. هنگام فعال بودن وب‌هوک، خطای WEBHOOK_ACTIVE با HTTP 409 دریافت می‌کنید.", "tags": [ "updates" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getUpdatesRequest" } } } }, "responses": { "200": { "description": "آرایه Update شامل update_id و message، membership یا callback_query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getUpdatesResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/setWebhook": { "post": { "operationId": "setWebhook", "summary": "تنظیم وب‌هوک", "description": "ارسال رویدادها به یک نشانی عمومی HTTPS را فعال می‌کند. هدر X-Vispa-Bot-Secret-Token را با secret_token خود به‌صورت امن مقایسه کنید. پس از پذیرش رویداد پاسخ 2xx بدهید. تحویل دست‌کم یک‌بار است و تلاش مجدد با فاصله افزایشی انجام می‌شود؛ بر اساس update_id از پردازش تکراری جلوگیری کنید.", "tags": [ "updates" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/setWebhookRequest" } } } }, "responses": { "200": { "description": "true در صورت ثبت موفق.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/setWebhookResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/deleteWebhook": { "post": { "operationId": "deleteWebhook", "summary": "حذف وب‌هوک", "description": "دریافت با وب‌هوک را متوقف می‌کند و امکان polling را باز می‌کند. ", "tags": [ "updates" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deleteWebhookRequest" } } } }, "responses": { "200": { "description": "true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deleteWebhookResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/getWebhookInfo": { "post": { "operationId": "getWebhookInfo", "summary": "وضعیت وب‌هوک", "description": "نشانی وب‌هوک، شمار رویدادهای منتظر و وضعیت آخرین تحویل را می‌خواند. ", "tags": [ "updates" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getWebhookInfoRequest" } } } }, "responses": { "200": { "description": "url، pending_update_count و در صورت ثبت، last_error، last_error_at و last_success_at.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getWebhookInfoResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/sendMessage": { "post": { "operationId": "sendMessage", "summary": "ارسال پیام متنی", "description": "به یک عضو فعال ربات پیام متنی می‌فرستد. Start همین ربات الزامی است. message_id خروجی را برای ویرایش یا حذف ذخیره کنید.", "tags": [ "send" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendMessageRequest" } } } }, "responses": { "200": { "description": "Message شامل message_id، chat.id، date، type و محتوای پیام.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendMessageResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/sendPhoto": { "post": { "operationId": "sendPhoto", "summary": "ارسال عکس", "description": "رسانه را به عضو فعال ربات ارسال می‌کند و پیام با بابل مخصوص همان نوع نمایش داده می‌شود. ابتدا فایل را با uploadFile بارگذاری کنید؛ نوع واقعی فایل باید با نوع این متد سازگار باشد. ویس و موسیقی از فایل صوتی استفاده می‌کنند.", "tags": [ "send" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendPhotoRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/sendPhotoMultipartRequest" } } } }, "responses": { "200": { "description": "Message شامل message_id و اطلاعات عمومی رسانه.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendPhotoResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/sendVoice": { "post": { "operationId": "sendVoice", "summary": "ارسال ویس", "description": "رسانه را به عضو فعال ربات ارسال می‌کند و پیام با بابل مخصوص همان نوع نمایش داده می‌شود. ابتدا فایل را با uploadFile بارگذاری کنید؛ نوع واقعی فایل باید با نوع این متد سازگار باشد. ویس و موسیقی از فایل صوتی استفاده می‌کنند.", "tags": [ "send" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendVoiceRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/sendVoiceMultipartRequest" } } } }, "responses": { "200": { "description": "Message شامل message_id و اطلاعات عمومی رسانه.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendVoiceResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/sendVideo": { "post": { "operationId": "sendVideo", "summary": "ارسال فیلم", "description": "رسانه را به عضو فعال ربات ارسال می‌کند و پیام با بابل مخصوص همان نوع نمایش داده می‌شود. ابتدا فایل را با uploadFile بارگذاری کنید؛ نوع واقعی فایل باید با نوع این متد سازگار باشد. ویس و موسیقی از فایل صوتی استفاده می‌کنند.", "tags": [ "send" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendVideoRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/sendVideoMultipartRequest" } } } }, "responses": { "200": { "description": "Message شامل message_id و اطلاعات عمومی رسانه.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendVideoResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/sendAudio": { "post": { "operationId": "sendAudio", "summary": "ارسال موسیقی و صوت", "description": "رسانه را به عضو فعال ربات ارسال می‌کند و پیام با بابل مخصوص همان نوع نمایش داده می‌شود. ابتدا فایل را با uploadFile بارگذاری کنید؛ نوع واقعی فایل باید با نوع این متد سازگار باشد. ویس و موسیقی از فایل صوتی استفاده می‌کنند.", "tags": [ "send" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendAudioRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/sendAudioMultipartRequest" } } } }, "responses": { "200": { "description": "Message شامل message_id و اطلاعات عمومی رسانه.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendAudioResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/sendDocument": { "post": { "operationId": "sendDocument", "summary": "ارسال فایل", "description": "فایل پاک را به عضو فعال ربات ارسال و آن را در بابل عمومی فایل نمایش می‌دهد؛ حتی اگر محتوای فایل صوت یا فیلم باشد. ابتدا فایل را با uploadFile بارگذاری کنید؛ نوع واقعی فایل باید با نوع این متد سازگار باشد. ویس و موسیقی از فایل صوتی استفاده می‌کنند.", "tags": [ "send" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendDocumentRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/sendDocumentMultipartRequest" } } } }, "responses": { "200": { "description": "Message شامل message_id و اطلاعات عمومی رسانه.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendDocumentResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/sendAnimation": { "post": { "operationId": "sendAnimation", "summary": "ارسال تصویر متحرک", "description": "رسانه را به عضو فعال ربات ارسال می‌کند و پیام با بابل مخصوص همان نوع نمایش داده می‌شود. فایل GIF پاک‌سازی‌شده به ویدئوی MP4 با kind=animation تبدیل می‌شود؛ MP4 آپلودشده معمولی از نوع video است و باید با sendVideo ارسال شود.", "tags": [ "send" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendAnimationRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/sendAnimationMultipartRequest" } } } }, "responses": { "200": { "description": "Message شامل message_id و اطلاعات عمومی رسانه.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendAnimationResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/sendMediaGroup": { "post": { "operationId": "sendMediaGroup", "summary": "ارسال آلبوم", "description": "۲ تا ۱۰ عکس یا فیلم را به‌عنوان یک آلبوم می‌فرستد. در این نسخه آلبوم، دکمه و پاسخ به پیام ندارد.", "tags": [ "send" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendMediaGroupRequest" } } } }, "responses": { "200": { "description": "آرایه Message؛ هر عضو message_id مستقل دارد.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendMediaGroupResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/sendCard": { "post": { "operationId": "sendCard", "summary": "ارسال کارت تعاملی", "description": "یک کارت ساختاریافته از نوع اطلاع‌رسانی، محصول، وضعیت یا رسید می‌فرستد. کارت رسید فقط نمایشی است؛ این متد عملیات پرداخت یا تأیید تراکنش انجام نمی‌دهد.", "tags": [ "cards" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendCardRequest" } } } }, "responses": { "200": { "description": "Message با type=card و شیء card.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendCardResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/answerCallbackQuery": { "post": { "operationId": "answerCallbackQuery", "summary": "پاسخ به کلیک دکمه", "description": "به callback_query دریافتی از کلیک کاربر پاسخ می‌دهد. دکمه callback به کاربر و پیام مشخص متصل است؛ داده callback_data دلخواه دیگران پذیرفته نمی‌شود.", "tags": [ "cards" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/answerCallbackQueryRequest" } } } }, "responses": { "200": { "description": "true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/answerCallbackQueryResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/editMessageText": { "post": { "operationId": "editMessageText", "summary": "ویرایش متن پیام", "description": "محتوای پیام قبلی همین ربات را در همان گفت‌وگو به‌روزرسانی می‌کند. فقط پیام متنی همین ربات قابل ویرایش است. عضویت فعال برای ویرایش الزامی است.", "tags": [ "edit" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/editMessageTextRequest" } } } }, "responses": { "200": { "description": "Message به‌روزشده.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/editMessageTextResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/editMessageCaption": { "post": { "operationId": "editMessageCaption", "summary": "ویرایش کپشن رسانه", "description": "محتوای پیام قبلی همین ربات را در همان گفت‌وگو به‌روزرسانی می‌کند. فقط پیام رسانه؛ برای حذف کپشن رشته خالی بفرستید. عضویت فعال برای ویرایش الزامی است.", "tags": [ "edit" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/editMessageCaptionRequest" } } } }, "responses": { "200": { "description": "Message به‌روزشده.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/editMessageCaptionResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/editMessageMedia": { "post": { "operationId": "editMessageMedia", "summary": "جایگزینی رسانه", "description": "محتوای پیام قبلی همین ربات را در همان گفت‌وگو به‌روزرسانی می‌کند. پیام متنی یا کارت به رسانه تبدیل نمی‌شود. عضویت فعال برای ویرایش الزامی است. پیام عضو آلبوم فقط می‌تواند با عکس یا فیلم جایگزین شود؛ تبدیل عضو آلبوم به ویس، صوت، فایل عمومی یا انیمیشن مجاز نیست.", "tags": [ "edit" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/editMessageMediaRequest" } } } }, "responses": { "200": { "description": "Message به‌روزشده.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/editMessageMediaResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/editMessageCard": { "post": { "operationId": "editMessageCard", "summary": "ویرایش کارت", "description": "محتوای پیام قبلی همین ربات را در همان گفت‌وگو به‌روزرسانی می‌کند. فقط پیام کارت؛ شیء کامل کارت جدید را بفرستید. عضویت فعال برای ویرایش الزامی است.", "tags": [ "edit" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/editMessageCardRequest" } } } }, "responses": { "200": { "description": "Message به‌روزشده.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/editMessageCardResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/editMessageReplyMarkup": { "post": { "operationId": "editMessageReplyMarkup", "summary": "ویرایش دکمه‌های پیام", "description": "محتوای پیام قبلی همین ربات را در همان گفت‌وگو به‌روزرسانی می‌کند. آرایه خالی inline_keyboard دکمه‌های پیام را حذف می‌کند. عضویت فعال برای ویرایش الزامی است.", "tags": [ "edit" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/editMessageReplyMarkupRequest" } } } }, "responses": { "200": { "description": "Message به‌روزشده.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/editMessageReplyMarkupResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/deleteMessage": { "post": { "operationId": "deleteMessage", "summary": "حذف پیام", "description": "یک پیام خروجی همین ربات را حذف می‌کند. حذف پیام متعلق به ربات پس از Stop هم مجاز است؛ پیام دیگران قابل حذف نیست.", "tags": [ "edit" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deleteMessageRequest" } } } }, "responses": { "200": { "description": "true؛ حذف دوباره همان پیام نیز true است.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deleteMessageResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/deleteMessages": { "post": { "operationId": "deleteMessages", "summary": "حذف چند پیام", "description": "۱ تا ۱۰۰ پیام خروجی همین ربات را در یک گفت‌وگو حذف می‌کند. تمام شناسه‌ها باید به همین ربات و chat_id تعلق داشته باشند.", "tags": [ "edit" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deleteMessagesRequest" } } } }, "responses": { "200": { "description": "true در صورت موفقیت.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deleteMessagesResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/uploadFile": { "post": { "operationId": "uploadFile", "summary": "بارگذاری امن فایل", "description": "فایل را در قرنطینه بررسی، اسکن و به قالب امن تبدیل می‌کند؛ فقط فایل پاک شناسه قابل‌ارسال می‌گیرد. پیش‌فرض سقف ۵۰ MiB و سقف سخت ۱۰۰ MiB است؛ مدیر نصب می‌تواند حد پایین‌تری تعیین کند. فایل اجرایی، HTML، SVG، آرشیو و فایل ماکرو رد می‌شوند. نوع فایل از نام و MIME واقعی تشخیص داده می‌شود؛ پارامتر kind وجود ندارد. سهمیه ذخیره‌سازی پیش‌فرض هر ربات ۱ GiB است و مدیر نصب می‌تواند آن را تغییر دهد.", "tags": [ "files" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/uploadFileRequest" } } } }, "responses": { "200": { "description": "اطلاعات فایل شامل file_id، kind، mime_type، file_name، file_size، sha256 و متادیتای موجود.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/uploadFileResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/getFile": { "post": { "operationId": "getFile", "summary": "اطلاعات فایل", "description": "اطلاعات عمومی فایل پاک و متعلق به همین ربات را می‌خواند. لینک امضاشده را محرمانه نگه دارید. برای دانلود سمت سرور می‌توانید GET یا HEAD به https://bots.vispaco.net/download.php?file_id=… با هدر Authorization: Bearer بفرستید. هر دو مسیر دانلود Range را پشتیبانی می‌کنند؛ مسیر خصوصی دیسک افشا نمی‌شود.", "tags": [ "files" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getFileRequest" } } } }, "responses": { "200": { "description": "اطلاعات عمومی File به‌همراه download_url امضاشده با اعتبار یک ساعت و expires_at به ثانیه Unix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getFileResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/getSubscribers": { "post": { "operationId": "getSubscribers", "summary": "فهرست اعضای فعال", "description": "اعضای فعال ربات را به‌صورت صفحه‌بندی‌شده برمی‌گرداند. عضویت ممکن است پس از این پاسخ تغییر کند؛ مجوز ارسال دوباره بررسی می‌شود.", "tags": [ "broadcast" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getSubscribersRequest" } } } }, "responses": { "200": { "description": "subscribers شامل chat_id و started_at، به‌همراه next_cursor یا null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getSubscribersResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/createBroadcast": { "post": { "operationId": "createBroadcast", "summary": "ساخت ارسال انبوه", "description": "ارسال متن، رسانه یا کارت را در صف ارسال انبوه ثبت می‌کند؛ ارسال با worker انجام می‌شود. مجوز هر مخاطب هنگام پردازش بررسی می‌شود. sent یعنی ثبت پیام در پیام‌رسان؛ رسید خواندن نیست. برای جلوگیری از ساخت کمپین تکراری از Idempotency-Key استفاده کنید.", "tags": [ "broadcast" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createBroadcastRequest" } } } }, "responses": { "200": { "description": "broadcast_id، status، counts، created_at و completed_at.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createBroadcastResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/getBroadcast": { "post": { "operationId": "getBroadcast", "summary": "وضعیت ارسال انبوه", "description": "وضعیت کلی و شمارش نتایج یک ارسال انبوه را می‌خواند. ", "tags": [ "broadcast" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getBroadcastRequest" } } } }, "responses": { "200": { "description": "broadcast_id، status و counts شامل queued، sent، failed و cancelled، به‌همراه زمان‌ها.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getBroadcastResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/getBroadcastRecipients": { "post": { "operationId": "getBroadcastRecipients", "summary": "نتیجه تک‌تک مخاطبان", "description": "نتیجه ارسال هر مخاطب را صفحه‌بندی‌شده می‌خواند. برای ویرایش یا حذف یک پیام انبوه، chat_id و message_id نتیجه همان مخاطب را در متد ویرایش/حذف استفاده کنید.", "tags": [ "broadcast" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getBroadcastRecipientsRequest" } } } }, "responses": { "200": { "description": "recipients شامل chat_id، status، message_id و last_error، به‌همراه next_cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getBroadcastRecipientsResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/cancelBroadcast": { "post": { "operationId": "cancelBroadcast", "summary": "لغو ارسال انبوه", "description": "ارسال‌های هنوز منتظر را لغو می‌کند. پیام‌های قبلاً ارسال‌شده حذف نمی‌شوند؛ برای حذف آن‌ها از message_id هر مخاطب استفاده کنید.", "tags": [ "broadcast" ], "security": [ { "botToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Reuse only with the exact same request; conflicting payload returns HTTP 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancelBroadcastRequest" } } } }, "responses": { "200": { "description": "true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancelBroadcastResponse" } } } }, "default": { "description": "Failure; inspect HTTP status and string error_code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/download.php": { "get": { "operationId": "downloadBotFile", "summary": "Download a clean file owned by this bot", "description": "Use Authorization: Bearer plus file_id, or the complete signed download_url returned by getFile (id, exp, sig). Signed URLs are bearer capabilities and expire after one hour. No arbitrary remote URL fetch. Supports single byte ranges.", "security": [ { "botToken": [] }, { "signedDownload": [] } ], "parameters": [ { "name": "file_id", "in": "query", "schema": { "type": "string", "pattern": "^[a-f0-9]{48}$" }, "description": "Required with Bearer authentication." }, { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "Signed URL mode only; use complete URL from getFile." }, { "name": "exp", "in": "query", "schema": { "type": "integer" }, "description": "Signed URL expiry; Unix seconds." }, { "name": "sig", "in": "query", "schema": { "type": "string" }, "description": "Signed URL HMAC; do not construct manually." }, { "name": "Range", "in": "header", "schema": { "type": "string" }, "description": "Single byte range, for example bytes=0-1023." } ], "responses": { "200": { "description": "File bytes.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Requested byte range.", "headers": { "Content-Range": { "schema": { "type": "string" } } } }, "403": { "description": "Signature or authorization rejected." }, "404": { "description": "File unavailable or does not belong to this bot." }, "416": { "description": "Invalid or unsatisfiable byte range." } } }, "head": { "operationId": "headBotFile", "summary": "Read file headers without body", "description": "Use Authorization: Bearer plus file_id, or the complete signed download_url returned by getFile (id, exp, sig). Signed URLs are bearer capabilities and expire after one hour. No arbitrary remote URL fetch. Supports single byte ranges.", "security": [ { "botToken": [] }, { "signedDownload": [] } ], "parameters": [ { "name": "file_id", "in": "query", "schema": { "type": "string", "pattern": "^[a-f0-9]{48}$" }, "description": "Required with Bearer authentication." }, { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "Signed URL mode only; use complete URL from getFile." }, { "name": "exp", "in": "query", "schema": { "type": "integer" }, "description": "Signed URL expiry; Unix seconds." }, { "name": "sig", "in": "query", "schema": { "type": "string" }, "description": "Signed URL HMAC; do not construct manually." }, { "name": "Range", "in": "header", "schema": { "type": "string" }, "description": "Single byte range, for example bytes=0-1023." } ], "responses": { "200": { "description": "File bytes.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Requested byte range.", "headers": { "Content-Range": { "schema": { "type": "string" } } } }, "403": { "description": "Signature or authorization rejected." }, "404": { "description": "File unavailable or does not belong to this bot." }, "416": { "description": "Invalid or unsatisfiable byte range." } } } } }, "components": { "securitySchemes": { "botToken": { "type": "http", "scheme": "bearer", "description": "Server-side bot token, rotated through the bot manager." }, "signedDownload": { "type": "apiKey", "in": "query", "name": "sig", "description": "Use complete signed download_url from getFile, including id and exp." } }, "schemas": { "Card": { "type": "object", "required": [ "type", "title" ], "properties": { "type": { "type": "string", "enum": [ "info", "product", "status", "receipt" ] }, "title": { "type": "string", "description": "Nonempty; max 256 UTF-8 bytes." }, "text": { "type": "string", "description": "Max 8192 UTF-8 bytes." }, "subtitle": { "type": "string", "description": "Max 512 UTF-8 bytes." }, "fields": { "type": "array", "maxItems": 12, "items": { "type": "object", "required": [ "label", "value" ], "properties": { "label": { "type": "string", "description": "Nonempty; max 128 UTF-8 bytes." }, "value": { "type": "string", "description": "Nonempty; max 1024 UTF-8 bytes." } } } } } }, "Button": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "Nonempty; max 128 UTF-8 bytes." }, "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "No embedded credentials; max 2048 UTF-8 bytes." }, "callback_data": { "type": "string", "description": "Nonempty; max 256 UTF-8 bytes." }, "copy_text": { "type": "string", "description": "Nonempty; max 256 UTF-8 bytes." } }, "oneOf": [ { "required": [ "url" ], "not": { "anyOf": [ { "required": [ "callback_data" ] }, { "required": [ "copy_text" ] } ] } }, { "required": [ "callback_data" ], "not": { "anyOf": [ { "required": [ "url" ] }, { "required": [ "copy_text" ] } ] } }, { "required": [ "copy_text" ], "not": { "anyOf": [ { "required": [ "url" ] }, { "required": [ "callback_data" ] } ] } } ] }, "ReplyMarkup": { "type": "object", "required": [ "inline_keyboard" ], "properties": { "inline_keyboard": { "type": "array", "maxItems": 10, "description": "Maximum 80 buttons overall. Empty array removes all buttons.", "items": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "$ref": "#/components/schemas/Button" } } } } }, "InputMedia": { "type": "object", "required": [ "type", "media" ], "properties": { "type": { "type": "string", "enum": [ "photo", "video" ] }, "media": { "type": "string", "pattern": "^[a-f0-9]{48}$" }, "caption": { "type": "string", "description": "Maximum 4096 UTF-8 bytes." } } }, "ApiError": { "type": "object", "required": [ "ok", "error_code", "description" ], "properties": { "ok": { "const": false }, "error_code": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "additionalProperties": true } } }, "Message": { "type": "object", "required": [ "message_id", "chat", "date", "type" ], "properties": { "message_id": { "type": "integer" }, "chat": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "const": "private" } } }, "date": { "type": "integer", "description": "Unix epoch seconds." }, "type": { "type": "string" }, "text": { "type": "string" }, "caption": { "type": "string" }, "card": { "oneOf": [ { "$ref": "#/components/schemas/Card" }, { "type": "null" } ] }, "file": { "type": [ "object", "null" ] }, "reply_markup": { "$ref": "#/components/schemas/ReplyMarkup" }, "from": { "type": "object", "properties": { "id": { "type": "string" } } } }, "additionalProperties": true }, "Chat": { "type": "object", "required": [ "id", "type", "status" ], "properties": { "id": { "type": "string" }, "type": { "const": "private" }, "status": { "type": "string" }, "started_at": { "type": [ "integer", "null" ], "description": "Unix epoch seconds." }, "stopped_at": { "type": [ "integer", "null" ], "description": "Unix epoch seconds." } } }, "File": { "type": "object", "required": [ "file_id", "mime_type", "file_name", "file_size", "kind", "sha256" ], "properties": { "file_id": { "type": "string" }, "mime_type": { "type": "string" }, "file_name": { "type": "string" }, "file_size": { "type": "integer" }, "kind": { "type": "string" }, "sha256": { "type": "string" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "duration": { "type": [ "number", "null" ] } }, "additionalProperties": true }, "Update": { "type": "object", "required": [ "update_id" ], "properties": { "update_id": { "type": "integer" }, "message": { "$ref": "#/components/schemas/Message" }, "membership": { "$ref": "#/components/schemas/Membership" }, "callback_query": { "$ref": "#/components/schemas/CallbackQuery" } }, "additionalProperties": true }, "Broadcast": { "type": "object", "required": [ "broadcast_id", "status", "counts" ], "properties": { "broadcast_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "cancelled" ] }, "counts": { "type": "object", "properties": { "queued": { "type": "integer" }, "sent": { "type": "integer" }, "failed": { "type": "integer" }, "cancelled": { "type": "integer" } } }, "created_at": { "type": [ "integer", "null" ], "description": "Unix epoch seconds." }, "completed_at": { "type": [ "integer", "null" ], "description": "Unix epoch seconds." } } }, "DownloadFile": { "allOf": [ { "$ref": "#/components/schemas/File" }, { "type": "object", "required": [ "download_url", "expires_at" ], "properties": { "download_url": { "type": "string", "format": "uri", "description": "Signed URL, expires after one hour. Treat as a private bearer capability." }, "expires_at": { "type": "integer", "description": "Unix epoch seconds." } } } ] }, "Bot": { "type": "object", "required": [ "id", "is_bot", "username", "display_name", "description" ], "properties": { "id": { "type": "integer" }, "is_bot": { "const": true }, "username": { "type": "string" }, "display_name": { "type": "string" }, "description": { "type": "string" } } }, "WebhookInfo": { "type": "object", "required": [ "url", "pending_update_count" ], "properties": { "url": { "type": "string" }, "pending_update_count": { "type": "integer" }, "last_error": { "type": [ "string", "null" ] }, "last_error_at": { "type": [ "integer", "null" ] }, "last_success_at": { "type": [ "integer", "null" ] } } }, "SubscriberPage": { "type": "object", "required": [ "subscribers", "next_cursor" ], "properties": { "subscribers": { "type": "array", "items": { "type": "object", "required": [ "chat_id", "started_at" ], "properties": { "chat_id": { "type": "string" }, "started_at": { "type": "integer" } } } }, "next_cursor": { "type": [ "string", "null" ] } } }, "BroadcastRecipientPage": { "type": "object", "required": [ "recipients", "next_cursor" ], "properties": { "recipients": { "type": "array", "items": { "type": "object", "required": [ "chat_id", "status", "message_id", "last_error" ], "properties": { "chat_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "sent", "failed", "cancelled" ] }, "message_id": { "type": [ "integer", "null" ] }, "last_error": { "type": [ "string", "null" ] } } } }, "next_cursor": { "type": [ "string", "null" ] } } }, "Membership": { "type": "object", "required": [ "chat_id", "status" ], "properties": { "chat_id": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "stopped" ] }, "start_parameter": { "type": [ "string", "null" ], "description": "Optional; emitted for Start/Stop command updates." }, "reason": { "type": "string", "enum": [ "blocked" ], "description": "Optional; a blocking event can emit membership alone without a message or start_parameter." } } }, "CallbackQuery": { "type": "object", "required": [ "id", "from", "chat_id", "message_id", "data" ], "properties": { "id": { "type": "string" }, "from": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } }, "chat_id": { "type": "string" }, "message_id": { "type": "integer" }, "data": { "type": "string" } } }, "getMeRequest": { "type": "object", "properties": {}, "example": {} }, "getMeResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/Bot" } } }, "getChatRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "required": [ "chat_id" ] }, "getChatResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/Chat" } } }, "getChatMemberRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "required": [ "chat_id" ] }, "getChatMemberResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/Chat" } } }, "getUpdatesRequest": { "type": "object", "properties": { "offset": { "type": "integer", "description": "برای تأیید رویدادهای قبلی، آخرین update_id پردازش‌شده + ۱ را بفرستید. شناسه‌های کوچک‌تر تأیید می‌شوند. مقدار ۰ تأییدی انجام نمی‌دهد.", "minimum": 0 }, "limit": { "type": "integer", "description": "تعداد رکورد، از ۱ تا ۱۰۰؛ پیش‌فرض ۱۰۰.", "minimum": 1, "maximum": 100, "default": 100 }, "timeout": { "type": "integer", "description": "فقط ۰؛ long polling پشتیبانی نمی‌شود. از short polling یا وب‌هوک استفاده کنید.", "enum": [ 0 ], "default": 0 } }, "example": { "limit": 100 } }, "getUpdatesResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/Update" } } } }, "setWebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "description": "URL با نام دامنه عمومی HTTPS روی پورت ۴۴۳، بدون نام کاربری، رمز یا fragment؛ IP داخلی و مقصد غیرمجاز رد می‌شوند." }, "secret_token": { "type": "string", "description": "۱۶ تا ۲۵۶ حرف لاتین، رقم، زیرخط یا خط تیره؛ مقدار هدر تأیید وب‌هوک.", "pattern": "^[A-Za-z0-9_-]{16,256}$" }, "drop_pending_updates": { "type": "boolean", "description": "true رویدادهای منتظر را کنار می‌گذارد؛ پیش‌فرض false." } }, "example": { "url": "https://bot.example.com/webhook", "secret_token": "REPLACE_WITH_RANDOM_SECRET_32_BYTES" }, "required": [ "url", "secret_token" ] }, "setWebhookResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "type": "boolean" } } }, "deleteWebhookRequest": { "type": "object", "properties": { "drop_pending_updates": { "type": "boolean", "description": "با true رویدادهای منتظر هم کنار گذاشته می‌شوند." } }, "example": {} }, "deleteWebhookResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "type": "boolean" } } }, "getWebhookInfoRequest": { "type": "object", "properties": {}, "example": {} }, "getWebhookInfoResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/WebhookInfo" } } }, "sendMessageRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "text": { "type": "string", "description": "متن ساده و غیرخالی، حداکثر ۱۶۳۸۴ بایت UTF-8." }, "parse_mode": { "type": "string", "description": "فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود.", "enum": [ "plain" ], "default": "plain" }, "reply_markup": { "$ref": "#/components/schemas/ReplyMarkup", "description": "inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید." }, "reply_to_message_id": { "type": "integer", "description": "شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن.", "minimum": 1 } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "text": "سلام! به ربات ما خوش آمدید." }, "required": [ "chat_id", "text" ] }, "sendMessageResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/Message" } } }, "sendPhotoRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "photo": { "type": "string", "description": "file_id فایل پاک و متعلق به همین ربات؛ یا فایل مستقیم در درخواست multipart. آدرس URL پذیرفته نمی‌شود.", "pattern": "^[a-f0-9]{48}$" }, "caption": { "type": "string", "description": "کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown." }, "reply_markup": { "$ref": "#/components/schemas/ReplyMarkup", "description": "inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید." }, "reply_to_message_id": { "type": "integer", "description": "شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن.", "minimum": 1 }, "parse_mode": { "type": "string", "description": "فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود.", "enum": [ "plain" ], "default": "plain" } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "photo": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "caption": "نمونه رسانه" }, "required": [ "chat_id", "photo" ] }, "sendPhotoResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/Message" } } }, "sendVoiceRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "voice": { "type": "string", "description": "file_id فایل پاک و متعلق به همین ربات؛ یا فایل مستقیم در درخواست multipart. آدرس URL پذیرفته نمی‌شود.", "pattern": "^[a-f0-9]{48}$" }, "caption": { "type": "string", "description": "کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown." }, "reply_markup": { "$ref": "#/components/schemas/ReplyMarkup", "description": "inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید." }, "reply_to_message_id": { "type": "integer", "description": "شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن.", "minimum": 1 }, "parse_mode": { "type": "string", "description": "فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود.", "enum": [ "plain" ], "default": "plain" } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "voice": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "caption": "نمونه رسانه" }, "required": [ "chat_id", "voice" ] }, "sendVoiceResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/Message" } } }, "sendVideoRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "video": { "type": "string", "description": "file_id فایل پاک و متعلق به همین ربات؛ یا فایل مستقیم در درخواست multipart. آدرس URL پذیرفته نمی‌شود.", "pattern": "^[a-f0-9]{48}$" }, "caption": { "type": "string", "description": "کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown." }, "reply_markup": { "$ref": "#/components/schemas/ReplyMarkup", "description": "inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید." }, "reply_to_message_id": { "type": "integer", "description": "شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن.", "minimum": 1 }, "parse_mode": { "type": "string", "description": "فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود.", "enum": [ "plain" ], "default": "plain" } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "video": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "caption": "نمونه رسانه" }, "required": [ "chat_id", "video" ] }, "sendVideoResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/Message" } } }, "sendAudioRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "audio": { "type": "string", "description": "file_id فایل پاک و متعلق به همین ربات؛ یا فایل مستقیم در درخواست multipart. آدرس URL پذیرفته نمی‌شود.", "pattern": "^[a-f0-9]{48}$" }, "caption": { "type": "string", "description": "کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown." }, "reply_markup": { "$ref": "#/components/schemas/ReplyMarkup", "description": "inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید." }, "reply_to_message_id": { "type": "integer", "description": "شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن.", "minimum": 1 }, "parse_mode": { "type": "string", "description": "فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود.", "enum": [ "plain" ], "default": "plain" } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "audio": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "caption": "نمونه رسانه" }, "required": [ "chat_id", "audio" ] }, "sendAudioResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/Message" } } }, "sendDocumentRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "document": { "type": "string", "description": "file_id فایل پاک و متعلق به همین ربات؛ یا فایل مستقیم در درخواست multipart. آدرس URL پذیرفته نمی‌شود.", "pattern": "^[a-f0-9]{48}$" }, "caption": { "type": "string", "description": "کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown." }, "reply_markup": { "$ref": "#/components/schemas/ReplyMarkup", "description": "inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید." }, "reply_to_message_id": { "type": "integer", "description": "شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن.", "minimum": 1 }, "parse_mode": { "type": "string", "description": "فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود.", "enum": [ "plain" ], "default": "plain" } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "document": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "caption": "نمونه رسانه" }, "required": [ "chat_id", "document" ] }, "sendDocumentResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/Message" } } }, "sendAnimationRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "animation": { "type": "string", "description": "file_id فایل پاک و متعلق به همین ربات؛ یا فایل مستقیم در درخواست multipart. آدرس URL پذیرفته نمی‌شود.", "pattern": "^[a-f0-9]{48}$" }, "caption": { "type": "string", "description": "کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown." }, "reply_markup": { "$ref": "#/components/schemas/ReplyMarkup", "description": "inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید." }, "reply_to_message_id": { "type": "integer", "description": "شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن.", "minimum": 1 }, "parse_mode": { "type": "string", "description": "فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود.", "enum": [ "plain" ], "default": "plain" } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "animation": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "caption": "نمونه رسانه" }, "required": [ "chat_id", "animation" ] }, "sendAnimationResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/Message" } } }, "sendMediaGroupRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "media": { "type": "array", "description": "۲ تا ۱۰ شیء با type برابر photo/video، فیلد media برابر file_id و caption اختیاری.", "items": { "$ref": "#/components/schemas/InputMedia" }, "minItems": 2, "maxItems": 10 } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "media": [ { "type": "photo", "media": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" }, { "type": "photo", "media": "cccccccccccccccccccccccccccccccccccccccccccccccc" } ] }, "required": [ "chat_id", "media" ] }, "sendMediaGroupResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "sendCardRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "card": { "$ref": "#/components/schemas/Card", "description": "type: info/product/status/receipt؛ title الزامی تا ۲۵۶ بایت، text تا ۸۱۹۲، subtitle تا ۵۱۲ و fields تا ۱۲ جفت label (۱۲۸) و value (۱۰۲۴ بایت UTF-8)." }, "reply_markup": { "$ref": "#/components/schemas/ReplyMarkup", "description": "inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید." }, "reply_to_message_id": { "type": "integer", "description": "شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن.", "minimum": 1 }, "parse_mode": { "type": "string", "description": "فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود.", "enum": [ "plain" ], "default": "plain" } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "card": { "type": "status", "title": "سفارش آماده شد", "text": "سفارش شما آماده ارسال است.", "fields": [ { "label": "شماره سفارش", "value": "1042" } ] }, "reply_markup": { "inline_keyboard": [ [ { "text": "پیگیری سفارش", "callback_data": "order:1042" } ] ] } }, "required": [ "chat_id", "card" ] }, "sendCardResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/Message" } } }, "answerCallbackQueryRequest": { "type": "object", "properties": { "callback_query_id": { "type": "string", "description": "id رویداد callback_query که همین ربات دریافت کرده است." }, "text": { "type": "string", "description": "متن پاسخ، حداکثر ۱۰۲۴ بایت UTF-8." }, "show_alert": { "type": "boolean", "description": "درخواست نمایش به‌صورت اعلان برجسته؛ پیش‌فرض false." } }, "example": { "callback_query_id": "dddddddddddddddddddddddddddddddddddddddddddddddd", "text": "درخواست شما ثبت شد.", "show_alert": false }, "required": [ "callback_query_id" ] }, "answerCallbackQueryResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "type": "boolean" } } }, "editMessageTextRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "message_id": { "type": "integer", "description": "شناسه پیام خروجی همین ربات در همین گفت‌وگو؛ از پاسخ ارسال ذخیره کنید.", "minimum": 1 }, "text": { "type": "string", "description": "متن ساده و غیرخالی، حداکثر ۱۶۳۸۴ بایت UTF-8." }, "reply_markup": { "$ref": "#/components/schemas/ReplyMarkup", "description": "inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید." }, "parse_mode": { "type": "string", "description": "فقط plain؛ متن و کپشن بدون HTML/Markdown پردازش می‌شوند.", "enum": [ "plain" ], "default": "plain" } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "message_id": 42, "text": "متن به‌روزرسانی شد." }, "required": [ "chat_id", "message_id", "text" ] }, "editMessageTextResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/Message" } } }, "editMessageCaptionRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "message_id": { "type": "integer", "description": "شناسه پیام خروجی همین ربات در همین گفت‌وگو؛ از پاسخ ارسال ذخیره کنید.", "minimum": 1 }, "caption": { "type": "string", "description": "کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown." }, "reply_markup": { "$ref": "#/components/schemas/ReplyMarkup", "description": "inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید." }, "parse_mode": { "type": "string", "description": "فقط plain؛ متن و کپشن بدون HTML/Markdown پردازش می‌شوند.", "enum": [ "plain" ], "default": "plain" } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "message_id": 42, "caption": "کپشن جدید" }, "required": [ "chat_id", "message_id" ] }, "editMessageCaptionResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/Message" } } }, "editMessageMediaRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "message_id": { "type": "integer", "description": "شناسه پیام خروجی همین ربات در همین گفت‌وگو؛ از پاسخ ارسال ذخیره کنید.", "minimum": 1 }, "media": { "type": "string", "description": "file_id پاک و متعلق به همین ربات." }, "type": { "type": "string", "description": "photo، voice، video، audio، document یا animation؛ پیش‌فرض نوع قبلی." }, "caption": { "type": "string", "description": "کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown." }, "reply_markup": { "$ref": "#/components/schemas/ReplyMarkup", "description": "inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید." } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "message_id": 42, "media": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "type": "photo" }, "required": [ "chat_id", "message_id", "media" ] }, "editMessageMediaResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/Message" } } }, "editMessageCardRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "message_id": { "type": "integer", "description": "شناسه پیام خروجی همین ربات در همین گفت‌وگو؛ از پاسخ ارسال ذخیره کنید.", "minimum": 1 }, "card": { "$ref": "#/components/schemas/Card", "description": "type: info/product/status/receipt؛ title الزامی تا ۲۵۶ بایت، text تا ۸۱۹۲، subtitle تا ۵۱۲ و fields تا ۱۲ جفت label (۱۲۸) و value (۱۰۲۴ بایت UTF-8)." }, "reply_markup": { "$ref": "#/components/schemas/ReplyMarkup", "description": "inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید." } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "message_id": 42, "card": { "type": "status", "title": "سفارش آماده شد", "text": "سفارش شما آماده ارسال است.", "fields": [ { "label": "شماره سفارش", "value": "1042" } ] } }, "required": [ "chat_id", "message_id", "card" ] }, "editMessageCardResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/Message" } } }, "editMessageReplyMarkupRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "message_id": { "type": "integer", "description": "شناسه پیام خروجی همین ربات در همین گفت‌وگو؛ از پاسخ ارسال ذخیره کنید.", "minimum": 1 }, "reply_markup": { "$ref": "#/components/schemas/ReplyMarkup", "description": "inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید." } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "message_id": 42, "reply_markup": { "inline_keyboard": [] } }, "required": [ "chat_id", "message_id", "reply_markup" ] }, "editMessageReplyMarkupResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/Message" } } }, "deleteMessageRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "message_id": { "type": "integer", "description": "شناسه پیام خروجی همین ربات در همین گفت‌وگو؛ از پاسخ ارسال ذخیره کنید.", "minimum": 1 } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "message_id": 42 }, "required": [ "chat_id", "message_id" ] }, "deleteMessageResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "type": "boolean" } } }, "deleteMessagesRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "message_ids": { "type": "array", "description": "۱ تا ۱۰۰ شناسه مثبت message_id از پیام‌های خروجی همین ربات.", "items": { "type": "integer" }, "minItems": 1, "maxItems": 100 } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "message_ids": [ 42, 43 ] }, "required": [ "chat_id", "message_ids" ] }, "deleteMessagesResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "type": "boolean" } } }, "uploadFileRequest": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "فایل multipart؛ نام فایل باید پسوند مجاز و سازگار با MIME واقعی داشته باشد." } }, "example": { "file": "@./photo.jpg" }, "required": [ "file" ] }, "uploadFileResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/File" } } }, "getFileRequest": { "type": "object", "properties": { "file_id": { "type": "string", "description": "شناسه فایل پاک همین ربات؛ از پاسخ uploadFile یا پیام بگیرید.", "pattern": "^[a-f0-9]{48}$" } }, "example": { "file_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" }, "required": [ "file_id" ] }, "getFileResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/DownloadFile" } } }, "getSubscribersRequest": { "type": "object", "properties": { "cursor": { "type": "string", "description": "next_cursor پاسخ قبلی؛ در اولین درخواست حذف شود. مقدار را به‌عنوان توکن صفحه‌بندی نگه دارید." }, "limit": { "type": "integer", "description": "تعداد رکورد، از ۱ تا ۱۰۰؛ پیش‌فرض ۱۰۰.", "minimum": 1, "maximum": 100, "default": 100 } }, "example": { "limit": 100 } }, "getSubscribersResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/SubscriberPage" } } }, "createBroadcastRequest": { "type": "object", "properties": { "method": { "type": "string", "description": "یکی از sendMessage، sendPhoto، sendVoice، sendVideo، sendAudio، sendDocument، sendAnimation یا sendCard." }, "payload": { "type": "object", "description": "پارامترهای متد ارسال بدون chat_id؛ reply_to_message_id در انبوه استفاده نمی‌شود." }, "chat_ids": { "type": "array", "description": "اختیاری: ۱ تا ۱۰٬۰۰۰ chat_id از مخاطبان همین ربات. با حذف این فیلد همه اعضای فعال فعلی هدف می‌شوند.", "items": { "type": "string" }, "minItems": 1, "maxItems": 10000 } }, "example": { "method": "sendMessage", "payload": { "text": "خبر تازه برای اعضای ربات" } }, "required": [ "method", "payload" ] }, "createBroadcastResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/Broadcast" } } }, "getBroadcastRequest": { "type": "object", "properties": { "broadcast_id": { "type": "integer", "description": "شناسه ارسال انبوه متعلق به همین ربات.", "minimum": 1 } }, "example": { "broadcast_id": 12 }, "required": [ "broadcast_id" ] }, "getBroadcastResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/Broadcast" } } }, "getBroadcastRecipientsRequest": { "type": "object", "properties": { "broadcast_id": { "type": "integer", "description": "شناسه ارسال انبوه متعلق به همین ربات.", "minimum": 1 }, "cursor": { "type": "string", "description": "next_cursor پاسخ قبلی؛ در اولین درخواست حذف شود. مقدار را به‌عنوان توکن صفحه‌بندی نگه دارید." }, "limit": { "type": "integer", "description": "تعداد رکورد، از ۱ تا ۱۰۰؛ پیش‌فرض ۱۰۰.", "minimum": 1, "maximum": 100, "default": 100 } }, "example": { "broadcast_id": 12, "limit": 100 }, "required": [ "broadcast_id" ] }, "getBroadcastRecipientsResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/BroadcastRecipientPage" } } }, "cancelBroadcastRequest": { "type": "object", "properties": { "broadcast_id": { "type": "integer", "description": "شناسه ارسال انبوه متعلق به همین ربات.", "minimum": 1 } }, "example": { "broadcast_id": 12 }, "required": [ "broadcast_id" ] }, "cancelBroadcastResponse": { "type": "object", "required": [ "ok", "result" ], "properties": { "ok": { "const": true }, "result": { "type": "boolean" } } }, "sendPhotoMultipartRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "photo": { "type": "string", "format": "binary", "description": "Direct multipart upload. The same scanning and normalization policy applies." }, "caption": { "type": "string", "description": "کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown." }, "reply_markup": { "$ref": "#/components/schemas/ReplyMarkup", "description": "inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید." }, "reply_to_message_id": { "type": "integer", "description": "شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن.", "minimum": 1 }, "parse_mode": { "type": "string", "description": "فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود.", "enum": [ "plain" ], "default": "plain" } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "photo": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "caption": "نمونه رسانه" }, "required": [ "chat_id", "photo" ] }, "sendVoiceMultipartRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "voice": { "type": "string", "format": "binary", "description": "Direct multipart upload. The same scanning and normalization policy applies." }, "caption": { "type": "string", "description": "کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown." }, "reply_markup": { "$ref": "#/components/schemas/ReplyMarkup", "description": "inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید." }, "reply_to_message_id": { "type": "integer", "description": "شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن.", "minimum": 1 }, "parse_mode": { "type": "string", "description": "فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود.", "enum": [ "plain" ], "default": "plain" } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "voice": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "caption": "نمونه رسانه" }, "required": [ "chat_id", "voice" ] }, "sendVideoMultipartRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "video": { "type": "string", "format": "binary", "description": "Direct multipart upload. The same scanning and normalization policy applies." }, "caption": { "type": "string", "description": "کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown." }, "reply_markup": { "$ref": "#/components/schemas/ReplyMarkup", "description": "inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید." }, "reply_to_message_id": { "type": "integer", "description": "شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن.", "minimum": 1 }, "parse_mode": { "type": "string", "description": "فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود.", "enum": [ "plain" ], "default": "plain" } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "video": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "caption": "نمونه رسانه" }, "required": [ "chat_id", "video" ] }, "sendAudioMultipartRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "audio": { "type": "string", "format": "binary", "description": "Direct multipart upload. The same scanning and normalization policy applies." }, "caption": { "type": "string", "description": "کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown." }, "reply_markup": { "$ref": "#/components/schemas/ReplyMarkup", "description": "inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید." }, "reply_to_message_id": { "type": "integer", "description": "شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن.", "minimum": 1 }, "parse_mode": { "type": "string", "description": "فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود.", "enum": [ "plain" ], "default": "plain" } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "audio": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "caption": "نمونه رسانه" }, "required": [ "chat_id", "audio" ] }, "sendDocumentMultipartRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "document": { "type": "string", "format": "binary", "description": "Direct multipart upload. The same scanning and normalization policy applies." }, "caption": { "type": "string", "description": "کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown." }, "reply_markup": { "$ref": "#/components/schemas/ReplyMarkup", "description": "inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید." }, "reply_to_message_id": { "type": "integer", "description": "شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن.", "minimum": 1 }, "parse_mode": { "type": "string", "description": "فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود.", "enum": [ "plain" ], "default": "plain" } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "document": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "caption": "نمونه رسانه" }, "required": [ "chat_id", "document" ] }, "sendAnimationMultipartRequest": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… .", "pattern": "^vc_[a-f0-9]{40}$", "examples": [ "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] }, "animation": { "type": "string", "format": "binary", "description": "Direct multipart upload. The same scanning and normalization policy applies." }, "caption": { "type": "string", "description": "کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown." }, "reply_markup": { "$ref": "#/components/schemas/ReplyMarkup", "description": "inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید." }, "reply_to_message_id": { "type": "integer", "description": "شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن.", "minimum": 1 }, "parse_mode": { "type": "string", "description": "فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود.", "enum": [ "plain" ], "default": "plain" } }, "example": { "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "animation": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "caption": "نمونه رسانه" }, "required": [ "chat_id", "animation" ] } } } }