Chamadas Automáticas

Faz anúncios, IVR ou chamadas de inquérito a uma lista de números; devolve o resultado e as teclas premidas. Chave de integração (bt_…, âmbito autocall).

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

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

Obrigatório: name, trunk_slug e media_file_id ou tts_template. Se forem indicados os dois, é reproduzido primeiro o áudio personalizado e depois o anúncio pré-gravado.

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

POSTupdate_campaign

Atualização parcial; só os campos enviados são alterados. status não envie (derruba a campanha em curso); para o estado start/pause/cancel utilize.

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

POSTadd_leads

No máximo 5.000 registos por pedido. O mesmo número não é adicionado duas vezes na mesma campanha (duplicate).

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

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

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

POSTrequeue_leads

Volta a colocar na fila números já chamados (calls é reposto a zero, a tecla premida é limpa). O número que já está em espera não é afetado (skipped). Nos lembretes de cobrança, em vez de confiar na tecla "paguei", use-o para voltar a ligar com base no seu próprio registo.

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

POSTstart · pause · cancel

{ "campaign_id": 7 }

start coloca a campanha em fila; as chamadas começam dentro da janela de dia/hora. Se adicionar números a uma campanha concluída, esta reabre automaticamente.

GETresults

Resultado por número. limit (por defeito 200, no 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

Registo de eventos da campanha (originate, answered, amd, dtmf, cdr, error) — para diagnóstico.

Webhook

webhook_url se estiver definido, a Buluthat envia-lhe o resultado por POST. Eventos: call_finished (uma vez por número), dtmf (no momento em que a tecla é premida), campaign_finished. Cabeçalhos X-Buluthat-Event, X-Buluthat-Delivery, X-Buluthat-Signature: sha256=… (webhook_secret se for indicado). Corpo results tem os mesmos campos que. Para a validação da assinatura e a política de repetição, ver Webhooks.

Anúncio personalizado e custo

O modelo é dividido em partes fixas e variáveis; a frase fixa é sintetizada uma só vez numa lista de mil pessoas, o mesmo {tutar} o valor não é sintetizado uma segunda vez (poupança medida de %97,9). Envie os valores das variáveis em formato padrão ("1.000 TL" seja sempre escrito da mesma forma). A distinção Sr./Sra. é automática a partir do nome; nos nomes unissexo o tratamento fica em branco.

Cliente PHP

Descarregado do separador Painel > Chamadas Automáticas > 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 */ }