مستندات وب‌سرویس

وب‌سرویس (API)

ارتباط امن سیستم‌های شما با دیالینگ از طریق JWT

دسترسی به وب‌سرویس

این صفحه مستندات عمومی API دیالینگ است. برای استفاده عملی باید در سامانه ثبت‌نام کنید، حسابتان فعال باشد و گزینه وب‌سرویس برای حساب شما در مدیریت روشن شود. توکن و رمز عبور را در اختیار دیگران نگذارید.

آدرس پایه

https://my.dialing.ir/api/v1

همه درخواست‌ها به‌جز دریافت توکن باید هدر زیر را داشته باشند:

Authorization: Bearer {{access_token}}

فایل Collection را از دکمه «دانلود خروجی Postman» بگیرید و در Postman از مسیر Import → File وارد کنید. بعد از اجرای Get Token، متغیر access_token به‌صورت خودکار پر می‌شود.

۱) دریافت توکن JWT

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

Request

POST https://my.dialing.ir/api/v1/auth/token
Content-Type: application/json
Accept: application/json

{
    "username": "09121234567",
    "password": "your-password"
}

Response 200

{
    "ok": true,
    "message": "توکن با موفقیت صادر شد.",
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "token_type": "Bearer",
        "expires_in": 3600
    }
}

حساب باید فعال باشد؛ در غیر این صورت پاسخ 403 با خطای account_inactive برمی‌گردد.
وب‌سرویس حساب باید در پنل مدیریت فعال باشد؛ در غیر این صورت پاسخ 403 با خطای api_disabled برمی‌گردد.
توکن معمولاً ۱ ساعت معتبر است (قابل تنظیم در سرور).
پس از تعویض رمز یا قطع وب‌سرویس، توکن قبلی باطل می‌شود و درخواست‌های بعدی هم رد می‌شوند.
در صورت تلاش‌های ناموفق زیاد، موقتاً مسدود می‌شوید (Rate Limit).

Response 403 — حساب غیرفعال

{
    "ok": false,
    "error": "account_inactive",
    "message": "حساب کاربری غیرفعال است."
}

Response 403 — وب‌سرویس غیرفعال

{
    "ok": false,
    "error": "api_disabled",
    "message": "دسترسی وب‌سرویس برای این حساب فعال نیست. با پشتیبانی تماس بگیرید."
}

۲) لیست داخلی‌ها

Request

GET https://my.dialing.ir/api/v1/extensions
Authorization: Bearer {{access_token}}
Accept: application/json

Response 200

{
    "ok": true,
    "message": "",
    "data": {
        "count": 1,
        "items": [
            {
                "id": 10,
                "extension": "282",
                "name": "پشتیبانی",
                "sip_uri": "282@ringtime.ir:4443",
                "server": "ringtime.ir",
                "port": 4443,
                "password": "********",
                "tech": "PJSIP/282"
            }
        ]
    }
}

فیلد extension شمارهٔ داخلی است. در تماس امن (روش ۱) همین مقدار را به‌عنوان extension_id بفرستید، نه فیلد id.

۳) لیست سرورها

Request

GET https://my.dialing.ir/api/v1/servers
Authorization: Bearer {{access_token}}
Accept: application/json

Response 200

{
    "ok": true,
    "message": "",
    "data": {
        "count": 1,
        "items": [
            {
                "name": "سرور تهران",
                "address": "https://ringtime.ir",
                "pjsip_port": 4443
            }
        ]
    }
}

۴) لیست شماره‌های خروجی

Request

GET https://my.dialing.ir/api/v1/outbound
Authorization: Bearer {{access_token}}
Accept: application/json

Response 200

{
    "ok": true,
    "message": "",
    "data": {
        "count": 1,
        "numbers": [
            "02191000000"
        ]
    }
}

۵) Directory (Direct Dial)

دفترچه مخاطبین پنل برای شماره‌گیری مستقیم

Request

GET https://my.dialing.ir/api/v1/directory
Authorization: Bearer {{access_token}}
Accept: application/json

Response 200

{
    "ok": true,
    "message": "",
    "data": {
        "count": 2,
        "items": [
            {
                "id": 1,
                "name": "امور مشتریان",
                "number": "02191001111"
            },
            {
                "id": 2,
                "name": "پشتیبانی",
                "number": "09121234567"
            }
        ]
    }
}

۶) تماس امن

دو روش برای POST /calls/safe وجود دارد. در هر درخواست فقط یکی از فیلدهای extension_id یا from_mobile را بفرستید. سرخط باید متعلق به حساب شما باشد. فیلد اختیاری duration حداکثر مدت مکالمه را بر حسب ثانیه تعیین می‌کند و باید عدد صحیح بزرگ‌تر از صفر باشد؛ برای مثال مقدار 300 یعنی ۳۰۰ ثانیه (۵ دقیقه). در صورت عدم ارسال، مدت مکالمه نامحدود است. حداکثر ۱۰ درخواست در دقیقه برای هر حساب و IP پذیرفته می‌شود.

روش ۱ — داخلی به موبایل

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

Request

