32  Slack bot

Σημείωση

Οι διαχειριστές χώρου εργασίας διαχειρίζονται τα Slack bots από τις Ρυθμίσεις. Εάν η Ενσωμάτωση Slack δεν εμφανίζεται στις Ρυθμίσεις, επιβεβαιώστε ότι είστε διαχειριστής χώρου εργασίας.

Το Slack bot επιτρέπει στα μέλη του χώρου εργασίας να συνομιλούν με Sophea agents μέσα από το Slack. Το bot χρησιμοποιεί το Socket Mode του Slack, επομένως δεν υπάρχει δημόσιο HTTPS endpoint, request URL ή signing secret που να πρέπει να διαμορφωθεί στην πλευρά του Slack. Καταχωρίζετε μία φορά μια εφαρμογή Slack στο api.slack.com, την εγκαθιστάτε στον χώρο εργασίας σας και κατόπιν επικολλάτε ένα Bot Token και ένα App-Level Token στο Nous.

Αυτό το κεφάλαιο καλύπτει ολόκληρη τη διαδικασία: δημιουργία της εφαρμογής Slack με τα scopes που χρειάζεται το Nous, ενεργοποίηση του Socket Mode και έκδοση App-Level Token, εγκατάσταση της εφαρμογής, προσθήκη του bot στο Nous στη διαδρομή /app/admin/bots/slack, δρομολόγηση καναλιών σε agents και επιβεβαίωση ότι οι αναφορές και τα άμεσα μηνύματα φτάνουν στη Sophea.

32.1 Προαπαιτούμενα

Πριν ξεκινήσετε, επιβεβαιώστε τα εξής:

• Μπορείτε να συνδεθείτε στον επιθυμητό χώρο εργασίας Slack ως διαχειριστής ή έχετε διαχειριστή που μπορεί να εγκαταστήσει την εφαρμογή Slack για εσάς.
• Μπορείτε να συνδεθείτε στο Nous ως διαχειριστής χώρου εργασίας.
• Τουλάχιστον ένας agent έχει δημοσιευτεί στον χώρο εργασίας σας. Ανατρέξτε στην ενότητα Agents εάν δεν έχει δημοσιευτεί ακόμη agent.
• Προαιρετικά, αλλά συνιστάται: τουλάχιστον ένα σύνολο εγγράφων είναι έτοιμο. Ανατρέξτε στην ενότητα Σύνολα εγγράφων.

Συμβουλή

Επιλέξτε ένα ιδιωτικό κανάλι ανάπτυξης στο Slack για την πρώτη δοκιμή, για παράδειγμα #sophea-dev. Δοκιμάστε εκεί τις αναφορές και τα άμεσα μηνύματα πριν προσκαλέσετε το bot σε κανάλια που βλέπουν οι χρήστες σας.

32.2 Καταχώριση εφαρμογής Slack

Ανοίξτε το https://api.slack.com/apps σε νέα καρτέλα και ακολουθήστε τα παρακάτω βήματα.

1. Κάντε κλικ στο Create New App και κατόπιν επιλέξτε From scratch.
2. Εισαγάγετε ένα όνομα εφαρμογής, για παράδειγμα Sophea Bot, και επιλέξτε τον επιθυμητό χώρο εργασίας Slack.
3. Κάντε κλικ στο Create App. Το Slack σάς μεταφέρει στη σελίδα ρυθμίσεων της εφαρμογής.

32.2.1 Διαμόρφωση scopes του bot

Ανοίξτε το OAuth & Permissions στην αριστερή πλαϊνή γραμμή και προσθέστε τα scopes που χρειάζεται το Nous για να διαβάζει αναφορές, να διαβάζει το ιστορικό καναλιού ως συναφές περιεχόμενο και να δημοσιεύει απαντήσεις.

Προσθέστε τα ακόλουθα bot token scopes:

