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.
- Ç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.
- Olayları alması gereken Adres bilgisini girin, örneğin
https://crm.local/calls. - Yöntem seçin: POST (öntanımlı) ya da GET.
- Olaylar altında neyin gönderileceğini işaretleyin: Yeni bir çağrı, Biten bir çağrı, Durum değiştiren bir çağrı.
- İ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. - 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 ad | Olay | Ne zaman gönderilir |
|---|---|---|
| Yeni bir çağrı | call-started | Gelen 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-started | ringing-in | dialing |
call-state-changed | active | ringing-out, ardından active |
call-ended | ended | ended |
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ı.
| Alan | Anlamı |
|---|---|
event | call-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ı. |
direction | in ya da out. |
state | GET /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. |
number | Karşı tarafın numarası. CRM kayıtlarınızı bu alana göre eşleştirin. |
name | Kiş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. |
uri | Karşı tarafın SIP adresi. |
dialed | Giden 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_ts | Olayın gerçekleştiği an. |
callstart_ts | Telefonun çağrıyı ilk öğrendiği an. |
callstate_ts | Çağrının geçerli state durumuna girdiği an. |
duration_s | Yanı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ır | Yavaş bir alıcı çalmayı, çağrıları ya da aktarmaları asla geciktirmez. |
| Dolu bir kuyruk olayları atar | Alı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ır | webhooks_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 kez | Aynı 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
| Belirti | Neyi denetlemeli |
|---|---|
| Hiç web kancası yok | Sı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 ediyor | Alı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ünde | Alıcı çok uzun süre çok yavaş kaldı ve kuyruk doldu. Önce 200 ile yanıt verin, sonra işleyin. |
| Aynı olay iki kez | En az bir kez teslimatta beklenen bir durum. Aynı id, event ve callstate_ts değerlerine sahip olayları tek bir olay sayın. |