Hızlı Arama Nedir ve Nasıl Yapılır? -New

Genel bakış

Hipcall hızlı arama özelliği, gelen çağrıda aranacak hedef numarayı sizin webservisinize sorarak belirler. Örneğin bir kurye, sipariş sahibini arayacak ancak KVKK kapsamında onun numarasını bilmemesi gerekiyor. Kurye, hızlı aramanın dahili hattını çevirir, sipariş numarasını tuşlar; Hipcall bu bilgiyi sizin sunucunuza gönderir ve dönen hedef numarayı arar. Kurye müşteriyle konuşur ama numarayı hiçbir zaman görmez.

Başlamadan önce

Hipcall paketinizde API özelliğinin aktif olması gerekmektedir.
Servisiniz internet üzerinden erişilebilir olmalıdır. Geliştirme aşamasında ngrok veya benzeri bir tünel aracı kullanabilirsiniz.

Adım 1: Hızlı arama kaydı oluşturma

Hipcall panelinde Ayarlar → Geliştirici → Hızlı Arama bölümüne gidin ve Yeni butonuna basın. Açılan formda şu alanları doldurun:

Alan	Açıklama
Ad	Hızlı arama kaydına vereceğiniz isim (örn. "Sipariş Arama").
İç hat numarası	10'dan 9999'a kadar bir dahili numara (örn. `72`). Kurye bu numarayı tuşlayarak hızlı aramayı başlatır.
URL	Webservisinizin adresi (örn. `https://xxxx.ngrok-free.app/hizli-arama`). Hipcall bu adrese POST isteği gönderir.
Webservis kimlik doğrulama	İsteğe bağlı. İşaretlerseniz Kullanıcı adı ve Parola alanları açılır. Hipcall, isteklerini `Authorization: Basic <Base64>` başlığı ile gönderir.

Ayrıca iki adet anons yüklemeniz gerekir:

Numarayı aramadan önce giriş anonsu: Kullanıcıya tuşlama sırasında çalınacak ses dosyası (örn. "Lütfen sipariş numarasını tuşlayın.").
Eğer serviste hata varsa okunacak anons: Webservis başarısız olduğunda çalınacak ses dosyası.

Adım 2: Telefon numarasını hızlı aramaya yönlendirme

Hızlı arama kaydını oluşturmak tek başına yetmez. Gelen çağrıların bu kayda düşmesi için bir telefon numarasını hızlı aramaya atamanız gerekir:

Ayarlar → Telefon Sistemi → Telefon Numaraları bölümüne gidin.
Hızlı aramaya yönlendirmek istediğiniz numarayı seçin.
Çalışma Saatleri sekmesine geçin.
Mesai içi hedef alanında oluşturduğunuz hızlı arama dahili numarasını seçin.

Bu ayardan sonra ilgili numaraya gelen çağrılar önce anons dinletilip ardından webservisinize yönlendirilecektir.

Çalışma mantığı

Kullanıcı hızlı aramanın iç hat numarasını tuşlar (örn. 72).
Hipcall, webkanca adresinize call_init olayını gönderir.
Sistem, kullanıcıya yüklediğiniz giriş anonsunu çalar (örn. "Lütfen sipariş numarasını tuşlayın.").
Kullanıcı sipariş numarasını tuşlar (örn. 1234).
Hipcall, tuşlanan bilgiyi HTTP POST yöntemiyle webservisinize gönderir.
Webservisiniz hedef numarayı döndürür.
Hipcall hedef numarayı arar ve kullanıcıyı bağlar.

Hipcall'dan gelen istek formatı

Kullanıcı tuşlama yaptıktan sonra Hipcall, webservis URL'nize şu yapıda bir POST isteği gönderir:

{
  "timestamp": 1791891730,
  "number": "1234",
  "uuid": "e785****-****-****-****-********87e5",
  "user_id": null,
  "speed_dial_id": 19
}

İstek alanları

Alan	Tip	Açıklama
`timestamp`	integer	İsteğin unix zaman damgası.
`number`	string	Kullanıcının tuşladığı DTMF rakamları. Sizin sipariş kodunuz bu alandadır.
`uuid`	string	Çağrının benzersiz kimliği.
`user_id`	integer / null	Çağrıyı başlatan Hipcall kullanıcısının ID'si. Dış hat üzerinden geliyorsa `null` olabilir.
`speed_dial_id`	integer	Tetiklenen hızlı arama kaydının ID'si.

Not: Kimlik doğrulama etkinleştirdiyseniz Hipcall, isteğin Authorization başlığında Basic <Base64> değerini gönderir. Webservisiniz bu başlığı doğrulamalıdır.

Webservisden beklenen yanıt

Hipcall, webservisinizden aranacak hedef numarayı destination alanında bekler:

{ "destination": "90530XXXXXXX" }

Telefon numarasını alan kodu ile birlikte, yalnızca rakamlardan oluşan biçimde döndürün (örn. 905301234567).

