Ana içeriğe geç

Web kancaları

Web kancası, bir çağrıda her bir şey olduğunda telefonun seçtiğiniz bir adrese gönderdiği bir istektir. Bir CRM, müşterinin kartını ikinci zilden önce bu sayede açabilir, bir çağrı bittiğinde onu kaydedebilir ya da bir duvar panosunda bir lamba yakabilir. Web kancası gelen trafik için güvenlik duvarı kuralı gerektirmez: telefon size bağlanır. İstekler iş istasyonundan gönderildiği için adresin yalnızca o bilgisayardan erişilebilir olması yeterlidir — http://crm.local/calls gibi bir iç adres de herkese açık bir HTTPS adresi kadar iyi çalışır.

Web kancaları kurulumdan sonra siz açana kadar kapalıdır. Yerel REST API ile birlikte çalışırlar: bir olay bir şeyin değiştiğini söyler, API güncel ayrıntıları verir.

Açma​

Ayarlar → Bütünleştirme bölümünü açın. Web kancaları sekmenin ilk bölümüdür.

  1. Çağrılar hakkında başka bir sisteme haber ver seçeneğini işaretleyin. Aşağıda işaretlediğiniz her olay için bir istek gönderilir.
  2. Olayları alması gereken Adres bilgisini girin, örneğin https://crm.local/calls.
  3. Yöntem seçin: POST (öntanımlı) ya da GET.
  4. Olaylar altında neyin gönderileceğini işaretleyin: Yeni bir çağrı, Biten bir çağrı, Durum değiştiren bir çağrı.
  5. İsteğe bağlı olarak Yetkilendirme altında alıcınızın denetleyebileceği bir başlık belirleyin: bir Başlık adı (Authorization önerilir) ve bir Başlık değeri. Değer hiçbir zaman bir ayar dosyasında değil, bilgisayarın anahtarlığında saklanır; kaydedildikten sonra alan Kaydedildi — değiştirmek için yazın gösterir.
  6. Ulaşıp ulaşmadığını görmek için Sınama olayı gönder düğmesine basın. Hiç gerçekleşmemiş bir çağrı için, gerçek bir olayla aynı başlıklarla bir olay gönderir. Ham isteği kaydedin ve alıcınızı sürümünüzün gerçekte gönderdiğine göre oluşturun.

Programın istekleri gönderen bölümü Bütünleştirme modülüdür; Modüller içinde kapatılabilir.

Olaylar​

İşaretlendiği adOlayNe zaman gönderilir
Yeni bir çağrıcall-startedGelen bir çağrı çalmaya başladığında ya da giden bir çağrı yapıldığında.
Durum değiştiren bir çağrıcall-state-changedÇağrının state değeri değiştiğinde: çağrı yanıtlandığında, taraflardan biri tarafından beklemeye alındığında ya da sürdürüldüğünde, bir konferansa katıldığında ya da ondan ayrıldığında. Sesi kapatmak bu olayı göndermez.
Biten bir çağrıcall-endedÇağrı sona erdiğinde.

Her olay ayrı ayrı işaretlenebilir. Ekrana müşteri kartı açmak için yalnızca ilki, bir çağrı günlüğü için yalnızca sonuncusu gerekir. call-started ilk gönderilendir ve hızlı işlenmelidir.

İstek neye benzer​

https://crm.local/calls adresi ve POST yöntemiyle telefon şunu gönderir. Gövde JSON'dur, başlık ise Yetkilendirme altında belirlediğiniz başlıktır:

POST /calls HTTP/1.1
Host: crm.local
Authorization: Bearer my-secret-token
Content-Type: application/json
User-Agent: ai-softphone/1.1.5-macos-dmg

User-Agent, programın sürümünü ve nasıl kurulduğunu taşır.

Gelen bir çağrı, olay olay​

1020 dahilisinden 1002 hesabına gelen bir çağrı çalar, yanıtlanır ve yanıtlayan kişi tarafından dört saniye sonra kapatılır. Üç olay da işaretliyken alıcı art arda üç istek alır. Hepsi aynı id ve seance_id değerini taşır.

1. Çalıyor: call-started​

