Hipcall Harici Yönetim (External Management) Nedir ve Nasıl Kullanılır?

Bu makalemizde Hipcall External Management sisteminden bahsedeceğiz. Bu özellik, çağrı yönlendirme kararlarını kendi web servisinize devretmenizi sağlar. Gelen çağrı bir External Manager'a düştüğünde, Supervisor çağrı bilgilerini sizin URL'inize POST eder ve dönen JSON'daki komutları sırasıyla uygular.

Geri bildirimlerinizi https://community.hipcall.com/c/turkce/gelistiriciler/12 üzerinden mühendislik ekibimiz ile paylaşabilirsiniz.

External manager için kurulum

Hipcall panelinde Ayarlar > Geliştirici > Harici yönetimler menüsüne gidin ve yeni bir kayıt oluşturun. Aşağıdaki bilgilerin hazır olması gerekir:

Ad: Kaydı panelde ayırt etmenizi sağlayan isim
Dahili numara: Bu harici yönetim kaydının dahili numarası
Web servis URL'i: Hipcall'ın çağrı bilgisini POST edeceği endpoint
Basic Auth bilgileri (opsiyonel): Webservisiniz Basic Auth ile korunuyorsa kullanıcı adı ve parola
Varsayılan hedef (default target): Webservis hata verdiğinde veya cevap dönmediğinde çağrının yönleneceği yer

Kaydı oluşturduktan sonra, çağrıların bu kayda düşmesi için Ayarlar > Telefon sistemi > Telefon numaraları menüsünden ilgili numaranın Mesai içi hedef alanına bu kaydı atayın.

Geliştirme sırasında hata ayıklamak için harici yönetim kaydınızın Kayıtlar sekmesinden "Hata Ayıklama Modu"nu açabilirsiniz. Bu mod en fazla 2 saat aktif kalır ve süre dolunca logları siler.

Nasıl çalışır?

Harici yönetim modülüne çağrı düştüğünde, Hipcall sizin verdiğiniz web servisine bir JSON POST eder:

{
  "caller": "+908508852972",
  "callee": "908508851980",
  "direction": "inbound",
  "timestamp": 1729721495,
  "external_manager_id": 2,
  "uuid": "8bcfdf1d-d7b9-434d-9207-d33a8e73ac47",
  "data": {},
  "call_flow": [
    {
      "timestamp": 1729721495,
      "action": "init",
      "detail": {
        "id": 2,
        "type": "external_manager"
      }
    }
  ]
}

Alan	Tip	Açıklama
`caller`	string	Arayan telefon numarası (E.164)
`callee`	string	Aranan numara
`direction`	string	Çağrı yönü
`timestamp`	integer	Unix zaman damgası
`external_manager_id`	integer	External Manager ID'si
`uuid`	string	Eşsiz çağrı kimliği
`data`	object	External Manager üzerinde tutulan key-value veri
`call_flow`	array	O ana kadarki çağrı akışı geçmişi

Web servis, HTTP 200 durumu ile aşağıdaki formatta bir JSON döndürmelidir:

{
  "version": "1",
  "seq": [
    {
      "action": "say",
      "args": {
        "text": "Hipcall'a hoş geldiniz. Satış için 1, destek için 2'ye basın.",
        "language": "tr-TR"
      }
    },
    {
      "action": "gather",
      "args": {
        "min_digits": 1,
        "max_digits": 1,
        "ask": "http://example.com/sessizlik.wav",
        "variable_name": "departman"
      }
    },
    {
      "action": "connect",
      "args": {
        "destination": "1000"
      }
    }
  ]
}

seq içindeki komutlar verildiği sırayla işlenir.

External management'ta olan özellikler

`play` — Ses dosyası çal

Verilen URL'deki MP3/WAV dosyasını arayana dinletir.

{ "action": "play", "args": { "url": "https://example.com/karsilama.mp3" } }

`say` — Metni sese çevir (TTS) (yeni)

Verdiğiniz metni Hipcall TTS servisi ile sese dönüştürür ve arayana dinletir.

{
  "action": "say",
  "args": {
    "text": "Siparişiniz hazır.",
    "language": "tr-TR"
  }
}

text: En fazla 1000 karakter
language: BCP-47 formatında (örn. tr-TR, en-US, de)

`dial` — Dış numaraya yönlendir

Çağrıyı harici bir telefon numarasına bağlar.

{ "action": "dial", "args": { "destination": "+905326202911" } }

`connect` — İç hatta yönlendir

Çağrıyı dahili numarası olan bir hedefe (kullanıcı, ekip/kuyruk, akıllı yönlendirme, karşılama anonsu vb.) bağlar.

{ "action": "connect", "args": { "destination": "1000" } }

`gather` — Tuşlamaları topla

