وب سرویس پیامک

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

آدرس پایه: https://api.ariaservice.net/sms/v1
قالب: JSON روی HTTPS
احراز هویت: توکن شخصی API که به صورت Bearer ارسال می‌شود (احراز هویت و توکن)
OpenAPI 3.0: https://api.ariaservice.net/sms/v1/openapi.json که در مرجع تعاملی قابل مرور است

وب سرویس قبلی پیامک

آدرس‌های قبلی sms-api.ariaservice.net/api/v1 و کلیدهای قبلی آن در دوره انتقال کار می‌کنند و پاسخ‌هایشان هدر Deprecation: true و پیوندی به همین صفحه دارد. برای پروژه‌های جدید از این وب سرویس و توکن حساب آریانت استفاده کنید.

شروع سریع

در پنل، در cloud.ariaservice.net/users/api-tokens توکنی با دسترسی‌های لازم (جدول زیر) بسازید.
خطوط ارسال را ببینید و از یکی از آن‌ها پیامک بفرستید (from شماره خط یا id آن است):

export ARIANET_TOKEN="paste-your-token-here"
BASE=https://api.ariaservice.net/sms/v1
AUTH="Authorization: Bearer $ARIANET_TOKEN"

curl -s $BASE/lines -H "$AUTH"
curl -s -X POST $BASE/messages -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"from":"300074360","recipients":["09121234567","09351234567"],"body":"Your code is 1234","client_reference":"order-981"}'

پاسخ 202 Accepted است:

{"batch_id":"01JC8Z...","status":"processing","total_recipients":2,"total_cost_rial":3000,"filtered_blocked_count":0}

هر ارسال یک batch می‌سازد و هزینه از کیف پول حساب کسر می‌شود؛ وضعیت را با GET /batches/{id} و GET /messages?batch_id=... دنبال کنید. شماره‌هایی که در فهرست مسدود شما هستند ارسال نمی‌شوند (filtered_blocked_count). قیمت هر پیام، و اینکه هزینه به ازای هر پیام است یا هر بخش پیامک، در GET /prices آمده است.

ارسال

POST /messages این فیلدها را می‌گیرد:

فیلد	نوع
`recipients`	آرایه رشته، ۱ تا ۱۰۰	شماره‌های موبایل (الزامی)
`from`	رشته عددی	شماره خط (`number`) یا `id` آن از `GET /lines` (الزامی)
`body`	رشته، حداکثر ۲۰۰۰ نویسه	متن پیام؛ الزامی مگر اینکه `template_id` داده شود
`template_id`	عدد	ارسال یکی از قالب‌های شما به جای `body`
`scheduled_at`	زمان ISO 8601 در آینده	ارسال در زمان مشخص به جای همین حالا
`client_reference`	رشته	شناسه شما برای این ارسال؛ اگر نباشد هدر `Idempotency-Key` به کار می‌رود. ارسال تکراری با همان شناسه دوباره انجام نمی‌شود

با scheduled_at هنوز چیزی ارسال یا کسر نمی‌شود: پاسخ {"scheduled_id":12,"status":"pending","scheduled_at":"..."} است، ارسال در GET /scheduled دیده می‌شود و تا وقتی در انتظار است با DELETE /scheduled/{id} لغو می‌شود.

فهرست‌ها و صفحه‌بندی

همه فهرست‌ها page و per_page (حداکثر ۲۰۰) می‌گیرند و این‌طور پاسخ می‌دهند:

{"data":[...],"meta":{"total":134,"current_page":1,"per_page":50}}

GET /messages بر اساس batch_id، status و to هم فیلتر می‌شود و GET /blocked-recipients بر اساس phone.

احراز هویت و دسترسی‌ها