• app_mentions:read: επιτρέπει στο bot να βλέπει πότε οι χρήστες το αναφέρουν με @mention σε ένα κανάλι.
• channels:history: επιτρέπει στο bot να διαβάζει πρόσφατα μηνύματα σε δημόσια κανάλια ως συναφές περιεχόμενο νήματος.
• groups:history: όπως παραπάνω, για ιδιωτικά κανάλια στα οποία έχει προσκληθεί το bot.
• im:history: επιτρέπει στο bot να διαβάζει άμεσα μηνύματα που απευθύνονται σε αυτό.
• im:read: επιτρέπει στο bot να εμφανίζει συνομιλίες άμεσων μηνυμάτων.
• im:write: επιτρέπει στο bot να ανοίγει άμεση συνομιλία με έναν χρήστη.
• chat:write: επιτρέπει στο bot να δημοσιεύει απαντήσεις.
• chat:write.public: επιτρέπει στο bot να δημοσιεύει σε δημόσια κανάλια στα οποία δεν έχει συμμετάσχει.
• users:read: επιτρέπει στο bot να αντιστοιχίζει user IDs σε ονόματα για εξατομικευμένες απαντήσεις.
• team:read: επιτρέπει στο bot να διαβάζει βασικές πληροφορίες του χώρου εργασίας.
• files:read: προαιρετικό. Προσθέστε το μόνο εάν η δρομολόγηση καναλιών πρέπει να επιθεωρεί συνημμένα.

Προσθέστε περισσότερα scopes μόνο εάν τα χρειάζεται η δρομολόγηση καναλιών σας. Το Slack θα προειδοποιεί τους χρήστες κατά την επανεγκατάσταση κάθε φορά που αλλάζετε scopes.

32.2.2 Ενεργοποίηση του Socket Mode και έκδοση App-Level Token

Το Slack bot της Sophea συνδέεται στο Slack μέσω WebSocket, επομένως δεν διαμορφώνετε request URL για Event Subscriptions.

1. Ανοίξτε το Socket Mode στην αριστερή πλαϊνή γραμμή και ενεργοποιήστε το Enable Socket Mode.
2. Όταν το Slack ζητήσει ένα App-Level Token, δώστε στο token ένα όνομα, για παράδειγμα Sophea socket, και προσθέστε το scope connections:write. Αυτό είναι το μόνο scope που χρειάζεται το συγκεκριμένο token.
3. Αντιγράψτε το token που δημιουργήθηκε. Ξεκινά με xapp-. Το Slack δεν θα το εμφανίσει ξανά, γι’ αυτό διατηρήστε το προσωρινά σε ασφαλές σημείο.

Ανοίξτε το Event Subscriptions στην αριστερή πλαϊνή γραμμή και ενεργοποιήστε το Enable Events. Αφήστε κενό το request URL. Τα συμβάντα φτάνουν μέσω της σύνδεσης Socket Mode. Στην ενότητα Subscribe to bot events, προσθέστε τουλάχιστον:

• app_mention: το bot αναφέρεται σε ένα κανάλι.
• message.im: ένας χρήστης στέλνει άμεσο μήνυμα στο bot.
• message.channels: δημοσιεύεται μήνυμα σε δημόσιο κανάλι στο οποίο βρίσκεται το bot. Προσθέστε το μόνο εάν θέλετε το bot να αντιδρά χωρίς ρητή αναφορά.
• message.groups: όπως παραπάνω, για ιδιωτικά κανάλια.

Αποθηκεύστε τις αλλαγές.

32.2.3 Εγκατάσταση της εφαρμογής και λήψη του Bot Token

Ανοίξτε το Install App στην αριστερή πλαϊνή γραμμή και κάντε κλικ στο Install to Workspace. Εγκρίνετε τα ζητούμενα scopes στην οθόνη συγκατάθεσης του Slack.

Το Slack σάς επιστρέφει στη σελίδα της εφαρμογής. Αντιγράψτε το Bot User OAuth Token από το OAuth & Permissions. Ξεκινά με xoxb-. Τώρα έχετε τις δύο υποχρεωτικές τιμές και μία προαιρετική:

