ثبت‌نام

دریافت توکن API پیامک

دریافت توکن API از پنل ویکی‌پیام

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

دریافت توکن API شروع سریع API
  • توکن API را در اختیار افراد غیرمجاز قرار ندهید.
  • توکن را داخل کدهای عمومی یا مخزن Git عمومی منتشر نکنید.
  • در پروژه‌های Laravel بهتر است توکن داخل فایل .env نگهداری شود.
  • در صورت نیاز به تغییر یا تمدید توکن، از بخش پروفایل من در پنل اقدام کنید.
توکن API فقط باید سمت سرور استفاده شود. آن را در JavaScript عمومی، query string، localStorage، sessionStorage، مخزن Git یا سورس قابل مشاهده کاربران قرار ندهید.
سرویسMethodEndpointکاربردBearer Token
موجودی GET https://wikipayam.ir/api/v1/user/balance دریافت موجودی کاربر بله
ارسال پیامک POST https://wikipayam.ir/api/v1/sms/send ارسال پیامک تکی یا چندتایی بله
وضعیت تحویل POST https://wikipayam.ir/api/v1/sms/deliver پیگیری وضعیت تحویل پیامک بله
دریافت legacy POST https://wikipayam.ir/api/v1/sms/receive دریافت پیامک‌های قدیمی بله
مدیریت دریافت‌ها GET https://wikipayam.ir/api/v1/receives لیست و مدیریت پیام‌های دریافتی جدید بله
OTP پیامکی POST https://wikipayam.ir/api/v1/otp/sms/send ارسال کد تأیید پیامکی بله
OTP صوتی POST https://wikipayam.ir/api/v1/voice-otp/send ارسال کد تأیید با تماس صوتی بله
سازگار با هلو GET/POST https://wikipayam.ir/api/v1/service/holoo اتصال سازگار با نرم‌افزار هلو بله
SMS Service API - Public

راهنمای کامل وب‌سرویس‌های ویکی پیام

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

Base URL: https://wikipayam.ir Prefix: api/v1

روش‌های اتصال

REST/JSON جدید

ارسال درخواست با Bearer Token و بدنه JSON.

Legacy Query Params

ارسال پیامک با پارامترهای URL برای سازگاری با سیستم‌های قدیمی.

Holoo Compatible

Endpoint سازگار با نرم‌افزار هلو به دو روش GET و POST.

Voice OTP

ارسال کد تأیید از طریق تماس صوتی و ثبت درخواست در صف پردازش.

شروع سریع

۱
دریافت Token

توکن را از پروفایل پنل ویکی پیام دریافت کنید و محرمانه نگه دارید.

رفتن به صفحه دریافت Token ↗
۲
تنظیم Headerها

هدرهای Accept و Content-Type را برابر application/json قرار دهید.

۳
ارسال درخواست

Endpoint موردنظر را فراخوانی و شناسه پیامک را برای پیگیری ذخیره کنید.

Authorization: Bearer YOUR_AUTH_TOKEN_HERE
Accept: application/json
Content-Type: application/json
⚡ اتصال سریع

شروع ۵ دقیقه‌ای برای برنامه‌نویسان

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

۱. دریافت Token

از بخش پروفایل پنل ویکی پیام، توکن API خود را دریافت کنید.

دریافت Token ↗
۲. انتخاب خط

یک شماره ارسال‌کننده فعال مثل 10002000 انتخاب کنید.

۳. تست موجودی

ابتدا Endpoint موجودی را تست کنید تا Token تأیید شود.

۴. ارسال پیامک

با /sms/send پیامک تست ارسال کنید.

۵. بررسی تحویل

شناسه پیامک را ذخیره و با /sms/deliver پیگیری کنید.

دسترسی سریع به Token: برای دریافت یا مشاهده توکن API وارد پروفایل ویکی پیام شوید. باز کردن صفحه پروفایل ↗
هشدار امنیتی Token: توکن API فقط باید در سمت سرور استفاده شود. از قرار دادن Token در JavaScript فرانت‌اند، اپلیکیشن عمومی، گیت عمومی یا سورس قابل مشاهده کاربران خودداری کنید.
🧪 تست زنده API

آزمایشگاه وب‌سرویس ویکی پیام

برای تست سریع Endpointها، اطلاعات خود را وارد کنید و درخواست را مستقیم از مرورگر ارسال کنید. توکن را عمومی منتشر نکنید.

درخواست ساخته‌شده

درخواست تست اینجا نمایش داده می‌شود.

پاسخ سرور