دسترسی (scope)	اجازه
`sms:messages:read`	پیام‌های ارسالی و دریافتی، batchها، ارسال‌های زمان‌بندی‌شده، قیمت‌ها و گزارش
`sms:messages:write`	ارسال و لغو ارسال زمان‌بندی‌شده، شماره‌های مسدود و وب‌هوک
`sms:lines:read`	خطوط ارسال
`sms:templates:read`	قالب‌ها
`sms:templates:write`	ساخت، ویرایش و حذف قالب

توکن بدون هیچ دسترسی، بدون محدودیت است؛ درخواست خط اختصاصی (POST /lines) چنین توکنی می‌خواهد. پیامک فقط در ریجن iran-1 اجرا می‌شود و به هدر Arianet-Region نیازی ندارد.

منابع

متد و مسیر	کاربرد
`POST /messages`	ارسال فوری یا در `scheduled_at` (بخش ارسال)
`GET /messages` ، `GET /messages/{id}`	پیام‌های ارسالی و وضعیت تحویل
`GET /batches` ، `GET /batches/{id}`	batchهای ارسال
`GET /scheduled` ، `DELETE /scheduled/{id}`	ارسال‌های زمان‌بندی‌شده و لغو ارسال در انتظار
`GET /inbound`	پیام‌های دریافتی روی خطوط شما
`GET /lines` ، `POST /lines`	خطوط ارسال؛ درخواست خط اختصاصی (`number`، `note`)
`GET /templates` ، `POST /templates` ، `GET`/`PUT`/`DELETE /templates/{id}`	قالب‌ها (`name`، `body`)
`GET /blocked-recipients` ، `POST /blocked-recipients` ، `DELETE /blocked-recipients/{id}`	شماره‌های مسدود؛ ورودی `phone` و `note`، خروجی `mobile` و `reason`
`GET /webhook` ، `PUT /webhook` ، `POST /webhook/secret`	وب‌هوک (`url`، `enabled`، `events`) و ساخت کلید امضای جدید؛ بخش وب‌هوک
`GET /reports/summary`	ارسال‌شده، تحویل‌شده، ناموفق و هزینه، با ریز روزانه (`from`، `to`)
`GET /prices`	قیمت هر پیام و پله‌های حجمی

جزئیات بدنه و پاسخ هر endpoint در مرجع تعاملی آمده است.

وضعیت‌ها

شیء	مقدارهای `status`
پیام (`GET /messages`)	`queued` در صف، `sent` ارسال‌شده، `delivered` تحویل‌شده، `failed` ناموفق، `undelivered` تحویل‌نشده، `rejected` ردشده، `expired` منقضی
ارسال (`GET /batches`)	`pending`، `processing`، `partial` بخشی ناموفق، `completed`، `failed`
زمان‌بندی‌شده (`GET /scheduled`)	`scheduled`، `processing`، `sent`، `failed`، `cancelled`

فیلتر status در GET /messages و GET /batches همین مقدارها را می‌گیرد.

جزئیات پیام و تایم‌لاین

هر پیام در GET /messages این فیلدها را هم دارد:

فیلد	معنی
`operator`	اپراتور گیرنده از روی پیش‌شماره: `mci` همراه اول، `mtn` ایرانسل، `rightel` رایتل، `other` (برای شماره‌های ترابردشده تقریبی است)
`encoding`	`unicode` (فارسی) یا `gsm` (لاتین)
`queued_at`	زمان ثبت در صف
`provider.name`	درگاه ارسال، مثلاً `magfa`
`provider.message_id`	شناسه‌ی پیگیری پیام در اپراتور (مگفا)
`provider.status_code`	آخرین کد وضعیت اپراتور: `0` هنوز وضعیتی نیست، `8` تحویل به اپراتور، `1` تحویل به گوشی، `2` به گوشی تحویل نشد، `16` به اپراتور نرسید، `-1` منقضی
`provider.error_code`	کد خطای مگفا وقتی پیام را نپذیرفته است
`delivery_checks`	تعداد استعلام وضعیت تحویل
`last_checked_at`	زمان آخرین استعلام

