به گفت‌وگوها
قابلیت اضافه کنید.

اولین پیام در سه قدم

1. ۱

   ربات بسازید و توکن بگیرید

   از مدیربات داخل برنامه، ربات خود را بسازید. توکن را تنها روی سرور خود نگه دارید و در درخواست‌ها با Authorization: Bearer بفرستید.

2. ۲

   کاربر ربات شما را شروع کند

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

3. ۳

   به همان شناسه پیام بفرستید

   متد sendMessage را صدا بزنید و message_id پاسخ را برای ویرایش یا حذف بعدی ذخیره کنید.

درخواست و احراز هویت

نام متد را در مسیر https://bots.vispaco.net/v2/<method> مشخص کنید. درخواست‌ها با HTTPS و متد POST فرستاده می‌شوند؛ بدنه معمولاً JSON است. آپلود فایل از multipart/form-data استفاده می‌کند.

POST https://bots.vispaco.net/v2/sendMessage
Authorization: Bearer YOUR_BOT_TOKEN
Content-Type: application/json

پاسخ موفق دارای ok: true و result است. خطا دارای ok: false، error_code و description است. error_code یک شناسه متنی است؛ کد HTTP پاسخ را هم بررسی کنید.

{
  "ok": true,
  "result": { "message_id": 42 }
}

{
  "ok": false,
  "error_code": "BOT_NOT_STARTED",
  "description": "User must start this bot before receiving messages"
}

جلوگیری از ارسال تکراری

برای درخواست‌های قابل تکرار، هدر Idempotency-Key با ۱ تا ۱۲۸ حرف لاتین، رقم یا کاراکترهای ._:- بفرستید. هنگام تکرار همان درخواست پس از قطع ارتباط، همان کلید و همان بدنه را نگه دارید. استفاده از همان کلید با متد یا بدنه متفاوت، خطای IDEMPOTENCY_CONFLICT با HTTP 409 می‌دهد. برای عملیات جدید کلید جدید بسازید.

شناسه گفت‌وگو و عضویت

chat_id شناسه متنی پایدار و غیرقابل‌حدس کاربر است؛ شماره تلفن، نام کاربری یا شناسه عددی داخلی را به جای آن نفرستید. داشتن این شناسه به‌تنهایی مجوز ارسال نیست.

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

دریافت رویدادها

از polling یا وب‌هوک برای دریافت پیام و تعامل کاربر استفاده کنید. update_id را ذخیره و پردازش رویداد را در برنامه خود نسبت به تکرار مقاوم کنید. برای polling، پس از پردازش آخرین رویداد، offset را برابر update_id + 1 بفرستید؛ رویدادهای کوچک‌تر تأیید می‌شوند. جزئیات در مرجع متدها آمده است.

فایل امن، توکن محرمانه

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

• نوع واقعی فایل، اندازه و نوع رسانه باید از محدودیت‌های سرور عبور کنند؛ نام و پسوند فایل معیار اعتماد نیستند.
• فایل پیش از قابل‌استفاده‌شدن اسکن می‌شود. نبود اسکنر یا خطای آن باعث رد آپلود می‌شود. عکس‌ها دوباره کدگذاری، صوت و ویدئو تبدیل، و PDF پاک‌سازی می‌شود.
• توکن ربات را در JavaScript مرورگر، مخزن کد، نشانی URL یا گزارش‌ها قرار ندهید. در صورت افشا، آن را تعویض کنید.
• دریافت فایل از مسیر محافظت‌شده API انجام می‌شود؛ مسیر خصوصی فایل را منتشر نکنید.

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

خطا و تلاش مجدد

سقف پیش‌فرض هر ربات ۶۰ درخواست API در ثانیه، ۲۰ ارسال در ثانیه (شامل ارسال انبوه)، ۱۰ آپلود در دقیقه و ۱۰ ساخت ارسال انبوه در دقیقه است. مدیر نصب می‌تواند این سقف‌ها را تغییر دهد. پاسخ RATE_LIMITED با HTTP 429 شامل parameters.retry_after به ثانیه است؛ پیش از تلاش بعدی صبر کنید.