ایجاد کمپین پیامکی | مستندات نجوا

یک کمپین پیامکی جدید می‌سازد و بلافاصله یک «اجرا» (execution) زمان‌بندی‌شده برای آن ثبت می‌کند. پارامترها به‌صورت فرم (multipart/form-data یا application/x-www-form-urlencoded) ارسال می‌شوند؛ اگر می‌خواهید فایل مخاطبان را همراه درخواست بفرستید حتماً باید از multipart/form-data استفاده کنید. سرشماره (sender) باید متعلق به حساب شما بوده و مجوز ارسال کمپین (can_send_panel_campaign) داشته باشد، در غیر این صورت خطای ۴۱۲ برمی‌گردد. جامعهٔ هدف از طریق inclusion_segments مشخص می‌شود؛ شناسهٔ این سگمنت‌ها همان segment_id است که از سرویس «بارگذاری مخاطبان» (POST /v2/sms/campaigns/contacts) دریافت می‌کنید.

احراز هویت

نوع احراز هویتتوکن BearerbearerAuth

کلید API را در هدر Authorization با پیشوند Bearer بفرستید:

``` Authorization: Bearer YOURAPIKEY ```

این روش برای سرویس‌های نسخهٔ ۲، نسخهٔ ۳ و بارگذاری فایل به کار می‌رود. سرویس‌های نسخهٔ ۱ کلید را از مسیر URL می‌گیرند و هدری نمی‌خواهند.

هدر لازم

Authorization: Bearer YOUR_ACCESS_TOKEN

کلید خود را کجا پیدا کنم؟

اطلاعات ورود را از پنل کاربری خود بگیرید و توکن را فقط روی سرور و در یک متغیر محیطی نگه دارید؛ هرگز آن را در کد سمت کاربر قرار ندهید.

بدنهٔ درخواست

multipart/form-dataالزامی

فیلدهای فرم. مقادیر `inclusion_segments` و `exclusion_segments` می‌توانند چند بار با همان نام تکرار شوند (آرایه). لینک‌ها با نام‌گذاری اندیس‌دار `links[0]actual_url`، `links[1]actual_url` و … ارسال می‌شوند.

