Snedstreckskommandon

Ett anpassat snedstreckskommando gör att personer kan skriva /något i meddelandefältet för att anropa din tjänst. Antimatter skickar kommandot till din URL och visar ditt svar, antingen bara för den personen eller för hela kanalen.

Så fungerar ett snedstreckskommando

1. Någon skriver /weather Paris och skickar det. Texten publiceras inte.
2. Antimatter skickar en HTTP-begäran till kommandots URL, med vem som skrev det, var, och texten efter utlösaren.
3. Din tjänst svarar inom begäranstiden (30 sekunder som standard) med ett meddelande.
4. Antimatter visar svaret: bara för den personen (tillfälligt) eller i kanalen för alla.

Kommandon tillhör en gemenskap, och ett utlösande ord är unikt inom den. Inbyggda kommandon som /join, /msg eller /away kan inte ersättas. Appar (plugins) kan också registrera kommandon; se Serverdelen.

Skapa ett kommando

Egna snedstreckskommandon är aktiverade som standard (Aktivera egna slash-kommandon i Systemkonsol › Integrationer › Hantera integrationer, ServiceSettings.EnableCommands). Community-administratörer och systemadministratörer kan som standard skapa dem.

1. Öppna din avatar i övre högra hörnet, välj sedan Integrationer › Slash-kommando och därefter Lägg till slash-kommandon.
2. Fyll i Titel och Beskrivning (visas på integrationsssidorna).
3. Ange Kommandots aktiveringsord, utan snedstreck och utan mellanslag, till exempel weather.
4. Ange Begärans URL och välj Metod för begäran: POST (standard) eller GET.
5. Välj om så önskas ett Svarets användarnamn och en Svarsikon. De används endast när servern tillåter att integrationer åsidosätter namn och ikoner (se Namn och ikon).
6. Markera Komplettera automatiskt för att visa kommandot när någon skriver /, med ett Tip för automatisk komplettering (dess argument, till exempel [city]) och en Beskrivning av automatisk komplettering.
7. Välj Spara och kopiera den visade tokenen. Din tjänst använder den för att kontrollera att begäranden kommer från din server.

Med API:et POST /api/v4/commands med {"team_id", "trigger", "url", "method": "P", "display_name", "description", "auto_complete": true, "auto_complete_hint", "auto_complete_desc", "username", "icon_url"}. Metoden är P för POST eller G för GET. PUT /api/v4/commands/{command_id}/regen_token genererar en ny token.

Begäran som din tjänst tar emot

Ett POST-kommando skickar en formulärkoderad kropp (application/x-www-form-urlencoded); ett GET-kommando skickar samma fält i frågesträngen. Token finns också i Authorization: Token <token>-huvudet.

Svaret

Svara med 200 och JSON (Content-Type: application/json):

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

Ett svar som inte är JSON visas som ett tillfälligt meddelande med kroppen som text. 204 No Content visar ingenting. Alla statuskoder utanför 200–299 visar personen ett fel.

Exempeltjänst

En minimal kommandotjänst i Python, med endast standardbiblioteket:

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

Om tjänsten körs på en privat nätverksadress måste en systemadministratör tillåta den i Tillåt osäkra interna anslutningar till (ServiceSettings.AllowedUntrustedInternalConnections).

Försenade svar

För arbete som tar längre tid än tidsgränsen, svara omedelbart (till exempel med ett tillfälligt "Jobbar på det…") och skicka sedan det faktiska svaret till response_url. Det tar samma JSON som svaret och fungerar upp till 5 gånger inom 30 minuter efter kommandot.

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

Kör ett kommando med API:t

Skript och bots kan köra valfritt kommando, inbyggt eller anpassat, som om de hade skrivit det:

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 listar de kommandon som användare kan autofylla i en gemenskap.

Autofyllning

Kommandon som skapas på integrationsssiderna autofylls med deras utlösare, ledtråd och beskrivning. Kommandon som registreras av appar kan beskriva sina underkommandon och argument i detalj med AutocompleteData, från model.NewAutocompleteData(trigger, hint, helpText):

• AddCommand(sub) lägger till ett underkommando, som i sig är ett AutocompleteData.
• AddTextArgument(helpText, hint, pattern) lägger till fri text.
• AddStaticListArgument(helpText, required, items) erbjuder en fast lista av AutocompleteListItem{Item, Hint, HelpText}.
• AddDynamicListArgument(helpText, url, required) ber appen om förslag medan användarna skriver. URL:en är en ruta i din app, till exempel /plugins/com.example.weather/cities. Den tar emot användaren, kanalen och gemenskapen, och returnerar en JSON-lista av {"Item", "Hint", "HelpText"}.

De Named…-varianterna (AddNamedTextArgument och andra) lägger till --name value-flaggor. Båda webbgränssnitten visar dessa förslag.

När någon skriver ett kommando visar Fusion kommandot och varje argument som en block, där det argument som just skrivs är markerat med sin hjälptext. Argumenten kommer från AutocompleteData eller, i dess frånvaro, från antydningen: i en antydning som @[username]... #[channel] går ord som börjar med @ till argumentet för personer och ord som börjar med # till argumentet för kanaler, oavsett ordning; ... betyder att argumentet kan upprepas, och det sista argumentet tar resten av texten.

Kanaler i argument

I ett kommandos argumenter, @ föreslår personer, # föreslår kanaler och slutför dem som #channel-name, och ~ slutför dem som ~channel-name. Antimatters webbgränssnitt och mobilapp skriver kanallänkar med #, så ett kommando som tar en kanal bör acceptera båda formerna: de inbyggda /join, /mute och /invite gör det, och deras ledtrådar säger #[channel].