{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791021263333",
"callstate_ts": "1791021263333",
"dialed": "",
"direction": "in",
"duration_s": "0",
"event": "call-started",
"event_ts": "1791021263333",
"id": "5b1c0a6e-0c7e-4c53-9f57-2c4f1f0d6a11",
"name": "Jack Russel",
"number": "1020",
"reason": "none",
"seance_id": "e3f0b9f4-1a2c-4d8b-9c35-6a7b8c9d0e1f",
"state": "ringing-in",
"uri": "sip:1020@pbx.example.com"
}

Arayanı number ile arayıp müşterinin kartını göstermenin zamanı budur. state değeri ringing-in, duration_s ise 0'dır.

2. Yanıtlandı: call-state-changed​

Yaklaşık üç saniye sonra:

{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791021263333",
"callstate_ts": "1791021266126",
"dialed": "",
"direction": "in",
"duration_s": "0",
"event": "call-state-changed",
"event_ts": "1791021266131",
"id": "5b1c0a6e-0c7e-4c53-9f57-2c4f1f0d6a11",
"name": "Jack Russel",
"number": "1020",
"reason": "none",
"seance_id": "e3f0b9f4-1a2c-4d8b-9c35-6a7b8c9d0e1f",
"state": "active",
"uri": "sip:1020@pbx.example.com"
}

state artık active'dir ve callstate_ts değişiklik anına ilerlemiştir, callstart_ts ise olduğu yerde kalır.

3. Bitiyor: call-ended​

Dört saniyelik konuşmadan sonra:

{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791021263333",
"callstate_ts": "1791021270400",
"dialed": "",
"direction": "in",
"duration_s": "4",
"event": "call-ended",
"event_ts": "1791021270406",
"id": "5b1c0a6e-0c7e-4c53-9f57-2c4f1f0d6a11",
"name": "Jack Russel",
"number": "1020",
"reason": "local-hangup",
"seance_id": "e3f0b9f4-1a2c-4d8b-9c35-6a7b8c9d0e1f",
"state": "ended",
"uri": "sip:1020@pbx.example.com"
}

state değeri ended, duration_s konuşmanın süresidir ve reason onu kimin bitirdiğini söyler: burada local-hangup, çünkü bu telefondaki kişi kapattı.

Giden bir çağrı, olay olay​

Aynı dahili 1002 hesabından aranır: kişi 1020 numarasını tuşlar, telefon çalar, karşı taraf yanıtlar, yedi saniye konuşur ve kapatır. Alıcı dört istek alır; gelen bir çağrıdakinden bir fazla, çünkü giden bir çağrının karşı uçta çalarken kendine ait bir durumu vardır.

1. Tuşlanıyor: call-started​

{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791023883072",
"callstate_ts": "1791023883072",
"dialed": "1020",
"direction": "out",
"duration_s": "0",
"event": "call-started",
"event_ts": "1791023883072",
"id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24",
"name": "",
"number": "1020",
"reason": "none",
"seance_id": "c47d2e90-6b13-4f85-a2d7-18e9b0f35a6c",
"state": "dialing",
"uri": "sip:1020@pbx.example.com:5060"
}

direction değeri out, state değeri dialing'dir ve dialed numarayı tuşlandığı biçimiyle içerir. Telefon karşı tarafın adını henüz bilmediği için name boştur.

2. Karşı uçta çalıyor: call-state-changed​

Yarım saniye sonra:

{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791023883072",
"callstate_ts": "1791023883591",
"dialed": "1020",
"direction": "out",
"duration_s": "0",
"event": "call-state-changed",
"event_ts": "1791023883591",
"id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24",
"name": "",
"number": "1020",
"reason": "none",
"seance_id": "c47d2e90-6b13-4f85-a2d7-18e9b0f35a6c",
"state": "ringing-out",
"uri": "sip:1020@pbx.example.com:5060"
}

state değeri ringing-out'tur.

3. Karşı taraf yanıtlıyor: call-state-changed​

Bundan dört saniye sonra:

{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791023883072",
"callstate_ts": "1791023887072",
"dialed": "1020",
"direction": "out",
"duration_s": "0",
"event": "call-state-changed",
"event_ts": "1791023887076",
"id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24",
"name": "Jack Russel",
"number": "1020",
"reason": "none",
"seance_id": "c47d2e90-6b13-4f85-a2d7-18e9b0f35a6c",
"state": "active",
"uri": "sip:1020@pbx.example.com"
}

