Εντολές καθέτου

Μια προσαρμοσμένη εντολή καθέτου επιτρέπει στους χρήστες να πληκτρολογήσουν /κάτι στο πεδίο μηνύματος για να καλέσουν την υπηρεσία σας. Το Antimatter στέλνει την εντολή στη διεύθυνση URL σας και εμφανίζει την απάντησή σας, είτε μόνο στον χρήστη είτε σε όλο το κανάλι.

Πώς λειτουργεί μια εντολή καθέτου

1. Κάποιος πληκτρολογεί /weather Paris και το στέλνει. Το κείμενο δεν δημοσιεύεται.
2. Το Antimatter στέλνει ένα HTTP αίτημα στη διεύθυνση URL της εντολής, μαζί με πληροφορίες για τον χρήστη, τη θέση και το κείμενο μετά τη λέξη ενεργοποίησης.
3. Η υπηρεσία σας απαντά εντός του χρονικού ορίου του αιτήματος (30 δευτερόλεπτα από προεπιλογή) με ένα μήνυμα.
4. Το Antimatter εμφανίζει την απάντηση: μόνο σε αυτόν τον χρήστη (προσωρινή) ή στο κανάλι για όλους.

Οι εντολές ανήκουν σε μια κοινότητα και η λέξη ενεργοποίησης είναι μοναδική εντός αυτής. Οι ενσωματωμένες εντολές, όπως /join, /msg ή /away, δεν μπορούν να αντικατασταθούν. Οι εφαρμογές (plugins) μπορούν επίσης να καταχωρίσουν εντολές· δείτε Το μέρος του server.

Δημιουργία εντολής

Οι προσαρμοσμένες εντολές καθέτου είναι ενεργοποιημένες από προεπιλογή (Ενεργοποίηση προσαρμοσμένων εντολών καθέτου στο Κονσόλα συστήματος › Ολοκληρώσεις › Διαχείριση ολοκληρώσεων, ServiceSettings.EnableCommands). Οι διαχειριστές κοινότητας και οι συστημικοί διαχειριστές μπορούν να τις δημιουργήσουν από προεπιλογή.

1. Ανοίξτε το μενού ομάδας, στη συνέχεια Ρυθμίσεις ομάδας, κάντε κλικ στην επιλογή Ολοκληρώσεις στο τέλος των καρτελών της, έπειτα στις Εντολές καθέτου και στην Προσθήκη εντολής καθέτου.
2. Συμπληρώστε το Τίτλος και την Περιγραφή (εμφανίζονται στις σελίδες ολοκληρώσεων).
3. Εισάγετε τη Λέξη ενεργοποίησης εντολής, χωρίς καθέτη και χωρίς κενά, για παράδειγμα weather.
4. Εισάγετε τη Διεύθυνση URL αιτήματος και επιλέξτε τη Μέθοδος αιτήματος: POST (η προεπιλογή) ή GET.
5. Επιλέξτε προαιρετικά ένα Όνομα χρήστη απόκρισης και μια Εικόνα απόκρισης. Χρησιμοποιούνται μόνο όταν ο server επιτρέπει στις ολοκληρώσεις να αντικαθιστούν ονόματα και εικόνες (βλ. Όνομα και εικόνα).
6. Σημειώστε Αυτόματη συμπλήρωση για να εμφανίζεται η εντολή στη λίστα όταν οι χρήστες πληκτρολογούν /, με Συμβουλή αυτόματης συμπλήρωσης (τα ορίσματά της, όπως [city]) και Περιγραφή αυτόματης συμπλήρωσης.
7. Επιλέξτε Αποθήκευση και αντιγράψτε το token που εμφανίζεται. Η υπηρεσία σας το χρησιμοποιεί για να ελέγχει ότι τα αιτήματα προέρχονται από τον server σας.

Μέσω API: POST /api/v4/commands με {"team_id", "trigger", "url", "method": "P", "display_name", "description", "auto_complete": true, "auto_complete_hint", "auto_complete_desc", "username", "icon_url"}. Η μέθοδος είναι P για POST ή G για GET. Η PUT /api/v4/commands/{command_id}/regen_token εκδίδει ένα νέο token.

Το αίτημα που λαμβάνει η υπηρεσία σας

Μια εντολή POST στέλνει ένα σώμα σε μορφή φόρμας (application/x-www-form-urlencoded); μια εντολή GET στέλνει τα ίδια πεδία στην συμβολοσειρά ερωτήματος. Το token βρίσκεται επίσης στο κεφάλαιο Authorization: Token <token>.

Η απάντηση

Απαντήστε με 200 και JSON (Content-Type: application/json):

{
  "response_type": "in_channel",
  "text": "Paris: 18 °C, light rain",
  "attachments": []
}

Μια απάντηση που δεν είναι JSON εμφανίζεται ως προσωρινό μήνυμα με το σώμα ως κείμενο. Το 204 No Content δεν εμφανίζει τίποτα. Κάθε κατάσταση εκτός του εύρους 200–299 εμφανίζει στο άτομο ένα σφάλμα.

Παράδειγμα υπηρεσίας

Μια ελάχιστη υπηρεσία εντολών σε Python, χρησιμοποιώντας μόνο τη βιβλιοθήκη προεπιλογής:

import hmac
import json
from http.server import BaseHTTPRequestHandler, HTTPServer
from urllib.parse import parse_qs

TOKEN = "the token shown when you saved the command"