هنوز درخواستی ارسال نشده است.
Response اینجا نمایش داده می‌شود.
⌘ کد آماده برنامه‌نویسی

Code Snippets سازگار با Postman

برای هر سرویس، نمونه کد آماده در زبان‌های رایج تولید شده است. مقادیر نمونه مانند YOUR_AUTH_TOKEN_HERE، 10002000 و شماره گیرنده را با اطلاعات واقعی پنل جایگزین کنید.

زبان / ابزار
نکته: در درخواست‌های جدید، احراز هویت از طریق هدر Authorization: Bearer انجام می‌شود. روش Legacy و Holoo GET برای سازگاری با سیستم‌های قدیمی در مستند باقی مانده‌اند.

نمونه کد

کد آماده برای سرویس انتخاب‌شده.

کد آماده اینجا نمایش داده می‌شود.
🧮 ابزار محاسبه

محاسبه تعداد پارت و هزینه پیامک

بر اساس متن، تعداد گیرنده و تعرفه هر پارت، برآورد هزینه ارسال محاسبه می‌شود.

پیامک فارسی معمولاً ۷۰ کاراکتر در پارت اول و ۶۷ کاراکتر در پیامک‌های چندبخشی محاسبه می‌شود. پیامک انگلیسی معمولاً ۱۶۰ و ۱۵۳ کاراکتر است.

نتیجه محاسبه

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

سرویس موجودی

GET

دریافت موجودی کاربر

GET {{base_url}}/{{api_prefix}}/user/balance

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

AuthorizationBearer {{auth_token}}
Acceptapplication/json

نمونه cURL

curl --location --request GET '{{base_url}}/{{api_prefix}}/user/balance' \
  --header 'Authorization: Bearer {{auth_token}}' \
  --header 'Accept: application/json'

نمونه پاسخ موفق

{
  "data": {
    "balance": 34359938,
    "currency": "IRR",
    "user_id": 1,
    "user_name": "admin"
  }
}

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

POST

ارسال پیامک تکی

POST {{base_url}}/{{api_prefix}}/sms/send

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

AuthorizationBearer {{auth_token}}
Content-Typeapplication/json
Acceptapplication/json

بدنه درخواست

[
    {
      "sender": "{{sender}}",
      "receiver": "09123456789",
      "message": "Your verification code is: 123456",
      "track_id": "TRACK_001"
    }
  ]

نمونه cURL

curl --location --request POST '{{base_url}}/{{api_prefix}}/sms/send' \
    --header 'Authorization: Bearer {{auth_token}}' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data '[
      {
          "sender": "{{sender}}",
          "receiver": "09123456789",
          "message": "Your verification code is: 123456",
          "track_id": "TRACK_001"
      }
  ]'

نمونه پاسخ موفق

{
    "data": [
      {
        "id": "69e5eeab439260d336015405",
        "sender": "100010000",
        "receiver": "09123456789",
        "track_id": "TRACK_001"
      }
    ]
  }
POST

ارسال چند پیامک

POST {{base_url}}/{{api_prefix}}/sms/send

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

AuthorizationBearer {{auth_token}}
Content-Typeapplication/json
Acceptapplication/json

بدنه درخواست

[
    {
      "sender": "{{sender}}",
      "receiver": "09123456789",
      "message": "Hello from sender 1",
      "track_id": "TRACK_001"
    },
    {
      "sender": "{{sender}}",
      "receiver": "09987654321",
      "message": "Hello from sender 1",
      "track_id": "TRACK_002"
    },
    {
      "sender": "{{sender}}",
      "receiver": "09123456789",
      "message": "Hello from sender 2",
      "track_id": "TRACK_003"
    }
  ]

نمونه cURL

curl --location --request POST '{{base_url}}/{{api_prefix}}/sms/send' \
    --header 'Authorization: Bearer {{auth_token}}' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data '[
      {
          "sender": "{{sender}}",
          "receiver": "09123456789",
          "message": "Hello from sender 1",
          "track_id": "TRACK_001"
      },
      {
          "sender": "{{sender}}",
          "receiver": "09987654321",
          "message": "Hello from sender 1",
          "track_id": "TRACK_002"
      },
      {
          "sender": "{{sender}}",
          "receiver": "09123456789",
          "message": "Hello from sender 2",
          "track_id": "TRACK_003"
      }
  ]'

نمونه پاسخ موفق

