Mine põhisisu juurde

Veebikonksud

Veebikonks on päring, mille telefon saadab teie valitud aadressile iga kord, kui kõnega midagi juhtub. Nii saab CRM avada kliendikaardi enne teist helinat, logida kõne selle lõppedes või süüdata seinatahvlil tule. Veebikonks ei vaja sissetulevaid tulemüüri reegleid: telefon võtab teiega ise ühendust. Kuna päringud saadetakse tööjaamast, peab aadress olema kättesaadav ainult sellest arvutist — sisemine http://crm.local/calls töötab sama hästi kui avalik HTTPS-aadress.

Veebikonksud on pärast paigaldamist väljas, kuni te need sisse lülitate. Need töötavad koos kohaliku REST API-ga: sündmus ütleb, et midagi muutus, API annab hetkeandmed.

Nende sisselülitamine​

Avage Seaded → Sidumine. Veebikonksud on vahekaardi esimene jaotis.

  1. Märkige Teisele süsteemile kõnedest teatamine. Iga allpool märgitud sündmuse kohta saadetakse üks päring.
  2. Sisestage Aadress, mis peab sündmused vastu võtma, näiteks https://crm.local/calls.
  3. Valige Meetod: POST (vaikimisi) või GET.
  4. Märkige jaotises Sündmused, mida saata: Uus kõne, Lõppev kõne, Olekut muutev kõne.
  5. Soovi korral määrake jaotises Volitamine päis, mida teie vastuvõtja saab kontrollida: Päise nimi (soovitatakse Authorization) ja Päise väärtus. Väärtust hoitakse arvuti võtmehoidjas, mitte kunagi seadete failis; pärast salvestamist näitab väli teksti Salvestatud — kirjutage, et see asendada.
  6. Vajutage Saada proovisündmus, et näha, kas see jõuab kohale. See saadab ühe sündmuse kõne kohta, mida kunagi ei toimunud, samade päistega nagu päris sündmus. Logige toorpäring ja ehitage vastuvõtja selle järgi, mida teie versioon tegelikult saadab.

Päringuid saatev programmi osa on moodul Sidumine; selle saab välja lülitada jaotises Moodulid.

Sündmused​

Märgitud kuiSündmusSaadetakse, kui
Uus kõnecall-startedSissetulev kõne hakkab helisema või tehakse väljaminev kõne.
Olekut muutev kõnecall-state-changedKõne state muutub: sellele vastatakse, kumbki pool paneb selle ootele või jätkab, või see liitub konverentsiga või lahkub sealt. Vaigistamine seda ei saada.
Lõppev kõnecall-endedKõne on lõppenud.

Iga sündmust saab märkida eraldi. Hüpikkaardile piisab esimesest; kõnelogile ainult viimasest. call-started saadetakse esimesena ja seda tuleks töödelda kiiresti.

Milline päring välja näeb​

Aadressi https://crm.local/calls ja meetodi POST korral saadab telefon selle. Sisu on JSON ja päis on see, mille määrasite jaotises Volitamine:

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 sisaldab programmi versiooni ja paigaldamise viisi.

Sissetulev kõne sündmuse kaupa​

Kõne sisenumbrilt 1020 kontole 1002 heliseb, sellele vastatakse ja vastaja lõpetab selle neli sekundit hiljem. Kui kõik kolm sündmust on märgitud, saab vastuvõtja üksteise järel kolm päringut. Neil kõigil on sama id ja seance_id.

1. Heliseb: 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"
}

Nüüd on aeg otsida helistaja number järgi üles ja näidata kliendikaarti. state on ringing-in ja duration_s on 0.

2. Vastatakse: call-state-changed​

Umbes kolm sekundit hiljem:

