Hipcall harici yönetim (external management) nedir ve nasıl kullanılır?

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

Aşağıdaki bilgilerin hazır olması gerekir:

• 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

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.0",
  "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.

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:

1. dial ve connect mutlaka sırada son olmalıdır. Çağrı bağlandığı anda kalan komut kuyruğu temizlenir; sonraki komutlar çalışmaz.
2. 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.
3. 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.
4. 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
• 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.