Σύνδεση Προσαρμοσμένων Στοιχείων για προγραμματιστές

Αυτή η σελίδα απευθύνεται σε προγραμματιστές που συνδέουν το backend μιας εταιρείας με το Skava. Η δημιουργία και η έκδοση ενός στοιχείου API καλύπτονται στη σελίδα Προσαρμοσμένα Στοιχεία: Διεπαφές API. Εδώ καλύπτουμε όλα όσα πρέπει να συμβούν στο άλλο άκρο της γραμμής.

Η ιδέα σε μία φράση: Το Skava δεν γνωρίζει τον τομέα σας. Γνωρίζει ακριβώς μία μορφή, την κάρτα. Εσείς αποφασίζετε τι γράφει, εμείς ελέγχουμε μόνο το σχήμα, το μέγεθος και την ασφάλεια. Η παραγγελία υλικού είναι ένα παράδειγμα. Η επόμενη εταιρεία συλλέγει ανατροφοδότηση χρηστών, η επόμενη καταχωρεί φωτογραφία chantier στα αρχεία της.

Η ροή σε μια ματιά

1. Ένας διαχειριστής εταιρείας δημιουργεί ένα στοιχείο API στο Skava: ένα φόρμα μαζί με τη διεύθυνση, τη μέθοδο και το token του backend σας.
2. Κάποιος στο τσάτ συμπληρώνει το έντυπο και το στέλνει.
3. Το Skava καλεί το backend σας και στέλνει τις συμπληρωμένες τιμές ως JSON.
4. Η απάντησή σας γίνεται η κάρτα στο τσάτ.
5. Επιλογικά, αναφέρετε νέες καταστάσεις αργότερα μέσω του callback. Κάθε αναφορά γίνεται άλλη κάρτα, ενώ η προηγούμενη παραμένει.

Απαιτήσεις για το backend σας

• HTTPS. Μόνο https://, χωρίς http, χωρίς διαπιστευτήρια στη διεύθυνση, το πολύ 2000 χαρακτήρες.
• Δημόσια προσβάσιμο. Ο host πρέπει να αντιστοιχεί αποκλειστικά σε δημόσιες IP. Το localhost, τα ιδιωτικά δίκτυα, τα link-local και τα cloud metadata απορρίπτονται, και αυτό ελέγχεται σε κάθε κλήση.
• Σταθερή διεύθυνση. Η Skava επιλύει τον host μία φορά και κλειδώνει τη σύνδεση σε αυτή την IP. Μια αλλαγή DNS κατά τη διάρκεια της κλήσης δεν έχει επίδραση.
• Χωρίς ανακατευθύνσεις. Ένα 301 προς τη «σωστή» διεύθυνση μετράει ως αποτυχία. Εισάγετε την τελική διεύθυνση αμέσως.
• Χρόνος απόκρισης. Το timeout ρυθμίζεται ανά στοιχείο και έχει σκληρό όριο 30 δευτερολέπτων. Αν χρειάζεστε περισσότερο χρόνο, απαντήστε αμέσως και αναφέρετε το αποτέλεσμα αργότερα μέσω του callback.
• Μέγεθος απόκρισης. Το Skava διαβάζει το πολύ 256 KiB.
• Content-Type. Το σώμα αναλύεται μόνο με application/json.

Το αίτημα που φτάνει σε εσάς

Η μέθοδος είναι GET, POST, PUT ή PATCH, ανάλογα με το στοιχείο. Με POST, PUT και PATCH οι τιμές φτάνουν ως σώμα JSON, ενώ με GET ως παράμετροι ερωτήματος.

Η πιστοποίηση είναι ένα κεφαλαίο, του οποίου το όνομα και το πρόθεμα τιμής ρυθμίζονται στο στοιχείο, συνήθως Authorization με πρόθεμα Bearer . Το token αποθηκεύεται κρυπτογραφημένο από την πλευρά μας. Τα κεφαλαιώδη host, content-length, content-type, cookie και accept-encoding δεν μπορούν να οριστούν.

Το σώμα είναι ένα επίπεδο αντικείμενο. Τα κλειδιά επιλέγονται από όποιον δημιούργησε το στοιχείο. Η ενσωμάτωση εμφανίζεται μόνο όπου έχουν προστεθεί πίνακας ή επιλογέας προϊόντος:

{"artikelnummer": "5100110", "menge": 20, "note": "Please deliver in the morning", "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "project": "Spitalstrasse 11", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/…", "callback_token": "…"}

Τρία κλειδιά προέρχονται πάντα από εμάς, οπότε μην τα χρησιμοποιείτε εσείς:

• locale: ο κωδικός γλώσσας του χρήστη. Απαντήστε σε αυτή τη γλώσσα. Δεν μεταφράζουμε εμείς τα κείμενά σας.
• callback_url και callback_token: η αναδρομική κλήση για αυτή τη μία αλληλεπίδραση, δείτε παρακάτω. Υπάρχουν μόνο όταν η κλήση προέρχεται από μια συνομιλία.

Πεδία ngữ cảnh όπως όνομα, εταιρεία, έργο ή υποσυνομιλία συμπληρώνονται από τον ίδιο τον διακομιστή, με βάση το κανάλι στο οποίο εκτελέστηκε το στοιχείο. Ένας πελάτης που έχει τροποποιηθεί δεν μπορεί να δηλώσει διαφορετικό όνομα έργου εκεί.

Η απάντηση: το μορφότυπο κάρτας

Απαντήστε με 2xx και ένα αντικείμενο card. Αυτό ακριβώς γίνεται η κάρτα στη συνομιλία:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

• v (υποχρεωτικό): ο ακέραιος 1. Ως κείμενο ("1") απορρίπτεται. Χωρίς αυτό, η απάντηση δεν μετράει ως κάρτα και εφαρμόζεται ο χάρτης απάντησης που έχει οριστεί στο στοιχείο.
• title: ο τίτλος της κάρτας.
• state: μόνο χρώμα και τόνο εικονιδίου, ένα από ok, pending, warn, error. Μια άγνωστη τιμή επιστρέφει στο ok και λαμβάνετε μια ένδειξη.
• status_text: ελεύθερο κείμενο που δεν ερμηνεύουμε. Βρίσκεται στην κορυφή της κάρτας και εμφανίζεται επίσης στη λίστα συνομιλιών και σε μια ειδοποίηση push.
• fields: μια λίστα με label και value. Μέχρι 20 εγγραφές, label 80 χαρακτήρες, value 200, title και status_text 120 ο καθένας. Οι τιμές που είναι πολύ μεγάλες συμπτύσσονται, δεν απορρίπτονται: μια παραγγελία δεν πρέπει να αποτυγχάνει λόγω λεπτομέρειας.
• icon: δείτε παρακάτω.

Τι κάνει η Skava στα κείμενά σας πριν φτάσουν στη συνομιλία: οι αλλαγές γραμμής και οι χαρακτήρες ελέγχου αφαιρούνται (ένας χαρακτήρας από δεξιά προς τα αριστερά θα μπορούσε αλλιώς να αντιστρέψει την εμφάνιση ενός ποσού), τα backticks αντικαθίστανται και ό,τι ξεκινά με [SKAVA: εξουδετερώνεται. Το τελευταίο αποτρέπει μια τιμή κάρτας να διαβαστεί ως διαφορετικό στοιχείο συνομιλίας, για παράδειγμα ένα αίτημα πληρωμής.

Σύνδεσμοι σε πεδία, HTML και εικόνες δεν μπορούν να οριστούν. Μια συνομιλία είναι ένα περιβάλλον εμπιστοσύνης, και μια κλικαρίσιμη διεύθυνση από ένα εξωτερικό backend θα ήταν πρόσκληση να ξαναχτίσετε μια σελίδα σύνδεσης.

Τα εισοδήματα του χρήστη ανήκουν στον διακομιστή: εμφανίζονται στην πρώτη κάρτα και δεν μπορείτε να τα αντικαταστήσετε. Στη συνομιλία αποτελούν το αρχείο όσων υποβλήθηκαν πραγματικά.

Εικονίδια

Με το icon η κάρτα αποκτά το δικό της σήμα στο κεφάλαιο. Δύο τρόποι:

Ένα όνομα από το ενσωματωμένο σετ: package, package-check, package-open, box, boxes, truck, forklift, warehouse, settings, cog, gauge, wrench, hammer, drill, hard-hat, ruler, paint-roller, construction, clipboard-check, receipt, file-text, camera, clock, calendar-clock, circle-check, circle-alert, triangle-alert, send, mail-check, shopping-cart, credit-card, map-pin.

Ή το δικό σας SVG ως συμβολοσειρά. Από αυτό η Skava λαμβάνει μόνο τη γεωμετρία (path, circle, ellipse, rect, line, polyline, polygon με τα αριθμητικά τους χαρακτηριστικά) και δημιουργεί τη δική της εικόνα. Τα σενάρια, τα στυλ, οι εξωτερικές αναφορές, το foreignObject και τα χαρακτηριστικά συμβάντων απορρίπτονται. Ένα doctype ή μια οντότητα οδηγεί σε απόρριψη. Το αρχείο μπορεί να έχει μέγεθος έως 8 KiB και να περιέχει έως 16 σχήματα. Το χρώμα, το πάχος της γραμμής και το μέγεθος ορίζονται από τη Skava, ώστε ένα εικονίδιο να μην μπορεί να παραπλανήσει ως έλεγχος. Εργαστείτε σε πλέγμα 24 επί 24.

Χωρίς icon παραμένει το προεπιλεγμένο σύμβολο.

Η αναδρομική κλήση: αναφορά μετέπειτα καταστάσεων

Η κλήση περιλαμβάνει callback_url και callback_token. Χρησιμοποιήστε τα για να αναφέρετε νέες καταστάσεις αργότερα:

POST <callback_url> με Authorization: Bearer <callback_token> και Content-Type: application/json, σώμα έως 32 KiB:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}, "seq": 3, "final": false}