Bir anons çalar ve arayanın DTMF tuşlarını toplar. Toplanan değer, External Manager'ın data haritasında verdiğiniz değişken adıyla saklanır ve bir sonraki webservis çağrısında size geri gönderilir.

İki kullanım şekli vardır:

Hazır ses dosyası ile:

{
  "action": "gather",
  "args": {
    "min_digits": 1,
    "max_digits": 4,
    "ask": "https://example.com/pin-girin.wav",
    "variable_name": "pin_kodu"
  }
}

TTS ile:

{
  "action": "gather",
  "args": {
    "min_digits": 1,
    "max_digits": 4,
    "text": "Lütfen PIN kodunuzu girin.",
    "language": "tr-TR",
    "variable_name": "pin_kodu"
  }
}

ask ve text aynı anda kullanılamaz. variable_name sadece harf, rakam ve alt çizgi içerebilir, en fazla 32 karakterdir.

Dikkat: ask ile verdiğiniz ses dosyasının URL'si erişilemiyorsa (örneğin 404 dönüyorsa) Hipcall anonsu çalamadan boş data ile webservisinize geri döner. Kodunuz boş değer gördüğünde tekrar gather gönderirse bu döngü saniyede defalarca tekrar edebilir. Ses dosyasının erişilebilir olduğundan emin olun.

`set_caller_name` — Arayan kimliğini değiştir (yeni)

Çağrı bağlandığında karşı tarafa görünen arayan adı/numarasını değiştirir.

{ "action": "set_caller_name", "args": { "caller_name": "SatisEkibi" } }

caller_name sadece alfanümerik karakter, en fazla 32 karakterdir.

`hangup` — Çağrıyı sonlandır

Normal şekilde çağrıyı kapatır.

{ "action": "hangup" }

`reject` — Çağrıyı reddet (yeni)

Çağrıyı reddedildi (busy) sinyali ile sonlandırır.

{ "action": "reject" }

Önemli sıralama kuralları

FreeSWitch'in çalışma modeli nedeniyle bazı komutlar sonrasındaki komutları geçersiz kılar. Bunlara dikkat edin:

dial ve connect mutlaka sırada son olmalıdır. Çağrı bağlandığı anda kalan komut kuyruğu temizlenir; sonraki komutlar çalışmaz.
hangup ve reject çağrıyı bitirir. Sonrasındaki komutlar hiç çalışmaz. Bu yüzden vedalaşma anonsunu önce çalın, sonra hangup verin.
gather da en sonda olmalıdır. Tuşlama tamamlandığında Hipcall webservisinize yeni bir istek atar (bu kez data içinde toplanan değer dolu olur). Webservisinizin döneceği yeni seq listesi, kalan komutların yerine geçer.
set_caller_name'i başa koyun. Bağlanmadan önce etkili olması için dial/connect'ten önce verilmelidir.

Önerilen sıralama

Konum	Uygun aksiyonlar
Başta	`set_caller_name`
Ortada	`play`, `say` (istediğiniz kadar)
Sonda	`dial`, `connect`, `gather`, `hangup` veya `reject` (sadece biri)

Hata durumları

Aşağıdaki durumlarda çağrı, External Manager için tanımladığınız varsayılan hedefe yönlendirilir:

Webservis 200 dışında bir HTTP cevabı dönerse
Webservis 15 saniye içinde cevap vermezse (zaman aşımı)
Cevap geçerli bir JSON değilse
JSON, beklenen formata uymuyorsa (eksik alan, hatalı tip vb.)
Webservise ulaşılamazsa (network hatası)

Tüm hatalar External Manager loglarına kaydedilir, sorun gidermek için bu loglara bakabilirsiniz. Geçersiz JSON veya beklenen formata uymayan bir cevap döndüğünde loglarda 422 Invalid payload format hatası görünür.

Sonraki Adımlar

External Management'ın gerçek bir kullanımını adım adım görmek için örnek senaryolara göz atabilirsiniz:

External Management ile Çağrıları Kendi Servisinizle Yönlendirme: Arayanı CRM verisiyle tanıyıp PIN doğrulamasına göre çağrıyı farklı kuyruklara yönlendirin.
PIN Doğrulaması ile Arayanları Yetkilendirme: Arayanları telefon numarası ve PIN ile doğrulayıp sonuca göre farklı dahililere yönlendirin.

External manager için kurulum

Nasıl çalışır?

External management'ta olan özellikler

play — Ses dosyası çal

say — Metni sese çevir (TTS) (yeni)

dial — Dış numaraya yönlendir

connect — İç hatta yönlendir

gather — Tuşlamaları topla

set_caller_name — Arayan kimliğini değiştir (yeni)

hangup — Çağrıyı sonlandır

reject — Çağrıyı reddet (yeni)