Skråstregskommandoer

En brugerdefineret skråstregskommando giver folk mulighed for at skrive /noget i beskedfeltet for at kalde din service. Antimatter sender kommandoen til din URL og viser dit svar, enten kun til den pågældende person eller til hele kanalen.

Sådan fungerer en skråstregskommando

En person skriver /weather Paris og sender den. Teksten bliver ikke publiceret.
Antimatter sender en HTTP-anmodning til kommandoen URL, med hvem der skrev den, hvor, og teksten efter triggeren.
Din service svarer inden for anmodningens timeout (30 sekunder som standard) med en besked.
Antimatter viser svaret: kun til den pågældende person (ephemeral) eller i kanalen for alle.

Kommandoer tilhører et community, og et triggerord er unikt inden for det. Indbyggede kommandoer som /join, /msg eller /away kan ikke erstattes. Apps (plugins) kan også registrere kommandoer; se Serverdelen.

Opret en kommando

Brugerdefinerede skråstregskommandoer er aktiveret som standard (Aktivér brugerdefinerede skråstregskommandoer i Systemkonsol › Integrationer › Integrationshåndtering, ServiceSettings.EnableCommands). Community-administratorer og systemadministratorer kan som standard oprette dem.

Åbn fællesskabsmenuen, vælg Teamindstillinger, klik på Integrationer i slutningen af fanerne, derefter på Skråstregskommandoer og Tilføj skråstregskommando.
Udfyld Titel og Beskrivelse (vises på integrations-siderne).
Indtast Kommandos udløsende ord uden skråstreg og uden mellemrum, for eksempel weather.
Indtast Anmodnings-URL og vælg Anmodningsmetode: POST (standard) eller GET.
Vælg eventuelt et Brugernavn for svar og et Ikon for svar. De bruges kun, når serveren tillader, at integrationer overskriver navne og ikoner (se Navn og ikon).
Marker Autofuldførelse for at vise kommandoen, når folk skriver /, med et Autofuldførelse-hint (dens argumenter, såsom [city]) og en Autofuldførelsesbeskrivelse.
Vælg Gem, og kopier den viste token. Din service bruger den til at kontrollere, at anmodninger kommer fra 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 er P for POST eller G for GET. PUT /api/v4/commands/{command_id}/regen_token udsteder et nyt token.

Anmodningen, som din service modtager

En POST-kommando sender en form-encoderet body (application/x-www-form-urlencoded); en GET-kommando sender de samme felter i query-strengen. Tokenet findes også i Authorization: Token <token>-headeren.

Felt	Værdi
`token`	Kommandons token. Tjek det ved hver anmodning.
`command`	Triggeren med skråstreget, for eksempel `/weather`.
`text`	Alt efter triggeren, for eksempel `Paris`.
`user_id`, `user_name`	Hvem, der kørte den.
`channel_id`, `channel_name`	Hvor, den blev kørt.
`team_id`, `team_domain`	Fællesskabets ID og URL-navn.
`root_id`	Tråden, hvis den blev kørt i en tråds svarboks.
`trigger_id`	Gør det muligt for dit svar at åbne en dialog (se Dialoger). Det er kun gyldigt i en kort periode.
`response_url`	En URL til at sende flere svar senere (se Forzinkede svar).
`user_mentions`, `user_mentions_ids`, `channel_mentions`, `channel_mentions_ids`	De personer og offentlige kanaler, der nævnes i teksten, hvis der er nogen. Kanaler tæller med, uanset om de er skrevet som `#channel-name` eller `~channel-name`.

Serverens Site-URL skal være indstillet, før brugerdefinerede kommandoer kan køres: Antimatter bygger response_url ud fra den.

Svaret

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

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

