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

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

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

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

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

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

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

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

Η πιστοποίηση είναι ένα header, του οποίου το όνομα και το πρόθεμα της τιμής διαμορφώνονται στο στοιχείο, συνήθως Authorization με το πρόθεμα Bearer . Το token αποθηκεύεται κρυπτογραφημένο από την πλευρά μας. Τα headers 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ữσης όπως όνομα, εταιρεία, έργο ή υποσυζήτηση συμπληρώνονται από τον ίδιο τον διακομιστή, προερχόμενα από το κανάλι στο οποίο εκτελέστηκε το στοιχείο. Ένας παραποιημένος πελάτης δεν μπορεί να ισχυριστεί διαφορετικό όνομα έργου εκεί.

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

Απαντήστε με 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.
• πεδία: μια λίστα με ετικέτα και τιμή. Μέγιστο 20 εγγραφές, ετικέτα 80 χαρακτήρες, τιμή 200, τίτλος και κείμενο_κατάστασης 120 το καθένα. Οι τιμές που είναι πολύ μεγάλες συντομεύονται, δεν απορρίπτονται: μια παραγγελία δεν πρέπει να αποτύχει λόγω μιας λεπτομέρειας.
• εικονίδιο: δείτε παρακάτω.

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

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

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

Εικονίδια

Με το 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 και τα χαρακτηριστικά συμβάντων απορρίπτονται. Ένας τύπος εγγράφου ή μια οντότητα οδηγεί σε απόρριψη. Το αρχείο μπορεί να είναι το πολύ 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 για να δημοσιευθεί η κάρτα διακριτικά, χωρίς αριθμό μη αναγνωσμένων και χωρίς ειδοποίηση. Για ενδιάμεσα βήματα που δεν πρέπει να ξυπνήσουν κανέναν. Χωρίς αυτό, η κάρτα είναι ένα απόλυτα φυσιολογικό μήνυμα.

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

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

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

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

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

Βήμα 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 μετράει ως προσβάσιμο.
• Το Test request εκτελεί μια πραγματική κλήση με δείγματα τιμών, ακόμα και ενώ το στοιχείο είναι ακόμα προσχέδιο, και εμφανίζει το αίτημα, την απάντηση και τα μηνύματα του επικυρωτή κάρτας.
• Το Preview στην καρτέλα δίπλα του: επικολλήστε το JSON της απάντησής σας, ελέγξτε και θα δείτε την ολοκληρωμένη κάρτα μαζί με τις υποδείξεις. Ελέγχεται στον διακομιστή με τον ίδιο κώδικα όπως στην παραγωγή.
• Παράδειγμα διακομιστή: ένας πλήρης παράδειγμα προμηθευτής εκτελείται στο api.skava.io και χρησιμοποιεί όλα τα παραπάνω. Ο πηγαίος κώδικάς του βρίσκεται στο αποθετήριο στο example_order_server/, περίπου 600 γραμμές καθαρού τυπικού βιβλιοθήκης, έτοιμες για αντιγραφή.

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

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

Σχετικά

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