Çağrı Detaylarını ve Ses Kayıtlarını Webkancalarla Kendi Sisteminize Aktarın

Genel Bakış

Hipcall, çağrı detay kayıtlarını kontrol paneli ve REST API üzerinden erişilebilir kılar; ancak pek çok ekip bu verileri kendi sistemlerine — bir veri ambarına, uyumluluk arşivine, CRM'e veya özel analitik paneline — aktarmak ister. Bunu çağrı biter bitmez gerçek zamanlı yapmak için call_hangup webkancası tam olarak tasarlanmıştır.

Bu rehber, call_hangup olayını nasıl alacağınızı, çağrı kaydını kendi veritabanınızda nasıl saklayacağınızı ve imzalı URL süresi dolmadan ses dosyasını otomatik olarak nasıl indireceğinizi gösterir.

Nasıl Çalışır

Bir çağrı sona erdiğinde Hipcall, uç noktanıza bir call_hangup webkancası gönderir. Sunucunuz yükü çözümler, çağrı kaydını veritabanına ekler ve — bir kayıt URL'si mevcutsa — ses dosyasını arka planda indirir.

Mimari

flowchart TD
    A[Çağrı sona erer] --> B[Hipcall call_hangup webkancası gönderir]
    B --> C[Sunucunuz yükü alır]
    C --> D[CDR'ı veritabanına kaydet]
    D --> E{record_url\nmevcut mu?}
    E -- Evet --> F[Arka planda ses dosyasını indir]
    E -- Hayır --> G[Tamamlandı]
    F --> H[MP3'ü yerel olarak kaydet\nkayıt yolunu güncelle]

Adım 1: Hipcall'da Webkancayı Oluşturun

1. Hipcall kontrol panelinizde Hesap > Entegrasyonlar bölümüne gidin.
2. Yeni Entegrasyon Oluştur'a tıklayın ve Webkanca'yı seçin.
3. Webkancayı şu şekilde yapılandırın:

Yerel geliştirme: Yerel sunucunuzu dışarıya açmak için ngrok kullanın. ngrok http 5007 komutunu çalıştırın ve oluşturulan URL'yi hedef olarak kullanın.

Adım 2: Webkancayı Alın

Hipcall, her çağrı sona erdiğinde uç noktanıza şu yapıda bir JSON yükü gönderir:

{
  "event": "call_hangup",
  "data": {
    "uuid": "3f2b8c1e-7a4d-4e9b-9c55-1d2e6f8a0b43",
    "direction": "inbound",
    "caller_number": "+90530XXXXXXX",
    "callee_number": "+90850XXXXXXX",
    "started_at": "2026-04-02T10:00:00Z",
    "answered_at": "2026-04-02T10:00:06Z",
    "bridged_at": "2026-04-02T10:00:06Z",
    "ended_at": "2026-04-02T10:00:45Z",
    "call_duration": 39,
    "missing_call": false,
    "missing_call_reason": null,
    "hangup_by": "contact",
    "record_url": "https://storage.hipcall.com.tr/...?X-Amz-Expires=604800&...",
    "voicemail_id": null,
    "voicemail_url": null,
    "user_id": 1001,
    "contact_id": 2002,
    "channel_id": 3003,
    "number_id": 3003,
    "company_id": 4004
  }
}

Temel alanlar:

HTTP 200 yanıtını hızlıca gönderin — ağır işlemleri arka plana alın.

Adım 3: CDR'ı Saklayın

Her zaman event === "call_hangup" kontrolü yapın — uç noktanız gelecekte başka olaylar da alabilir. Webkanca yeniden denenmesi durumunda yinelenen kayıtları önlemek için uuid'yi birincil anahtar olarak kullanın.

@app.route('/webhook/hipcall-cdr', methods=['POST'])
def receive_cdr():
    payload = request.json
    if payload.get('event') != 'call_hangup':
        return jsonify({"status": "ignored"}), 200

    data = payload.get('data', {})
    uuid = data.get('uuid')

    # Yineleme kontrolü — Hipcall zaman aşımında yeniden deneyebilir
    if db.execute('SELECT 1 FROM cdrs WHERE uuid = ?', (uuid,)).fetchone():
        return jsonify({"status": "exists"}), 200

    db.execute('''
        INSERT INTO cdrs
          (uuid, caller_number, callee_number, direction,
           duration, started_at, ended_at, record_url, hangup_by)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
    ''', (
        uuid,
        data.get('caller_number'), data.get('callee_number'),
        data.get('direction'),     data.get('call_duration'),
        data.get('started_at'),    data.get('ended_at'),
        data.get('record_url'),    data.get('hangup_by'),
    ))
    db.commit()
    return jsonify({"status": "success"}), 201

Adım 4: Ses Dosyasını İndirin

record_url önceden imzalanmış bir URL'dir — çağrı bittikten kısa süre sonra geçerliliğini yitirir. Webkanca uç noktanız anında yanıt verebilmesi için dosyayı arka plan iş parçacığında indirin.

İndirmeden önce birkaç saniye bekleyin: ses dosyası kapanıştan hemen sonra depolamaya yüklenir ve kısa bir gecikme dosyanın hazır olmasını garanti eder.

def download_recording(record_url, uuid):
    time.sleep(10)  # Dosyanın depoda hazır olmasını bekle
    response = requests.get(record_url, stream=True, timeout=30)
    if response.status_code == 200:
        path = f"./data/records/{uuid}.mp3"
        with open(path, 'wb') as f:
            for chunk in response.iter_content(chunk_size=8192):
                f.write(chunk)
        db.execute(
            'UPDATE cdrs SET local_record_path = ? WHERE uuid = ?',
            (f"/api/records/{uuid}.mp3", uuid)
        )
        db.commit()

# Webkanca işleyicisinde CDR eklendikten sonra tetikle
record_url = data.get('record_url')
if record_url:
    threading.Thread(
        target=download_recording,
        args=(record_url, uuid),
        daemon=True
    ).start()

Kullanılan Araçlar

Sonraki Adımlar

• Webkancaları dokümantasyonu — Olaylara abone olun, yeniden deneme mantığını yapılandırın, imzaları doğrulayın
• REST API kimlik doğrulaması — Uç noktanızı API anahtarları veya Temel Kimlik Doğrulama ile güvence altına alın
• REST API — CDR uç noktaları — REST API üzerinden geçmiş çağrı kayıtlarını isteğe bağlı olarak çekin