Skråstrek-kommandoer

En egendefinert skråstrek-kommando lar brukere skrive /noe i meldingsfeltet for å kalle tjenesten din. Antimatter sender kommandoen til URL-en din og viser svaret ditt, enten kun til personen eller til hele kanalen.

Slik fungerer en skråstrek-kommando

1. Noen skriver /weather Paris og sender den. Teksten blir ikke publisert.
2. Antimatter sender en HTTP-forespørsel til kommandoen sin URL, med hvem som skrev den, hvor, og teksten etter utløseren.
3. Tjenesten din svarer innenfor tidsbegrensningen for forespørselen (30 sekunder som standard) med en melding.
4. Antimatter viser svaret: kun til den personen (midlertidig) eller i kanalen for alle.

Kommandoer tilhører et team, og et utløserord er unikt innenfor teamet. Innbygde kommandoer som /join, /msg eller /away kan ikke erstattes. Apps (plugins) kan også registrere kommandoer; se Serverdelen.

Lag en kommando

Egendefinerte skråstrek-kommandoer er aktivert som standard (Aktiver skråstrek-kommandoer i Systemkonsoll › Integrasjoner › Integrasjonsadministrasjon, ServiceSettings.EnableCommands). Teamadministratorer og systemadministratorer kan lage dem som standard.

1. Åpne avataren din øverst til høyre, deretter Integrasjoner › Skråstrek-kommandoer, deretter Legg til skråstrek-kommando.
2. Fyll inn Tittel og Beskrivelse (vises på integrasjonssidene).
3. Skriv inn Utløserord for kommando, uten skråstrek og uten mellomrom, for eksempel weather.
4. Skriv inn URL for forespørsel og velg Metode for forespørsel: POST (standard) eller GET.
5. Vilkårlig: Sett et Svarerbrukernavn og et Ikon for svar. Disse brukes bare når serveren tillater at integrasjoner overstyrer navn og ikoner (se Navn og ikon).
6. Avkryss Autofullstending for å liste kommandoen når folk skriver /, med en Autofullføringshint (argumentene, som [city]) og en Autofullføringsbeskrivelse.
7. Velg Lagre, og kopier tokenet som vises. Tjenesten din bruker det til å sjekke at forespørsler kommer fra serveren din.

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 er P for POST eller G for GET. PUT /api/v4/commands/{command_id}/regen_token utsteder en ny token.

Forespørselen tjenesten din mottar

En POST-kommando sender en form-kodet kropp (application/x-www-form-urlencoded); en GET-kommando sender de samme feltene i spørringsstrengen. Tokenet finnes også i Authorization: Token <token>-hodet.

Svaret

Svar med 200 og JSON (Content-Type: application/json):

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

Et svar som ikke er JSON vises som en midlertidig melding med kroppen som tekst. 204 No Content viser ingenting. Enhver status utenfor 200–299 viser personen en feil.

Eksempel på tjeneste

En minimal kommandotjeneste i Python, med bare 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()

Hvis tjenesten kjører på en privat nettverksadresse, må en systemadministrator tillate den i Tillat upålitelige interne tilkoblinger til (ServiceSettings.AllowedUntrustedInternalConnections).

Uforsinkelte svar

For arbeid som tar lenger tid enn tidsavbruddet, svar umiddelbart (for eksempel med en midlertidig melding som «Jobber på det…»), og POST deretter det egentlige svaret til response_url. Den tar samme JSON som svaret, og fungerer opptil 5 ganger innen 30 minutter etter kommandoen.

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

Kjør en kommando med API-et

Skript og bots kan kjøre enhver kommando, innebygd eller tilpasset, som om de hadde skrevet den:

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 viser en liste over kommandoer som folk kan fullstende i en fellesskap.

Autofullstending

Kommandoer som er opprettet på integrasjonssidene fullstendes med utløser, ledetråd og beskrivelse. Kommandoer registrert av apper kan beskrive underkommandoer og argumenter i detalj med AutocompleteData, fra model.NewAutocompleteData(trigger, hint, helpText):

• AddCommand(sub) legger til en underkommando, som i seg selv er en AutocompleteData.
• AddTextArgument(helpText, hint, pattern) legger til fri tekst.
• AddStaticListArgument(helpText, required, items) tilbyr en fast liste med AutocompleteListItem{Item, Hint, HelpText}.
• AddDynamicListArgument(helpText, url, required) ber appen din om forslag mens folk skriver. URL-en er en rute i appen din, for eksempel /plugins/com.example.weather/cities. Den mottar bruker, kanal og fellesskap, og returnerer en JSON-liste med {"Item", "Hint", "HelpText"}.

Variantene Named… (AddNamedTextArgument og andre) legger til --name value-flagg. Begge grensesnittene viser disse forslagene.

Mens noen skriver en kommando, viser Fusion kommandoen og hvert av argumentene som en blokk, der den som skrives er fremhevet med hjelpeteksten. Argumentene kommer fra AutocompleteData eller, uten det, fra hintet: i et hint som @[username]... #[channel], går ord som starter med @ til argumentet for personer, og ord som starter med # til argumentet for kanaler, uavhengig av rekkefølgen; ... betyr at argumentet gjentas, og det siste argumentet tar resten av teksten.

Kanaler i argumenter

I argumentene til en kommando foreslår @ personer, # foreslår kanaler og fullfører dem som #channel-name, og ~ fullfører dem som ~channel-name. Antimatters nettgrensesnitt og mobilapp skriver kanallinker med #, så en kommando som tar en kanal bør akseptere begge formene: de innebygde /join, /mute og /invite gjør dette, og hintene deres sier #[channel].