class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        body = self.rfile.read(int(self.headers["Content-Length"])).decode()
        form = {key: values[0] for key, values in parse_qs(body).items()}
        if not hmac.compare_digest(form.get("token", ""), TOKEN):
            self.send_response(401)
            self.end_headers()
            return
        answer = {
            "response_type": "ephemeral",
            "text": f"Hello @{form['user_name']}, you asked for: {form.get('text', '')}",
        }
        data = json.dumps(answer).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(data)

HTTPServer(("0.0.0.0", 8080), Handler).serve_forever()

Εάν η υπηρεσία εκτελείται σε διεύθυνση ιδιωτικού δικτύου, ένας διαχειριστής συστήματος πρέπει να την επιτρέψει στο Επιτρέπει μη αξιόπιστες εσωτερικές συνδέσεις προς (ServiceSettings.AllowedUntrustedInternalConnections).

Καθυστερημένες απαντήσεις

Για εργασίες που διαρκούν περισσότερο από το όριο χρόνου, απαντήστε αμέσως (για παράδειγμα με ένα προσωρινό «Δουλεύω πάνω σε αυτό…») και στη συνέχεια στείλτε την πραγματική απάντηση στο response_url. Λαμβάνει το ίδιο JSON με την απάντηση και λειτουργεί έως 5 φορές εντός 30 λεπτών από την εντολή.

curl -X POST "$RESPONSE_URL" -H 'Content-Type: application/json' \
  -d '{"response_type": "in_channel", "text": "Report ready: https://reports.example.com/42"}'

Εκτέλεση εντολής μέσω της API

Σενάρια και bots μπορούν να εκτελέσουν οποιαδήποτε εντολή, ενσωματωμένη ή προσαρμοσμένη, σαν να την είχαν πληκτρολογήσει:

curl -X POST https://chat.example.com/api/v4/commands/execute \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"channel_id": "'$CHANNEL_ID'", "command": "/weather Paris"}'

GET /api/v4/teams/{team_id}/commands/autocomplete εμφανίζει τις εντολές που μπορούν να συμπληρωθούν αυτόματα από τους χρήστες σε μια κοινότητα.

Αυτόματη συμπλήρωση

Οι εντολές που δημιουργούνται στις σελίδες ολοκληρωμάτων συμπληρώνονται αυτόματα με το ενεργοποιητή, την ένδειξη και την περιγραφή τους. Οι εντολές που καταγράφονται από εφαρμογές μπορούν να περιγράψουν αναλυτικά τις υποεντολές και τα ορίσματά τους με AutocompleteData, από model.NewAutocompleteData(trigger, hint, helpText):

• AddCommand(sub) προσθέτει μια υποεντολή, η οποία είναι επίσης AutocompleteData.
• AddTextArgument(helpText, hint, pattern) προσθέτει ελεύθερο κείμενο.
• AddStaticListArgument(helpText, required, items) προσφέρει μια σταθερή λίστα από AutocompleteListItem{Item, Hint, HelpText}.
• AddDynamicListArgument(helpText, url, required) ζητά από την εφαρμογή σας προτάσεις καθώς πληκτρολογούν οι χρήστες. Το URL είναι μια διαδρομή της εφαρμογής σας, όπως /plugins/com.example.weather/cities. Λαμβάνει τον χρήστη, το κανάλι και την κοινότητα και επιστρέφει μια JSON λίστα από {"Item", "Hint", "HelpText"}.

Οι παραλλαγές Named… (AddNamedTextArgument και άλλες) προσθέτουν σημαίες --name value και και οι δύο διεπαφές ιστού εμφανίζουν αυτές τις προτάσεις. Μια τιμή με κενούς χαρακτήρες μπορεί να περικλείεται σε εισαγωγικά ώστε να συμπληρώνεται αυτόματα ως μία παράμετρος, για παράδειγμα --name "my remote": τα διπλά εισαγωγικά λειτουργούν για κάθε εντολή, ενώ οι εντολές του ίδιου του Antimatter που δέχονται σημαίες δέχονται επίσης απλά ή καμπυλωτά εισαγωγικά.

Ενώ κάποιος πληκτρολογεί μια εντολή, το Fusion εμφανίζει την εντολή και κάθε ένα από τα ορίσματά της ως μπλοκ, με το ορίσμα που πληκτρολογείται να είναι nổiμαρκαρισμένο μαζί με το κείμενο βοήθειας. Τα ορίσματα προέρχονται από AutocompleteData ή, αν δεν υπάρχει, από την ένδειξη: σε μια ένδειξη όπως @[username]... #[channel], οι λέξεις που ξεκινούν με @ πάνε στο ορίσμα χρηστών και οι λέξεις που ξεκινούν με # στο ορίσμα καναλιών, ανεξαρτήτως σειράς· ... σημαίνει ότι το ορίσμα επαναλαμβάνεται, και το τελευταίο ορίσμα λαμβάνει το υπόλοιπο κείμενο.

Κανάλια σε ορίσματα

Στα ορίσματα μιας εντολής, το @ προτείνει χρήστες, το # προτείνει κανάλια και τα συμπληρώνει ως #channel-name, και το ~ τα συμπληρώνει ως ~channel-name. Η διαδικτυακή διεπαφή και η κινητή εφαρμογή του Antimatter γράφουν τους συνδέσμους καναλιών με #, οπότε μια εντολή που λαμβάνει κανάλι θα πρέπει να αποδέχεται και τις δύο μορφές: οι ενσωματωμένες /join, /mute και /invite το κάνουν, και οι ενδείξεις τους αναφέρουν #[channel].