Автоматичний дзвінок

Здійснює для списку номерів дзвінок-оголошення, IVR або опитування; повертає результат і натискання клавіш. Ключ інтеграції (bt_…, область autocall).

Кінцева точка: https://api.buluthat.com/api/autocall.php?action=<işlem>

Типовий потік:

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" } } ]
  }'

Обов'язково: name, trunk_slug та media_file_id або tts_template. Якщо вказано обидва, спочатку відтворюється персоналізований голос, потім готове оголошення.

Відповідь: { "ok": true, "data": { "id": 7, "status": "draft", … } }

POSTupdate_campaign

Часткове оновлення; змінюються лише надіслані поля. status не надсилайте (це зупиняє кампанію, що працює); для стану start/pause/cancel використовуйте.

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

POSTadd_leads

Максимум 5.000 записів в одному запиті. Той самий номер у тій самій кампанії вдруге не додається (duplicate).

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

Короткий формат: { "campaign_id": 7, "phones": ["05551112233", "05551112234"] }

Відповідь: { "inserted": 2, "duplicate": 0, "invalid": 0 }

POSTrequeue_leads

Повторно ставить у чергу номери, на які вже дзвонили (calls обнуляється, натискання клавіш очищується). Номер, який уже очікує, не зачіпається (skipped). Під час нагадування про оплату, замість того щоб довіряти кнопці «Я сплатив», використовуйте для повторного дзвінка за власними записами.

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

POSTstart · pause · cancel

{ "campaign_id": 7 }

start ставить кампанію в чергу; набір починається у вікні дня/часу. Якщо додати номер до завершеної кампанії, кампанія автоматично відкривається знову.

GETresults

Результат за номером. limit (за замовчуванням 200, максимум 1000), offset; фільтри 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" }
  } ]
}

Статуси: 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

Журнал подій кампанії (originate, answered, amd, dtmf, cdr, error) — для діагностики.

Webhook

webhook_url якщо визначено, Buluthat надсилає вам результат через POST. Події: call_finished (один раз на номер), dtmf (у момент натискання клавіші), campaign_finished. Заголовки X-Buluthat-Event, X-Buluthat-Delivery, X-Buluthat-Signature: sha256=… (webhook_secret якщо надано). Тіло results має ті самі поля, що й. Про перевірку підпису та політику повторів див. Webhook.

Персоналізоване оголошення та вартість

Шаблон розбивається на фіксовані та змінні сегменти; фіксована фраза в списку на тисячу осіб озвучується один раз, те саме {tutar} значення вдруге не створюється (виміряна економія %97,9). Передавайте значення змінних у стандартному форматі ("1.000 TL" нехай завжди пишеться однаково). Розрізнення «пан/пані» — автоматично за іменем; для унісекс-імен звертання залишається порожнім.

PHP-клієнт

Завантажено з вкладки Панель > Автоматичний дзвінок > 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 */ }