API کانال‌یار

با همین API که افزونه‌ی وردپرس کانال‌یار با آن کار می‌کند، از هر سایت یا نرم‌افزاری (لاراول، جنگو، نود، اپ موبایل و …) در کانال‌های تلگرام، بله و روبیکا پست بگذارید، ویرایشش کنید یا پاکش کنید. ربات، پراکسی و حد پیام‌رسان‌ها با ماست.

شروع و احراز هویت

1. در پنل کانال‌یار ثبت‌نام کنید و پلن بگیرید.
2. کلید اتصال را از پنل کپی کنید. این کلید مثل رمز است؛ فقط سمت سرور نگهش دارید، نه در کد مرورگر یا اپ.
3. کانال‌تان را اضافه و تأیید کنید (از پنل، یا با API کانال‌ها).

آدرس پایه:

https://canalyarr.ir/bot-relay/v1

کلید را در هدر Authorization بفرستید:

Authorization: Bearer YOUR_KEY

روش قدیمی‌تر، گذاشتن کلید در آدرس (/v1/YOUR_KEY/publish)، هم کار می‌کند، ولی آدرس در لاگ‌ها می‌ماند؛ هدر امن‌تر است.

همه‌ی درخواست‌ها POST هستند و بدنه‌شان فرم است (multipart/form-data یا application/x-www-form-urlencoded). فیلدهایی که ساختار دارند، رشته‌ی JSON هستند.

پاسخ و خطا

پاسخ همیشه JSON است و کلید ok دارد. هر پاسخ ناموفق این سه کلید را دارد:

{
  "ok": false,
  "error": "متن خطا به فارسی، مناسب نمایش به کاربر",
  "description": "همان متن (برای سازگاری با شکل Bot API)",
  "error_code": 402
}

وضعیت حساب

POST/api/account

پلن، انقضا، سهمیه‌ی ماه و فهرست کانال‌ها. شناسه‌ی کانال‌ها و مقدار chat که در انتشار لازم دارید، از همین‌جا می‌آید.

curl -X POST https://canalyarr.ir/bot-relay/v1/api/account \
  -H "Authorization: Bearer YOUR_KEY"

{
  "ok": true,
  "plan": { "name": "حرفه‌ای", "max_channels": 5, "branding": false, … },
  "platforms": ["telegram", "bale", "rubika"],
  "expires": 1767225600,
  "active": true,
  "quota": 1000,
  "used": 42,
  "channels": [
    { "id": 7, "platform": "telegram", "chat": "@myshop", "title": "فروشگاه من", "status": "verified", "verified": true }
  ],
  …
}

quota صفر یعنی نامحدود. expires زمان یونیکس است و صفر یعنی بی‌انقضا.

کانال‌ها

فقط در کانال‌های تأییدشده می‌شود پست گذاشت. تأیید یعنی ثابت کنید کانال مال شماست: ربات کانال‌یار را (نامش در bots پاسخ حساب است) مدیر کانال کنید، کانال را اضافه کنید تا ربات یک کد شش‌رقمی در آن بگذارد، و آن کد را برگردانید.

افزودن

POST/api/channels/add

curl -X POST https://canalyarr.ir/bot-relay/v1/api/channels/add \
  -H "Authorization: Bearer YOUR_KEY" \
  -d platform=telegram -d chat=@myshop

پاسخ، کانال را با idش برمی‌گرداند.

تأیید

POST/api/channels/verify

فیلدها: id (شناسه‌ی کانال) و code (کد شش‌رقمی‌ای که در کانال گذاشته شد).

پیام آزمایشی و حذف

POST/api/channels/test

POST/api/channels/remove

هر دو فیلد id می‌گیرند.

انتشار پست

POST/publish

یک پست را هم‌زمان در یک یا چند کانال می‌گذارد. هر کانال موفق یک پست از سهمیه‌ی ماه کم می‌کند.

curl -X POST https://canalyarr.ir/bot-relay/v1/publish \
  -H "Authorization: Bearer YOUR_KEY" \
  -F 'text=*کیف چرمی دست‌دوز*
قیمت: ۱٬۲۰۰٬۰۰۰ تومان
https://myshop.ir/p/123' \
  -F 'channels=[{"platform":"telegram","chat":"@myshop"},{"platform":"bale","chat":"@myshop"}]' \
  -F image0=@bag-1.jpg \
  -F image1=@bag-2.jpg

{
  "ok": true,
  "results": [
    { "platform": "telegram", "chat": "@myshop", "ok": true, "ids": ["812", "813"], "text_id": "812", "kind": "caption", "error": "", "note": "" },
    { "platform": "bale", "chat": "@myshop", "ok": false, "ids": [], "error": "این کانال برای این سایت تأیید نشده است.", "code": "" }
  ],
  "usage": { "used": 43, "quota": 1000 }
}

اگر دست‌کم یک کانال موفق باشد، پاسخ 200 است؛ نتیجه‌ی هر کانال را جدا در results ببینید. ids، text_id و kind را نگه دارید؛ برای ویرایش و حذف همین پست لازمشان دارید. note اگر خالی نباشد، می‌گوید چه چیزی خودکار تنظیم شد (مثلاً جدا رفتن متن از تصویر).

ویرایش و حذف پست

POST/edit

سهمیه مصرف نمی‌کند. فیلد items یک آرایه‌ی JSON است، حداکثر ۳۰ مورد در هر درخواست:

[
  { "op": "edit",   "platform": "telegram", "chat": "@myshop", "id": "812", "kind": "caption", "text": "متن تازه" },
  { "op": "delete", "platform": "bale",     "chat": "@myshop", "ids": ["55", "56"] }
]

• id و kind برای ویرایش، همان text_id و kind پاسخ انتشار است. فقط متن عوض می‌شود، نه تصویرها.
• ids برای حذف، همان ids پاسخ انتشار است (آلبوم چند پیام دارد).
• تلگرام پیام‌های قدیمی‌تر از ۴۸ ساعت را همیشه حذف نمی‌کند.

curl -X POST https://canalyarr.ir/bot-relay/v1/edit \
  -H "Authorization: Bearer YOUR_KEY" \
  --data-urlencode 'items=[{"op":"edit","platform":"telegram","chat":"@myshop","id":"812","kind":"caption","text":"*ناموجود*"}]'

پاسخ مثل انتشار است: ok و یک results برای هر مورد.

محدودیت‌ها

• ۱۲۰ درخواست در دقیقه برای هر کلید.
• حداکثر ۱۰ تصویر در هر پست و ۳۲ مگابایت برای کل درخواست.
• متن پیام ۴۰۹۶ و کپشن تصویر ۱۰۲۴ نویسه.
• در پلن‌هایی که امضا دارند، «ارسال توسط کانال‌یار» زیر هر پست می‌آید و در حد طول متن حساب می‌شود.
• زمان‌بندی و صف ارسال سمت شماست؛ API پست را همان لحظه منتشر می‌کند.

سؤال یا مشکل؟ از بخش تیکت‌های پنل بپرسید.