POST https://my.dialing.ir/api/v1/calls/safe
Authorization: Bearer {{access_token}}
Content-Type: application/json
Accept: application/json

{
    "extension_id": 282,
    "mobile": "09121234567",
    "line_number": "02191000000",
    "duration": 300
}

Response 202

{
    "ok": true,
    "message": "درخواست تماس امن پذیرفته شد.",
    "data": {
        "accepted": true,
        "extension_id": 282,
        "mobile": "09121234567",
        "line_number": "02191000000",
        "duration": 300
    }
}

extension_id باید شمارهٔ داخلی موجود در فیلد extension خروجی /extensions باشد، نه فیلد id.

روش ۲ — موبایل به موبایل

ابتدا موبایل طرف اول (from_mobile) زنگ می‌خورد و سپس تماس با موبایل مقصد (mobile) از سرخط برقرار می‌شود. در این روش extension_id ارسال نکنید.

Request

POST https://my.dialing.ir/api/v1/calls/safe
Authorization: Bearer {{access_token}}
Content-Type: application/json
Accept: application/json

{
    "from_mobile": "09121111111",
    "mobile": "09121234567",
    "line_number": "02191000000",
    "duration": 300
}

Response 202

{
    "ok": true,
    "message": "درخواست تماس امن پذیرفته شد.",
    "data": {
        "accepted": true,
        "from_mobile": "09121111111",
        "mobile": "09121234567",
        "line_number": "02191000000",
        "duration": 300
    }
}

شماره from_mobile و mobile باید موبایل معتبر ایران (09xxxxxxxxx) و با هم متفاوت باشند.

۷) گزارش تماس‌ها

حداکثر limit در هر درخواست ۲۰۰ است (پیش‌فرض ۵۰).

Request — بر اساس تاریخ

GET https://my.dialing.ir/api/v1/reports?from_date=2026-07-01&to_date=2026-07-14&limit=50
Authorization: Bearer {{access_token}}
Accept: application/json

تاریخ میلادی: YYYY-MM-DD یا شمسی: YYYY/MM/DD

Request — بر اساس شماره گزارش

GET https://my.dialing.ir/api/v1/reports?from_id=150000&limit=50
Authorization: Bearer {{access_token}}
Accept: application/json

از شناسه from_id به بعد (صعودی) حداکثر limit رکورد برمی‌گردد.

Response 200

{
    "ok": true,
    "message": "",
    "data": {
        "count": 1,
        "total": 120,
        "limit": 50,
        "items": [
            {
                "id": 150001,
                "type": 1,
                "type_label": "تماس ورودی",
                "calldate": "2026-07-14 12:00:00",
                "src": "09121234567",
                "dst": "282",
                "trunk_num": "02191000000",
                "duration": 45,
                "billsec": 40,
                "disposition": "1",
                "uniqueid": "1720960000.123",
                "has_recording": true,
                "recording_url": "https://my.dialing.ir/api/v1/reports/150001/recording"
            }
        ]
    }
}

۸) دانلود فایل صوتی گزارش

Request

GET https://my.dialing.ir/api/v1/reports/{id}/recording
Authorization: Bearer {{access_token}}

پاسخ موفق فایل audio/wav است (نه JSON). این آدرس را در مرورگر بدون توکن باز نکنید؛ حتماً هدر Authorization بفرستید (مثلاً با Postman).

Alternative: GET https://my.dialing.ir/api/v1/reports/recording/{id}

۹) لیست فایل‌های صوتی تماس‌ها (ضبط مکالمه)

فقط تماس‌هایی که فایل ضبط‌شده دارند، همراه نام فایل، حجم و لینک دانلود. مثل گزارش تماس، حداکثر limit در هر درخواست ۲۰۰ است (پیش‌فرض ۵۰).

Request — بر اساس تاریخ

GET https://my.dialing.ir/api/v1/recordings?from_date=2026-07-01&to_date=2026-07-14&limit=50
Authorization: Bearer {{access_token}}
Accept: application/json

تاریخ میلادی: YYYY-MM-DD یا شمسی: YYYY/MM/DD — نتایج نزولی (جدیدترین اول)

Request — بر اساس شماره گزارش

GET https://my.dialing.ir/api/v1/recordings?from_id=150000&limit=50
Authorization: Bearer {{access_token}}
Accept: application/json

از شناسه from_id به بعد به‌صورت صعودی؛ مناسب همگام‌سازی دوره‌ای فایل‌های جدید.

Response 200

{
    "ok": true,
    "message": "",
    "data": {
        "count": 1,
        "total": 37,
        "limit": 50,
        "items": [
            {
                "id": 150001,
                "report_id": 150001,
                "type": 1,
                "type_label": "تماس ورودی",
                "calldate": "2026-07-14 12:00:00",
                "src": "09121234567",
                "dst": "282",
                "trunk_num": "02191000000",
                "duration": 45,
                "billsec": 40,
                "disposition": "1",
                "uniqueid": "1720960000.123",
                "filename": "in-282-09121234567-20260714-120000-1720960000.123.wav",
                "file_size_mb": 0.312,
                "download_url": "https://my.dialing.ir/api/v1/recordings/150001"
            }
        ]
    }
}