Felt	Betydning
`response_type`	`ephemeral` (standard): kun den person, der kørte kommandoen, ser svaret, og det gemmes ikke efter en genindlæsning. `in_channel`: svaret sendes i kanalen.
`text`, `attachments`	Beskeden, som for webhooks: Markdown-tekst og vedhæftninger, herunder knapper og menuer.
`username`, `icon_url`	Navnet og billedet, der skal vises, hvis overrides er tilladt. Kommandons egne indstillinger har forrang for disse.
`channel_id`	Send svaret i en anden kanal, som personen skal være medlem af.
`goto_location`	En URL, der åbnes, når kommandoen er kørt.
`props`, `type`	Ekstra egenskaber og en brugerdefineret indlægstype, som ved webhooks. Et svar, der sendes til en forumkanal, skal indeholde `props.am_thread_title`, ellers afvises det.
`extra_responses`	Flere svar, hver med de samme felter, sendes efter det første.
`skip_slack_parsing`	`true` bevarer teksten, som den er, uden at konvertere Slack-stil links og omtaler.

Et svar, der ikke er JSON, vises som en ephemeral-besked med bodyen som tekst. 204 No Content viser intet. Enhver status uden for 200–299 viser personen en fejl.

Eksempel-service

En minimal kommando-service i Python, kun med 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 kører på en privat netværksadresse, skal en systemadministrator tillade den i Tillad upålidelige interne forbindelser til (ServiceSettings.AllowedUntrustedInternalConnections).

Forzinkede svar

For arbejde, der tager længere tid end timeouten, svar straks (for eksempel med en ephemeral "Arbejder på det…"), og POST derefter det reelle svar til response_url. Det tager den samme JSON som svaret, og virker op til 5 gange inden for 30 minutter efter kommandoen.

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 en kommando med API'et

Skripter og bots kan køre enhver kommando, indbygget eller tilpasset, som om de havde tastet 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 de kommandoer, folk kan autoudfylde i en fællesskab.

Autoudfyldning

Kommandoer oprettet på integrationssiderne udfyldes automatisk med deres trigger, hint og beskrivelse. Kommandoer registreret af apps kan beskrive deres underkommandoer og argumenter i detaljer med AutocompleteData, fra model.NewAutocompleteData(trigger, hint, helpText):

AddCommand(sub) tilføjer en underkommando, som selv er en AutocompleteData.
AddTextArgument(helpText, hint, pattern) tilføjer frit tekst.
AddStaticListArgument(helpText, required, items) tilbyder en fast liste af AutocompleteListItem{Item, Hint, HelpText}.
AddDynamicListArgument(helpText, url, required) beder din app om forslag, mens folk skriver. URL'en er en rute i din app, f.eks. /plugins/com.example.weather/cities. Den modtager brugeren, kanalen og fællesskabet, og returnerer en JSON-liste af {"Item", "Hint", "HelpText"}.

Varianterne Named… (AddNamedTextArgument og andre) tilføjer flagene --name value. Begge webgrænseflader viser disse forslag. En værdi med mellemrum kan sættes i anførselstegn, så den autoudfyldes som ét argument, for eksempel --name "my remote": dobbelte anførselstegn virker til alle kommandoer, og Antimatters egne kommandoer, der tager imod flag, accepterer også enkelte eller buede anførselstegn.

Mens nogen indtaster en kommando, viser Fusion kommandoen og hvert af dens argumenter som en blok, hvor det, der indtastes, er fremhævet med sin hjælpetekst. Argumenterne kommer fra AutocompleteData eller, hvis denne mangler, fra hintet: I et hint som @[username]... #[channel] henviser ord, der starter med @, til personargumentet, og ord, der starter med #, til kanalargumentet, uanset rækkefølgen; ... betyder, at argumentet gentages, og det sidste argument tager resten af teksten.

Kanaler i argumenter

I en kommandos argumenter foreslår @ personer, # foreslår kanaler og fuldfører dem som #channel-name, og ~ fuldfører dem som ~channel-name. Antimatters webgrænseflade og mobilapp skriver kanallinks med #, så en kommando, der tager imod en kanal, bør acceptere begge former: de indbyggede /join, /mute og /invite gør det, og deres hint lyder #[channel].