Πέρα από την κάρτα υπάρχουν τρεις προαιρετικές τιμές:

• seq: ο δικός σας μετρητής. Ένα αναφορά με μικρότερη ή ίση τιμή απορρίπτεται, ώστε δύο αναφορές να μην ξεπεράσουν η μία την άλλη. Χωρίς seq, επικρατεί η τελευταία που φτάνει.
• final: κλείνει την αλληλεπίδραση. Το token γίνεται άκυρο και δεν εμφανίζονται περαιτέρω κάρτες. Επιτρέπεται επίσης στην πρώτη απάντηση, για ροές χωρίς επόμενα βήματα.
• notify: ορίστε το σε false για να δημοσιευτεί η κάρτα σιωπηλά, χωρίς αριθμό μη αναγνωσμένων και χωρίς ειδοποίηση. Για ενδιάμεσα βήματα που δεν πρέπει να ξυπνήσουν κανέναν. Χωρίς αυτό, η κάρτα είναι ένα απόλυτα κανονικό μήνυμα.

Κάθε αναφορά γίνεται η δική της κάρτα στο chat, η προηγούμενη παραμένει. Έτσι είναι αναγνωρίσιμο ποια κατάσταση αναφέρθηκε. Από αυτό προκύπτει μια σύσταση: στέλνετε μόνο ό,τι άλλαξε. Μια κάρτα που επαναλαμβάνει αριθμό παραγγελίας, στοιχεία και σύνολο για τέταρτη φορά είναι απλώς θόρυβος για τον αναγνώστη.

Δύο όρια: η ίδια αναφορά δύο φορές δεν παράγει δεύτερη κάρτα, και μια αλληλεπίδραση μπορεί να δημοσιεύσει το πολύ 50 κάρτες. Μια αλληλεπίδραση δέχεται αναφορές για 90 ημέρες.

Απαντήσεις στις οποίες πρέπει να αντιδράσεις

• 200 με {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Διάβασε τα hints: δηλώνουν τι συντομεύτηκε ή τι αφαιρέθηκε.
• 401: λάθος token ή interaction id. Μην επαναλαμβάνεις την προσπάθεια.
• 410: η interaction έκλεισε ή έληξε. Μην επαναλαμβάνεις την προσπάθεια.
• 422: η κάρτα δεν είναι διαθέσιμη, με hints ως αιτία. Διόρθωσέ την πρώτα.
• 400 σφάλμα JSON, 413 πολύ μεγάλο μέγεθος, 429 υπερβολικές αιτήσεις (επανάληψη με καθυστέρηση), 500 σφάλμα από εμάς, επανάληψη αργότερα.

Παράδειγμα 1: παραγγελία με ιστορικό κατάστασης

Βήμα 1, η αίτηση στο backend σας:

POST https://api.example.com/v1/orders
Authorization: Bearer <your token>
{"artikelnummer": "5100110", "menge": 20, "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/1111…", "callback_token": "secret"}

Βήμα 2, η άμεση απάντησή σας:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

Η συνομιλία εμφανίζει πλέον μια κάρτα με εικονίδιο πακέτου, την κατάσταση και τις εισαγωγές του χρήστη.

Βήμα 3, αργότερα κατά την επιλογή:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Being picked", "icon": "cog", "fields": []}, "seq": 2, "notify": false}

Μια ήσυχη δεύτερη κάρτα χωρίς πεδία: άλλαξε μόνο η κατάσταση.

Βήμα 4, κατά την αποστολή:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}, {"label": "Carrier", "value": "DPD"}]}, "seq": 3}

Αυτή η κάρτα μπορεί να ξυπνήσει κάποιον, γι' αυτό δεν υπάρχει notify: false.

Βήμα 5, κατά την παράδοση:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "ok", "status_text": "Delivered", "icon": "package-check", "fields": []}, "seq": 4, "final": true}

Με το final η αλληλεπίδραση κλείνει και το token δεν λειτουργεί πλέον.

