Berichtlengte Verzending — `send` (POST)Rapport — `status` (GET)Overige acties OTP-SMS Webhook Voorbeeld (PHP)

Buluthat SMS API

Bulk-SMS, gepersonaliseerde SMS, OTP-SMS (verificatiecode), inkomende SMS, bezorgrapport en zwarte lijst.

Adres: https://api.buluthat.com/api/sms.php?action=<eylem>
Identiteit: Authorization: Bearer <anahtar> (of X-Api-Key: <anahtar>). Sleutel: Paneel > Bulk-SMS > API en instellingen.
Body: JSON (Content-Type: application/json) of formulier. Antwoorden zijn JSON, UTF-8.
Fout: {"ok":false,"error":"<kod>","message":"<açıklama>"} + HTTP 4xx/5xx.
Nummers 05321234567, 5321234567, +905321234567, 905321234567 wordt in de formaten geaccepteerd.

Berichtlengte

Codering	1 SMS	2 SMS	3 SMS	… 7 SMS
Standaard	160	306	459	1071
Turks (bij Ş ş Ğ ğ ç ı İ)	155	298	447	1043
Unicode (emoji enz.)	70	134	201	469

^ { } \ [ ] ~ | € telt als twee tekens. Ö ö Ü ü Ç vallen onder de standaardcodering.

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

Veld	Omschrijving
`header`	Goedgekeurde afzendernaam. Indien leeg de standaardafzendernaam.
`message`	Tekst. Plaatshouders: `{ad}` `{soyad}` `{adsoyad}` `{telefon}` `{firma}` `{ret_link}` + overige velden van de ontvanger.
`recipients`	`[{phone, name?, ref?, <alan>…}]`. Hetzelfde nummer wordt eenmaal verstuurd.
`phones`	Snelkoppeling: `["0532…","0533…"]` of tekst met komma's (hetzelfde bericht voor iedereen).
`messages`	Voor elke persoon een volledig andere tekst: `[{phone, message, ref?}]` (in dat geval `message` is niet nodig).
`send_at`	Toekomstige datum (maximaal 90 dagen). Indien leeg, direct.
`is_commercial`	Commercieel bericht. `true` als `iys_recipient_type`: `BIREYSEL` / `TACIR`; gaat niet naar ontvangers zonder İYS-toestemming.
`valid_for`	Als de telefoon uit staat, de proefperiode, `SS:DD` (00:01 – 48:00).
`rate_per_minute`	Verzendingen per minuut (0 = snelst).
`custom_ref`	Uw eigen referentie; `status` wordt opgevraagd met.

Antwoord:

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

Nummers op de zwarte lijst, foutieve nummers en (als de dubbelingsbeveiliging aan staat) nummers die vandaag dezelfde tekst kregen, worden overgeslagen; er wordt geen tegoed afgeschreven. Tegoed van een niet-afgeleverd bericht wordt automatisch gecrediteerd.

Foutcodes: missing_recipients, missing_message, request_failed (onvoldoende tegoed, afzendernaam niet goedgekeurd, bericht te lang… — message licht toe), account_inactive.

Rapport — `status` (GET)

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

Berichtstatussen: queued (in de wachtrij), sending, waiting (wacht op rapport van de operator), delivered, failed, expired, rejected, cancelled.

Overige acties

Handeling	Methode	Omschrijving
`balance`	GET	`{"sms":1200,"otp":500,"lots":[…]}` resterend tegoed en vervaldatums
`headers`	GET	Goedgekeurde afzendernamen
`campaigns`	GET	Verzendlijst (`from`, `to`, `limit`, `offset`)
`cancel`	POST	`campaign_id` — niet-verzonden berichten geannuleerd, tegoed gecrediteerd
`inbound`	GET	Inkomende SMS: `since_id`, `limit` → `[{id, from, to, keyword, text, optout, received_at}]`
`blacklist`	GET	Zwarte lijst
`blacklist_add` / `blacklist_remove`	POST	`phones: ["0532…"]`

OTP-SMS

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

U kunt de code ook zelf opgeven (code, 4-10 cijfers); als wij het genereren, wordt het slechts eenmaal in dit antwoord teruggegeven, opgeslagen wordt alleen de hash.
template kunt u de tekst wijzigen met ({kod} verplicht, {firma}, {sure}).
OTP wordt eerst van het OTP-tegoed afgeschreven, daarna van het SMS-tegoed; wordt zonder wachten verzonden.
Voor hetzelfde nummer geldt een verzendlimiet per 10 minuten.

Webhook

Geeft u in Paneel > Bulk-SMS > API en instellingen een adres op, dan worden gebeurtenissen gePOST:

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}}

Als u geen 2xx teruggeeft, wordt na 1 min, 5 min, 15 min, 1 u, 3 u, 6 u opnieuw geprobeerd.

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

← Spraakverificatie (OTP) Webhooks