id و report_id یکی هستند و همان شناسه گزارش تماس‌اند.
file_size_mb حجم تقریبی فایل بر حسب مگابایت است.
برای دانلود، آدرس download_url را با هدر Authorization صدا بزنید.

۱۰) دانلود فایل صوتی با آدرس کوتاه

Request

GET https://my.dialing.ir/api/v1/recordings/{id}
Authorization: Bearer {{access_token}}

دقیقاً همان خروجی reports/{id}/recording است؛ پاسخ موفق فایل audio/wav است (نه JSON).

۱۱) لیست صوت‌های آپلودی (Sounds)

همان فایل‌های صوتی که از بخش «فایل‌های صوتی» پنل بارگذاری کرده‌اید؛ برای انتخاب صوت در تماس و پخش فایل استفاده می‌شود.

Request

GET https://my.dialing.ir/api/v1/sounds
Authorization: Bearer {{access_token}}
Accept: application/json

Response 200

{
    "ok": true,
    "message": "",
    "data": {
        "count": 2,
        "items": [
            {
                "id": 12,
                "name": "welcome",
                "description": "پیام خوش‌آمدگویی",
                "server_id": 3,
                "server": "سرور تهران"
            },
            {
                "id": 15,
                "name": "off_hours",
                "description": "پیام خارج از ساعت کاری",
                "server_id": 3,
                "server": "سرور تهران"
            }
        ]
    }
}

مقدار id همان sound_id برای تماس و پخش فایل صوتی است.

۱۲) تماس و پخش فایل صوتی

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

Request

POST https://my.dialing.ir/api/v1/calls/play_file
Authorization: Bearer {{access_token}}
Content-Type: application/json
Accept: application/json

{
    "sound_id": 12,
    "mobile": "09121234567",
    "line_number": "02191000000"
}

Response 202

{
    "ok": true,
    "message": "درخواست تماس و پخش فایل صوتی پذیرفته شد.",
    "data": {
        "accepted": true,
        "sound_id": 12,
        "sound_name": "welcome",
        "mobile": "09121234567",
        "line_number": "02191000000"
    }
}

sound_id شناسه صوت از خروجی /sounds است.
line_number باید یکی از سرخط‌های شما در خروجی /outbound باشد.
mobile با فرمت 09xxxxxxxxx.
حداکثر ۱۰ درخواست در دقیقه برای هر حساب و IP پذیرفته می‌شود.

نمونه پاسخ خطا

{
    "ok": false,
    "error": "unauthorized",
    "message": "توکن احراز هویت الزامی است."
}

وب‌هوک گزارش تماس

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

نکات امنیتی

توکن و رمز داخلی‌ها را در کد سمت کاربر (مرورگر) ذخیره نکنید.
فقط از HTTPS استفاده کنید.
در پاسخ‌های خطا، جزئیات داخلی سرور برنمی‌گردد.
دسترسی فقط برای حساب‌هایی است که وب‌سرویس آن‌ها در مدیریت فعال شده باشد.

نمونه cURL

TOKEN=$(curl -s -X POST 'https://my.dialing.ir/api/v1/auth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "09121234567",
    "password": "***"
  }' | jq -r '.data.access_token')

curl -s 'https://my.dialing.ir/api/v1/extensions' \
  -H "Authorization: Bearer $TOKEN"

curl -s 'https://my.dialing.ir/api/v1/servers' \
  -H "Authorization: Bearer $TOKEN"

curl -s 'https://my.dialing.ir/api/v1/outbound' \
  -H "Authorization: Bearer $TOKEN"

curl -s 'https://my.dialing.ir/api/v1/directory' \
  -H "Authorization: Bearer $TOKEN"

curl -s -X POST 'https://my.dialing.ir/api/v1/calls/safe' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"extension_id":282,"mobile":"09121234567","line_number":"02191000000"}'

curl -s -X POST 'https://my.dialing.ir/api/v1/calls/safe' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"from_mobile":"09121111111","mobile":"09121234567","line_number":"02191000000"}'

curl -s 'https://my.dialing.ir/api/v1/sounds' \
  -H "Authorization: Bearer $TOKEN"

curl -s -X POST 'https://my.dialing.ir/api/v1/calls/play_file' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"sound_id":12,"mobile":"09121234567","line_number":"02191000000"}'

curl -s 'https://my.dialing.ir/api/v1/reports?from_date=2026-07-01&to_date=2026-07-14&limit=20' \
  -H "Authorization: Bearer $TOKEN"

curl -s 'https://my.dialing.ir/api/v1/recordings?from_date=2026-07-01&to_date=2026-07-14&limit=20' \
  -H "Authorization: Bearer $TOKEN"

curl -L 'https://my.dialing.ir/api/v1/recordings/12345' \
  -H "Authorization: Bearer $TOKEN" \
  -o call.wav

curl -L 'https://my.dialing.ir/api/v1/reports/12345/recording' \
  -H "Authorization: Bearer $TOKEN" \
  -o call.wav