Comenzi cu slash

O comandă cu slash personalizată permite utilizatorilor să tasteze /ceva în caseta de mesaje pentru a chema serviciul dumneavoastră. Antimatter trimite comanda către URL-ul dumneavoastră și afișează răspunsul, fie doar pentru persoana respectivă, fie pentru întregul canal.

Cum funcționează o comandă cu slash

1. Cineva tastează /weather Paris și o trimite. Textul nu este publicat.
2. Antimatter trimite o cerere HTTP către URL-ul comenzii, cu informații despre cine a tastat-o, unde și textul de după declanșator.
3. Serviciul dumneavoastră răspunde în cadrul timpului de așteptare al cererii (30 de secunde implicit) cu un mesaj.
4. Antimatter afișează răspunsul: doar pentru acea persoană (efemer) sau în canal pentru toată lumea.

Comenzile aparțin unei comunități, iar un cuvânt declanșator este unic în cadrul acesteia. Comenzile integrate, cum ar fi /join, /msg sau /away, nu pot fi înlocuite. Aplicațiile (pluginurile) pot, de asemenea, înregistra comenzi; consultați Partea de server.

Crearea unei comenzi

Comenzile cu slash personalizate sunt activate implicit (Activați comenzile personalizate Slash în Consola de sistem › Integrări › Managementul integrării, ServiceSettings.EnableCommands). Administratorii comunității și administratorii de sistem le pot crea implicit.

1. Deschideți avatarul din colțul din dreapta sus, apoi Integrări › Comenzi cu slash, apoi Adăugați comanda Slash.
2. Completați Titlu și Descriere (afisate pe paginile de integrări).
3. Introduceți Comandă De Declanșare Cuvânt, fără slash și fără spații, de exemplu weather.
4. Introduceți Cerere URL și alegeți Metoda Cereri: POST (implicit) sau GET.
5. Opțional, setați un Răspuns utilizator și o Adresa icoanei. Acestea sunt utilizate doar dacă serverul permite integrărilor să suprascrie numele și icoanele (a se vedea Nume și iconiță).
6. Bifați Completare automată pentru a lista comanda când utilizatorii tastează /, cu un Completare automată Indiciu (argumentele sale, de exemplu [city]) și o Completarea Automată a Descrieri.
7. Alegeți Salvează și copiați tokenul afișat. Serviciul dumneavoastră îl folosește pentru a verifica dacă cererile provin de la serverul dumneavoastră.

Prin API: POST /api/v4/commands cu {"team_id", "trigger", "url", "method": "P", "display_name", "description", "auto_complete": true, "auto_complete_hint", "auto_complete_desc", "username", "icon_url"}. Metoda este P pentru POST sau G pentru GET. PUT /api/v4/commands/{command_id}/regen_token emite un token nou.

Cererea pe care o primește serviciul

O comandă POST trimite un corp codificat ca formular (application/x-www-form-urlencoded); o comandă GET trimite aceleași câmpuri în șirul de interogare. Tokenul se află și în antetul Authorization: Token <token>.

Răspunsul

Răspundeți cu 200 și JSON (Content-Type: application/json):

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

O răspuns care nu este în format JSON este afișat ca mesaj efemer, cu textul corpului mesajului. 204 No Content nu afișează nimic. Orice cod de stare în afara intervalului 200–299 afișează utilizatorului o eroare.

Serviciu de exemplu

Un serviciu de comandă minimal în Python, cu doar biblioteca standard:

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()

Dacă serviciul rulează pe o adresă de rețea privată, un administrator de sistem trebuie să îl permită în Permiteți conexiunile interne de neîncrederi la (ServiceSettings.AllowedUntrustedInternalConnections).

Răspunsuri întârziate

Pentru lucruri care durează mai mult decât timpul de așteptare, răspundeți imediat (de exemplu, cu un mesaj efemer „Lucrez la el…”), apoi trimiteți răspunsul real la response_url. Acesta acceptă același JSON ca răspunsul și funcționează de până la 5 ori în 30 de minute de la comandă.

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

Executați o comandă prin API

Scripturile și boturile pot executa orice comandă, integrată sau personalizată, ca și cum ar fi tastat-o:

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 listează comenzile pe care utilizatorii le pot completa automat într-o comunitate.

Completare automată

Comenzile create în paginile de integrare se completează automat cu declanșatorul, indiciul și descrierea. Comenzile înregistrate de aplicații pot descrie în detaliu subcomenzile și argumentele cu AutocompleteData, din model.NewAutocompleteData(trigger, hint, helpText):

• AddCommand(sub) adaugă o subcomandă, care este la rândul ei un AutocompleteData.
• AddTextArgument(helpText, hint, pattern) adaugă text liber.
• AddStaticListArgument(helpText, required, items) oferă o listă fixă de AutocompleteListItem{Item, Hint, HelpText}.
• AddDynamicListArgument(helpText, url, required) solicită aplicației dvs. sugestii pe măsură ce utilizatorii tastează. URL-ul este o rută a aplicației, de exemplu /plugins/com.example.weather/cities. Primește utilizatorul, canalul și comunitatea și returnează o listă JSON de {"Item", "Hint", "HelpText"}.

Variantele Named… (AddNamedTextArgument și altele) adaugă opțiuni de tip --name value. Ambele interfețe web afișează aceste sugestii.

În timp ce cineva tastează o comandă, Fusion afișează comanda și fiecare dintre argumentele acesteia sub formă de bloc, cel care este tastat fiind evidențiat împreună cu textul de ajutor. Argumentele provin din AutocompleteData sau, în lipsa acestuia, din indiciu: într-un indiciu de tipul @[username]... #[channel], cuvintele care încep cu @ se atribuie argumentului de persoane, iar cele care încep cu # argumentului de canal, indiferent de ordinea lor; ... înseamnă că argumentul se repetă, iar ultimul argument preia restul textului.

Canale în argumente

În argumentele unei comenzi, @ sugerează persoane, # sugerează canale și le completează sub forma #channel-name, iar ~ le completează sub forma ~channel-name. Interfața web și aplicația mobilă Antimatter scriu linkurile către canale cu #, astfel încât o comandă care primește un canal ar trebui să accepte ambele forme: comanda încorporată /join, /mute și /invite o fac, iar indiciile lor indică #[channel].