الاتصال الآلي

يجري مقطعًا صوتيًا أو 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 */ }