Hipcall API İle Kısa Çağrıları Otomatik Etiketleme

Genel bakış

8 saniye süren ve cevaplanmış bir çağrı raporlarda "başarılı" görünür. Gerçekte 8 saniyede hiçbir iş konuşulmaz. Bu çağrılar yanlış numara, ses gelmemesi veya ajanın hattı erken kapatması gibi sorunlara işaret eder.

Ekip liderlerinin sorunlu çağrıları tek tek aramak zorunda kalmaması için kısa çağrıları webkanca üzerinden tespit edip etiketleyin.

Başlamadan önce

• Aktif bir Hipcall API anahtarı edinin.
• call_hangup webkanca olayını karşılayacak altyapıyı kurun.
• Hipcall panelinde Ayarlar > Çağrı Merkezi > Etiketler menüsüne giderek gerekli etiketleri oluşturun. API üzerinden etiket oluşturulmaz, var olan etiketler atanır. Konfigürasyon için etiket ID değerlerini not edin.

Hangi süre alanını kullanmalısınız?

Çağrı kaydı zamanla ilgili birden fazla alan içerir. Doğru alanı seçin. Yanlış alan hatalı rapor üretir.

Konuşma süresini ölçmek için call_duration değerini kullanmayın. 45 saniye çalıp açılmayan bir çağrının call_duration değeri 45 saniyedir. Müşterinin 15 saniye anons dinleyip 6 saniye konuştuğu bir çağrının call_duration değeri 21 saniyedir.

Gerçek konuşma süresini hesaplamak için ended_at ile bridged_at zaman damgaları arasındaki farkı alın.

Kim kapattı ve neden önemli?

Kısa çağrıları incelerken hattı kimin kapattığına bakın. Bu bilgiyi hangup_by alanından alabilirsiniz.

• contact: Müşteri kapattı. Yanlış numara veya meşguliyet kaynaklı doğal bir düşmedir.
• user: Ajan kapattı. Ajanın yüzüne kapatması veya donanım sorunu anlamına gelir. Kalite yöneticisi için kırmızı alarmdır.

İki ayrı etiket kullanın (örneğin short-call-agent ve short-call-customer). Tek bir genel etiket basmak, müşteri hatalarıyla kasti ajan kapatmalarını birbirine karıştırır.

Adım 1: Etiket ekleme

Çağrıya etiket eklemek için POST /api/v3/calls/{call_id}/tags endpoint'ini kullanın. İstek gövdesinde etiketin adını değil, tag_id değerini gönderin.

var apiToken = Environment.GetEnvironmentVariable("HIPCALL_API_TOKEN") 
    ?? throw new InvalidOperationException("HIPCALL_API_TOKEN ortam değişkeni bulunamadı.");

client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", apiToken);

var tagBody = new { tag_id = 5635 };
var tagContent = new StringContent(JsonSerializer.Serialize(tagBody), Encoding.UTF8, "application/json");

var response = await client.PostAsync($"calls/{callUuid}/tags", tagContent);

İşlem başarılı olduğunda API 200 OK (veya 201 Created) döner ve atanan etiketin detaylarını verir:

{
  "data": {
    "id": 5635,
    "name": "test-kisa-cagri-1",
    "description": "test",
    "color": "#ef4444",
    "color_name": "red"
  }
}

Var olmayan bir tag_id gönderirseniz API 404 Not Found döner. Bu endpoint idempotent'tir. Aynı etiketi iki kez göndermek hata fırlatmaz, başarılı döner ancak mükerrer kayıt oluşturmaz.

Adım 2: Webkanca kuralları

Bir önceki görevde cevapsız çağrıları yakalayan bir kural yazmıştınız. Artık aynı webkanca uç noktanız (call_hangup) iki farklı kuralı yan yana değerlendirecektir:

flowchart TD
    A[call_hangup Webkanca Olayı] --> B(RuleEngine)
    B --> C{MissedCallRule<br>Eşleşiyor mu?}
    B --> D{ShortCallTagRule<br>Eşleşiyor mu?}
    
    C -- Evet<br>(Cevapsız Çağrı) --> E[Sonuç Kodu Ata<br>& Görev Aç]
    C -- Hayır --> F[Atla]
    
    D -- Evet<br>(Cevaplanmış & Süre < Eşik) --> G{Kim Kapattı?}
    D -- Hayır --> H[Atla]
    
    G -- Ajan (user) --> I[Ajan Kısa Çağrı Etiketi Ekle]
    G -- Müşteri (contact) --> J[Müşteri Kısa Çağrı Etiketi Ekle]
    
    E --> K((Bitiş))
    F --> K
    I --> K
    J --> K
    H --> K

Kuralı işletmeden önce çağrının bridged_at ve ended_at değerlerine sahip olduğunu doğrulayın, cevapsız çağrıları es geçin.

Uygulamanızı test etmek için aşağıdaki curl komutu ile altı saniye konuşulmuş sahte bir call_hangup olayını yerel sunucunuza gönderebilirsiniz:

curl -X POST http://localhost:5000/hipcall/events/whsec_live_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "credited": false,
    "team_touch_at": null,
    "first_touch_duration": 10,
    "contact_id": null,
    "callee_id": null,
    "answered_at": "2026-09-29T14:13:33Z",
    "voicemail_url": null,
    "caller_number": "+90850XXXXXXX",
    "missing_call_reason": null,
    "call_duration": 12,
    "callback_time": null,
    "call_flow": [
      {
        "action": "hangup",
        "detail": {
          "hangup_by": "contact"
        },
        "timestamp": 1790691215
      },
      {
        "action": "bridge",
        "detail": {
          "id": 4200,
          "type": "user"
        },
        "timestamp": 1790691205
      },
      {
        "action": "init",
        "detail": {
          "id": null,
          "type": "contact"
        },
        "timestamp": 1790691203
      }
    ],
    "direction": "outbound",
    "callee_number": "+90530XXXXXXX",
    "voicemail_id": null,
    "callback_user_id": null,
    "callee_type": "contact",
    "ended_at": "2026-09-29T14:13:35Z",
    "missing_call": false,
    "channel_type": "number",
    "callback_cdr_uuid": null,
    "voicemail_type": null,
    "caller_id": 4200,
    "started_at": "2026-09-29T14:13:23Z",
    "bridged_at": "2026-09-29T14:13:33Z",
    "channel_id": 942,
    "caller_type": "user",
    "user_id": 4200,
    "hangup_by": "contact",
    "uuid": "410c92c5-...masked...",
    "record_url": "https://storage.hipcall.com.tr/recordings/...masked...",
    "number_id": 942,
    "company_id": 80719
  },
  "event": "call_hangup"
}'

Eşik değerini ve etiket ID'lerini koda gömmeyin. Dinamik değer kullanmak yeniden derleme yapmadan değişiklik imkanı verir. Bunları appsettings.json dosyasından okuyun:

{
  "Hipcall": {
    "ShortCallThresholdSeconds": 10,
    "ShortCallAgentTagId": 5618,
    "ShortCallCustomerTagId": 5635
  }
}

C# kural sınıfı

Bu kural sınıfı IPostCallRule arayüzünü uygular. Süreleri hesaplar, eşiğin altındaysa kapatan tarafa göre uygun etiketi API'ye gönderir.

using System;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;

public sealed class ShortCallTagRule : IPostCallRule
{
    public string RuleName => "ShortCallTagRule";

    private readonly HipcallApiClient _api;
    private readonly HipcallSettings _settings;
    private readonly ILogger<ShortCallTagRule> _logger;

    public ShortCallTagRule(
        HipcallApiClient api,
        IOptions<HipcallSettings> settings,
        ILogger<ShortCallTagRule> logger)
    {
        _api = api;
        _settings = settings.Value;
        _logger = logger;
    }

    public bool Matches(WebhookPayload payload)
    {
        if (payload.Data == null) return false;
        if (payload.Event != "call_hangup") return false;
        
        if (payload.Data.IsMissedCall) return false;
        if (string.IsNullOrEmpty(payload.Data.BridgedAt)) return false;

        return true;
    }

    public async Task ExecuteAsync(WebhookPayload payload, CancellationToken ct = default)
    {
        var call = payload.Data!;

        if (!DateTime.TryParse(call.BridgedAt, out var bridgedAt) || 
            !DateTime.TryParse(call.EndedAt, out var endedAt))
        {
            return;
        }

        var talkDurationSeconds = (endedAt - bridgedAt).TotalSeconds;

        if (talkDurationSeconds >= _settings.ShortCallThresholdSeconds)
        {
            return;
        }

        int tagId = call.HangupBy == "user" 
            ? _settings.ShortCallAgentTagId 
            : _settings.ShortCallCustomerTagId;

        if (tagId == 0) return;

        await _api.AddTagToCallAsync(call.Uuid, tagId, ct);
    }
}

Son olarak, bu kuralı uygulamanızın kural motoruna dahil etmek için Program.cs dosyanıza şu kaydı ekleyin:

builder.Services.AddSingleton<IPostCallRule, ShortCallTagRule>();

Hata aldığınızda

404 Not Found

{
  "errors": {
    "detail": "Not Found"
  }
}

Panelde bulunmayan bir tag_id gönderdiniz. Etiketin panelde oluşturulduğunu ve ID değerinin konfigürasyonda doğru tanımlandığını kontrol edin.

422 Unprocessable Entity

{
  "errors": {
    "tag_id": [
      "Missing field: tag_id"
    ]
  }
}

Etiketin adını gönderdiniz. İstek gövdesini sayısal tag_id alanını içerecek şekilde düzenleyin.

Parametre listesi

Sonraki adımlar

• Temsilci bazında kısa çağrı raporları oluşturarak eğitim ihtiyaçlarını belirleyin.
• Müşteri kaynaklı kısa çağrıların hacmini izleyerek santral menünüzdeki (IVR) olası yönlendirme hatalarını tespit edin.
• Zaman içindeki gerçek konuşma sürelerini analiz ederek eşik değerinizi en uygun şekilde güncelleyin.