ارسال‌های پیشرفته

این صفحه عملیات مکمل ارسال عادی را پوشش می‌دهد: Batch، زمان‌بندی، لغو، استعلام گروهی وضعیت و دریافت شماره‌های فرستنده مجاز حساب.

ارسال چند پیام متفاوت

POST /v1/messages/batch
X-API-Key: YOUR_API_KEY
Idempotency-Key: batch-1405-05-18-01
Content-Type: application/json

{
  "sender": "300099000121",
  "messages": [
    {
      "recipient": "09121234567",
      "message": "پیام اول",
      "clientReference": "A-1"
    },
    {
      "recipient": "09123334444",
      "message": "پیام دوم",
      "clientReference": "A-2"
    }
  ]
}

در هر درخواست حداکثر ۵۰۰ پیام پذیرفته می‌شود. Idempotency-Key برای کل Batch الزامی است و SMSDaily برای پردازش داخلی آیتم‌ها شناسه‌های مستقل می‌سازد.

نمونه پاسخ:

[
  {
    "trackingCode": "SMS-20260810-B001",
    "status": "queued",
    "encoding": "Persian",
    "characterCount": 8,
    "partCount": 1,
    "submittedAt": "2026-08-10T07:25:00Z",
    "duplicate": false
  },
  {
    "trackingCode": "SMS-20260810-B002",
    "status": "queued",
    "encoding": "Persian",
    "characterCount": 8,
    "partCount": 1,
    "submittedAt": "2026-08-10T07:25:00Z",
    "duplicate": false
  }
]

نمونه C# برای Batch

using System.Net.Http.Json;

var request = new HttpRequestMessage(HttpMethod.Post, "/v1/messages/batch");
request.Headers.Add("Idempotency-Key", "batch-1405-05-18-01");
request.Content = JsonContent.Create(new
{
    sender = "300099000121",
    messages = new[]
    {
        new { recipient = "09121234567", message = "پیام اول", clientReference = "A-1" },
        new { recipient = "09123334444", message = "پیام دوم", clientReference = "A-2" }
    }
});

using var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

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

POST /v1/messages/scheduled
X-API-Key: YOUR_API_KEY
Idempotency-Key: reminder-781
Content-Type: application/json

{
  "sender": "300099000121",
  "recipient": "09121234567",
  "message": "یادآوری جلسه",
  "sendAt": "2026-08-10T12:00:00Z",
  "clientReference": "meeting-781"
}

در RC2 زمان ارسال باید حداقل ۳۰ ثانیه بعد و حداکثر ۳۰ روز آینده باشد. پیام تا زمان تعیین‌شده در صف SMSDaily باقی می‌ماند.

نمونه C# برای زمان‌بندی

var request = new HttpRequestMessage(HttpMethod.Post, "/v1/messages/scheduled");
request.Headers.Add("Idempotency-Key", $"meeting-{meetingId}");
request.Content = JsonContent.Create(new
{
    sender = "300099000121",
    recipient = "09121234567",
    message = "یادآوری جلسه",
    sendAt = DateTimeOffset.UtcNow.AddHours(2),
    clientReference = $"meeting-{meetingId}"
});

using var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();

لغو پیام صف‌شده

POST /v1/messages/{trackingCode}/cancel
X-API-Key: YOUR_API_KEY

فقط پیامی قابل لغو است که هنوز در وضعیت قابل لغو باشد و به مسیر پایین‌دستی ارسال نشده باشد.

نمونه پاسخ:

{
  "trackingCode": "SMS-20260810-A1B2C3D4",
  "status": "cancelled",
  "cancelledAt": "2026-08-10T07:28:00Z"
}

اگر پیام از مرحله قابل لغو عبور کرده باشد، پاسخ 409 Conflict دریافت می‌شود.

دریافت وضعیت چند پیام

POST /v1/messages/status
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "trackingCodes": [
    "SMS-20260810-A1B2C3D4",
    "SMS-20260810-E5F60718"
  ]
}

در هر درخواست حداکثر ۱۰۰ کد پیگیری پذیرفته می‌شود. پاسخ، وضعیت عمومی پیام‌های پیدا‌شده برای همان حساب را برمی‌گرداند.

[
  {
    "trackingCode": "SMS-20260810-A1B2C3D4",
    "clientReference": "order-781",
    "sender": "300099000121",
    "recipient": "09121234567",
    "status": "delivered",
    "partCount": 1,
    "submittedAt": "2026-08-10T07:10:00Z",
    "updatedAt": "2026-08-10T07:12:35Z"
  }
]

نمونه C# برای استعلام گروهی

using var response = await client.PostAsJsonAsync(
    "/v1/messages/status",
    new
    {
        trackingCodes = new[]
        {
            "SMS-20260810-A1B2C3D4",
            "SMS-20260810-E5F60718"
        }
    });

response.EnsureSuccessStatusCode();

شماره‌های فرستنده مجاز

GET /v1/senders
X-API-Key: YOUR_API_KEY

نمونه پاسخ:

[
  { "sender": "300099000121", "active": true },
  { "sender": "02170001234", "active": true }
]

برنامه مشتری فقط باید یکی از Senderهای فعال حساب را انتخاب کند. انتخاب سرویس‌دهنده و مسیر پایین‌دستی براساس Sender در داخل SMSDaily انجام می‌شود و جزئیات Provider بخشی از قرارداد عمومی نیست.

نمونه پایه HttpClient برای همه مثال‌ها

var client = new HttpClient
{
    BaseAddress = new Uri("https://service.smsdaily.ir")
};
client.DefaultRequestHeaders.Add("X-API-Key", apiKey);

بهتر است در برنامه واقعی HttpClient را از IHttpClientFactory دریافت کنید و برای 429 و خطاهای موقت 5xx Retry با Backoff کنترل‌شده داشته باشید. برای درخواست‌های ارسال، Retry فقط با همان Idempotency-Key درخواست اولیه انجام شود.