• Bot Token (xoxb-): από το OAuth & Permissions.
• App-Level Token (xapp-): από Basic Information -> App-Level Tokens, αυτό που εκδώσατε με connections:write.
• User Token (xoxp-, προαιρετικό): μόνο εάν χρειάζεστε δυνατότητες πλαστοπροσωπίας χρήστη τις οποίες δεν μπορεί να εκτελέσει το bot με το δικό του token. Οι περισσότεροι χώροι εργασίας αφήνουν αυτό το πεδίο κενό.

Προειδοποίηση

Και τα δύο tokens είναι διαπιστευτήρια. Αντιμετωπίστε τα όπως τους κωδικούς πρόσβασης. Μην τα επικολλάτε σε συνομιλίες, μην τα δεσμεύετε στο git και μην τα εμφανίζετε σε στιγμιότυπα οθόνης όταν καταγράφετε βίντεο εισαγωγής. Εάν υποψιάζεστε διαρροή, ανανεώστε το αντίστοιχο token από το developer portal του Slack.

32.3 Προσθήκη του bot στο Nous

Ανοίξτε την ενότητα Ενσωματώσεις στην αριστερή πλαϊνή γραμμή και κάντε κλικ στην Ενσωμάτωση Slack. Ανοίγει η σελίδα Ενσωμάτωση Slack στη διαδρομή /app/admin/bots/slack. Η σελίδα εμφανίζει κάθε καταχωρισμένο Slack bot, με στήλες Όνομα, Κατάσταση, Προεπιλεγμένη διαμόρφωση και Πλήθος καναλιών.

Σελίδα Ενσωμάτωση Slack που εμφανίζει τη λίστα bot

Κάντε κλικ στο Νέο Slack Bot επάνω αριστερά στη λίστα για να ανοίξετε τη φόρμα καταχώρισης.

Φόρμα Νέο Slack Bot με πεδία ονόματος και token

Συμπληρώστε τη φόρμα:

• Name This Slack Bot: μια ευανάγνωστη ετικέτα, για παράδειγμα Admin Guide Demo Bot. Εμφανίζεται μόνο στο περιβάλλον διαχείρισης.
• Slack Bot Token: επικολλήστε το token xoxb- από το OAuth & Permissions.
• Slack App Token: επικολλήστε το token xapp- που εκδώσατε στην ενότητα Basic Information -> App-Level Tokens.
• Slack User Token (Optional): επικολλήστε ένα token xoxp- μόνο εάν χρειάζεστε διευρυμένη πρόσβαση σε ιδιωτικά κανάλια.

Κάντε κλικ στο Δημιουργία. Το Nous επαληθεύει τα tokens καλώντας το API του Slack και ανοίγοντας τη σύνδεση Socket Mode. Εάν ένα token δεν είναι έγκυρο ή ο χώρος εργασίας δεν μπορεί να επικοινωνήσει με το Slack, η φόρμα επιστρέφει σφάλμα και δεν αποθηκεύεται τίποτα.

Μετά τη δημιουργία, το bot εμφανίζεται στη λίστα. Το Nous ανοίγει τη σύνδεση Socket Mode στο παρασκήνιο. Όταν το Slack παραδώσει το πρώτο συμβάν, η στήλη Κατάσταση ενημερώνεται αναλόγως.

32.4 Δρομολόγηση καναλιών σε agents

Ανοίξτε το bot από τη λίστα. Η σελίδα λεπτομερειών εμφανίζει τη διαμόρφωση δρομολόγησης καναλιών.

Διαμόρφωση δρομολόγησης καναλιών για Slack bot

Η δρομολόγηση καναλιών υποδεικνύει στο Nous ποιος agent πρέπει να απαντά όταν γίνεται αναφορά στο bot σε συγκεκριμένο κανάλι.

Για να προσθέσετε μια διαμόρφωση:

