Μετάβαση στο κύριο περιεχόμενο

Webhooks

Ένα webhook είναι ένα αίτημα που στέλνει το τηλέφωνο σε μια διεύθυνση της επιλογής σας κάθε φορά που συμβαίνει κάτι σε μια κλήση. Έτσι ένα CRM μπορεί να ανοίξει την καρτέλα του πελάτη πριν από το δεύτερο κουδούνισμα, να καταγράψει μια κλήση όταν τελειώσει ή να ανάψει μια λυχνία σε έναν πίνακα ενδείξεων. Ένα webhook δεν χρειάζεται κανόνες τείχους προστασίας για εισερχόμενη κίνηση: το τηλέφωνο συνδέεται προς εσάς. Επειδή τα αιτήματα στέλνονται από τον σταθμό εργασίας, η διεύθυνση χρειάζεται να είναι προσβάσιμη μόνο από αυτόν τον υπολογιστή — μια εσωτερική http://crm.local/calls λειτουργεί εξίσου καλά με μια δημόσια διεύθυνση HTTPS.

Τα webhooks είναι ανενεργά μετά την εγκατάσταση, μέχρι να τα ενεργοποιήσετε. Λειτουργούν μαζί με το τοπικό REST API: ένα συμβάν λέει ότι κάτι άλλαξε, το API δίνει τις τρέχουσες λεπτομέρειες.

Ενεργοποίηση​

Ανοίξτε τις Ρυθμίσεις → Ενσωμάτωση. Τα Webhooks είναι η πρώτη ενότητα της καρτέλας.

  1. Σημειώστε το Ενημέρωσε άλλο σύστημα για τις κλήσεις. Στέλνεται ένα αίτημα για κάθε συμβάν που σημειώνετε παρακάτω.
  2. Εισαγάγετε τη Διεύθυνση που θα λαμβάνει τα συμβάντα, για παράδειγμα https://crm.local/calls.
  3. Επιλέξτε τη Μέθοδο: POST (η προεπιλογή) ή GET.
  4. Στα Συμβάντα σημειώστε τι θα στέλνεται: Νέα κλήση, Τέλος κλήσης, Αλλαγή κατάστασης κλήσης.
  5. Προαιρετικά, στην Πιστοποίηση, ορίστε μια κεφαλίδα που μπορεί να ελέγξει ο παραλήπτης σας: ένα Όνομα κεφαλίδας (προτείνεται το Authorization) και μια Τιμή κεφαλίδας. Η τιμή φυλάσσεται στη θυρίδα κλειδιών του υπολογιστή, ποτέ σε αρχείο ρυθμίσεων· μόλις αποθηκευτεί, το πεδίο δείχνει Αποθηκευμένο — πληκτρολογήστε για αντικατάσταση.
  6. Πατήστε Στείλε δοκιμαστικό συμβάν για να δείτε ότι φτάνει. Στέλνει ένα συμβάν για μια κλήση που δεν έγινε ποτέ, με τις ίδιες κεφαλίδες όπως ένα πραγματικό. Καταγράψτε το ακατέργαστο αίτημα και χτίστε τον παραλήπτη σας με βάση αυτό που πραγματικά στέλνει η έκδοσή σας.

Το μέρος του προγράμματος που στέλνει τα αιτήματα είναι η μονάδα Ενσωμάτωση· μπορεί να απενεργοποιηθεί στις Μονάδες.

Τα συμβάντα​

Σημειώνεται ωςΣυμβάνΣτέλνεται όταν
Νέα κλήσηcall-startedΜια εισερχόμενη κλήση αρχίζει να χτυπά ή γίνεται μια εξερχόμενη κλήση.
Αλλαγή κατάστασης κλήσηςcall-state-changedΑλλάζει η state της κλήσης: απαντάται, μπαίνει σε αναμονή ή συνεχίζεται από οποιαδήποτε πλευρά, ή μπαίνει σε διάσκεψη ή βγαίνει από αυτήν. Η σίγαση δεν το στέλνει.
Τέλος κλήσηςcall-endedΗ κλήση τελείωσε.