GET /messages/{id} علاوه بر این‌ها timeline را برمی‌گرداند: فهرست مرحله‌ها به ترتیب زمان، هر کدام با type، at، status_code و error_code.

`type`	معنی
`queued`	ثبت در صف
`sent_to_provider`	ارسال به مگفا و دریافت شناسه‌ی پیگیری
`provider_refused`	مگفا پیام را نپذیرفت (هزینه برگشت داده می‌شود)
`status_checked`	استعلام وضعیت بدون نتیجه‌ی نهایی
`delivered_to_operator`	تحویل به شبکه‌ی اپراتور، در انتظار گوشی
`delivered`	تحویل به گوشی گیرنده
`not_delivered`	به گوشی تحویل نشد
`not_sent_to_operator`	به شبکه‌ی اپراتور نرسید
`expired`	گزارش تحویل در ۲۴ ساعت نیامد
`rejected`	رد شد

هر ارسال در GET /batches هم channel (panel، api یا system)، sender_ip (پوشیده، مثل 85.133.133.x) و completed_at دارد.

وب‌هوک

با PUT /webhook آدرس، روشن یا خاموش بودن و رویدادهای دلخواه را تنظیم کنید:

curl -s -X PUT $BASE/webhook -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/sms-hook","enabled":true,"events":["message.delivered","message.failed","inbound.received"]}'

رویداد	چه زمانی
`batch.completed`	پایان هر ارسال؛ برای وب‌هوک روشن همیشه فرستاده می‌شود
`message.delivered`	پیام به گیرنده تحویل شد
`message.failed`	پیام هرگز تحویل نمی‌شود (`failed`، `undelivered`، `rejected`، `expired`)
`inbound.received`	پیامکی روی خط اختصاصی شما دریافت شد

سه رویداد آخر فقط وقتی فرستاده می‌شوند که در events باشند؛ به‌طور پیش‌فرض خاموش‌اند.

هر رویداد یک POST با بدنهٔ {"event","occurred_at","data"} است و data همان شکلی را دارد که API برای آن شیء برمی‌گرداند:

{"event":"message.delivered","occurred_at":"2026-11-12T17:20:00+00:00","data":{"id":"01m78c...","batch_id":"01m78c...","to":"09121234567","from":"300074360","body":"Your code is 1234","parts":1,"status":"delivered","cost_rial":1750,"error":null,"sent_at":"...","delivered_at":"...","created_at":"..."}}

هدر X-Signature برابر HMAC-SHA256 بدنهٔ خام با کلید امضای وب‌هوک شماست؛ آن را بررسی کنید. پاسخ غیر 2xx تا ۵ بار با فاصلهٔ رو به افزایش دوباره فرستاده می‌شود.

خطاها

خطاها JSON هستند: {"code": "...", "message": "..."}.

HTTP	معنی
401	توکن نبود یا نامعتبر است
402	`insufficient_balance`: موجودی کافی نیست
403	`insufficient_scope`، `forbidden`، `identity_needed`، `account_suspended` یا `sender_line_not_usable` (این خط برای ارسال حساب شما نیست)
404	`not_found` (مثلاً قالبِ حساب دیگر)
422	`validation_failed`، `all_recipients_blocked`، `already_blocked`، `not_cancellable`
429	`rate_limit_exceeded` / `rate_limited`
503	`sms_unavailable`، `region_unavailable`
504	`gateway_timeout`: پاسخ به‌موقع نرسید؛ ممکن است ارسال انجام شده باشد، قبل از تکرار `GET /messages` را بررسی کنید (`client_reference` برای همین است)

شروع سریع​

ارسال​

فهرست‌ها و صفحه‌بندی​

احراز هویت و دسترسی‌ها​

منابع​

وضعیت‌ها​

جزئیات پیام و تایم‌لاین​

وب‌هوک​

خطاها​