نام	نوع	الزامی	توضیح
`sender`*	string	الزامی	شمارهٔ خط ارسال‌کننده. باید یکی از خطوط حساب شما باشد و مجوز `can_send_panel_campaign` داشته باشد. اگر خالی باشد خطای ۴۰۰ و اگر نامعتبر/بدون مجوز باشد خطای ۴۱۲ برمی‌گردد. نمونه`9830008080`
`name`*	string	الزامی	نام کمپین برای شناسایی آن در پنل. نمونه`کمپین تخفیف نوروز`
`template_body`*	string	الزامی	متن پیامک کمپین. این متن بدون تغییر به سرویس مدیریت کمپین ارسال می‌شود و اعتبارسنجی محتوایی (طول، کاراکتر، لینک) در این سرویس انجام نمی‌شود. نمونه`مشتری گرامی، جشنوارهٔ نوروزی آغاز شد. لغو۱۱`
`send_datetime`*	string	الزامی	زمان ارسال کمپین با قالب RFC3339. اگر قالب نامعتبر باشد خطای ۴۱۷ برمی‌گردد. محدودیت: باید با time.Parse(time.RFC3339, ...) قابل تجزیه باشد نمونه`2026-03-15T09:30:00+03:30`
`inclusion_segments`	string	اختیاری	شناسهٔ سگمنت‌های هدف کمپین. می‌توان این فیلد را چند بار تکرار کرد. هر مقدار باید عدد صحیح باشد وگرنه خطای ۴۰۰ برمی‌گردد. این شناسه همان `segment_id` خروجی سرویس بارگذاری مخاطبان است. محدودیت: هر مقدار باید با strconv.Atoi قابل تبدیل باشد نمونه`1024`
`exclusion_segments`	string	اختیاری	شناسهٔ سگمنت‌هایی که باید از جامعهٔ هدف حذف شوند. مانند `inclusion_segments` قابل تکرار است و هر مقدار باید عدد صحیح باشد. محدودیت: هر مقدار باید با strconv.Atoi قابل تبدیل باشد نمونه`2048`
`links[i]actual_url`	string	اختیاری	نشانی اصلی لینکی که در متن پیام کوتاه‌سازی/رهگیری می‌شود. اندیس `i` از ۰ شروع می‌شود و حداکثر تا ۹ (یعنی حداکثر ۱۰ لینک) خوانده می‌شود. خواندن لینک‌ها به محض رسیدن به اولین اندیس خالی متوقف می‌شود، بنابراین اندیس‌ها باید پیوسته و بدون فاصله باشند. محدودیت: حداکثر ۱۰ لینک (maxCampaignLinks = 10) نمونه`https://najva.com/spring-sale`
`links[i]has_utm`	string	اختیاری	اگر دقیقاً مقدار `true` باشد، پارامترهای UTM به این لینک افزوده می‌شود؛ هر مقدار دیگری معادل `false` در نظر گرفته می‌شود. مقادیر مجاز`truefalse`پیش‌فرض`false`نمونه`true`
`utm.utm_source`	string	اختیاری	مقدار utm_source لینک‌ها. اگر ارسال نشود مقدار پیش‌فرض `najva` استفاده می‌شود. پیش‌فرض`najva`نمونه`najva`
`utm.utm_medium`	string	اختیاری	مقدار utm_medium لینک‌ها. اگر ارسال نشود مقدار پیش‌فرض `sms` استفاده می‌شود. پیش‌فرض`sms`نمونه`sms`
`utm.utm_campaign`	string	اختیاری	مقدار utm_campaign لینک‌ها. اگر ارسال نشود مقدار پیش‌فرض `{id}` استفاده می‌شود که در سمت سرویس کمپین با شناسهٔ کمپین جایگزین می‌شود. پیش‌فرض`{id}`نمونه`nowruz-1405`
`file`	string	اختیاری	فایل اختیاری مخاطبان که بدون هیچ اعتبارسنجی یا تغییری به سرویس مدیریت کمپین ارسال می‌شود. اگر این بخش در فرم نباشد، درخواست بدون فایل ادامه پیدا می‌کند (خطایی تولید نمی‌شود). محدودیت: در این سرویس هیچ سقف حجمی برای آن اعمال نشده است

نمونهٔ درخواست

{
  "sender": "9830008080",
  "name": "کمپین تخفیف نوروز",
  "template_body": "مشتری گرامی، جشنوارهٔ نوروزی آغاز شد. لغو۱۱",
  "send_datetime": "2026-03-15T09:30:00+03:30",
  "inclusion_segments": [
    "1024",
    "1025"
  ],
  "exclusion_segments": [
    "2048"
  ],
  "links[0]actual_url": "https://najva.com/spring-sale",
  "links[0]has_utm": "true",
  "utm.utm_source": "najva",
  "utm.utm_medium": "sms",
  "utm.utm_campaign": "nowruz-1405"
}

پاسخ‌ها

ساختار پاسخ

نام	نوع	الزامی	توضیح
`return`	ApiStatus	اختیاری	وضعیت پاسخ. مقدار `status` با کد وضعیت HTTP پاسخ یکسان است.
`status`*	integer	الزامی	کد وضعیت — همان کد وضعیت HTTP پاسخ. نمونه`200`
`message`*	string	الزامی	پیام فارسی قابل نمایش به کاربر. نمونه`درخواست تایید شد.`
`entries`	CreateCampaignResponse	اختیاری
`campaign_id`	integer	اختیاری	شناسهٔ کمپین ساخته‌شده. نمونه`42`
`execution_id`	integer· int64	اختیاری	شناسهٔ اجرای کمپین. برای گزارش‌گیری از همین مقدار استفاده کنید. نمونه`100`قالب`int64`
`execution_status`	string	اختیاری	وضعیت اجرا. فهرست کامل مقادیر در این سرویس تعریف نشده است. نمونه`SCHEDULED`

نمونهٔ پاسخ

{
  "return": {
    "status": 200,
    "message": "درخواست تایید شد."
  },
  "entries": {
    "campaign_id": 42,
    "execution_id": 100,
    "execution_status": "SCHEDULED"
  }
}