Messaging API

Messaging API

Messaging API نویدا برای ارسال پیام به یک گیرنده از طریق حساب‌های پیام‌رسان و سرویس‌های پیامک متصل به حساب شما طراحی شده است.

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

Base URL

احراز هویت

تمام درخواست‌های Messaging API باید با یک API Key ارسال شوند.

ارسال پیام

این Endpoint یک پیام برای یک گیرنده ایجاد می‌کند. در صورت پذیرفته شدن درخواست، پاسخ 201 Created برگردانده می‌شود.

ارسال واقعی پیام به‌صورت asynchronous انجام می‌شود؛ بنابراین پاسخ 201 به معنی تحویل پیام به گیرنده نیست، بلکه به معنی پذیرفته شدن درخواست و ایجاد پیام در نویدا است.

ساده‌ترین درخواست

curl -X POST "https://api.navidaa.ir/v1/messages/send" \
  -H "X-API-Key: navidaa_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "09123456789",
    "message": "سلام، این یک پیام آزمایشی از نویدا است.",
    "channels": ["eitaa"]
  }'

پارامترهای درخواست

to — گیرنده

شماره تلفن گیرنده است. نویدا فرمت‌های متداول شماره تلفن ایران را می‌پذیرد:

شماره پس از پردازش به فرمت استاندارد ذخیره و برگردانده می‌شود:

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

message — متن پیام

{
  "message": "سلام، سفارش شما با موفقیت ثبت شد."
}

• متن پیام نمی‌تواند خالی باشد.
• پس از حذف فاصله‌های ابتدا و انتها نباید خالی شود.
• در تنظیمات فعلی حداکثر 1000 کاراکتر است.
• نمی‌تواند همزمان با template ارسال شود.

ارسال با Template

اگر پیام دارای ساختار ثابتی است، می‌توانید به‌جای ارسال مستقیم متن از قالب‌های ساخته‌شده در داشبورد استفاده نمایید.

{{name}} عزیز،
سفارش {{order_id}} با موفقیت ثبت شد.

curl -X POST "https://api.navidaa.ir/v1/messages/send" \
  -H "X-API-Key: navidaa_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "09123456789",
    "template": {
      "id": 12,
      "parameters": {
        "name": "علی",
        "order_id": "A-123"
      }
    },
    "channels": ["bale"]
  }'

تمام پارامترهای تعریف‌شده در قالب باید دقیقاً ارسال شوند. ارسال پارامتر اضافه یا حذف یکی از پارامترهای موردنیاز باعث رد شدن درخواست خواهد شد.

نام پارامترها باید با حرف انگلیسی یا _ شروع شوند و تنها شامل حروف انگلیسی، اعداد و _ باشند.

یک Template بدون پارامتر نیز معتبر است:

{
  "template": {
    "id": 15,
    "parameters": {}
  }
}

در هر درخواست فقط یکی از message یا template را ارسال نمایید.

انتخاب کانال

فیلد channels مشخص می‌کند پیام از چه کانال یا کانال‌هایی ارسال شود.

یک کانال

{
  "channels": "eitaa"
}

{
  "channels": ["eitaa"]
}

چند کانال

{
  "channels": ["eitaa", "bale", "sms"]
}

ترتیب کانال‌ها در حالت failover اهمیت دارد: Eitaa → Bale → SMS

انتخاب حساب مشخص

این در حالتی هست که به عنوان مثال شما چندین حساب از یک پیام‌رسان خاص را دارید. برای مثال شما دو حساب ایتا را در داشبورد متصل کرده‌اید و نیاز دارید یکی از آنها را انتخاب کنید.

{
  "channels": [
    {
      "channel": "eitaa",
      "account_id": 15
    },
    {
      "channel": "sms",
      "account_id": 22
    }
  ]
}

account_id مربوط به هر حسابتان را می‌توانید در داشبورد پیدا کنید.

اگر برای یک کانال چند حساب دارید، پیشنهاد می‌شود یک حساب پیش‌فرض تعیین نمایید.

Strategy یا روش ارسال

