API کانالیار
با همین API که افزونهی وردپرس کانالیار با آن کار میکند، از هر سایت یا نرمافزاری (لاراول، جنگو، نود، اپ موبایل و …) در کانالهای تلگرام، بله و روبیکا پست بگذارید، ویرایشش کنید یا پاکش کنید، و در اینستاگرام پست و استوری منتشر کنید. ربات، پراکسی و حد پیامرسانها با ماست.
شروع و احراز هویت
- در پنل کانالیار ثبتنام کنید و پلن بگیرید.
- کلید اتصال را از پنل کپی کنید. این کلید مثل رمز است؛ فقط سمت سرور نگهش دارید، نه در کد مرورگر یا اپ.
- کانالتان را اضافه و تأیید کنید (از پنل، یا با 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
}
| وضعیت | یعنی |
|---|---|
400 | ورودی نامعتبر: متن خالی، کانال انتخابنشده، متن بلندتر از حد، … |
402 | اشتراک منقضی (code: "expired") یا هنوز پلنی خریده نشده (code: "inactive"). |
403 | کلید نامعتبر یا غیرفعال. |
404 | مسیر یا دستور ناشناخته. |
429 | بیش از ۱۲۰ درخواست در دقیقه. هدر Retry-After میگوید چند ثانیه صبر کنید. |
502 | ارسال به هیچ کانالی موفق نشد؛ دلیل هر کانال در results است. |
503 | سرویس موقتاً در دسترس نیست؛ کمی بعد دوباره بفرستید. |
وضعیت حساب
POST/api/account
پلن، انقضا، سهمیه و مصرف ماه (quota، used)، سقف و مصرف امروز (daily، used_today؛ سقف ۰ یعنی بیحد، روز به وقت تهران) و فهرست کانالها. شناسهی کانالها و مقدار 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,
"daily": 60,
"used_today": 7,
"channels": [
{ "id": 7, "platform": "telegram", "chat": "@myshop", "title": "فروشگاه من", "status": "verified", "verified": true }
],
…
}
quota صفر یعنی نامحدود. expires زمان یونیکس است و صفر یعنی بیانقضا.
کانالها
فقط در کانالهای تأییدشده میشود پست گذاشت. تأیید یعنی ثابت کنید کانال مال شماست: ربات کانالیار را (نامش در bots پاسخ حساب است) مدیر کانال کنید، کانال را اضافه کنید تا ربات یک کد ششرقمی در آن بگذارد، و آن کد را برگردانید.
افزودن
POST/api/channels/add
| فیلد | توضیح |
|---|---|
platform | telegram، bale یا rubika |
chat | شناسهی کانال، مثل @myshop |
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
یک پست را همزمان در یک یا چند کانال میگذارد. هر کانال موفق یک پست از سهمیهی ماه و امروز کم میکند؛ مصرف تازه در usage پاسخ برمیگردد.
| فیلد | توضیح |
|---|---|
text | متن پست؛ حداکثر ۴۰۹۶ نویسه. *پررنگ*، `کد`، ~خطخورده~ و [متن](https://پیوند) (پیوند متنی) در تلگرام قالب میگیرند و در بله و روبیکا به متن ساده تبدیل میشوند (پیوند بهشکل «متن: پیوند»). |
channels | JSON: [{"platform":"telegram","chat":"@myshop"}, …] |
image0 … image9 | اختیاری؛ فایل تصویر (JPG، PNG، WEBP یا GIF). چند تصویر در تلگرام و بله آلبوم میشوند. |
image_mode | caption (پیشفرض: متن زیر تصویر)، before (تصویرها، بعد متن)، after (متن، بعد تصویرها) یا none (بدون تصویر). اگر متن از حد کپشن (۱۰۲۴ نویسه) بلندتر باشد، خودکار before میشود. |
file | اختیاری، بهجای تصویرها: یک فایل تا ۳۰ مگابایت. MP3/M4A با پخشکنندهی موزیک و MP4 با پخشکنندهی ویدیو میرود، بقیه بهصورت سند. |
file_kind | اختیاری، document: فایل را حتماً بهصورت سند بفرست (مثلاً ویدیو بدون پخشکننده). |
rubika_extra | اختیاری، 1: روبیکا آلبوم ندارد؛ پیشفرض فقط تصویر اول میرود. با این فیلد بقیه هم، هرکدام در یک پست جدا، پشت سرش میروند. |
ig_mode, ig_link, ig_headline, ig_highlight, ig_label | اختیاری، فقط برای کانال اینستاگرام: ig_mode یکی از post (پیشفرض)، story یا both؛ استوری ۹:۱۶ از همان تصویرها ساخته میشود. ig_link نشانی صفحهی محصول (خالی: اولین پیوند متن)، ig_headline تیتر استوری (خالی: خط اول متن)، ig_highlight نام هایلایت (مثلاً دستهی محصول) و ig_label برچسب بالای لینک. استیکر لینک و هایلایت فقط برای حسابی است که با نام کاربری و رمز وصل شده؛ شناسهی استوری در story_id برمیگردد و با /edit (op: delete) حذف میشود. ig_story=1 قدیمی هم کار میکند و یعنی both. |
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, "today": 8, "daily": 60 }
}
اگر دستکم یک کانال موفق باشد، پاسخ 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 برای هر مورد.
گزارش ارسالها
POST/api/reports
خلاصهی ۳۰ روز (summary)، شمار روزانه (daily) و سطرهای گزارش، ۵۰ تا در هر صفحه. همهی فیلدها اختیاریاند: page، days (۱ تا ۹۰، پیشفرض ۱۴)، platform، result (ok یا failed)، from و to (زمان یونیکس).
{ "ok": true, "summary": { "total": 120, "failed": 3, … }, "daily": [ … ], "total": 120, "page": 1,
"rows": [ { "time": 1767225600, "platform": "managed", "method": "publish", "status": 200, "ok": true, "error": "" } ] }
channels: پستهای موفق هر کانال؛ d_* امروز (وقت تهران)، w_* هفت روز و m_* سی روز گذشته، *_new پست تازه و *_edit ویرایش پست قبلی.
خرید و فاکتور
POST/api/pay/start
ساخت سفارش و گرفتن آدرس درگاه. فیلدها: plan_id و months (از plans پاسخ حساب)، return_url (بعد از پرداخت کاربر با mkc_pay=ok|failed|canceled به آن برمیگردد؛ باید روی نشانی سایت شما باشد) و coupon اختیاری. مبلغ را سرور حساب میکند. پاسخ: url و amount.
POST/api/orders
همهی سفارشها و پرداختهای این سایت، تازهترین اول: id، number، پلن، مبلغ، تخفیف، مالیات، paid و invoiced_at.
POST/api/invoice
POST/api/invoice/pay
POST/api/invoice/issue
invoiceباid: جزئیات یک سفارش؛ اگر فاکتور رسمی صادر شده، مشخصات خریدار و فروشنده درofficial.invoice/payباidوreturn_url: پرداخت سفارشی که باز مانده.invoice/issueباid: صدور فاکتور رسمی برای خرید پرداختشده. مشخصات مالیاتی:buyer_type(personیاcompany)، و برای شخصnational_code، برای شرکتcompany_name،company_national_idوcompany_economic_code.
حساب، کلید و معرفی
POST/api/profile
POST/api/profile/update
مشخصات صاحب حساب: first_name، last_name، email، business، site_url و همان فیلدهای مالیاتی. در update فقط فیلدهایی که میفرستید عوض میشوند. شمارهی موبایل شناسهی ورود است و با API عوض نمیشود.
POST/api/key/rotate
کلید تازه میسازد و در key برمیگرداند. کلید فعلی همان لحظه از کار میافتد؛ پاسخ را فوراً ذخیره کنید. مصرف ماه با کلید تازه ادامه مییابد.
POST/api/sites
POST/api/sites/add
هر سایت کلید، کانالها و اشتراک خودش را دارد. sites همهی سایتهای حساب را با پلن، انقضا و current (سایتِ همین کلید) برمیگرداند، ولی کلید بقیهی سایتها را نه. sites/add با name (اجباری، دستکم دو حرف) و site_url اختیاری سایت تازه میسازد و کلیدش را فقط همین یک بار در key برمیگرداند. سایت تازه تا خرید پلن فعال نیست. حداکثر ۱۰ سایت.
POST/api/referral
پیوند معرفی (link)، آمار (stats: دعوتشده، خریده، روزهای هدیه)، هدیهی هر خرید (days) و درصد تخفیف تازهوارد (discount).
پشتیبانی (تیکت)
| دستور | فیلدها |
|---|---|
/api/tickets | — فهرست تیکتها، بههمراه دستهها (categories) و اولویتها (priorities) |
/api/tickets/new | subject، category، body، priority (اختیاری)، file (اختیاری؛ تصویر JPG، PNG یا WebP) |
/api/tickets/get | id — تیکت با همهی پیامها؛ پاسخهای تازه خواندهشده میشوند |
/api/tickets/reply | id، body، file (اختیاری). پاسخ به تیکت بسته آن را دوباره باز میکند. |
/api/tickets/close | id |
/api/tickets/attachment | id پیام — خود تصویر برمیگردد، نه JSON |
این بخش و بخش حساب فقط برای کلیدی است که به حساب مشتری در پنل وصل است.
محدودیتها
- ۱۲۰ درخواست در دقیقه برای هر کلید.
- حداکثر ۱۰ تصویر در هر پست و ۳۲ مگابایت برای کل درخواست.
- متن پیام ۴۰۹۶ و کپشن تصویر ۱۰۲۴ نویسه.
- در پلنهایی که امضا دارند، «ارسال توسط کانالیار» زیر هر پست میآید و در حد طول متن حساب میشود.
- زمانبندی و صف ارسال سمت شماست؛ API پست را همان لحظه منتشر میکند.
سؤال یا مشکل؟ از بخش تیکتهای پنل بپرسید.