Lunghezza del messaggio Invio — `send` (POST)Report — `status` (GET)Altre azioni SMS OTP Webhook Esempio (PHP)

API SMS Buluthat

SMS di massa, SMS personalizzati, SMS OTP (codice di verifica), SMS in entrata, report di consegna e lista nera.

Indirizzo: https://api.buluthat.com/api/sms.php?action=<eylem>
Identità: Authorization: Bearer <anahtar> (oppure X-Api-Key: <anahtar>). Chiave: Pannello > SMS di massa > API e Impostazioni.
Corpo: JSON (Content-Type: application/json) oppure modulo. Le risposte sono in JSON, UTF-8.
Errore: {"ok":false,"error":"<kod>","message":"<açıklama>"} + HTTP 4xx/5xx.
Numeri 05321234567, 5321234567, +905321234567, 905321234567 è accettato nei formati.

Lunghezza del messaggio

Codifica	1 SMS	2 SMS	3 SMS	… 7 SMS
Standard	160	306	459	1071
Turco (se contiene Ş ş Ğ ğ ç ı İ)	155	298	447	1043
Unicode (emoji ecc.)	70	134	201	469

^ { } \ [ ] ~ | € contano come due caratteri. Ö ö Ü ü Ç sono nella codifica standard.

Invio — `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"
}

Campo	Descrizione
`header`	Intestazione approvata. Se vuoto, intestazione predefinita.
`message`	Testo. Segnaposto: `{ad}` `{soyad}` `{adsoyad}` `{telefon}` `{firma}` `{ret_link}` + gli altri campi del destinatario.
`recipients`	`[{phone, name?, ref?, <alan>…}]`. Lo stesso numero viene inviato una sola volta.
`phones`	Scorciatoia: `["0532…","0533…"]` oppure testo separato da virgole (stesso messaggio per tutti).
`messages`	Testo completamente diverso per persona: `[{phone, message, ref?}]` (in questo caso `message` non serve).
`send_at`	Data futura (massimo 90 giorni). Se vuoto, subito.
`is_commercial`	Messaggio commerciale. `true` se `iys_recipient_type`: `BIREYSEL` / `TACIR`; non viene inviato ai destinatari privi del consenso IYS.
`valid_for`	Se il telefono è spento, durata di prova, `SS:DD` (00:01 – 48:00).
`rate_per_minute`	Invio al minuto (0 = il più veloce).
`custom_ref`	Il Suo riferimento; `status` si interroga con.

Risposta:

{"ok":true,"data":{"campaign_id":152,"status":"queued","recipients":2,"credits":2,
 "skipped":{"invalid":0,"blacklist":0,"duplicate":0}, ...}}

I numeri in lista nera, errati e (se la protezione dai duplicati è attiva) che hanno già ricevuto lo stesso testo oggi vengono saltati; nessun credito scalato. Il credito dei messaggi non recapitati viene rimborsato automaticamente.

Codici di errore: missing_recipients, missing_message, request_failed (crediti insufficienti, intestazione non approvata, messaggio troppo lungo… — message spiega), account_inactive.

Report — `status` (GET)

?action=status&campaign_id=152 oppure &custom_ref=EYLUL-KAMPANYA; facoltativo status, phone, limit (≤1000), offset.

Stati del messaggio: queued (in coda), sending, waiting (in attesa del rapporto dell'operatore), delivered, failed, expired, rejected, cancelled.

Altre azioni

Azione	Metodo	Descrizione
`balance`	GET	`{"sms":1200,"otp":500,"lots":[…]}` credito residuo e date di scadenza
`headers`	GET	Intestazioni approvate
`campaigns`	GET	Elenco di invio (`from`, `to`, `limit`, `offset`)
`cancel`	POST	`campaign_id` — messaggi non inviati annullati, credito rimborsato
`inbound`	GET	SMS in entrata: `since_id`, `limit` → `[{id, from, to, keyword, text, optout, received_at}]`
`blacklist`	GET	Lista nera
`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

Il codice può essere fornito anche da Voi (code, 4-10 cifre); se l'abbiamo generato noi, viene restituito una sola volta in questa risposta; viene conservato solo l'hash.
template può modificare il testo con ({kod} obbligatorio, {firma}, {sure}).
L'OTP viene scalato prima dal credito OTP, poi dal credito SMS; viene inviato senza attese.
Esiste un limite di invio allo stesso numero ogni 10 minuti.

Webhook

Se inserisce un indirizzo in Pannello > SMS di massa > API e Impostazioni, gli eventi vengono inviati in 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}}

Se non restituite 2xx, si riprova dopo 1 min, 5 min, 15 min, 1 h, 3 h, 6 h.

Esempio (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);

← Verifica vocale (OTP) Webhook