Κάθε συμβάν μπορεί να σημειωθεί χωριστά. Ένα αναδυόμενο παράθυρο πελάτη χρειάζεται μόνο το πρώτο· ένα αρχείο κλήσεων μόνο το τελευταίο. Το call-started στέλνεται πρώτο και πρέπει να διεκπεραιώνεται γρήγορα.

Πώς μοιάζει το αίτημα​

Με τη διεύθυνση https://crm.local/calls και τη μέθοδο POST, το τηλέφωνο στέλνει το εξής. Το σώμα είναι JSON, και η κεφαλίδα είναι αυτή που ορίσατε στην Πιστοποίηση:

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 φέρει την έκδοση του προγράμματος και τον τρόπο με τον οποίο εγκαταστάθηκε.

Μια εισερχόμενη κλήση, συμβάν προς συμβάν​

Μια κλήση από το εσωτερικό 1020 προς τον λογαριασμό 1002 χτυπά, απαντάται, και τέσσερα δευτερόλεπτα αργότερα ο άνθρωπος που απάντησε την τερματίζει. Με σημειωμένα και τα τρία συμβάντα, ο παραλήπτης λαμβάνει τρία αιτήματα, το ένα μετά το άλλο. Όλα φέρουν το ίδιο id και seance_id.

1. Χτυπά: 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"
}

Αυτή είναι η στιγμή να αναζητήσετε τον καλούντα με βάση το number και να δείξετε την καρτέλα του πελάτη. Η state είναι ringing-in και η duration_s είναι 0.

2. Απαντάται: call-state-changed​

Περίπου τρία δευτερόλεπτα αργότερα:

{
"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 είναι τώρα active, και το callstate_ts έχει μετακινηθεί στη στιγμή της αλλαγής, ενώ το callstart_ts μένει εκεί που ήταν.

3. Τελειώνει: call-ended​

Μετά από τέσσερα δευτερόλεπτα συνομιλίας:

{
"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 είναι ended, η duration_s είναι η διάρκεια της συνομιλίας, και το reason λέει ποιος την τερμάτισε: εδώ local-hangup, επειδή τερμάτισε ο άνθρωπος σε αυτό το τηλέφωνο.

Μια εξερχόμενη κλήση, συμβάν προς συμβάν​

Το ίδιο εσωτερικό καλείται από τον λογαριασμό 1002: ο χρήστης πληκτρολογεί 1020, το τηλέφωνο χτυπά, η άλλη πλευρά απαντά, μιλά για επτά δευτερόλεπτα και τερματίζει. Ο παραλήπτης λαμβάνει τέσσερα αιτήματα, ένα περισσότερο από ό,τι για μια εισερχόμενη κλήση, επειδή μια εξερχόμενη κλήση έχει δική της κατάσταση όσο χτυπά στην άλλη άκρη.

1. Καλείται: 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 είναι out, η state είναι dialing, και το dialed περιέχει τον αριθμό όπως πληκτρολογήθηκε. Το τηλέφωνο δεν ξέρει ακόμη το όνομα του συνομιλητή, οπότε το name είναι κενό.

2. Χτυπά στην άλλη άκρη: call-state-changed​

Μισό δευτερόλεπτο αργότερα:

{
"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 είναι ringing-out.

3. Η άλλη πλευρά απαντά: call-state-changed​

Τέσσερα δευτερόλεπτα μετά:

{
"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 είναι active. Το name έχει πλέον συμπληρωθεί, και το uri είναι η διεύθυνση του συνομιλητή όπως την ανέφερε η απάντηση. Η duration_s είναι ακόμη 0: μετρά από αυτή τη στιγμή.

4. Τελειώνει: call-ended​

Επτά δευτερόλεπτα αργότερα η άλλη πλευρά τερματίζει:

{
"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 είναι 7, και το reason είναι remote-hangup, επειδή η άλλη πλευρά τερμάτισε την κλήση. Όταν τερματίζετε εσείς, είναι local-hangup, όπως στην παραπάνω εισερχόμενη κλήση.

Οι καταστάσεις, δίπλα δίπλα​

Εισερχόμενη κλήσηΕξερχόμενη κλήση
call-startedringing-indialing
call-state-changedactiveringing-out, μετά active
call-endedendedended

Τα πεδία​

Κάθε τιμή είναι συμβολοσειρά, μαζί με τους αριθμούς και τις χρονοσημάνσεις: "duration_s": "42". Μια στιγμή που δεν είναι γνωστή είναι κενή συμβολοσειρά. Τα ονόματα ακολουθούν μία σύμβαση: _id είναι αναγνωριστικό, _ts είναι χρόνος Unix σε χιλιοστά του δευτερολέπτου (UTC), _s είναι διάρκεια σε δευτερόλεπτα — όπως και στο REST API, όπου οι τιμές είναι αριθμοί JSON.

ΠεδίοΣημασία
eventcall-started, call-state-changed ή call-ended.
idΗ κλήση: το ίδιο UUID όπως στα GET /calls και /calls/{id}/…, και το ίδιο σε κάθε συμβάν της κλήσης.
seance_idΗ συνομιλία στην οποία ανήκει η κλήση· δείτε παρακάτω.
directionin ή out.
stateΟι ίδιες τιμές όπως στο GET /calls: dialing, ringing-out, ringing-in, active, hold (σε αναμονή από αυτό το τηλέφωνο), onhold (σε αναμονή από τον συνομιλητή), conference ή ended.
numberΟ αριθμός του συνομιλητή. Αντιστοιχίστε τις εγγραφές του CRM σας με αυτό το πεδίο.
nameΤο όνομα του συνομιλητή, από τις Επαφές· μπορεί να είναι κενό και να συμπληρωθεί αργότερα στην κλήση, όπως στην παραπάνω εξερχόμενη κλήση.
uriΗ διεύθυνση SIP του συνομιλητή.
dialedΤα ψηφία που πληκτρολογήθηκαν, για μια εξερχόμενη κλήση· κενό για μια εισερχόμενη.
account, account_idΗ γραμμή στην οποία βρίσκεται η κλήση: username@server, και το αναγνωριστικό από το GET /accounts.
event_tsΠότε συνέβη το συμβάν.
callstart_tsΠότε το τηλέφωνο έμαθε για πρώτη φορά για την κλήση.
callstate_tsΠότε η κλήση μπήκε στην τρέχουσα state.
duration_sΟ χρόνος ομιλίας σε δευτερόλεπτα, από την απάντηση έως τον τερματισμό. Ορίζεται στο call-ended για μια κλήση που απαντήθηκε· 0 σε κάθε άλλη περίπτωση.
reasonΠώς τελείωσε η κλήση: local-hangup, remote-hangup, busy, no-answer, cancelled…· none μέχρι τότε.
answered_byno αν απάντησε στην κλήση άνθρωπος· διαφορετικά τι απάντησε.

Μία συνομιλία μέσα από μεταφορές​

Το seance_id ομαδοποιεί τις κλήσεις που αποτελούν μία συνομιλία. Μια κλήση που γίνεται ή λαμβάνεται από την αρχή ξεκινά μια νέα. Μια κλήση που δημιουργείται από μεταφορά, μια κλήση που αντικαθιστά μια άλλη, μια διαβούλευση για μια κλήση και κάθε κλήση που ενώνεται σε διάσκεψη κρατούν το seance_id της κλήσης από την οποία προήλθαν.

Μεταξύ τηλεφώνων ταξιδεύει στην κεφαλίδα SIP X-Seance-Id: όταν μια κλήση μεταφέρεται σε έναν συνάδελφο που επίσης χρησιμοποιεί το AI Softphone, και το τηλεφωνικό κέντρο προωθεί την κεφαλίδα, και οι δύο σταθμοί εργασίας αναφέρουν το ίδιο seance_id.

GET αντί για POST​

Το GET είναι για παραλήπτες που δεν μπορούν να δεχτούν σώμα αιτήματος, όπως ένα παλαιότερο CRM ή μια γέφυρα σεναρίων. Τα ίδια πεδία στέλνονται τότε ως παράμετροι ερωτήματος.

Με το GET η διεύθυνση μπορεί να είναι πρότυπο: κάθε [field] αντικαθίσταται από την τιμή εκείνου του πεδίου, με κωδικοποίηση ποσοστού. Για παράδειγμα:

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

Τα σύμβολα κράτησης θέσης χρησιμοποιούν τα παραπάνω ονόματα πεδίων. Τα πρότυπα που αποθηκεύτηκαν με τα παλαιότερα ονόματα ([accountId], [at], [duration], [answeredBy], [seanceId]) εξακολουθούν να λειτουργούν.

Πώς παραδίδονται τα συμβάντα​

ΣυμπεριφοράΤι σημαίνει για εσάς
Τα συμβάντα μπαίνουν σε ουρά, δεν στέλνονται από την ίδια την κλήσηΈνας αργός παραλήπτης δεν καθυστερεί ποτέ το κουδούνισμα, τις κλήσεις ή τις μεταφορές.
Μια γεμάτη ουρά απορρίπτει συμβάνταΑν ο παραλήπτης σας σταματήσει να απαντά, τα συμβάντα χάνονται αλλά το τηλέφωνο συνεχίζει να λειτουργεί. Παρακολουθείτε το webhooks_dropped_total.
Οι παραδόσεις που απορρίφθηκαν ή δεν έφτασαν μετρώνταιΑν το webhooks_failed_total ανεβαίνει ενώ το webhooks_delivered_total μένει σταθερό, το πρόβλημα είναι στον παραλήπτη.
Τα συμβάντα φτάνουν με σειράΈναρξη κλήσης, μετά οι αλλαγές κατάστασης, μετά τέλος κλήσης. Για να ταξινομήσετε τα συμβάντα που έχετε αποθηκεύσει, χρησιμοποιήστε το callstate_ts, όχι την ώρα που έφτασαν.
Τουλάχιστον μία φοράΤο ίδιο συμβάν μπορεί να έρθει δύο φορές. Τα id, event και callstate_ts μαζί ταυτοποιούν ένα συμβάν: φροντίστε ο χειριστής σας να παραλείπει ένα που έχει ήδη δει.

Λήψη των συμβάντων​

Ο ένας κανόνας για έναν παραλήπτη: απαντήστε αμέσως 200 και κάντε τη δουλειά μετά. Ένας αργός παραλήπτης δεν επιβραδύνει το τηλέφωνο, αλλά γεμίζει την ουρά, και μια γεμάτη ουρά απορρίπτει συμβάντα.

Για παράδειγμα, σε Node.js με Express:

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

Για να καταγράψετε την έκβαση μιας κλήσης — απαντήθηκε, αναπάντητη, απορρίφθηκε — πάρτε την καταχώριση με το ίδιο seance_id και number από το GET /history?limit=20 του REST API. Όταν η υπηρεσία σας ξεκινήσει ξανά μετά από μια παύση, διαβάστε το GET /history?limit=200 και αποθηκεύστε ό,τι χάσατε: webhooks για τον πραγματικό χρόνο, το ιστορικό για να συμπληρώσετε τα κενά.

Για να δείτε τα αιτήματα πριν είναι έτοιμο το CRM, στρέψτε τη Διεύθυνση σε έναν διαδικτυακό επιθεωρητή αιτημάτων και πατήστε Στείλε δοκιμαστικό συμβάν.

Όταν δεν φτάνει τίποτα​

ΣύμπτωμαΤι να ελέγξετε
Δεν φτάνει κανένα webhookΠατήστε Στείλε δοκιμαστικό συμβάν. Αν φτάσει, τα συμβάντα που χρειάζεστε δεν είναι σημειωμένα· αν όχι, η διεύθυνση είναι λάθος ή δεν είναι προσβάσιμη από τον σταθμό εργασίας.
Το webhooks_failed_total συνεχίζει να ανεβαίνειΟ παραλήπτης απορρίπτει τα αιτήματα ή δεν είναι προσβάσιμος. Ελέγξτε το αρχείο καταγραφής του και αν απαντά σε ένα απλό αίτημα από τον σταθμό εργασίας.
Το webhooks_dropped_total είναι πάνω από το μηδένΟ παραλήπτης ήταν πολύ αργός για πολύ καιρό και η ουρά γέμισε. Απαντήστε πρώτα 200 και μετά επεξεργαστείτε.
Το ίδιο συμβάν δύο φορέςΑναμενόμενο με παράδοση «τουλάχιστον μία φορά». Αντιμετωπίστε τα συμβάντα με τα ίδια id, event και callstate_ts ως ένα.