{
"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 on nüüd active ja callstate_ts on liikunud muutuse hetkele, samal ajal kui callstart_ts jääb samaks.

3. Lõpeb: call-ended​

Neljasekundilise vestluse järel:

{
"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 on ended, duration_s on vestluse kestus ja reason ütleb, kes selle lõpetas: siin local-hangup, sest kõne lõpetas selle telefoni juures olev inimene.

Väljaminev kõne sündmuse kaupa​

Samale sisenumbrile helistatakse kontolt 1002: inimene valib 1020, telefon heliseb, teine pool vastab, räägib seitse sekundit ja lõpetab. Vastuvõtja saab neli päringut, ühe rohkem kui sissetuleva kõne puhul, sest väljamineval kõnel on oma olek ajal, mil see teises otsas heliseb.

1. Valitakse: 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 on out, state on dialing ja dialed sisaldab numbrit nii, nagu see valiti. Telefon ei tea veel teise osapoole nime, nii et name on tühi.

2. Heliseb teises otsas: call-state-changed​

Pool sekundit hiljem:

{
"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 on ringing-out.

3. Teine pool vastab: call-state-changed​

Neli sekundit pärast seda:

{
"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 on active. name on nüüd täidetud ja uri on osapoole aadress nii, nagu vastus selle teatas. duration_s on endiselt 0: seda loetakse sellest hetkest.

4. Lõpeb: call-ended​

Seitse sekundit hiljem lõpetab teine pool kõne:

{
"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 on 7 ja reason on remote-hangup, sest kõne lõpetas teine pool. Kui lõpetate ise, on see local-hangup, nagu ülaltoodud sissetuleva kõne puhul.

Olekud kõrvuti​

Sissetulev kõneVäljaminev kõne
call-startedringing-indialing
call-state-changedactiveringing-out, siis active
call-endedendedended

Väljad​

Iga väärtus on string, ka numbrid ja ajatemplid: "duration_s": "42". Teadmata hetk on tühi string. Nimed järgivad üht tava: _id on identifikaator, _ts on Unixi aeg millisekundites (UTC), _s on kestus sekundites — nagu REST API-s, kus väärtused on JSON-numbrid.

VäliTähendus
eventcall-started, call-state-changed või call-ended.
idKõne: sama UUID mis GET /calls ja /calls/{id}/… puhul ning sama kõne igas sündmuses.
seance_idVestlus, kuhu kõne kuulub; vaadake allpool.
directionin või out.
stateSamad väärtused mis GET /calls puhul: dialing, ringing-out, ringing-in, active, hold (selle telefoni poolt ootele pandud), onhold (teise osapoole poolt ootele pandud), conference või ended.
numberTeise osapoole number. Siduge oma CRM-i kirjed selle välja järgi.
nameTeise osapoole nimi Kontaktidest; see võib olla tühi ja täituda kõne käigus hiljem, nagu ülaltoodud väljamineva kõne puhul.
uriTeise osapoole SIP-aadress.
dialedValitud numbrid väljamineva kõne puhul; sissetuleva kõne puhul tühi.
account, account_idLiin, millel kõne on: username@server ja identifikaator GET /accounts kaudu.
event_tsMillal sündmus toimus.
callstart_tsMillal telefon kõnest esimest korda teada sai.
callstate_tsMillal kõne jõudis oma praegusesse olekusse state.
duration_sKõneaeg sekundites vastamisest lõpetamiseni. Määratakse call-ended korral vastatud kõnele; muul juhul 0.
reasonKuidas kõne lõppes: local-hangup, remote-hangup, busy, no-answer, cancelled…; seni none.
answered_byno, kui kõnele vastas inimene; muul juhul see, mis vastas.

Üks vestlus ümbersuunamiste üle​

seance_id rühmitab kõned, mis moodustavad ühe vestluse. Nullist tehtud või vastu võetud kõne alustab uut. Ümbersuunamisega loodud kõne, teist asendav kõne, kõne kohta peetav konsultatsioon ja iga konverentsi liidetud kõne säilitavad selle kõne seance_id, millest need pärinevad.

Telefonide vahel liigub see SIP-päises X-Seance-Id: kui kõne suunatakse kolleegile, kes samuti kasutab AI Softphone'i, ja keskjaam annab päise edasi, teatavad mõlemad tööjaamad sama seance_id.

GET POST-i asemel​

GET on mõeldud vastuvõtjatele, kes ei saa päringu sisu vastu võtta, näiteks vanemale CRM-ile või sildskriptile. Samad väljad saadetakse siis päringuparameetritena.

GET korral võib aadress olla mall: iga [väli] asendatakse selle välja protsentkodeeritud väärtusega. Näiteks:

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

Kohatäited kasutavad ülaltoodud väljade nimesid. Varasemate nimedega ([accountId], [at], [duration], [answeredBy], [seanceId]) salvestatud mallid töötavad edasi.

Kuidas sündmusi kohale toimetatakse​

KäitumineMida see teie jaoks tähendab
Sündmused pannakse järjekorda, mitte ei saadeta kõnest endastAeglane vastuvõtja ei viivita kunagi helisemist, kõnesid ega ümbersuunamisi.
Täis järjekord jätab sündmusi väljaKui teie vastuvõtja lakkab vastamast, lähevad sündmused kaduma, kuid telefon töötab edasi. Jälgige loendurit webhooks_dropped_total.
Tagasi lükatud ja kättesaamatud saatmised loetakse kokkuKui webhooks_failed_total kasvab ja webhooks_delivered_total seisab, on probleem vastuvõtjas.
Sündmused saabuvad järjekorrasKõne algas, siis oleku muutused, siis kõne lõppes. Talletatud sündmuste järjestamiseks kasutage callstate_ts, mitte saabumise aega.
Vähemalt üks kordSama sündmus võib tulla kaks korda. id, event ja callstate_ts koos tuvastavad sündmuse: laske töötlejal juba nähtu vahele jätta.

Sündmuste vastuvõtmine​

Vastuvõtja ainus reegel: vastake kohe 200 ja tehke töö hiljem. Aeglane vastuvõtja ei aeglusta telefoni, kuid täidab järjekorra ja täis järjekord jätab sündmusi välja.

Näiteks Node.js-is Expressiga:

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);

Kõne tulemuse — vastatud, vastamata, tagasi lükatud — logimiseks võtke REST API päringust GET /history?limit=20 sama seance_id ja number väärtusega kirje. Kui teie teenus pärast pausi uuesti käivitub, lugege GET /history?limit=200 ja talletage vahelejäänu: veebikonksud reaalajaks, ajalugu lünkade täitmiseks.

Et päringuid näha enne, kui CRM on valmis, suunake Aadress veebipõhisele päringute uurijale ja vajutage Saada proovisündmus.

Kui midagi kohale ei jõua​

SümptomMida kontrollida
Veebikonkse ei tule üldseVajutage Saada proovisündmus. Kui see jõuab kohale, pole vajalikke sündmusi märgitud; kui mitte, on aadress vale või tööjaamast kättesaamatu.
webhooks_failed_total kasvab pidevaltVastuvõtja lükkab päringud tagasi või pole kättesaadav. Kontrollige selle logi ja seda, kas see vastab tööjaamast tehtud lihtsale päringule.
webhooks_dropped_total on üle nulliVastuvõtja oli liiga kaua liiga aeglane ja järjekord sai täis. Vastake esmalt 200 ja töödelge hiljem.
Sama sündmus kaks kordaVähemalt ühekordse kohaletoimetamise puhul oodatav. Käsitlege sama id, event ja callstate_ts väärtusega sündmusi ühena.