Automatyczne połączenia

Wykonuje na liście numerów połączenie z komunikatem, IVR lub ankietą; zwraca wynik i wybrane klawisze. Klucz integracji (bt_…, zakres autocall).

Punkt końcowy: https://api.buluthat.com/api/autocall.php?action=<işlem>

Typowy przepływ:

1. media          -> anons id'sini al (ya da tts_template kullan)
2. trunks         -> çıkış hattının slug'ını al
3. create_campaign -> status "draft", digit_labels ile anket seçenekleri
4. add_leads      -> numaraları partiler hâlinde gönder
5. start          -> kampanyayı kuyruğa al
6. webhook        -> sonuçlar size gelsin (ya da results ile çekin)
7. summary        -> tuş dağılımı

GETping · media · trunks · caller_ids

GET https://api.buluthat.com/api/autocall.php?action=ping
GET https://api.buluthat.com/api/autocall.php?action=media       → [{ "id": 12, "name": "Hatırlatma anonsu" }]
GET https://api.buluthat.com/api/autocall.php?action=trunks      → çıkış hatları (slug)
GET https://api.buluthat.com/api/autocall.php?action=caller_ids  → kullanılabilir arayan numaralar

POSTcreate_campaign

curl -X POST "https://api.buluthat.com/api/autocall.php?action=create_campaign" \
  -H "Authorization: Bearer bt_xxx" -H "Content-Type: application/json" \
  -d '{
    "name": "Randevu hatırlatma",
    "campaign_type": "survey",
    "trunk_slug": "hat-1",
    "caller_id": "02124119610",
    "tts_enabled": true,
    "tts_template": "Merhaba {sayin}, {randevu} randevunuzu hatırlatmak için aradık. Geliyorsanız 1, iptal için 2.",
    "digit_labels": { "1": "Geliyorum", "2": "İptal" },
    "digit_destinations": { "9": "queue:4" },
    "start_time": "09:00", "end_time": "18:00",
    "weekdays": ["mon","tue","wed","thu","fri"],
    "max_channels": 3, "ring_timeout_seconds": 30,
    "retry_count": 1, "retry_delay_minutes": 30,
    "amd_enabled": true, "amd_action": "hangup",
    "webhook_url": "https://ornek.com/buluthat/sonuc",
    "webhook_secret": "gizli",
    "webhook_events": "call_finished,dtmf",
    "status": "draft",
    "leads": [ { "phone": "05551112233", "name": "Ahmet Yılmaz", "external_id": "CRM-1", "fields": { "randevu": "12 Eylül 14:00" } } ]
  }'

Wymagane: name, trunk_slug i media_file_id lub tts_template. Jeśli podane są oba, najpierw odtwarzany jest dźwięk spersonalizowany, potem gotowy komunikat.

Odpowiedź: { "ok": true, "data": { "id": 7, "status": "draft", … } }

POSTupdate_campaign

Aktualizacja częściowa; zmieniają się tylko wysłane pola. status nie wysyłaj (zrzuci działającą kampanię); dla statusu start/pause/cancel użyj.

{ "campaign_id": 7, "max_channels": 5, "retry_count": 2 }

POSTadd_leads

Maksymalnie 5.000 rekordów w jednym żądaniu. Ten sam numer nie jest dodawany drugi raz w tej samej kampanii (duplicate).

{ "campaign_id": 7, "leads": [ { "phone": "05551112233", "name": "Ahmet Yılmaz", "external_id": "CRM-1", "fields": { "borc": "1.240 TL" } } ] }

Format skrócony: { "campaign_id": 7, "phones": ["05551112233", "05551112234"] }

Odpowiedź: { "inserted": 2, "duplicate": 0, "invalid": 0 }

POSTrequeue_leads

Ponownie kolejkuje numery, do których już dzwoniono (calls jest zerowane, wybrany klawisz czyszczony). Numeru już oczekującego nie dotyka (skipped). W przypomnieniu o płatności zamiast polegać na klawiszu „zapłaciłem”, użyj go, aby zadzwonić ponownie na podstawie własnych rekordów.

{ "campaign_id": 7, "phones": ["05551112233"] }

POSTstart · pause · cancel

{ "campaign_id": 7 }

