شروع سریع

پیش‌نیازها

برای شروع به سه چیز نیاز دارید:

1. ورود به حساب یونیوم

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

curl -X POST "https://api.uniom.ir/auth/sendOtp" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+989123456789"}'

curl -X POST "https://api.uniom.ir/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+989123456789","otp":"123456"}'

2. اتصال حساب پیام‌رسان

برای پلتفرم‌هایی که اتصال با شماره دارند، جریان عمومی دو مرحله دارد:

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

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

برای بعضی پلتفرم‌ها، نوع اتصال متفاوت است. جزئیات هر مسیر در صفحه مرجع متدها آمده است.

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

3. ساخت کلید API

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

curl -X POST "https://api.uniom.ir/api_keys" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-bot",
    "credential_id": 42,
    "scopes": ["bot:send", "bot:receive"]
  }'

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

Authorization: apikey <PAT>

اگر می‌خواهید PAT را از داخل پنل بسازید، مسیر آن در تنظیمات حساب و توضیح کامل‌ترش در احراز هویت مدیریتی آمده است.

4. اولین پیام

curl -X POST "https://api.uniom.ir/bot<API_KEY>/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "@username",
    "text": "سلام، این اولین پیام از یونیوم است."
  }'

پاسخ موفق با همان الگوی Bot API برمی‌گردد:

{
  "ok": true,
  "result": {
    "message_id": 123,
    "date": 1767225600,
    "text": "سلام، این اولین پیام از یونیوم است."
  }
}

5. دریافت پیام

برای تست سریع از getUpdates استفاده کنید. برای محیط production معمولاً webhook مناسب‌تر است.

curl "https://api.uniom.ir/bot<API_KEY>/getUpdates?timeout=30&limit=10"