Emniyettepe Mh. Selam Sk. No:52 Ahikent Villaları - Eyüp/İSTANBUL
Müşteri Hizmetleri | 0850 532 99 99
0212 320 50 72

API Dokümanı

Bulutsantralim API ile aşağıdaki işlemleri yapabilirsiniz.

  • Uygulamalarınız üzerinden çağrı başlatabilirsiniz.
  • Santralinizdeki telefonsal olayları uygulamalarınıza bildirebilirsiniz.
  • Uygulamalarınız üzerinden çağrıların ses kayıtları dinleyebilir veya indirebilirsiniz.
  • Otomatik IVR araması projesi ve Sesli mesaj projesi başlatabilirsiniz.

ÇAĞRI BAŞLATMA

Uygulamalarınız üzerinden santraldeki bir dahiliye çağrı başlatmak için kullanılır. Bunun için HTTP GET metodu ile api.bulutsantralim.com adresi aşağıdaki parametrelerle çağrılır. İstek başarılı olduğunda HTTP 200 Status kodu ile mesajın Body’sinde call_uuid döner. İstek başarısız olduğunda ise ilgili HTTP Status kodu ile mesajın Body’sinde hata mesajı döner.

HAZIRLIK
Online İşlem Merkezi => Bulut Santralim => Santral Ayarlarım menüsü altından API Anahtarınızı (key) öğrenmelisiniz.

ÇAĞRI BAŞLATMA ÖRNEĞİ

http://api.bulutsantralim.com/originate?key=K12345678-1234-5678-4321-123456789012&extension=1001&destination=908505320000

BAŞARILI CEVAP

HTTP/1.1 200 OK
358c20bc-fd86-11e5-87a2-157d41a07454

BAŞARISIZ CEVAP

HTTP/1.1 400 Bad Request
extension 1005 not found

PARAMETRELER
Kullanılacak parametreler aşağıdakilerdir. Zorunlu olanlar koyu olarak belirtilmiştir.

  • key = Size özel oluşturulmuş API anahtarınızdır.
  • extension = Aramanın bağlanacağı dahili numaradır.
  • destination = Aranacak olan numara. (908505320000 formatında olmalı.)
  • caller_id = Aramada kullanılacak olan dış numara. (908505320000 formatında olmalı. Kullanılacak dış numaranın mutlaka en az bir dahilide seçili olması gerekir. Bu parametre verilmezse dahilide seçili olan dış no kullanılacaktır.)
  • manual_answer = Değeri true olarak gönderilirse dahilinin telefonu açmasını bekler. (Normalde otomatik olarak dahili açılır ve karşı numara aranır.)

OLAY BİLDİRME (POPUP – CDR – CEVAPSIZ)

Santralinizde gerçekleşen olayları (telefon çalıyor, telefon açıldı, telefon kapandı) uygulamalarınıza bildirmek için kullanılır. Telefon kapandı (hangup) bildirimi aynı zamanda CDR bildirimidir. Telefon kapandı bildirimi içesindeki çağrının cevaplanıp cevaplanamadığı (answered) bilgisi Kaçan çağrı tespiti için kullanılır. HTTP POST metodu ile santral ayarlarından girdiğiniz olay bildirim adresine aşağıdaki parametreler gönderilir. Veriler HTML Form Field olarak gönderilir.

HAZIRLIK
Online İşlem Merkezi => Bulut Santralim => Santral Ayarlarım menüsü altından hangi olayların bildirileceğini ve bildirim yapılacak URL’i belirtmelisiniz.

UYGULAMANIZA GÖNDERİLECEK BİLDİRİM ÖRNEĞİ