Παράδειγμα 2: μια ενέργεια χωρίς επόμενα βήματα

Δεν κάθε ροή έχει ιστορικό. Ένα στοιχείο με ένα μόνο πεδίο που παραδίδει κάτι στο σύστημά σας χρειάζεται μόνο μία απάντηση:

{"card": {"v": 1, "title": "Filed", "state": "ok", "status_text": "Stored under project 4711", "icon": "clipboard-check", "fields": [{"label": "Case", "value": "4711"}]}, "final": true}

Εδώ έχει σημασία το final: true: αλλιώς η αλληλεπίδραση θα παρέμενε ανοιχτή για 90 ημέρες με έγκυρο token, παρόλο που δεν θα αναφέρετε ποτέ ξανά κάτι.

Επιλογέας προϊόντων από τον κατάλογο

Μόλις η εταιρεία ανεβάσει τον κατάλογο προϊόντων της, το στοιχείο μπορεί να περιλαμβάνει το μπλοκ επιλογέα προϊόντων. Ο χρήστης δημιουργεί ένα καλάθι από αυτό, και εσείς το λαμβάνετε ως λίστα υπό το κλειδί που επέλεξε όποιος δημιούργησε το στοιχείο:

{"items": [{"artikelnummer": "5100110", "menge": 20}, {"artikelnummer": "5100111", "menge": 2}], "note": "…"}

Επειδή το κλειδί είναι ελεύθερο, αναζητήστε την πρώτη λίστα με αυτή τη δομή αντί για ένα σταθερό όνομα. Πριν από την αποστολή, το Skava ελέγχει ότι κάθε αριθμός υπάρχει πραγματικά στον κατάλογο της εταιρείας, με μέγιστο 50 στοιχεία. Στην κάρτα, τα στοιχεία εμφανίζονται ως λίστα με εικόνα προϊόντος, όνομα και ποσότητα.

Δοκιμές

• Η εντολή Ping στον επεξεργαστή στοιχείων στέλνει ένα απλό HEAD χωρίς token και χωρίς δεδομένα. Απαντήστε με οτιδήποτε. Κάθε απάντηση HTTP μετράει ως προσβάσιμο.
• Η δοκιμαστική αίτηση εκτελεί μια πραγματική κλήση με τιμές παραδείγματος, ακόμα και ενώ το στοιχείο είναι ακόμα προσχέδιο, και εμφανίζει την αίτηση, την απάντηση και τα μηνύματα του ελεγκτή κάρτας.
• Προεπισκόπηση στον γειτονικό καρτέλα: επικολλήστε το JSON της απάντησης, ελέγξτε και θα δείτε την τελική κάρτα μαζί με τις υποδείξεις. Ο έλεγχος γίνεται στον διακομιστή με τον ίδιο κώδικα που χρησιμοποιείται σε παραγωγή.
• Παράδειγμα διακομιστή: ένας πλήρης πάροχος παραδείγματος εκτελείται στο api.skava.io και χρησιμοποιεί όλα τα παραπάνω. Ο κώδικας του βρίσκεται στο αποθετήριο στο example_order_server/, περίπου 600 γραμμές καθαρού standard library, σχεδιασμένος για αντιγραφή.

Τι άλλο πρέπει να γνωρίζετε

• Η κάρτα είναι ένα τελικά κανονικό μήνυμα συνομιλίας. Εμφανίζεται στην αναζήτηση, μπορεί να παραχθεί και παραμένει στο ιστορικό.
• Στέλνεται από τον αποστολέα συστήματος, όχι από λογαριασμό της εταιρείας σας. Εμφανίζεται ακόμα και στην πλευρά όποιου εκτέλεσε το στοιχείο, και το ποιο σύστημα γράφει αναφέρεται στον τίτλο.
• Ποιος μπορεί να το εκτελεί ορίζεται στο στοιχείο: μόνο μέλη της εταιρείας ή και εξωτερικοί που μοιράζονται ένα chat μαζί του. Όταν η εταιρεία σας αποχωρεί από το chat, η άδεια λήγει αυτόματα.
• Ένα στοιχείο API με ληγμένο token είναι ανενεργό: οι τρέχουσες εφαρμογές το κρύβουν στο μενού και μια κλήση που στέλνεται ούτως ή άλλως απορρίπτεται στο server. Ένας διαχειριστής αποθηκεύει ένα νέο token για αυτό, κάτι που λειτουργεί και σε μια δημοσιευμένη διεπαφή.

Σχετικά

Δημιουργία και δημοσίευση: Προσαρμοσμένα Στοιχεία: Διεπαφές API. Συμπληρώσιμα έγγραφα αντί για διεπαφές: Προσαρμοσμένα Στοιχεία: Έγγραφα.