شروع کار

ساختار درخواست و پاسخ

همه متدها از یک قاعده پیروی می‌کنند: پارامترها به‌صورت فرم یا query string، پاسخ همیشه JSON با یک بخش return.

متد HTTP

بیشتر متدها هم GET و هم POST را می‌پذیرند. متد پیشنهادی هر صفحه اولین برچسب کنار آدرس آن است. برای ارسال پیام، POST را ترجیح دهید: متن فارسی و فهرست بلند گیرنده‌ها در آدرس GET زود به سقف طول URL می‌رسند.

متد	محل پارامترها	نمونه
GET	query string	sms/status
POST	بدنه با `application/x-www-form-urlencoded`	sms/send
POST	بدنه با `multipart/form-data`	media/upload
DELETE	query string	line/blocked/remove

کدگذاری پارامترها

متن‌ها UTF-8 هستند و باید URL-encode شوند. http_build_query در PHP، URLSearchParams در جاوااسکریپت و requests در پایتون این کار را خودکار انجام می‌دهند.
چند مقدار برای یک پارامتر (مثل چند گیرنده) با ویرگول انگلیسی جدا می‌شوند: 09121234567,09351234567.
پارامترهای آرایه‌ای sendarray به‌صورت رشته JSON فرستاده می‌شوند.
شماره موبایل را با 09 شروع کنید؛ شماره بین‌المللی با 00 و کد کشور.

تاریخ‌ها

همه پارامترهای تاریخ (date، startdate، enddate) UnixTime به ثانیه هستند، نه میلی‌ثانیه. فرستادن مقدار میلی‌ثانیه رایج‌ترین علت خطای 417 است.

# GNU date: 1 hour from now
date=$(($(date +%s) + 3600))

// 1 hour from now
$date = time() + 3600;

// a specific Tehran time
$date = (new DateTime('2026-10-14 09:00', new DateTimeZone('Asia/Tehran')))->getTimestamp();

// 1 hour from now (seconds, not milliseconds)
const date = Math.floor(Date.now() / 1000) + 3600;

import time

# 1 hour from now
date = int(time.time()) + 3600

شکل پاسخ

پاسخ همیشه JSON است و دو بخش دارد:

return: نتیجه کل درخواست. return.status برابر ۲۰۰ یعنی موفقیت و هر مقدار دیگری یکی از کدهای خطا است. return.message شرح فارسی همان کد است.
entries: داده پاسخ؛ برای متدهای ارسال یک ردیف برای هر پیام. در خطا null است.
متدهای صفحه‌بندی‌شده یک بخش metadata هم دارند (totalcount، currentpage، totalpages، pagesize).

success.json

{
    "return": {
        "status": 200,
        "message": "تایید شد"
    },
    "entries": [
        {
            "messageid": 8792343,
            "status": 1,
            "statustext": "در صف ارسال",
            "receptor": "09121234567",
            "cost": 1200
        }
    ]
}

error.json

{
    "return": {
        "status": 418,
        "message": "اعتبار حساب شما کافی نیست"
    },
    "entries": null
}

بررسی نتیجه

کد وضعیت HTTP پاسخ با return.status برابر است، اما همیشه خود return.status را بررسی کنید؛ برخی کتابخانه‌های HTTP روی پاسخ غیر ۲۰۰ استثنا پرتاب می‌کنند و بدنه پاسخ را در دسترس نمی‌گذارند. موفق بودن درخواست یعنی پیام پذیرفته شده، نه اینکه به گیرنده رسیده است؛ تحویل را با وضعیت پیام پیگیری کنید.