{
    "data": [
      {
        "id": "69e5eee2439260d336015409",
        "sender": "100010000",
        "receiver": "09123456789",
        "track_id": "TRACK_001"
      },
      {
        "id": "69e5eee2439260d33601540a",
        "sender": "100010000",
        "receiver": "09987654321",
        "track_id": "TRACK_002"
      },
      {
        "id": "69e5eee2439260d33601540b",
        "sender": "100010000",
        "receiver": "09123456789",
        "track_id": "TRACK_003"
      }
    ]
  }
POST

ارسال پیامک با فیلد جایگزین note

POST {{base_url}}/{{api_prefix}}/sms/send

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

AuthorizationBearer {{auth_token}}
Content-Typeapplication/json
Acceptapplication/json

بدنه درخواست

[
    {
      "sender": "{{sender}}",
      "receiver": "09123456789",
      "note": "This will be converted to message field automatically",
      "track_id": "TRACK_004"
    }
  ]

نمونه cURL

curl --location --request POST '{{base_url}}/{{api_prefix}}/sms/send' \
    --header 'Authorization: Bearer {{auth_token}}' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data '[
      {
          "sender": "{{sender}}",
          "receiver": "09123456789",
          "note": "This will be converted to message field automatically",
          "track_id": "TRACK_004"
      }
  ]'

سرویس وضعیت تحویل

POST

دریافت وضعیت تحویل پیامک

POST {{base_url}}/{{api_prefix}}/sms/deliver

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

AuthorizationBearer {{auth_token}}
Content-Typeapplication/json
Acceptapplication/json

بدنه درخواست

{
  "id": [
    "507f1f77bcf86cd799439011",
    "507f1f77bcf86cd799439012"
  ]
}

نمونه cURL

curl --location --request POST '{{base_url}}/{{api_prefix}}/sms/deliver' \
  --header 'Authorization: Bearer {{auth_token}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "id": ["507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012"]
}'

نمونه پاسخ موفق

{
  "data": [
    {
      "id": "69e5eeab439260d336015405",
      "deliver_status": "WAITING_FOR_UPDATE",
      "track_id": null
    }
  ]
}

سرویس دریافت پیامک قدیمی

POST

دریافت پیام‌های ورودی - قدیمی

POST {{base_url}}/{{api_prefix}}/sms/receive

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

AuthorizationBearer {{auth_token}}
Content-Typeapplication/json
Acceptapplication/json

بدنه درخواست

{
  "from_date": "2024-01-01"
}

نمونه cURL

curl --location --request POST '{{base_url}}/{{api_prefix}}/sms/receive' \
  --header 'Authorization: Bearer {{auth_token}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "from_date": "2024-01-01"
}'

مدیریت پیام‌های دریافتی جدید

GET

دریافت همه پیام‌های ورودی

GET {{base_url}}/{{api_prefix}}/receives?limit=20&offset=0&status=all

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

AuthorizationBearer {{auth_token}}
Acceptapplication/json

پارامترهای Query

نامنمونه مقدارتوضیح
limit20Number of records per page (max: 500)
offset0Number of records to skip
statusallFilter by status: all, read, unread

نمونه cURL

curl --location --request GET '{{base_url}}/{{api_prefix}}/receives?limit=20&offset=0&status=all' \
  --header 'Authorization: Bearer {{auth_token}}' \
  --header 'Accept: application/json'

نمونه پاسخ موفق

{
  "data": {
    "receives": [
      {
        "id": "65109b3030ca072f7a047623",
        "sender": "989127782175",
        "receiver": "989999159314",
        "message": "۱۱",
        "received_at": "2023-09-24 23:55:20"
      },
      {
        "id": "65109b3030ca072f7a047624",
        "sender": "989178100665",
        "receiver": "989999159314",
        "message": "لغو ",
        "received_at": "2023-09-24 23:55:20"
      }
    ],
    "pagination": {
      "total": 178,
      "limit": "2",
      "offset": "0",
      "returned_count": 2,
      "total_pages": 89
    },
    "filters": {
      "status": "all"
    }
  }
}
GET

دریافت پیام‌های ورودی با فیلتر

GET {{base_url}}/{{api_prefix}}/receives?sender=09123456789&from_date=2024-01-01&to_date=2024-12-31&status=unread&search=verification&sort_by=created_at&sort_order=desc&limit=50&offset=0

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

AuthorizationBearer {{auth_token}}
Acceptapplication/json

پارامترهای Query

نامنمونه مقدارتوضیح
sender09123456789Filter by sender number
from_date2024-01-01Start date filter
to_date2024-12-31End date filter
statusunreadStatus filter: all, read, unread
searchverificationSearch in message content
sort_bycreated_atSort field: created_at, sender, message
sort_orderdescSort order: asc, desc
limit50Records per page
offset0Records to skip