POST http://musteri.adresi.com.tr/event/
Host: musteri.adresi.com.tr
Accept: */*

event_type=ringing&domain_id=101&direction=inbound&caller_id_number=02123205062&outbound_caller_id_number=&destination_number=1001&dialed_user=1001&call_uuid=1234&start_stamp=2016-01-01 00:00:00

PARAMETRELER

  • event_type (ringing, answer, hangup)
  • domain_id
  • direction (internal, inbound, outbound)
  • caller_id_number
  • outbound_caller_id_number
  • destination_number
  • dialed_user
  • connected_user
  • call_uuid
  • start_stamp
  • answer_stamp
  • end_stamp
  • duration
  • recording_present (t, f)
  • answered (t, f)
  • queue
  • queue_wait_duration
  • sip_hangup_disposition
  • hangup_cause
  • failure_status
  • failure_phrase

SES KAYDI ERİŞİMİ

Santralinizdeki ses kayıtlarını uygulamalarınız üzerinden dinlemek veya indirmek için kullanılır. Bu işlem iki aşamadan oluşur. Birinci aşamada URL elde edilir. İkinci aşamada ise o URL’den ses dosyası indirilir/dinlenir.

Birinci aşama için; HTTP POST metodu ile api.bulutsantralim.com adresine aşağıdaki parametreler gönderilir. İstek başarılı olduğunda HTTP 200 Status kodu ile mesajın Body’sinde ses kaydına ait olan bir URL döner. İstek başarısız olduğunda ise ilgili HTTP Status kodu ile mesajın Body’sinde hata mesajı döner.

İkinci aşamada ise elde ettiğiniz URL bir player’a verilip dinleme yaptırılır veya direkt indirebilir. URL yaşam süresi 1 saattir.

HAZIRLIK
Online İşlem Merkezi => Bulut Santralim => Santral Ayarlarım menüsü altından API Anahtarınızı (key) öğrenmelisiniz.

URL İSTEME ÖRNEĞİ

http://api.bulutsantralim.com/recording_url?key=K12345678-1234-5678-4321-123456789012&call_uuid=12345678-1234-5678-4321-123456789012

BAŞARILI CEVAP

HTTP/1.1 200 OK
http://api.bulutsantralim.com/recording/Rbb9d6f36-d1a7-46f5-961e-4be2e2ba1b8e

 BAŞARISIZ CEVAP

HTTP/1.1 400 Bad Request
cannot find call with call_uuid 12345678-1234-5678-4321-123456789012

PARAMETRELER
Kullanılacak parametreler aşağıdakilerdir. Zorunlu olanlar koyu olarak belirtilmiştir.

  • key = Size özel oluşturulmuş API anahtarınızdır.
  • call_uuid = URL’ini istediğiniz ses kaydına ait uuid.

OTOMATİK ARAMA KAMPANYASI OLUŞTURMA

Yeni otomatik arama kampanyasını oluşturmak için HTTP(S) POST JSON yöntemini kullanabilirsiniz.
Aşağıdaki örnekte olduğu gibi bir JSON string POST etmeniz yeterlidir.

KAMPANYA BAŞLATMA ÖRNEĞİ

POST http://api.bulutsantralim.com/ivr_campaigns.json
Host: api.bulutsantralim.com
Content-Type: application/json
Accept: */*

{
 'key' : 'K12345678-1234-5678-4321-123456789012',
 'name' : 'Memnuniyet anketi',
 'date_range_begin' : '2017-05-09',
 'time_range_begin' : '09:00',
 'time_range_end' : '18:00',
 'ring_timeout' : 30,
 'cli' : '902129630131',
 'welcome_announcement_id' : 128,
 'call_retries' : 2,
 'digit_target_0' : 'notify_webhook',
 'digit_target_1' : 'notify_webhook',
 'digit_target_2' : 'user/1001',
 'digit_target_3' : 'group/700',
 'digit_target_4' : 'ivr/10',
 'digit_target_5' : 'announcement/428',
 'digit_target_6' : 'external/05321234567',
 'digit_target_7' : 'voicemail/1003',
 'digit_target_8' : 'queue/201',
 'digit_target_9' : 'queue/202',
 'digit_target_star' : 'restart',
 'digit_target_square' : 'user/1000',
 'timeout_target' : '',
 'invalid_target' : '',
 'digit_retries' : 1,
 'phone_list' : [
 {'phone' : '05512369874', 'phrase' : '#429 12/05/2017 #430 102.45 #431'},
 {'phone' : '05651236547', 'phrase' : '#429 12/05/2017 #430 65.12 #431'}
 ]
}

BAŞARILI CEVAP

HTTP/1.1 200 OK
20212

 BAŞARISIZ CEVAP

HTTP/1.1 400 Bad Request
name can't be blank

