U یونیوم مستندات

هسته یونیوم

حساب‌ها و تنظیمات دریافت

فهرست حساب‌های متصل، تست credential و تنظیمات مهم دریافت update.

credential چیست؟

credential همان حساب پیام‌رسان متصل‌شده به یونیوم است. API keyهای Bot API معمولاً به یکی از همین credentialها وصل می‌شوند.

مسیرهای مهم

مسیر کاربرد
GET /platforms فهرست پلتفرم‌های قابل استفاده
GET /platforms/credentials فهرست حساب‌های متصل کاربر
GET /platforms/credentials/{credential_id} جزئیات یک credential
POST /platforms/credentials/{credential_id}/test تست سلامت credential
PATCH /platforms/credentials/{credential_id}/settings تنظیمات دریافت update
DELETE /platforms/credentials/{credential_id} حذف یا غیرفعال‌سازی credential

مثال فهرست credentialها

curl "https://api.uniom.ir/platforms/credentials" \
  -H "Authorization: Bearer <JWT>"

تنظیمات دریافت update

برخی deploymentها برای credential تنظیمات جداگانه‌ای مثل این‌ها دارند:

تنظیم اثر عملی
include_self_updates updateهای ارسال‌شده توسط خود حساب را هم عبور می‌دهد
include_channel_updates channel_post و edited_channel_post را وارد جریان می‌کند
include_channel_update_recovery recovery برای updateهای کانال را فعال می‌کند
include_deleted_updates eventهای حذف پیام را هم دریافت می‌کنید

قبل از روشن‌کردن هر گزینه، ببینید consumer شما واقعاً آن eventها را handle می‌کند یا نه.

تست credential

اگر ارسال یا دریافت درست کار نمی‌کند، قبل از blame کردن Bot API این checkها را بزنید:

  1. خود credential فعال است؟
  2. حساب مقصد logout یا invalid نشده؟
  3. API key به credential درست وصل است؟
  4. تنظیمات دریافت update با workflow شما هماهنگ است؟

بازسازی اتصال یک credential خراب (reauth)

وقتی نشست یک حساب متصل از بین می‌رود (مثلاً کاربر در خود پیام‌رسان logout کرده یا احراز هویت شکست خورده)، نمی‌خواهید یک حساب جدید بسازید و کلید APIها را جابه‌جا کنید. مسیرهای reauth همان ردیف credential را ترمیم می‌کنند.

مرحله‌ی اول:

curl -X POST "https://api.uniom.ir/platforms/<platform_name>/credentials/<CREDENTIAL_ID>/reauth/start" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{}'

بدنه کاملاً اختیاری است؛ شماره تلفن به‌صورت پیش‌فرض از خود credential خوانده می‌شود. فقط در موارد استثنا (مثل شماره‌ی متفاوت در WhatsApp) می‌توانید بازنویسی کنید:

{ "phone": "+989123456789", "method": "pair_code" }

method برای WhatsApp می‌تواند pair_code یا qr باشد. پاسخ مثل جریان link/start شامل session_id، message، expires_in و verification_mode است.

مرحله‌ی دوم، مثل link/verify:

curl -X POST "https://api.uniom.ir/platforms/<platform_name>/credentials/<CREDENTIAL_ID>/reauth/verify" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<SESSION_ID>","otp":"12345"}'

اگر حساب رمز دوم (2FA) داشته باشد، پاسخ password_required: true می‌دهد و همان درخواست را با password دوباره می‌فرستید.

نکته‌های مهم:

  • بازسازی روی همان credential_id انجام می‌شود؛ وضعیت «خارج‌شده از حساب» و خطای احراز هویت آن پاک می‌شود و اتصال دوباره برقرار می‌گردد.
  • فقط موفقیت نهایی (نه حالت‌های میانی مثل password_required یا otp_required) حساب را ترمیم می‌کند.
  • بازسازی با همان شماره، سقف حساب‌های پلن را مصرف نمی‌کند.
  • اگر شماره‌ی حسابی که وارد می‌شود با شماره‌ی ثبت‌شده‌ی همان credential یکی نباشد، درخواست رد می‌شود تا اشتباهی حساب دیگری بازسازی نشود.

بخش‌های مرتبط