نمونه cURL

curl --location --request GET '{{base_url}}/{{api_prefix}}/receives?sender=09123456789&from_date=2024-01-01&to_date=2024-12-31&status=unread&search=verification&sort_by=created_at&sort_order=desc&limit=50&offset=0' \
  --header 'Authorization: Bearer {{auth_token}}' \
  --header 'Accept: application/json'
GET

دریافت پیام‌های خوانده‌نشده

GET {{base_url}}/{{api_prefix}}/receives/unread?limit=30&offset=0&sender=100020003000&from_date=2024-01-01&to_date=2024-02-01

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

AuthorizationBearer {{auth_token}}
Acceptapplication/json

پارامترهای Query

نامنمونه مقدارتوضیح
limit30Number of records per page (max: 500)
offset0Number of records to skip
sender100020003000Filter by sender number
from_date2024-01-01Start date filter
to_date2024-02-01End date filter

نمونه cURL

curl --location --request GET '{{base_url}}/{{api_prefix}}/receives/unread?limit=30&offset=0&sender=100020003000&from_date=2024-01-01&to_date=2024-02-01' \
  --header 'Authorization: Bearer {{auth_token}}' \
  --header 'Accept: application/json'

نمونه پاسخ موفق

{
  "data": {
    "total_unread": 178,
    "receives": [
      {
        "id": "65109b3030ca072f7a047623",
        "sender": "989127782175",
        "receiver": "989999159314",
        "message": "۱۱",
        "received_at": "2023-09-24 23:55:20"
      },
      {
        "id": "65109b3030ca072f7a047624",
        "sender": "989178100665",
        "receiver": "989999159314",
        "message": "لغو ",
        "received_at": "2023-09-24 23:55:20"
      }
    ],
    "pagination": {
      "limit": "2",
      "offset": "0",
      "returned_count": 2
    }
  }
}
GET

دریافت تعداد پیام‌های خوانده‌نشده

GET {{base_url}}/{{api_prefix}}/receives/unread/count

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

AuthorizationBearer {{auth_token}}
Acceptapplication/json

نمونه cURL

curl --location --request GET '{{base_url}}/{{api_prefix}}/receives/unread/count' \
  --header 'Authorization: Bearer {{auth_token}}' \
  --header 'Accept: application/json'

نمونه پاسخ موفق

{
  "data": {
    "unread_count": 178
  }
}
GET

دریافت آمار پیام‌های ورودی

GET {{base_url}}/{{api_prefix}}/receives/statistics?from_date=2024-01-01&to_date=2024-12-31

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

AuthorizationBearer {{auth_token}}
Acceptapplication/json

پارامترهای Query

نامنمونه مقدارتوضیح
from_date2024-01-01Start date for statistics
to_date2024-12-31End date for statistics

نمونه cURL

curl --location --request GET '{{base_url}}/{{api_prefix}}/receives/statistics?from_date=2024-01-01&to_date=2024-12-31' \
  --header 'Authorization: Bearer {{auth_token}}' \
  --header 'Accept: application/json'
GET

دریافت پیام ورودی با شناسه

GET {{base_url}}/{{api_prefix}}/receives/507f1f77bcf86cd799439011

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

AuthorizationBearer {{auth_token}}
Acceptapplication/json

نمونه cURL

curl --location --request GET '{{base_url}}/{{api_prefix}}/receives/507f1f77bcf86cd799439011' \
  --header 'Authorization: Bearer {{auth_token}}' \
  --header 'Accept: application/json'
POST

خوانده‌شدن پیام‌های مشخص

POST {{base_url}}/{{api_prefix}}/receives/mark-read

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

AuthorizationBearer {{auth_token}}
Content-Typeapplication/json
Acceptapplication/json

بدنه درخواست

{
  "receive_ids": [
    "507f1f77bcf86cd799439011",
    "507f1f77bcf86cd799439012"
  ]
}

نمونه cURL

curl --location --request POST '{{base_url}}/{{api_prefix}}/receives/mark-read' \
  --header 'Authorization: Bearer {{auth_token}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "receive_ids": ["507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012"]
}'

نمونه پاسخ موفق

{
  "data": {
    "marked_count": 1,
    "requested_count": 1
  }
}
POST

خوانده‌شدن همه پیام‌ها

POST {{base_url}}/{{api_prefix}}/receives/mark-read

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

