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

پنل و حساب

اتصال حساب‌ها

مسیر عمومی اتصال حساب پیام‌رسان به یونیوم و آماده‌سازی credential برای ساخت کلید API.

دید کلی

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

دیدن پلتفرم‌های قابل اتصال

curl "https://api.uniom.ir/platforms"

پاسخ شامل نام داخلی پلتفرم، نام نمایشی و وضعیت فعال بودن است.

جریان اتصال با شماره

کاربر یا پنل شما یونیوم پیام‌رسان مقصد 1. شروع اتصال حساب 2. درخواست OTP یا session 3. نتیجه و session_id 4. verify با کد دریافتی 5. تایید اتصال و نشست 6. credential آماده ساخت API key
جریان عمومی اتصال حساب با شماره و کد تایید

مسیر عمومی برای پلتفرم‌هایی که OTP دارند:

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

سپس با session_id و کد دریافتی:

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

اتصال بات‌های روبیکا و سروش‌پلاس

برخی پلتفرم‌ها به‌جای ورود با شماره و OTP، حساب را از طریق توکن بات متصل می‌کنند. برای این‌ها توکن بات خودِ پلتفرم را می‌فرستید؛ یونیوم آن را در credential نگه می‌دارد و از آن به بعد مثل هر credential دیگری می‌توانید روی آن کلید API بسازید و از قالب Bot API استفاده کنید. پاسخ این مسیر status، credential_id، اطلاعات بات (bot) و message را برمی‌گرداند.

curl -X POST "https://api.uniom.ir/platforms/rubika/link/bot" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{"bot_token":"<RUBIKA_BOT_TOKEN>"}'

curl -X POST "https://api.uniom.ir/platforms/soroushplus/link/bot" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{"bot_token":"<SPLUS_BOT_TOKEN>"}'

خطای رایج این دو مسیر، توکن نامعتبر است؛ در این حالت بعد از اینکه توکن سمت یونیوم با getMe روی خود پلتفرم بررسی شد، پاسخ خطای 400 برمی‌گردد. اگر سرور روبیکا در دسترس نباشد، پاسخ 503 است و می‌توانید بعداً دوباره تلاش کنید.

صفحه حساب‌های پیام‌رسان متصل در پنل یونیوم
نمای کلی credentialهای متصل، وضعیت اتصال و کنترل‌های عملیاتی هر حساب.

مدیریت credentialها

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

برای این APIهای مدیریتی، اگر JWT ندارید و از قبل Personal Access Token ساخته‌اید، می‌توانید از PAT هم استفاده کنید:

Authorization: apikey <PAT>

سقف تعداد حساب‌ها

تعداد حساب‌های متصل به سقف پلن شما محدود است. پلن رایگان به‌طور پیش‌فرض سه حساب دارد؛ اگر ظرفیت پلن پر باشد و بخواهید حساب چهارم را وصل کنید، مسیر اتصال با کد 403 و پیام «Maximum number of social accounts reached for your plan» رد می‌شود. سقف فعلی و تعداد مصرف‌شده را از GET /user/me (فیلد max_social_accounts) یا GET /user/social-accounts (فیلدهای count، max_allowed و can_add_more) بخوانید.

دو نکته:

  • بازسازی یک credential موجود (مسیر reauth) با همان شماره، سقف پلن را مصرف نمی‌کند؛ چون حساب جدیدی ساخته نمی‌شود.
  • برای افزایش ظرفیت با پشتیبانی تماس بگیرید؛ ارتقای پلن از API انجام نمی‌شود.

نکته عملی

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