Webhooks
Ένα webhook είναι ένα αίτημα που στέλνει το τηλέφωνο σε μια διεύθυνση της επιλογής σας κάθε φορά που συμβαίνει κάτι σε μια κλήση. Έτσι ένα CRM μπορεί να ανοίξει την καρτέλα του πελάτη πριν από το δεύτερο κουδούνισμα, να καταγράψει μια κλήση όταν τελειώσει ή να ανάψει μια λυχνία σε έναν πίνακα ενδείξεων. Ένα webhook δεν χρειάζεται κανόνες τείχους προστασίας για εισερχόμενη κίνηση: το τηλέφωνο συνδέεται προς εσάς. Επειδή τα αιτήματα στέλνονται από τον σταθμό εργασίας, η διεύθυνση χρειάζεται να είναι προσβάσιμη μόνο από αυτόν τον υπολογιστή — μια εσωτερική http://crm.local/calls λειτουργεί εξίσου καλά με μια δημόσια διεύθυνση HTTPS.
Τα webhooks είναι ανενεργά μετά την εγκατάσταση, μέχρι να τα ενεργοποιήσετε. Λειτουργούν μαζί με το τοπικό REST API: ένα συμβάν λέει ότι κάτι άλλαξε, το API δίνει τις τρέχουσες λεπτομέρειες.
Ενεργοποίηση
Ανοίξτε τις Ρυθμίσεις → Ενσωμάτωση. Τα Webhooks είναι η πρώτη ενότητα της καρτέλας.
- Σημειώστε το Ενημέρωσε άλλο σύστημα για τις κλήσεις. Στέλνεται ένα αίτημα για κάθε συμβάν που σημειώνετε παρακάτω.
- Εισαγάγετε τη Διεύθυνση που θα λαμβάνει τα συμβάντα, για παράδειγμα
https://crm.local/calls. - Επιλέξτε τη Μέθοδο: POST (η προεπιλογή) ή GET.
- Στα Συμβάντα σημειώστε τι θα στέλνεται: Νέα κλήση, Τέλος κλήσης, Αλλαγή κατάστασης κλήσης.
- Προαιρετικά, στην Πιστοποίηση, ορίστε μια κεφαλίδα που μπορεί να ελέγξει ο παραλήπτης σας: ένα Όνομα κεφαλίδας (προτείνεται το
Authorization) και μια Τιμή κεφαλίδας. Η τιμή φυλάσσεται στη θυρίδα κλειδιών του υπολογιστή, ποτέ σε αρχείο ρυθμίσεων· μόλις αποθηκευτεί, το πεδίο δείχνει Αποθηκευμένο — πληκτρολογήστε για αντικατάσταση. - Πατήστε Στείλε δοκιμαστικό συμβάν για να δείτε ότι φτάνει. Στέλνει ένα συμβάν για μια κλήση που δεν έγινε ποτέ, με τις ίδιες κεφαλίδες όπως ένα πραγματικό. Καταγράψτε το ακατέργαστο αίτημα και χτίστε τον παραλήπτη σας με βάση αυτό που πραγματικά στέλνει η έκδοσή σας.
Το μέρος του προγράμματος που στέλνει τα αιτήματα είναι η μονάδα Ενσωμάτωση· μπορεί να απενεργοποιηθεί στις Μονάδες.
Τα συμβάντα
| Σημειώνεται ως | Συμβάν | Στέλνεται όταν |
|---|---|---|
| Νέα κλήση | 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-started | ringing-in | dialing |
call-state-changed | active | ringing-out, μετά active |
call-ended | ended | ended |
Τα πεδία
Κάθε τιμή είναι συμβολοσειρά, μαζί με τους αριθμούς και τις χρονοσημάνσεις: "duration_s": "42". Μια στιγμή που δεν είναι γνωστή είναι κενή συμβολοσειρά. Τα ονόματα ακολουθούν μία σύμβαση: _id είναι αναγνωριστικό, _ts είναι χρόνος Unix σε χιλιοστά του δευτερολέπτου (UTC), _s είναι διάρκεια σε δευτερόλεπτα — όπως και στο REST API, όπου οι τιμές είναι αριθμοί JSON.
| Πεδίο | Σημασία |
|---|---|
event | call-started, call-state-changed ή call-ended. |
id | Η κλήση: το ίδιο UUID όπως στα GET /calls και /calls/{id}/…, και το ίδιο σε κάθε συμβάν της κλήσης. |
seance_id | Η συνομιλία στην οποία ανήκει η κλήση· δείτε παρακάτω. |
direction | in ή 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_by | no αν απάντησε στην κλήση άνθρωπος· διαφορετικά τι απάντησε. |
Μία συνομιλία μέσα από μεταφορές
Το 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 ως ένα. |