PARAMETRELER
Kullanılacak parametreler aşağıdakilerdir. Zorunlu olanlar koyu olarak belirtilmiştir.

  • key = Size özel oluşturulmuş API anahtarınızdır. https://oim.verimor.com.tr/switch/domain/edit adresinden görebilir/üretebilirsiniz.
  • name: Kampanyanın adı.
  • date_range_begin: Kampanyanın aramaya başlayacağı tarih, YYYY-AA-GG formatında olmalıdır.
  • time_range_begin: Kampanyanın çalışma saatlerinin başlangıcı. SS:DD (veya S:DD) formatında olmalı.
  • time_range_end: Kampanyanın çalışma saatlerinin bitişi. SS:DD (veya S:DD) formatında olmalı.
  • ring_timeout: Aranan numara çalarken beklenecek süre (saniye), 10 – 60 sn. arasında olabilir.
  • cli: Arayan numara. Karşı taraf bu numarayı görür.
  • welcome_announcement_id: Aranan numaralara dinletilecek ses dosyasının ID’si. Bu ses dinletilip peşinden tuşlama beklenir. ID’leri https://oim.verimor.com.tr/switch/announcements sayfasından görebilirsiniz.
  • call_retries: Tekrar arama sayısı. Meşgul, ulaşılamıyor, cevap yok gibi durumlarda numaranın kaç defa daha aranacağını belirtir.
  • digit_target0 .. digit_target_9: Aranan kişi 0 – 9 tuşlarına bastığında yönlendirilecek hedefler (gerçekleşecek eylemler). Verebileceğiniz hedeflerin listesi aşağıda listelenmiştir. 0-9, star, square, timeout, invalid’den en az birisi için hedef verilmesi zorunludur.
  • digit_target_start: Aranan kişi yıldız (*) tuşuna bastığında yönlendirilecek hedef (gerçekleşecek eylem). Verebileceğiniz hedeflerin listesi aşağıda listelenmiştir. 0-9, star, square, timeout, invalid’den en az birisi için hedef verilmesi zorunludur.
  • digit_target_square: Aranan kişi kare (#) tuşuna bastığında yönlendirilecek hedef (gerçekleşecek eylem). Verebileceğiniz hedeflerin listesi aşağıda listelenmiştir. 0-9, star, square, timeout, invalid’den en az birisi için hedef verilmesi zorunludur.
  • timeout_target: Aranan kişi ses kaydını dinledikten sonra 2 saniye içinde bir tuşa basmadığında ve retry_count adedi kadar tekrar denemenin sonunda yönlendirilecek hedef (gerçekleşecek eylem). Verebileceğiniz hedeflerin listesi aşağıda listelenmiştir. 0-9, star, square, timeout, invalid’den en az birisi için hedef verilmesi zorunludur.
  • invalid_target: Aranan kişi ses kaydını dinledikten hatalı bir tuşa bastığında ve retry_count adedi kadar tekrar denemenin sonunda yönlendirilecek hedef (gerçekleşecek eylem). Verebileceğiniz hedeflerin listesi aşağıda listelenmiştir. 0-9, star, square, timeout, invalid’den en az birisi için hedef verilmesi zorunludur.
  • digit_retries: Tuşlama tekrar sayısı. Geçersiz tuşlama yapıldığında veya hiç tuşlama yapılmayıp 2 saniye zamanaşımı dolduğunda, ilgili uyarı okunup Menü baştan okunur.
  • phone_list: Aranacak numara listesi (zorunlu). ‘phone’ aranacak numaradır, ‘905321234567’ veya ‘05321234567’ veya ‘5321234567’ veya uluslararası için ‘00491234567’ şeklinde olmalıdır, ‘phone’ sahası zorunludur. ‘phrase’ sahası bu numaraya okunacak özel mesajı belirtir, formatı için aşağıda Cümle (phrase) Formatı başlığına bakınız. ‘phrase’ sahası zorunlu değildir.

HEDEF (TARGET) SEÇENEKLERİ

  • restart: Karşılama mesajını (announcement) veya cümleyi (phrase) tekrar dinlet, “mesajı tekrar dinlemek için 3’e basınız” şeklinde kullanılabilir.
  • user/1000: Aranan kişiyi 1000 numaralı dahiliye bağla.
  • group/700: Aranan kişiyi 700 numaralı çalma grubuna bağla.
  • queue/200: Aranan kişiyi 200 numaralı kuyruğa aktar.
  • ivr/10: Aranan kişiyi 10 numaralı Sesli Karşılama Menüsüne aktar.
  • external/05321234567: Aranan kişiyi 05321234567 numarasına bağla.
  • voicemail/1000: Aranan kişiyi 1000 numaralı dahilinin telesekreterine aktar. 1000 numaralı dahili ulaşılabilir olsa bile.
  • announcement/456: Aranan kişiye 456 ID’li Ses Dosyasını dinlet ve çağrıyı sonlandır. Ses dosyası ID’lerinizi https://oim.verimor.com.tr/switch/announcements sayfasından görebilirsiniz.
  • fax: Aranan kişiye faks sinyali gönder, faks alma işlemini başlat.
  • fax/isim@firmaadi.com.tr: Aranan kişiye faks sinyali gönder, faks alma işlemini başlat, faks alınırsa verilen e-posta adresine gönder.
  • hangup/hangup: Çağrıyı kapat (normal kapatma sinyali ver).
  • hangup/busy: Çağrıyı kapat (meşgul tonu ver).

CÜMLE (PHRASE) FORMATI

Karşı tarafa okunacak ‘cümle’, boşlukla ayrılmış ‘kelime’lerden oluşur.
Önceden https://oim.verimor.com.tr/switch/announcements adresinden şu ses dosyalarını yüklediğimizi düşünelim:

  • ID: 456, okunan mesaj: “Değerli müşterimiz, son ödeme tarihi”
  • ID: 457, okunan mesaj: “olan faturanızın tutarı”
  • ID: 458, okunan mesaj: “tur. İyi günler dileriz.”

ÖRNEK CÜMLE

#456 15/11/2017 #457 73.56 #458

Karşı tarafa “Değerli müşterimiz, son ödeme tarihi on beş kasım iki bin on yedi olan faturanızın tutarı yetmiş üç lira elli altı kuruştur. İyi günler dileriz.” şeklinde seslendirilecektir.

TUŞLAMA RAPORU ALIMI

Kampanyadaki numara aranıp tuşlama yapıldığında, tuşlamada “API’ye gönder” seçildiyse webhook_url sahasındaki URL’e aşağıdaki gibi bir HTTP POST request’i gönderilir.

BİLDİRİM ÖRNEĞİ

POST http://sizin.adresiniz.com.tr/ivr_push
Host: sizin.adresiniz.com.tr

notification_id=5&notification_date=2017-05-10 13:18:56 UTC&domain_id=429&ivr_campaign_id=131&ivr_campaign_name=Memnuniyet anketi&ivr_lead_id=1878&phone=905321234567&digit=2&status=Başarılı&call_uuid=aacdb242-364b-11e7-8bed-c9aec7093786

BİLDİRİM SAHALARI
API’nize gönderilecek parametreler aşağıdakilerdir.

  • notification_id: Bu bildirime ait unique id.
  • notification_date: Bildirimi yapılan olayın gerçekleştiği tarih saat.
  • domain_id: Bulutsantral ID’si
  • ivr_campaign_id: Otomatik IVR arama kampanyasının ID’si
  • ivr_campaign_name: Otomatik IVR arama kampanyasının adı
  • ivr_lead_id: Kampanyadaki numaranın ID’si
  • phone: Aranan telefon numarası
  • digit: Aranan kişinin yaptığı tuşlama. Şu değerleri alabilir:
    • Boş string (“”): Çağrı başlamadı (numara meşgul, ulaşılamıyor, hatalı numara vs.). Bu durumda status sahasında ilgili hata yazar.
    • 0-9 arası bir rakam: Geçerli bir tuşlama yapıldı.
    • tire (-) işareti: tuşlama yapılmadı ve timeout oluştu.
    • ünlem (!) işareti ve rakam (örn: !4): Geçerli olmayan (tuşlama ayarlarında karşılığı olmayan) bir tuşa basıldı.
  • status: Çağrı durumu. “Başarılı”, “Cevapsız”, “Reddedildi”, “Hata” gibi açıklamaları içerir. “Başarılı” hariç her durum hata olarak yorumlanabilir.
  • call_uuid: Tuşlama için yapılan çağrının UUID’si. Yukarıdaki olay bildirme API’sini de kullanıyorsanız, orada gelen UUID ile eşleştirebilirsiniz.

Cevap Yaz


nineteen + fifteen =