Οι προσαρμοσμένες ενσωματώσεις API (Custom API integrations) επιτρέπουν στο chatbot σας να ζητά ζωντανές πληροφορίες από το ERP, την αποθήκη, το CRM ή άλλη υπηρεσία σας. Μπορούν επίσης να πραγματοποιούν αλλαγές, όπως η δημιουργία ενός ραντεβού. Μια ενσωμάτωση (integration) αποθηκεύει τη βασική διεύθυνση URL (base URL) - κάθε λειτουργία (operation) ορίζει ένα κλήσιμο αίτημα. Στη συνέχεια, συνδέετε τις επιλεγμένες λειτουργίες σε ένα chatbot ως ενέργειες AI (AI actions).
Πριν ξεκινήσετε
Βεβαιωθείτε ότι ο λογαριασμός σας περιλαμβάνει προσαρμοσμένες ενσωματώσεις API. Χρειάζεστε το URL του τελικού σημείου (endpoint), τη μέθοδο HTTP, τα ονόματα και τους τύπους παραμέτρων, τις απαιτήσεις ταυτοποίησης και ένα παράδειγμα απόκρισης. Το τελικό σημείο πρέπει να είναι προσβάσιμο από τους διακομιστές του ChatLab - το localhost στον υπολογιστή σας δεν αποτελεί τελικό σημείο παραγωγής.
Χρησιμοποιήστε HTTPS και μια δοκιμαστική υπηρεσία ή δοκιμαστικές εγγραφές για τη ρύθμιση. Ένα δοκιμαστικό αίτημα καλεί πραγματικά το τελικό σημείο, επομένως ένα αίτημα POST, PATCH ή DELETE μπορεί να αλλάξει εξωτερικά δεδομένα. Φροντίστε οι λειτουργίες να είναι ασφαλείς για επανάληψη όπου είναι δυνατόν.
1. Δημιουργία ενσωμάτωσης
- Ανοίξτε το Custom Integrations (Προσαρμοσμένες ενσωματώσεις) στην κύρια πλοήγηση.
- Κάντε κλικ στο + Define API Integration (+ Ορισμός ενσωμάτωσης API).
- Εισαγάγετε το API name (Όνομα API) και το API Base URL (Βασικό URL API), για παράδειγμα
https://api.example.com. - Κάντε κλικ στο Create API Integration (Δημιουργία ενσωμάτωσης API).
- Στην καταχώρισή του στη λίστα, κάντε κλικ στο View (Προβολή) και, στη συνέχεια, στο + Define API Operation (+ Ορισμός λειτουργίας API).
2. Ορισμός της λειτουργίας
Δώστε στη λειτουργία μια αναγνωρίσιμη ετικέτα και ένα αναγνώσιμο από μηχανές Operation name (Όνομα λειτουργίας), όπως getProductDetails. Χρησιμοποιήστε μόνο γράμματα και αριθμούς για το όνομα της λειτουργίας, χωρίς κενά ή κάτω παύλες. Περιγράψτε τι κάνει η λειτουργία και πότε πρέπει να τη χρησιμοποιεί το chatbot.
Εισαγάγετε το σχετικό URI, για παράδειγμα /v1/products/@productId@. Το βασικό URL και το URI αποτελούν τη διεύθυνση του αιτήματος.
Ορισμένα υπάρχοντα στιγμιότυπα οθόνης εμφανίζουν παλαιότερα παραδείγματα ονομάτων ή placeholders με άγκιστρα. Ακολουθήστε την τρέχουσα σύνταξη παρακάτω: ονόματα λειτουργιών όπως getProductDetails και placeholders παραμέτρων που περιβάλλονται από @.
Παράμετροι διαδρομής και ερωτήματος
Κάντε κλικ στο Add path variable (Προσθήκη μεταβλητής διαδρομής) για να ορίσετε το productId. Ορίστε τον τύπο δεδομένων και την πηγή τιμής του και, στη συνέχεια, συμπεριλάβετε το @productId@ στο URI. Οι μεταβλητές διαδρομής είναι υποχρεωτικές και κάθε καθορισμένη μεταβλητή διαδρομής πρέπει να εμφανίζεται στο URI για να μπορέσετε να αποθηκεύσετε ή να δοκιμάσετε.
Χρησιμοποιήστε το Add query parameter (Προσθήκη παραμέτρου ερωτήματος) για παραμέτρους όπως limit ή language που τοποθετούνται μετά το ερωτηματικό του URL. Εισαγάγετε το όνομα που αναμένει το API σας, τον τύπο, την περιγραφή και την πηγή τιμής.
Οι διαθέσιμες πηγές τιμών περιλαμβάνουν:
- Provided by user or chatbot: το μοντέλο παρέχει μια τιμή από τη συνομιλία. Εξηγήστε την αναμενόμενη μορφή και επισημάνετε κατάλληλα τις απαιτούμενες τιμές.
- Constant: μια τιμή ρυθμισμένη στη λειτουργία, όπως ένα σταθερό αναγνωριστικό λογαριασμού ή ένα περιορισμένο διαπιστευτήριο API.
- Random value: μια τιμή που δημιουργείται αυτόματα.
- Client context: μια τιμή που μεταβιβάζεται από τον ιστότοπο υποδοχής, όπου διατίθεται για τον λογαριασμό σας. Δείτε το Chat API.
Οι βαθμωτοί τύποι περιλαμβάνουν string, integer, double και boolean. Οι παράμετροι σώματος υποστηρίζουν επίσης πίνακες string και integer.
3. Διαμόρφωση της μεθόδου και του σώματος
Επιλέξτε GET, POST, PUT, PATCH ή DELETE ανάλογα με το τελικό σημείο σας. Για μεθόδους εκτός της GET, ο επεξεργαστής προσφέρει περιεχόμενο αιτήματος τύπου raw ή form-data.
Για ένα σώμα raw JSON, ορίστε τις παραμέτρους σώματος και εισαγάγετε τα σχετικά placeholders @name@ στο πρότυπο. Προσθέστε την κατάλληλη κεφαλίδα Content-Type που απαιτείται από το τελικό σημείο σας. Για παράδειγμα, με παράμετρο string name και πίνακα string tags:
{
"name": "@name@",
"tags": @tags@
}
Αυτό είναι ένα πρότυπο και όχι τελικό JSON μέχρι την αντικατάσταση των τιμών. Τα placeholders πινάκων δεν πρέπει να περιβάλλονται από εισαγωγικά. Κάθε καθορισμένη παράμετρος σώματος πρέπει να χρησιμοποιείται στο πρότυπο όταν ισχύει ο επεξεργαστής raw body. Ελέγξτε το παραγόμενο αίτημα κατά τη δοκιμή, συμπεριλαμβανομένου κειμένου που περιέχει εισαγωγικά ή ειδικούς χαρακτήρες.
4. Προσθήκη κεφαλίδων ταυτοποίησης
Χρησιμοποιήστε το Add header (Προσθήκη κεφαλίδας) για να ορίσετε τις κεφαλίδες που αναμένει το API. Για ένα διακριτικό φορέα (bearer token), χρησιμοποιήστε το όνομα κεφαλίδας Authorization, την πηγή τιμής Constant και την τιμή Bearer YOUR_RESTRICTED_TOKEN.
Κρατήστε τα μυστικά κλειδιά μακριά από προτροπές (prompts) και διευθύνσεις URL. Αποφύγετε λειτουργίες που επιστρέφουν διακριτικά σύνδεσης στο μοντέλο και βασίζονται σε οδηγίες για την απόκρυψή τους. Προτιμήστε ένα τελικό σημείο ενσωμάτωσης από την πλευρά του διακομιστή (server-side) που διαχειρίζεται τη δική του ταυτοποίηση και εκθέτει μόνο την επιτρεπόμενη λειτουργία.
5. Αποθήκευση και δοκιμή του αιτήματος
- Κάντε κλικ στο Save changes (Αποθήκευση αλλαγών) στον επεξεργαστή λειτουργίας. Σε αντίθεση με τις συνήθεις ρυθμίσεις του chatbot, αυτός ο επεξεργαστής διαθέτει ρητό κουμπί αποθήκευσης.
- Κάντε κλικ στο Test API Operation (Δοκιμή λειτουργίας API). Είναι απενεργοποιημένο όσο οι αλλαγές παραμένουν μη αποθηκευμένες.
- Εισαγάγετε αντιπροσωπευτικές τιμές παραμέτρων. Για εισαγωγές δοκιμής πινάκων, χρησιμοποιήστε τιμές διαχωρισμένες με κόμμα.
- Εκτελέστε τη δοκιμή μόνο σε δεδομένα που έχετε εξουσιοδότηση να διαβάσετε ή να τροποποιήσετε.
- Ελέγξτε τον κωδικό κατάστασης (status code), το σώμα απόκρισης, το URL αιτήματος, τις κεφαλίδες, το σώμα και οποιαδήποτε προειδοποίηση εμφανίζεται στα αποτελέσματα.
- Διορθώστε τα σφάλματα, αποθηκεύστε και επαναλάβετε ανάλογα με τις ανάγκες.
Μην κοινοποιείτε αποτελέσματα δοκιμών που περιέχουν διαπιστευτήρια. Επιστρέψτε εστιασμένα δεδομένα με σελιδοποίηση όπου είναι δυνατόν: οι μεγάλες αποκρίσεις ενδέχεται να περικοπούν πριν φτάσουν στο μοντέλο.
6. Σύνδεση της λειτουργίας σε ένα Chatbot
Ανοίξτε το chatbot σας και, στη συνέχεια, μεταβείτε στο Settings > Actions (Ρυθμίσεις > Ενέργειες). Χρησιμοποιήστε το κουμπί συν για να προσθέσετε μια ενέργεια, βρείτε τη λειτουργία σας στην κατηγορία προσαρμοσμένων API και συνδέστε την ή ενεργοποιήστε την. Η δημιουργία μιας ενσωμάτωσης σε επίπεδο λογαριασμού από μόνη της δεν καθιστά κάθε λειτουργία διαθέσιμη σε κάθε chatbot.
Ελέγξτε τις οδηγίες της ενέργειας και τις διαθέσιμες ρυθμίσεις ασφαλείας και, στη συνέχεια, περιμένετε την κατάσταση αποθήκευσης. Δείτε το AI actions για τον επεξεργαστή ενεργειών.
7. Επεξήγηση του χρόνου χρήσης
Ανοίξτε το Settings > Role & Behavior (Ρυθμίσεις > Ρόλος και συμπεριφορά).
Εάν χρησιμοποιείτε προσαρμοσμένες οδηγίες ρόλου, επιλέξτε το Custom Role Definition (Προσαρμοσμένος ορισμός ρόλου) και προσθέστε έναν ακριβή κανόνα, για παράδειγμα: "Όταν ο επισκέπτης ρωτά εάν ένα προϊόν είναι διαθέσιμο, καλέστε το getProductDetails με το αναγνωριστικό προϊόντος του. Αναφέρετε την επιστρεφόμενη διαθεσιμότητα. Εάν η αναζήτηση αποτύχει, εξηγήστε ότι δεν ήταν δυνατός ο έλεγχος της διαθεσιμότητας."
Διατηρήστε τις υπόλοιπες χρήσιμες οδηγίες του chatbot. Περιμένετε την κατάσταση αποθήκευσης και, στη συνέχεια, χρησιμοποιήστε την προεπισκόπηση στο Overview (Επισκόπηση) για να δοκιμάσετε ρεαλιστικές ερωτήσεις, ελλείπουσες παραμέτρους, σφάλματα και μη εξουσιοδοτημένα αιτήματα. Οι συνομιλίες προεπισκόπησης μπορούν να εκτελέσουν πραγματικές λειτουργίες.
Η κλήση από την τεχνητή νοημοσύνη δεν είναι εγγυημένη ούτε απαραίτητα μοναδική ανά αίτημα. Δοκιμάστε με το μοντέλο που έχει επιλεγεί για το chatbot σας - μην υποθέτετε ότι το όνομα του μοντέλου από μόνο του εγγυάται τη σωστή χρήση εργαλείων.
Ασφάλεια και αντιμετώπιση προβλημάτων
Το τελικό σημείο σας πρέπει να ταυτοποιεί τα αιτήματα και να εξουσιοδοτεί την πρόσβαση κάθε χρήστη πριν επιστρέψει ευαίσθητες πληροφορίες ή εκτελέσει μια αλλαγή. Ένα αναγνωριστικό πελάτη (client ID), διεύθυνση email, αριθμός παραγγελίας ή πεδίο περιβάλλοντος που παρέχεται από το πρόγραμμα περιήγησης δεν αποτελεί επαρκή απόδειξη ταυτότητας. Εάν διαβιβάζετε ένα διακριτικό ανά χρήστη μέσω του περιβάλλοντος πελάτη (client context), ο διακομιστής σας πρέπει να το επικυρώσει.
Επιστρέψτε μόνο τα πεδία που χρειάζεται το chatbot, όπως την κατάσταση παραγγελίας αντί για ένα πλήρες προφίλ πελάτη. Οι οδηγίες στις προτροπές μπορούν να καθοδηγήσουν τη διατύπωση, αλλά δεν μπορούν να εγγυηθούν ότι τα ευαίσθητα δεδομένα που επιστρέφονται στο μοντέλο θα παραμείνουν κρυφά.
Εάν το αίτημα εκτελείται επιτυχώς στον επεξεργαστή δοκιμών αλλά όχι σε μια συνομιλία, ελέγξτε τη συνδεδεμένη ενέργεια, την κατάσταση ενεργοποίησής της, τις οδηγίες, τις απαιτούμενες παραμέτρους και το διαθέσιμο περιβάλλον. Εάν αποτύχουν και τα δύο, ελέγξτε το URL, τη μέθοδο HTTP, την ταυτοποίηση, το παραγόμενο σώμα και τα αρχεία καταγραφής του τελικού σημείου σας. Αποφύγετε τις επανειλημμένες προσπάθειες μιας λειτουργίας εγγραφής μέχρι να βεβαιωθείτε εάν το προηγούμενο αίτημα ολοκληρώθηκε επιτυχώς.