state değeri active'dir. name artık doldurulmuştur ve uri, yanıtın bildirdiği biçimiyle karşı tarafın adresidir. duration_s hâlâ 0'dır: bu andan itibaren sayar.

4. Bitiyor: call-ended​

Yedi saniye sonra karşı taraf kapatır:

{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791023883072",
"callstate_ts": "1791023894781",
"dialed": "1020",
"direction": "out",
"duration_s": "7",
"event": "call-ended",
"event_ts": "1791023894789",
"id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24",
"name": "Jack Russel",
"number": "1020",
"reason": "remote-hangup",
"seance_id": "c47d2e90-6b13-4f85-a2d7-18e9b0f35a6c",
"state": "ended",
"uri": "sip:1020@pbx.example.com"
}

duration_s değeri 7, reason ise remote-hangup'tır, çünkü çağrıyı karşı taraf bitirdi. Siz kendiniz kapattığınızda, yukarıdaki gelen çağrıda olduğu gibi local-hangup olur.

Durumlar yan yana​

Gelen çağrıGiden çağrı
call-startedringing-indialing
call-state-changedactiveringing-out, ardından active
call-endedendedended

Alanlar​

Sayılar ve zaman damgaları dahil, her değer bir dizedir: "duration_s": "42". Bilinmeyen bir an boş bir dizedir. Adlar tek bir kurala uyar: _id bir tanımlayıcıdır, _ts milisaniye cinsinden Unix zamanıdır (UTC), _s saniye cinsinden bir süredir — değerlerin JSON sayıları olduğu REST API'dekiyle aynı.

AlanAnlamı
eventcall-started, call-state-changed ya da call-ended.
idÇağrı: GET /calls ve /calls/{id}/… içindekiyle aynı UUID; çağrının her olayında da aynı.
seance_idÇağrının ait olduğu görüşme; bkz. aşağısı.
directionin ya da out.
stateGET /calls içindekiyle aynı değerler: dialing, ringing-out, ringing-in, active, hold (bu telefon tarafından bekletilen), onhold (karşı taraf tarafından bekletilen), conference ya da ended.
numberKarşı tarafın numarası. CRM kayıtlarınızı bu alana göre eşleştirin.
nameKişiler'den alınan karşı tarafın adı; boş olabilir ve yukarıdaki giden çağrıda olduğu gibi çağrının ilerleyen bir anında doldurulabilir.
uriKarşı tarafın SIP adresi.
dialedGiden bir çağrı için tuşlanan rakamlar; gelen bir çağrı için boş.
account, account_idÇağrının bulunduğu hat: username@server ve GET /accounts içindeki tanımlayıcı.
event_tsOlayın gerçekleştiği an.
callstart_tsTelefonun çağrıyı ilk öğrendiği an.
callstate_tsÇağrının geçerli state durumuna girdiği an.
duration_sYanıttan kapatmaya kadar saniye cinsinden konuşma süresi. Yanıtlanan bir çağrı için call-ended olayında belirlenir; aksi hâlde 0.
reasonÇağrının nasıl bittiği: local-hangup, remote-hangup, busy, no-answer, cancelled…; o zamana kadar none.
answered_byÇağrıyı bir insan yanıtladıysa no; aksi hâlde onu yanıtlayan şey.

Aktarmalar boyunca tek bir görüşme​

seance_id, tek bir görüşmeyi oluşturan çağrıları gruplar. Sıfırdan yapılan ya da alınan bir çağrı yeni bir görüşme başlatır. Bir aktarmayla oluşturulan çağrı, başka bir çağrının yerini alan çağrı, bir çağrı hakkında yapılan danışma ve bir konferansa katılan her çağrı, geldikleri çağrının seance_id değerini korur.

Telefonlar arasında X-Seance-Id SIP başlığında taşınır: bir çağrı AI Softphone kullanan bir iş arkadaşına aktarıldığında ve santral başlığı iletirse, iki iş istasyonu da aynı seance_id değerini bildirir.