start kolejkuje kampanię; połączenia zaczynają się w oknie dni/godzin. Jeśli dodasz numer do zakończonej kampanii, kampania zostanie automatycznie ponownie otwarta.

GETresults

Wynik według numeru. limit (domyślnie 200, maksymalnie 1000), offset; filtry status, dtmf, phone.

GET https://api.buluthat.com/api/autocall.php?action=results&campaign_id=7&dtmf=1

{
  "ok": true, "total": 512, "limit": 200, "offset": 0,
  "data": [ {
    "campaign_id": 7, "lead_id": 91, "external_id": "CRM-1",
    "phone": "05551112233", "name": "Ahmet Yılmaz",
    "status": "answered", "attempts": 1,
    "dtmf": "1", "dtmf_label": "Geliyorum", "dtmf_all": ["1"],
    "amd_result": "HUMAN", "duration_seconds": 34, "talk_seconds": 22,
    "hangup_cause": "ANSWERED",
    "started_at": "2026-09-04 10:12:03", "answered_at": "2026-09-04 10:12:11", "ended_at": "2026-09-04 10:12:33",
    "custom_fields": { "randevu": "12 Eylül 14:00" }
  } ]
}

Statusy: pending, calling, answered, machine, no_answer, busy, failed, cancelled.

GETsummary

{ "ok": true, "data": {
  "total": 512, "answered": 388, "pressed": 301, "machine": 44,
  "answer_rate": 75.8, "press_rate": 77.6, "talk_seconds": 8624, "avg_talk_seconds": 22,
  "digits": [ { "digit": "1", "label": "Geliyorum", "total": 214, "percent": 55.2 }, { "digit": "2", "label": "İptal", "total": 87, "percent": 22.4 } ]
} }

GETevents

Dziennik zdarzeń kampanii (originate, answered, amd, dtmf, cdr, error) — do diagnostyki.

Webhook

webhook_url jeśli zdefiniowano, Buluthat wysyła wynik POST-em na Twój adres. Zdarzenia: call_finished (jednorazowo na numer), dtmf (w chwili naciśnięcia klawisza), campaign_finished. Nagłówki X-Buluthat-Event, X-Buluthat-Delivery, X-Buluthat-Signature: sha256=… (webhook_secret jeśli podano). Treść results zawiera te same pola co. Weryfikacja podpisu i polityka ponawiania — zob. Webhooki.

Spersonalizowany komunikat i koszt

Szablon jest dzielony na części stałe i zmienne; stałe zdanie jest syntezowane raz dla listy tysiąca osób, ta sama {tutar} ta sama wartość nie jest generowana drugi raz (zmierzone oszczędności %97,9). Wartości zmiennych wysyłaj w standardowej postaci ("1.000 TL" zawsze pisane tak samo). Rozróżnienie Pan/Pani odbywa się automatycznie na podstawie imienia; w przypadku imion unisex tytuł jest pomijany.

Klient PHP

Pobrane z zakładki Panel > Automatyczne połączenia > API buluthat-autocall-client.php:

require_once 'buluthat-autocall-client.php';
$bt = new BuluthatAutoCall('https://api.buluthat.com', 'bt_xxx');
$k = $bt->createCampaign(['name' => 'Ödeme hatırlatma', 'campaign_type' => 'survey', 'trunk_slug' => 'hat-1',
    'tts_enabled' => true, 'tts_template' => 'Merhaba {sayin}, {tutar} tutarındaki ödemenizi hatırlatmak için aradık. Ödediyseniz 1, ödemediyseniz 2.',
    'digit_labels' => ['1' => 'Ödedim', '2' => 'Ödemedim'], 'webhook_url' => 'https://crm.example.com/buluthat-sonuc.php']);
$bt->addLeads($k['id'], [['phone' => '05551112233', 'name' => 'Burak Yılmaz', 'external_id' => 'CARI-451', 'fields' => ['tutar' => '1.000 TL']]]);
$bt->start($k['id']);

// webhook tarafı
$olay = BuluthatAutoCall::readWebhook($secret);   // imzayı doğrular
if ($olay['event'] === 'call_finished' && $olay['data']['dtmf'] === '1') { /* ödedim dedi */ }