زمانی که شما میخواهید پیام خود را از چند حساب یا کانال ارسال کنید این فیلد معنا پیدا میکند.

strategy مشخص می‌کند نویدا چگونه از کانال‌های انتخاب‌شده استفاده کند. مقدار پیش‌فرض failover است.

{
  "to": "09123456789",
  "message": "سفارش شما ثبت شد.",
  "channels": ["eitaa", "bale", "sms"],
  "strategy": "failover"
}

{
  "to": "09123456789",
  "message": "اطلاعیه جدید برای حساب شما",
  "channels": ["eitaa", "bale"],
  "strategy": "broadcast"
}

Metadata

با metadata می‌توانید اطلاعات دلخواه سیستم خود را همراه پیام ذخیره نمایید.

{
  "metadata": {
    "order_id": "A-123",
    "user_id": "42"
  }
}

این اطلاعات در فرآیند ارسال دخالتی ندارند و برای مرتبط کردن پیام نویدا با داده‌های سیستم شما مناسب هستند. برای مثال: order_id، user_id، invoice_id یا ticket_id.

metadata هنگام دریافت وضعیت پیام نیز برگردانده خواهد شد.

زمان‌بندی ارسال

پیام می‌تواند بلافاصله یا در آینده ارسال شود. دو روش برای زمان‌بندی وجود دارد: send_at و delay. در یک درخواست فقط یکی از این دو قابل استفاده است.

ارسال در زمان مشخص — send_at

{
  "to": "09123456789",
  "message": "یادآوری جلسه شما",
  "channels": ["eitaa"],
  "send_at": "2026-09-20T18:00:00+03:30"
}

send_at باید یک تاریخ معتبر ISO 8601 باشد. اگر timezone ارسال نشود، مثل 2026-09-20T18:00:00، زمان براساس منطقه زمانی Asia/Tehran تفسیر می‌شود.

در صورت ارسال timezone، مثل 2026-09-20T18:00:00+03:30، نویدا زمان را به UTC تبدیل و ذخیره می‌کند. حداکثر زمان قابل برنامه‌ریزی در حال حاضر ۳۰ روز آینده است.

ارسال با تأخیر — delay

{
  "delay": "30m"
}

واحدهای پشتیبانی‌شده: s ثانیه، m دقیقه، h ساعت، d روز.

مقدار delay نیز نمی‌تواند پیام را بیش از ۳۰ روز در آینده زمان‌بندی کند.

Idempotency

برای جلوگیری از ایجاد چند پیام مشابه در اثر retry شدن درخواست از سمت سیستم خود، می‌توانید از Header اختیاری Idempotency-Key استفاده نمایید.

curl -X POST "https://api.navidaa.ir/v1/messages/send" \
  -H "X-API-Key: navidaa_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: order-A-123-created" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "09123456789",
    "message": "سفارش شما ثبت شد.",
    "channels": ["eitaa"]
  }'

اگر همان Key با همان Request دوباره ارسال شود، پیام جدیدی ایجاد نمی‌شود و پاسخ قبلی بازگردانده خواهد شد. در این حالت Header پاسخ شامل Idempotency-Replayed: true خواهد بود.

اگر همان Key با محتوای متفاوت ارسال شود، خطای 409 idempotency_key_conflict دریافت می‌کنید. اگر درخواست قبلی با همان Key هنوز در حال پردازش باشد، خطای 409 idempotency_key_in_progress برمی‌گردد.

حداکثر طول Idempotency Key برابر با 255 کاراکتر است.

نمونه کامل ارسال

curl -X POST "https://api.navidaa.ir/v1/messages/send" \
  -H "X-API-Key: navidaa_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: order-A-123-shipped" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "09123456789",
    "template": {
      "id": 12,
      "parameters": {
        "name": "علی",
        "order_id": "A-123"
      }
    },
    "channels": ["eitaa", "bale", "sms"],
    "strategy": "failover",
    "metadata": {
      "order_id": "A-123"
    },
    "delay": "5m"
  }'

در این درخواست، گیرنده 09123456789 است، محتوا از Template شماره 12 ساخته می‌شود، مسیر ارسال Eitaa → Bale → SMS است، استراتژی Failover است، زمان ارسال پنج دقیقه دیگر است و Metadata شامل order_id ذخیره می‌شود.

