API SMS Buluthat
SMS انبوه، SMS شخصی‌سازی‌شده، SMS OTP (کد تأیید)، SMS ورودی، گزارش تحویل و لیست سیاه.
- آدرس:
https://api.buluthat.com/api/sms.php?action=<eylem> - هویت:
Authorization: Bearer <anahtar>(یاX-Api-Key: <anahtar>). کلید: پنل > SMS انبوه > API و تنظیمات. - بدنه: JSON (
Content-Type: application/json) یا فرم. پاسخ‌ها JSON و UTF-8 هستند. - خطا:
{"ok":false,"error":"<kod>","message":"<açıklama>"}+ HTTP 4xx/5xx. - شماره‌ها
05321234567,5321234567,+905321234567,905321234567در قالب‌های پذیرفته می‌شود.
طول پیام
| کدگذاری | 1 SMS | 2 SMS | 3 SMS | … 7 SMS |
|---|---|---|---|---|
| استاندارد | 160 | 306 | 459 | 1071 |
| ترکی (اگر شامل Ş ş Ğ ğ ç ı İ باشد) | 155 | 298 | 447 | 1043 |
| یونیکد (ایموجی و غیره) | 70 | 134 | 201 | 469 |
^ { } \ [ ] ~ | € دو نویسه حساب می‌شود. Ö ö Ü ü Ç در کدگذاری استاندارد است.
ارسال — send (POST)
{
"header": "FIRMAADI",
"message": "Merhaba {ad}, {tutar} TL ödemeniz alınmıştır.",
"recipients": [
{"phone": "05321234567", "name": "Ayşe Yılmaz", "tutar": "1.250", "ref": "CARI-17"},
{"phone": "05331234567", "name": "Mehmet Kaya", "tutar": "300"}
],
"send_at": "2026-10-01 10:00",
"is_commercial": false,
"valid_for": "24:00",
"rate_per_minute": 500,
"custom_ref": "EYLUL-KAMPANYA"
}| حوزه | توضیح |
|---|---|
header | سرشناسه تأییدشده. اگر خالی باشد سرشناسه پیش‌فرض. |
message | متن. جایگزین‌ها: {ad} {soyad} {adsoyad} {telefon} {firma} {ret_link} + سایر فیلدهای گیرنده. |
recipients | [{phone, name?, ref?, <alan>…}]. همان شماره یک‌بار ارسال می‌شود. |
phones | میان‌بر: ["0532…","0533…"] یا متن جداشده با ویرگول (همان پیام برای همه). |
messages | متن کاملاً متفاوت برای هر شخص: [{phone, message, ref?}] (در این حالت message لازم نیست). |
send_at | تاریخ آینده (حداکثر 90 روز). اگر خالی باشد فوراً. |
is_commercial | پیام تجاری. true اگر iys_recipient_type: BIREYSEL / TACIR؛ به گیرنده‌ای که تأیید İYS ندارد ارسال نمی‌شود. |
valid_for | اگر تلفن خاموش باشد مدت آزمایش، SS:DD (00:01 – 48:00). |
rate_per_minute | ارسال در دقیقه (0 = سریع‌ترین). |
custom_ref | مرجع خودتان؛ status پرس‌وجو می‌شود. |
پاسخ:
{"ok":true,"data":{"campaign_id":152,"status":"queued","recipients":2,"credits":2,
"skipped":{"invalid":0,"blacklist":0,"duplicate":0}, ...}}شماره‌های لیست سیاه، نادرست و (اگر حفاظت از تکرار فعال باشد) کسانی که امروز همان متن را گرفته‌اند رد می‌شوند؛ اعتباری کسر نمی‌شود. اعتبار پیام تحویل‌نشده خودکار بازگردانده می‌شود.
کدهای خطا: missing_recipients, missing_message, request_failed (اعتبار ناکافی، سرشناسه تأییدنشده، پیام بسیار طولانی … — message توضیح می‌دهد)، account_inactive.
گزارش — status (GET)
?action=status&campaign_id=152 یا &custom_ref=EYLUL-KAMPANYA؛ اختیاری status, phone, limit (≤1000), offset.
وضعیت‌های پیام: queued (در صف)، sending, waiting (در انتظار گزارش اپراتور)، delivered, failed, expired, rejected, cancelled.
سایر اقدامات
| اقدام | روش | توضیح |
|---|---|---|
balance | GET | {"sms":1200,"otp":500,"lots":[…]} اعتبار باقی‌مانده و تاریخ انقضا |
headers | GET | سرشناسه‌های تأییدشده |
campaigns | GET | فهرست ارسال (from, to, limit, offset) |
cancel | POST | campaign_id — پیام‌های ارسال‌نشده لغو، اعتبار بازگردانده می‌شود |
inbound | GET | SMSهای ورودی: since_id, limit → [{id, from, to, keyword, text, optout, received_at}] |
blacklist | GET | لیست سیاه |
blacklist_add / blacklist_remove | POST | phones: ["0532…"] |
SMS OTP
POST ?action=otp_send {"phone":"05321234567","reference":"UYE-1452"}
→ {"ok":true,"data":{"id":88,"status":"sent","expires_at":"…"},"code":"482913"}
POST ?action=otp_verify {"id":88,"code":"482913"}
→ {"ok":true,"verified":true}
hata: wrong_code | expired | too_many_attempts | already_verified | not_found
GET ?action=otp_status&id=88- کد را خودتان هم می‌توانید بدهید (
code، 4-10 رقم)؛ اگر ما تولید کنیم فقط یک‌بار در همین پاسخ برمی‌گردد، آنچه ذخیره می‌شود فقط هش است. templateمی‌توانید متن را تغییر دهید ({kod}الزامی،{firma},{sure}).- OTP ابتدا از اعتبار OTP و پس از اتمام از اعتبار SMS کسر می‌شود؛ بدون انتظار ارسال می‌شود.
- ارسال به یک شماره در 10 دقیقه محدود است.
Webhook
اگر در پنل > SMS انبوه > API و تنظیمات نشانی وارد کنید رویدادها POST می‌شود:
X-Buluthat-Event: sms.delivery | sms.inbound | sms.optout
X-Buluthat-Signature: sha256=<HMAC-SHA256(gövde, sır)>
{"event":"delivery","data":{"message_id":9012,"campaign_id":152,"ref":"CARI-17",
"phone":"905321234567","status":"delivered","detail":"İletildi","done_at":"…"}}
{"event":"inbound","data":{"id":44,"from":"905321234567","to":"…","keyword":"","text":"…","optout":false}}اگر 2xx برنگردانید پس از 1 دقیقه، 5 دقیقه، 15 دقیقه، 1 ساعت، 3 ساعت و 6 ساعت دوباره تلاش می‌شود.
نمونه (PHP)
$ch = curl_init('https://api.buluthat.com/api/sms.php?action=send');
curl_setopt_array($ch, [
CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $key, 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['message' => 'Siparişiniz kargoda.', 'phones' => ['05321234567']]),
]);
$res = json_decode(curl_exec($ch), true);