POST yerine GET​

GET, eski bir CRM ya da bir betik köprüsü gibi istek gövdesi alamayan alıcılar içindir. Bu durumda aynı alanlar sorgu parametreleri olarak gönderilir.

GET ile adres bir şablon olabilir: her [alan], o alanın yüzde kodlanmış değeriyle değiştirilir. Örneğin:

https://crm.local/pop?phone=[number]&call=[id]

Yer tutucular yukarıdaki alan adlarını kullanır. Önceki adlarla ([accountId], [at], [duration], [answeredBy], [seanceId]) kaydedilmiş şablonlar çalışmaya devam eder.

Olaylar nasıl teslim edilir​

DavranışSizin için anlamı
Olaylar çağrının kendisinden gönderilmez, kuyruğa alınırYavaş bir alıcı çalmayı, çağrıları ya da aktarmaları asla geciktirmez.
Dolu bir kuyruk olayları atarAlıcınız yanıt vermeyi keserse olaylar kaybolur, ama telefon çalışmaya devam eder. webhooks_dropped_total değerini izleyin.
Reddedilen ve ulaşılamayan teslimatlar sayılırwebhooks_delivered_total yerinde sayarken webhooks_failed_total değerinin artması alıcıyı işaret eder.
Olaylar sırayla gelirÇağrı başladı, ardından durum değişiklikleri, ardından çağrı bitti. Sakladığınız olayları sıralamak için geliş zamanlarını değil, callstate_ts değerini kullanın.
En az bir kezAynı olay iki kez gelebilir. id, event ve callstate_ts birlikte bir olayı tanımlar: işleyicinizin daha önce gördüğü bir olayı atlamasını sağlayın.

Olayları alma​

Bir alıcı için tek kural: hemen 200 ile yanıt verin, işi sonra yapın. Yavaş bir alıcı telefonu yavaşlatmaz, ama kuyruğu doldurur ve dolu bir kuyruk olayları atar.

Örneğin Node.js'te Express ile:

const express = require("express");
const app = express();
app.use(express.json());

const SECRET = process.env.SOFTPHONE_SECRET; // the Header value from Settings

app.all("/calls", (req, res) => {
if (req.get("Authorization") !== SECRET) return res.sendStatus(401);

// POST sends a JSON body, GET sends query parameters
const call = Object.keys(req.body || {}).length ? req.body : req.query;
res.sendStatus(200); // answer first

setImmediate(() => { // then do the work
if (call.event === "call-started" && call.direction === "in") {
openCustomerCard(call.number, call.name); // your code
}
if (call.event === "call-ended") {
logCall(call.id, Number(call.duration_s), call.reason); // your code
}
});
});

app.listen(8080);

Bir çağrının sonucunu — yanıtlandı, cevapsız, reddedildi — kaydetmek için REST API içindeki GET /history?limit=20 yanıtından aynı seance_id ve number değerlerine sahip girdiyi alın. Hizmetiniz bir aradan sonra yeniden başladığında GET /history?limit=200 okuyun ve kaçırdıklarınızı saklayın: gerçek zaman için web kancaları, boşlukları doldurmak için geçmiş.

CRM hazır olmadan istekleri görmek için Adres alanını çevrimiçi bir istek denetleyicisine yöneltin ve Sınama olayı gönder düğmesine basın.

Hiçbir şey gelmediğinde​

BelirtiNeyi denetlemeli
Hiç web kancası yokSınama olayı gönder düğmesine basın. Gelirse, ihtiyacınız olan olaylar işaretli değildir; gelmezse adres yanlıştır ya da iş istasyonundan erişilemez.
webhooks_failed_total artmaya devam ediyorAlıcı istekleri reddediyor ya da ona ulaşılamıyor. Günlüğünü ve iş istasyonundan gelen basit bir isteğe yanıt verip vermediğini denetleyin.
webhooks_dropped_total sıfırın üstündeAlıcı çok uzun süre çok yavaş kaldı ve kuyruk doldu. Önce 200 ile yanıt verin, sonra işleyin.
Aynı olay iki kezEn az bir kez teslimatta beklenen bir durum. Aynı id, event ve callstate_ts değerlerine sahip olayları tek bir olay sayın.