Llamadas automáticas

Hace llamadas con locución, IVR o encuesta a la lista de números; devuelve el resultado y la pulsación. Clave de integración (bt_…, alcance autocall).

Endpoint: https://api.buluthat.com/api/autocall.php?action=<işlem>

Flujo típico:

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

Obligatorio: name, trunk_slug y media_file_id o tts_template. Si se indican ambos, primero se reproduce la voz personalizada y luego la locución predefinida.

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

POSTupdate_campaign

Actualización parcial; solo cambian los campos enviados. status no envíe (tumba la campaña en curso); para el estado start/pause/cancel utilice.

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

POSTadd_leads

Máximo 5.000 registros por solicitud. El mismo número no se agrega por segunda vez en la misma campaña (duplicate).

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

Forma breve: { "campaign_id": 7, "phones": ["05551112233", "05551112234"] }

Respuesta: { "inserted": 2, "duplicate": 0, "invalid": 0 }

POSTrequeue_leads

Vuelve a poner en cola los números llamados anteriormente (calls se restablece, se borra la pulsación). No se toca el número que ya está en espera (skipped). En un recordatorio de cobro, en lugar de fiarse de la tecla "ya pagué", úselo para volver a llamar según su propio registro.

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

POSTstart · pause · cancel

{ "campaign_id": 7 }

start pone la campaña en cola; la llamada empieza dentro de la ventana de día/hora. Si agrega números a una campaña completada, la campaña se reabre automáticamente.

GETresults

Resultado por número. limit (por defecto 200, máximo 1000), offset; filtros 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" }
  } ]
}

Estados: 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

Registro de eventos de la campaña (originate, answered, amd, dtmf, cdr, error) — para diagnóstico.

Webhook

webhook_url si está definido, Buluthat le envía el resultado por POST. Eventos: call_finished (una vez por número), dtmf (en el momento en que se pulsa la tecla), campaign_finished. Encabezados X-Buluthat-Event, X-Buluthat-Delivery, X-Buluthat-Signature: sha256=… (webhook_secret si se indica). Cuerpo results lleva los mismos campos que. Para la verificación de firma y la política de reintentos, véase Webhooks.

Locución personalizada y costo

La plantilla se divide en fragmentos fijos y variables; la frase fija se locuta una sola vez en una lista de mil personas, el mismo {tutar} el valor no se genera por segunda vez (ahorro medido: %97,9). Envíe los valores de las variables en formato estándar ("1.000 TL" que siempre se escriba igual). La distinción Sr./Sra. se hace automáticamente según el nombre; en nombres unisex se deja el tratamiento en blanco.

Cliente PHP

Descargado desde Panel > Llamadas automáticas > pestaña 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 */ }