Webkanca olayları

Hızlı arama süreci boyunca Hipcall, webkanca adresinize çağrının yaşam döngüsünü bildiren olaylar gönderir. Bu olaylar call_init, call_bridged ve call_hangup şeklinde sıralanır.

call_init — Çağrı başladı

Çağrı ilk başladığında gelen olay. call_flow dizisinde speed_dial tipinde bir init aksiyonu bulunur:

{
  "data": {
    "caller_number": "+90551XXXXXXX",
    "callee_number": "+90850XXXXXXX",
    "uuid": "e785****-****-****-****-********87e5",
    "direction": "inbound",
    "channel_id": 942,
    "number_id": 942,
    "channel_type": "number",
    "caller_type": "contact",
    "callee_type": null,
    "caller_id": null,
    "callee_id": null,
    "user_id": null,
    "started_at": "2026-10-13T11:42:04Z",
    "answered_at": null,
    "bridged_at": null,
    "ended_at": null,
    "call_duration": null,
    "first_touch_duration": null,
    "has_recording": false,
    "record_url": null,
    "missing_call": null,
    "missing_call_reason": null,
    "hangup_by": null,
    "credited": null,
    "contact_id": null,
    "company_id": null,
    "voicemail_id": null,
    "voicemail_url": null,
    "voicemail_type": null,
    "callback_time": null,
    "callback_user_id": null,
    "callback_cdr_uuid": null,
    "team_touch_at": null,
    "call_flow": [
      {
        "action": "init",
        "detail": {
          "id": 19,
          "type": "speed_dial"
        },
        "timestamp": 1791891724
      }
    ]
  },
  "event": "call_init"
}

call_bridged — Çağrı bağlandı

Hedef numara arandıktan sonra bağlantı kurulduğunda gelen olay. call_flow dizisinde route ve bridge aksiyonları eklenir:

{
  "data": {
    "caller_number": "+90551XXXXXXX",
    "callee_number": "+90850XXXXXXX",
    "uuid": "e785****-****-****-****-********87e5",
    "direction": "inbound",
    "started_at": "2026-10-13T11:42:04Z",
    "answered_at": null,
    "bridged_at": null,
    "call_flow": [
      {
        "action": "bridge",
        "detail": { "id": null, "type": "contact" },
        "timestamp": 1791891731
      },
      {
        "action": "route",
        "detail": { "id": null, "type": "contact" },
        "timestamp": 1791891730
      },
      {
        "action": "init",
        "detail": { "id": 19, "type": "speed_dial" },
        "timestamp": 1791891724
      }
    ]
  },
  "event": "call_bridged"
}

call_hangup — Çağrı kapandı

Çağrı sonlandığında gelen olay. call_duration, record_url, hangup_by gibi alanlar dolar:

{
  "data": {
    "caller_number": "+90551XXXXXXX",
    "callee_number": "+90850XXXXXXX",
    "uuid": "e785****-****-****-****-********87e5",
    "direction": "inbound",
    "started_at": "2026-10-13T11:42:04Z",
    "answered_at": "2026-10-13T11:42:04Z",
    "bridged_at": "2026-10-13T11:42:17Z",
    "ended_at": "2026-10-13T11:42:43Z",
    "call_duration": 39,
    "first_touch_duration": 13,
    "has_recording": true,
    "record_url": "https://storage.hipcall.com.tr/recordings/.../e785****-****-****-****-********87e5.mp3?...",
    "missing_call": false,
    "hangup_by": "user",
    "credited": false,
    "callee_id": 19,
    "callee_type": "speed_dial",
    "call_flow": [
      {
        "action": "hangup",
        "detail": { "hangup_by": "user" },
        "timestamp": 1791891763
      },
      {
        "action": "bridge",
        "detail": { "id": null, "type": "contact" },
        "timestamp": 1791891731
      },
      {
        "action": "route",
        "detail": { "id": null, "type": "contact" },
        "timestamp": 1791891730
      },
      {
        "action": "init",
        "detail": { "id": 19, "type": "speed_dial" },
        "timestamp": 1791891724
      }
    ]
  },
  "event": "call_hangup"
}

Başarısız olma durumları

Webservis ile herhangi bir nedenden başarısız bir iletişim kurulursa, sistem kullanıcıya hata anonsunu çalar ve görüşmeyi kapatır.

Başarısız sayılan durumlar:

Gelen cevabın HTTP kodu 200 değilse
HTTP isteği 3 saniye içinde cevaplanmaz ise
Webservisteki Basic Auth kullanıcı adı veya parolası yanlış ise
Gelen JSON formatı geçersiz ise
Gelen JSON'daki destination numarası aranabilir bir numara değilse (örn. 3ASDASDF)

Teknik destek

Firmamız üçüncü parti yazılımlara teknik destek vermemektedir. Bunun yerine Türkçe veya İngilizce olarak topluluktaki geliştiricilere sorularınızı iletebilirsiniz.