ایران ناتیفیکیشن

ارسال پیام از ربات

به یک مشترک (یا همه) پیام یا رسانه می‌فرستد.

POSThttps://api.irnoti.com/v1/botbuilder/bots/{id}/send
scope: bot.send

ارسال همیشه ناهم‌زمان و در صف است. برای یک مخاطب، recipient در پاسخ می‌آید. ارسال به all فقط برای ربات‌هایی مجاز است که اشتراک فعال دارند. **نکته:** مشترک باید قبلاً ربات را شروع کرده باشد.

پارامترها

ناممحلنوعتوضیح
id *مسیرstringشناسهٔ ربات.
to *بدنهobjectمخاطب؛ دقیقاً یکی از chatId، ref (برچسب لینک عضویت)، phone (شمارهٔ ثبت‌شده در ربات) یا all: true (همهٔ مشترکین).
message *بدنهobject{ text?, parseMode?: HTML|Markdown, buttons?, media?: {type, url}, silent? }؛ متن یا رسانه الزامی است (متن ≤۴۰۰۰ نویسه، کپشن ≤۱۰۰۰). دکمه‌ها آرایه‌ای از ردیف‌ها (هر ردیف ۱ تا ۴ دکمه با url یا callback)، و نشانی رسانه باید https باشد.
Idempotency-Keyهدرstringکلید یکتا (حداکثر ۱۰۰ نویسه). ارسال دوباره با همان کلید، کار تکراری نمی‌سازد و نتیجهٔ قبلی را برمی‌گرداند.

خطاهای خاص این endpoint

401unauthorizedکلید API نامعتبر یا منقضی است.
403insufficient_scopeکلید API دامنهٔ دسترسی لازم را ندارد.
400validation_errorورودی نامعتبر است (جزئیات در پاسخ).
404not_foundربات یا مشترک پیدا نشد یا متعلق به شما نیست.
409conflictاشتراک ربات منقضی شده است.

اجرای زنده (محیط تست)

باز کردن در کنسول کامل ←

این endpoint در محیط تست پشتیبانی نمی‌شود؛ برای اجرا، کلید واقعی را در حالت «اجرای واقعی» وارد کنید.

curl -X POST 'https://api.irnoti.com/v1/botbuilder/bots/5/send' \
  -H "Authorization: Bearer $IRNOTI_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-18-shipped' \
  -d '{
  "to": {
    "phone": "09121234567"
  },
  "message": {
    "text": "سفارش شما ارسال شد ✅",
    "buttons": [
      [
        {
          "url": "https://shop.example.com/track/18",
          "text": "پیگیری"
        }
      ]
    ]
  }
}'
پاسخ نمونه200 OK
{
  "queued": 1,
  "recipient": {
    "ref": "ig-campaign",
    "chatId": "123456"
  }
}
ارسال پیام از ربات — مستندات API | ایران ناتیفیکیشن