پاسخ ایجاد پیام

{
  "message_id": "7bc41a7b-3d61-47e3-9da1-8f1812d19c41",
  "status": "queued",
  "strategy": "failover",
  "scheduled_for": null,
  "template": null,
  "current_channel": {
    "type": "messenger",
    "provider": "eitaa",
    "credential_id": 15,
    "label": "حساب ایتا فروشگاه"
  }
}

message_id را برای بررسی وضعیت بعدی پیام نگهداری نمایید.

مشاهده وضعیت پیام

curl "https://api.navidaa.ir/v1/messages/7bc41a7b-3d61-47e3-9da1-8f1812d19c41" \
  -H "X-API-Key: navidaa_live_xxxxxxxxxxxxxxxxxxxx"

{
  "message_id": "7bc41a7b-3d61-47e3-9da1-8f1812d19c41",
  "status": "sent",
  "to": "+989123456789",
  "strategy": "failover",
  "scheduled_for": null,
  "template": null,
  "metadata": {
    "order_id": "A-123"
  },
  "successful_attempts": 1,
  "failed_attempts": 0,
  "created_at": "2026-09-16T10:00:00Z",
  "completed_at": "2026-09-16T10:00:02Z",
  "attempts": [
    {
      "sequence": 1,
      "channel": {
        "type": "messenger",
        "provider": "eitaa",
        "credential_id": 15,
        "label": "حساب ایتا فروشگاه"
      },
      "status": "sent",
      "error_code": null,
      "error_message": null,
      "provider_error": null,
      "due_at": "2026-09-16T10:00:00Z",
      "attempted_at": "2026-09-16T10:00:01Z",
      "finished_at": "2026-09-16T10:00:02Z"
    }
  ]
}

بخش attempts نتیجه هر تلاش واقعی ارسال را نمایش می‌دهد و در سناریوهای Failover برای بررسی اینکه هر کانال چه نتیجه‌ای داشته بسیار مفید است.

وضعیت‌های پیام

Attemptهای هر پیام نیز می‌توانند وضعیت‌های pending، sending، sent و failed داشته باشند.

هزینه ارسال

هزینه نویدا براساس ارسال موفق از حساب‌های پیام‌رسان شما محاسبه می‌شود. ارسال ناموفق هزینه‌ای از کیف پول نویدا کسر نمی‌کند.

در SMS، هزینه ارسال مستقیماً توسط سرویس‌دهنده SMS متصل شما محاسبه می‌شود.

در حالت failover هنگام پذیرش درخواست، موجودی کافی برای یک ارسال موفق پیام‌رسان بررسی می‌شود. در حالت broadcast، کیف پول باید موجودی کافی برای حداکثر تعداد ارسال‌های موفق و قابل محاسبه در مسیر را داشته باشد.

اگر موجودی کافی نباشد، خطای insufficient_balance دریافت خواهید کرد.

Rate Limit

Messaging API دارای محدودیت‌هایی در سطح مشتری، شماره گیرنده و حساب پیام‌رسان است. علاوه بر محدودیت پلن، هر حساب متصل نیز محدودیت ارسال مستقل دارد.

حداقل فاصله پیش‌فرض میان دو ارسال از یک حساب: 1000ms.

اگر یک Account در وضعیت cooldown باشد یا به محدودیت خود رسیده باشد، آن Attempt ارسال نمی‌شود و در حالت failover نویدا می‌تواند مسیر بعدی را امتحان کند.

خطاهای API

ساختار استاندارد خطا:

{
  "error": {
    "code": "template_parameters_mismatch",
    "message": "Template parameters must exactly match the template placeholders.",
    "details": {
      "template_id": 12,
      "expected": ["name", "order_id"],
      "missing": [],
      "extra": ["foo"]
    }
  },
  "request_id": "..."
}

request_id را هنگام ارتباط با پشتیبانی نگهداری نمایید؛ این شناسه می‌تواند برای بررسی درخواست مشخص استفاده شود.

نکات مهم