AuthorizationBearer {{auth_token}}
Content-Typeapplication/json
Acceptapplication/json

بدنه درخواست

{
  "mark_all": true
}

نمونه cURL

curl --location --request POST '{{base_url}}/{{api_prefix}}/receives/mark-read' \
  --header 'Authorization: Bearer {{auth_token}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "mark_all": true
}'
DELETE

حذف پیام‌های مشخص

DELETE {{base_url}}/{{api_prefix}}/receives

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

AuthorizationBearer {{auth_token}}
Content-Typeapplication/json
Acceptapplication/json

بدنه درخواست

{
  "receive_ids": [
    "507f1f77bcf86cd799439011",
    "507f1f77bcf86cd799439012"
  ]
}

نمونه cURL

curl --location --request DELETE '{{base_url}}/{{api_prefix}}/receives' \
  --header 'Authorization: Bearer {{auth_token}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "receive_ids": ["507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012"]
}'

نمونه پاسخ موفق

{
  "data": {
    "deleted_count": 1,
    "requested_count": 1
  }
}
DELETE

حذف همه پیام‌های خوانده‌شده

DELETE {{base_url}}/{{api_prefix}}/receives

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

AuthorizationBearer {{auth_token}}
Content-Typeapplication/json
Acceptapplication/json

بدنه درخواست

{
  "delete_all_read": true
}

نمونه cURL

curl --location --request DELETE '{{base_url}}/{{api_prefix}}/receives' \
  --header 'Authorization: Bearer {{auth_token}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "delete_all_read": true
}'

نمونه پاسخ موفق

{
  "data": {
    "deleted_count": 1,
    "message": "All read receives have been deleted"
  }
}
DELETE

حذف همه پیام‌های خوانده‌نشده

DELETE {{base_url}}/{{api_prefix}}/receives

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

AuthorizationBearer {{auth_token}}
Content-Typeapplication/json
Acceptapplication/json

بدنه درخواست

{
  "delete_all_unread": true
}

نمونه cURL

curl --location --request DELETE '{{base_url}}/{{api_prefix}}/receives' \
  --header 'Authorization: Bearer {{auth_token}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "delete_all_unread": true
}'
DELETE

حذف پیام‌های قدیمی‌تر از چند روز

DELETE {{base_url}}/{{api_prefix}}/receives

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

AuthorizationBearer {{auth_token}}
Content-Typeapplication/json
Acceptapplication/json

بدنه درخواست

{
  "delete_older_than_days": 30
}

نمونه cURL

curl --location --request DELETE '{{base_url}}/{{api_prefix}}/receives' \
  --header 'Authorization: Bearer {{auth_token}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "delete_older_than_days": 30
}'

سرویس پیامک OTP

POST

ارسال پیامک OTP

POST {{base_url}}/{{api_prefix}}/otp/sms/send

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

AuthorizationBearer {{auth_token}}
Content-Typeapplication/json
Acceptapplication/json

بدنه درخواست

[
  {
    "receiver": "09123456789",
    "code": "123456",
    "otp_pattern_id": 13,
    "track_id": "OTP_001"
  }
]

نمونه cURL

curl --location --request POST '{{base_url}}/{{api_prefix}}/otp/sms/send' \
  --header 'Authorization: Bearer {{auth_token}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '[
    {
        "receiver": "09123456789",
        "code": "123456",
        "otp_pattern_id": 13,
        "track_id": "OTP_001"
    }
]'

سرویس OTP صوتی

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

ارسال OTP صوتی

ثبت درخواست Voice OTP در صف پردازش تماس صوتی.

POST {{base_url}}/api/v1/voice-otp/send

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

AuthorizationBearer {{auth_token}}
Content-Typeapplication/json
Acceptapplication/json

پارامترهای بدنه

receiverشماره موبایل گیرنده کد صوتی
codeکد یکبارمصرف که در تماس صوتی اعلام می‌شود
track_idشناسه اختیاری برای پیگیری سمت سامانه شما

بدنه درخواست

{
  "receiver": "09123456789",
  "code": "123456",
  "track_id": "ORDER-1001"
}

نمونه cURL

curl --location --request POST '{{base_url}}/api/v1/voice-otp/send' \
  --header 'Authorization: Bearer {{auth_token}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "receiver": "09123456789",
  "code": "123456",
  "track_id": "ORDER-1001"
}'

نمونه پاسخ موفق