1. Κάντε κλικ στη Νέα ρύθμιση καναλιού.
2. Εισαγάγετε το αναγνωριστικό καναλιού Slack, για παράδειγμα C0123456789. Θα το βρείτε στο Slack κάνοντας δεξί κλικ στο κανάλι, επιλέγοντας View channel details και μεταβαίνοντας στο κάτω μέρος.
3. Επιλέξτε τον agent από το αναπτυσσόμενο μενού Βοηθός. Εμφανίζονται μόνο οι agents που έχουν ήδη δημοσιευτεί στον συγκεκριμένο χώρο εργασίας.
4. Προαιρετικά, περιορίστε το κανάλι σε ένα ή περισσότερα Σύνολα εγγράφων. Ο agent θα παραθέτει μόνο επιλέξιμα έγγραφα από αυτά τα σύνολα. Οι συνηθισμένες απαντήσεις σε κοινόχρηστο κανάλι μπορούν να αναζητούν μόνο δημόσιο περιεχόμενο του χώρου εργασίας. Ένα ιδιωτικό σύνολο δεν καθιστά τα έγγραφά του ορατά εκεί.
5. Κάντε κλικ στη Δημιουργία.

Επαναλάβετε για κάθε κανάλι που θέλετε να συνδέσετε. Τα κανάλια χωρίς συγκεκριμένη διαμόρφωση χρησιμοποιούν την προεπιλεγμένη persona του bot, εάν έχει οριστεί. Διαφορετικά, το bot παραμένει σιωπηλό σε μη διαμορφωμένα κανάλια.

Σημείωση

Το bot πρέπει να προσκληθεί σε ένα ιδιωτικό κανάλι πριν μπορέσει να λάβει συμβάντα από αυτό. Στο Slack, εκτελέστε /invite @Sophea Bot μέσα στο κανάλι. Τα δημόσια κανάλια λειτουργούν μόλις προστεθεί το αναγνωριστικό τους στο Nous.

Για να αφαιρέσετε μια διαμόρφωση, τοποθετήστε τον δείκτη πάνω στη σειρά και κάντε κλικ στο εικονίδιο κάδου. Για να αλλάξετε τον agent μιας διαμόρφωσης, κάντε κλικ στο όνομα του agent και επιλέξτε διαφορετικό. Οι αλλαγές εφαρμόζονται στην επόμενη αναφορά.

32.5 Δοκιμή και αντιμετώπιση προβλημάτων

Εκτελέστε τους παρακάτω ελέγχους με τη σειρά στο κανάλι ανάπτυξης, πριν ανακοινώσετε το bot στους χρήστες.

32.5.1 Έλεγχος άμεσου μηνύματος

1. Στο Slack, κάντε κλικ στο όνομα του bot στην ενότητα Apps της πλαϊνής γραμμής για να ανοίξετε άμεση συνομιλία.
2. Στείλτε ένα σύντομο prompt, για παράδειγμα γεια, λειτουργείς;.
3. Το bot απαντά μέσα σε λίγα δευτερόλεπτα. Εάν δεν απαντήσει, η πιθανότερη αιτία είναι ότι λείπει το scope im:history ή chat:write. Εγκαταστήστε ξανά την εφαρμογή αφού προσθέσετε τα scopes.

32.5.2 Έλεγχος αναφοράς σε κανάλι

1. Προσκαλέστε το bot στο κανάλι ανάπτυξης: /invite @Sophea Bot.
2. Αναφέρετέ το: @Sophea Bot τι περιλαμβάνει το σύνολο εγγράφων εισαγωγής μας;.
3. Το bot απαντά στο ίδιο νήμα. Η απάντηση παραθέτει το σύνολο εγγράφων που έχει συνδεθεί με αυτό το κανάλι.

Εάν το bot δεν απαντά σε μια αναφορά:

• Επιβεβαιώστε ότι το αναγνωριστικό καναλιού έχει καταχωριστεί στη δρομολόγηση καναλιών.
• Επιβεβαιώστε ότι έχει επιλεγεί agent για το κανάλι ή ότι έχει οριστεί προεπιλεγμένη persona στο bot.
• Ελέγξτε τη στήλη Κατάσταση στη σελίδα Ενσωμάτωση Slack και επιβεβαιώστε ότι ενημερώθηκε μετά την αναφορά. Εάν δεν ενημερώθηκε, το Slack δεν μπόρεσε να παραδώσει το συμβάν μέσω της σύνδεσης Socket Mode. Ανοίξτε το bot, ελέγξτε ξανά ότι το App Token (xapp-) παραμένει έγκυρο στο Slack και αποθηκεύστε ξανά το bot για να ανοίξει εκ νέου η σύνδεση.

32.5.3 Έλεγχος δικαιωμάτων

Η ορατότητα της απόκρισης στο Slack εξαρτάται από τον τρόπο παράδοσής της:

• Ένα άμεσο μήνυμα bot ή μια ephemeral απάντηση μπορεί να χρησιμοποιήσει τα δικαιώματα ιδιωτικών εγγράφων του αντιστοιχισμένου χρήστη Nous.
• Μια συνηθισμένη απάντηση που δημοσιεύεται σε κοινόχρηστο κανάλι πραγματοποιεί εκ σχεδιασμού αναζήτηση ως ανώνυμος χρήστης και μπορεί να χρησιμοποιήσει μόνο δημόσια έγγραφα του χώρου εργασίας, ακόμη και όταν ο αποστολέας έχει προσωπικά πρόσβαση σε ιδιωτικό περιεχόμενο.

Εάν μια απάντηση σε κοινόχρηστο κανάλι δεν έχει παραπομπές, επιβεβαιώστε ότι τα δρομολογημένα σύνολα εγγράφων περιέχουν δημόσιο περιεχόμενο του χώρου εργασίας. Για να δοκιμάσετε την ιδιωτική πρόσβαση ενός μέλους, χρησιμοποιήστε άμεσο μήνυμα ή ephemeral απάντηση και συγκρίνετέ την με το ίδιο ερώτημα στην κανονική συνομιλία Nous του μέλους στη διαδρομή /app.

32.5.4 Συνήθεις αποτυχίες

• invalid_auth κατά τη δημιουργία: το Bot Token (xoxb-) αντιγράφηκε λανθασμένα ή ανανεώθηκε στο Slack. Αντιγράψτε το ξανά από OAuth & Permissions -> Bot User OAuth Token.
• invalid app token κατά τη δημιουργία: από το App-Level Token (xapp-) λείπει το scope connections:write, έχει διαγραφεί ή επικολλήθηκε σε λάθος πεδίο. Δημιουργήστε το ξανά στην ενότητα Basic Information -> App-Level Tokens και επικολλήστε τη νέα τιμή.
• Το bot αγνοεί αναφορές σε δημόσιο κανάλι στο οποίο μόλις συμμετείχε: επιβεβαιώστε τα scopes app_mentions:read και chat:write.public και κατόπιν εγκαταστήστε ξανά την εφαρμογή.
• Το bot απαντά χωρίς παραπομπές: δεν έχει επιλεγεί σύνολο εγγράφων στη διαμόρφωση καναλιού ή έχει απενεργοποιηθεί το Χρήση Γνώσης στον συνδεδεμένο agent. Ανοίξτε τον agent στη διαδρομή /app/agents και επιβεβαιώστε τη ρύθμιση. Ανατρέξτε στην ενότητα Agents.
• Η Ενσωμάτωση Slack λείπει από τις Ρυθμίσεις: επιβεβαιώστε ότι είστε διαχειριστής χώρου εργασίας.

Όταν το κανάλι ανάπτυξης περάσει και τους τρεις ελέγχους, προσκαλέστε το bot στα κανάλια των χρηστών για τα οποία προορίζεται και ανακοινώστε το.