ارسال خدماتی به گروه تاییدشده

این قابلیت برای مشتریانی است که فهرست مخاطبان خود را از طریق فرآیند اداری، نامه و تعهدنامه به SMSDaily اعلام کرده‌اند و فهرست پس از بررسی تایید شده است.

کاربر API نمی‌تواند از طریق وب‌سرویس شماره جدیدی را به گروه تاییدشده اضافه کند یا عضویت گروه را تغییر دهد. این محدودیت عمداً در مرز Public Service اعمال شده است. پس از تایید گروه، مشتری می‌تواند به همان فهرست متن خدماتی مجاز خود را بدون انتخاب Pattern ارسال کند.

۱. دریافت گروه‌های قابل استفاده

GET /v1/approved-groups
X-API-Key: YOUR_API_KEY

نمونه پاسخ:

[
  {
    "code": "customers-1405",
    "name": "مشتریان تاییدشده ۱۴۰۵",
    "recipientCount": 824,
    "approvedAt": "2026-08-01T08:15:00Z"
  }
]

۲. ارسال پیام به گروه

POST /v1/approved-groups/customers-1405/messages
X-API-Key: YOUR_API_KEY
Idempotency-Key: campaign-1405-05-18-01
Content-Type: application/json

{
  "sender": "300099000121",
  "message": "{{fullName}} عزیز، درخواست شما ثبت شد.",
  "clientReference": "campaign-781"
}

فیلدهای درخواست

groupCode در URL باید یکی از گروه‌هایی باشد که از GET /v1/approved-groups دریافت کرده‌اید.

۳. شخصی‌سازی متن

برای فهرست‌هایی که نام و نام خانوادگی مخاطبان در فرآیند تایید ثبت شده است، متغیرهای زیر برای شخصی‌سازی متن گروه قابل استفاده‌اند:

• {{firstName}}
• {{lastName}}
• {{fullName}}
• {{mobile}}

نمونه:

{{firstName}} عزیز، قرارداد شما آماده بررسی است.

مخاطبان و داده‌های شخصی‌سازی از گروه تاییدشده خوانده می‌شوند؛ Public API امکان تزریق شماره جدید به این فهرست را ندارد.

۴. پاسخ و رهگیری

پاسخ 202 Accepted یک آرایه از رکوردهای ارسال است. برای هر مخاطب trackingCode مستقل صادر می‌شود:

[
  {
    "trackingCode": "SMS-20260810-001A12BC",
    "status": "queued",
    "encoding": "Persian",
    "characterCount": 31,
    "partCount": 1,
    "submittedAt": "2026-08-10T07:20:00Z",
    "duplicate": false
  },
  {
    "trackingCode": "SMS-20260810-001A12BD",
    "status": "queued",
    "encoding": "Persian",
    "characterCount": 35,
    "partCount": 1,
    "submittedAt": "2026-08-10T07:20:00Z",
    "duplicate": false
  }
]

هر trackingCode را می‌توان مستقل با GET /v1/messages/{trackingCode} رهگیری کرد. برای بررسی چند کد به‌صورت همزمان نیز POST /v1/messages/status در دسترس است.

۵. نمونه C# / .NET

using System.Net.Http.Json;
using System.Text.Json;

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

// ابتدا گروه‌های مجاز حساب را بخوانید.
using var groupsResponse = await client.GetAsync("/v1/approved-groups");
groupsResponse.EnsureSuccessStatusCode();
var groupsJson = await groupsResponse.Content.ReadAsStringAsync();
Console.WriteLine(groupsJson);

// سپس فقط به یکی از groupCodeهای تاییدشده ارسال کنید.
var request = new HttpRequestMessage(
    HttpMethod.Post,
    "/v1/approved-groups/customers-1405/messages");
request.Headers.Add("Idempotency-Key", "campaign-1405-05-18-01");
request.Content = JsonContent.Create(new
{
    sender = "300099000121",
    message = "{{fullName}} عزیز، درخواست شما ثبت شد.",
    clientReference = "campaign-781"
});

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

using var json = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
foreach (var item in json.RootElement.EnumerateArray())
{
    Console.WriteLine(item.GetProperty("trackingCode").GetString());
}

۶. خطاهای مهم

۷. نکات اجرایی

• برای هر کمپین یک Idempotency-Key پایدار تولید کنید تا Retry شبکه باعث ارسال دوباره کل گروه نشود.
• recipientCount را قبل از ارسال بررسی کنید تا حجم عملیات برای شما روشن باشد.
• وضعیت نهایی هر گیرنده مستقل است؛ موفقیت پذیرش کل درخواست به معنی تحویل همه پیام‌ها نیست.
• تغییر فهرست گروه از مسیر Public API انجام نمی‌شود و نیازمند فرآیند تایید اداری SMSDaily است.