{
  "data": {
    "message": "Voice OTP queued successfully",
    "id": "6a02f05a3492873a9e086e86"
    "track_id": "ORDER-1001"
  }
}
پاسخ موفق نشان می‌دهد درخواست در صف Voice OTP ثبت شده است. شناسه برگشتی id را برای پیگیری داخلی و گزارش‌گیری ذخیره کنید.

سرویس سازگار با هلو

POST

ارسال پیامک هلو

POST {{base_url}}/{{api_prefix}}/service/holoo

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

Content-Typeapplication/json
Acceptapplication/json
AuthorizationBearer {{token}}

بدنه درخواست

{
  "username": "{{username}}",
  "password": "{{auth_token}}",
  "from": "{{sender}}",
  "to": "09123456789",
  "message": "This is a test message from Holoo SMS"
}

نمونه cURL

curl --location --request POST '{{base_url}}/{{api_prefix}}/service/holoo' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{token}}' \
  --data '{
    "username": "{{username}}",
    "password": "{{auth_token}}",
    "from": "{{sender}}",
    "to": "09123456789",
    "message": "This is a test message from Holoo SMS"
}'
GET

ارسال پیامک هلو

GET {{base_url}}/{{api_prefix}}/service/holoo?username={{username}}&password={{auth_token}}&from={{sender}}&to=09123456789&message=تست

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

هدر خاصی ثبت نشده است.

پارامترهای Query

نامنمونه مقدارتوضیح
username{{username}}
password{{auth_token}}
from{{sender}}
to09123456789
messageتست

نمونه cURL

curl --location --request GET '{{base_url}}/{{api_prefix}}/service/holoo?username={{username}}&password={{auth_token}}&from={{sender}}&to=09123456789&message=تست'

کلاس آماده Laravel / PHP

یک Client سبک برای استفاده در پروژه‌های Laravel و PHP آماده شده است.

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

فایل config/sms.php را ایجاد کنید:

<?php

return [
    /*
    |--------------------------------------------------------------------------
    | SMS API Configuration
    |--------------------------------------------------------------------------
    */

    'base_url' => env('WIKIPAYAM_SMS_API_BASE_URL', 'https://wikipayam.ir'),
    'api_prefix' => env('WIKIPAYAM_SMS_API_PREFIX', 'api/v1'),
    'auth_token' => env('SMS_AUTH_TOKEN', ''),
    'sender' => env('SMS_SENDER', '10002000'),
    'username' => env('SMS_USERNAME', '09123456789'),
];

متغیرهای محیطی

به فایل .env خود اضافه کنید:

WIKIPAYAM_SMS_API_BASE_URL=https://wikipayam.ir
WIKIPAYAM_SMS_API_PREFIX=api/v1
SMS_AUTH_TOKEN=your_actual_auth_token_here
SMS_SENDER=10002000
SMS_USERNAME=09123456789

مثال استفاده

<?php

use App\Services\WikipayamSMSService;

// In your controller
class SMSController extends Controller
{
    protected WikipayamSMSService $wikipayamSMSService;

    public function __construct(WikipayamSMSService $wikipayamSMSService)
    {
        $this->wikipayamSMSService = $wikipayamSMSService;
    }

    public function sendVerificationCode(Request $request)
    {
        try {
            $result = $this->wikipayamSMSService->sendSMS(
                receiver: $request->phone_number,
                message: "Your verification code is: 123456",
                trackId: "VERIFY_" . uniqid()
            );

            return response()->json(['success' => true, 'data' => $result]);
        } catch (\Exception $e) {
            return response()->json(['success' => false, 'error' => $e->getMessage()], 500);
        }
    }

    public function checkBalance()
    {
        try {
            $balance = $this->wikipayamSMSService->getBalance();
            return response()->json(['balance' => $balance['balance'] ?? 0]);
        } catch (\Exception $e) {
            return response()->json(['error' => $e->getMessage()], 500);
        }
    }

    public function getUnreadMessages()
    {
        try {
            $unread = $this->wikipayamSMSService->getUnreadReceives(limit: 50);
            $count = $this->wikipayamSMSService->getUnreadCount();
            
            return response()->json([
                'unread_count' => $count,
                'messages' => $unread['receives'] ?? []
            ]);
        } catch (\Exception $e) {
            return response()->json(['error' => $e->getMessage()], 500);
        }
    }

    public function markMessageAsRead($id)
    {
        try {
            $result = $this->wikipayamSMSService->markSingleAsRead($id);
            return response()->json(['success' => $result]);
        } catch (\Exception $e) {
            return response()->json(['error' => $e->getMessage()], 500);
        }
    }
}