Příkazy s lomítkem

Vlastní příkaz s lomítkem umožňuje uživatelům napsat /něco do pole pro zprávy, aby zavolali váš servis. Antimatter pošle příkaz na vaši URL a zobrazí vaši odpověď, buď pouze dané osobě, nebo celému kanálu.

Jak příkaz s lomítkem funguje

Někdo napíše /weather Paris a odešle to. Text se nezveřejní.
Antimatter pošle HTTP požadavek na URL příkazu, včetně toho, kdo ho zadal, kde a jaký text následoval po spouštěcím slově.
Váš servis odpoví zprávou v rámci časového limitu požadavku (výchozí je 30 sekund).
Antimatter zobrazí odpověď: pouze dané osobě (dočasně) nebo v kanálu pro všechny.

Příkazy patří ke komunitě a spouštěcí slovo je v jejím rámci unikátní. Vestavěné příkazy, jako jsou /join, /msg nebo /away, nelze nahradit. Aplikace (pluginy) si také mohou registrovat příkazy; viz Serverová část.

Vytvoření příkazu

Vlastní příkazy s lomítkem jsou ve výchozím nastavení zapnuté (Povolit vlastní příkazy s lomítkem v Systémová konzole › Integrace › Správa integrací, ServiceSettings.EnableCommands). Administrátoři komunit a systémoví administrátoři je ve výchozím nastavení mohou vytvářet.

Otevřete nabídku týmu, pak Nastavení týmu, klikněte na Integrace na konci karet, pak na Příkazy s lomítkem a Přidat příkaz s lomítkem.
Vyplňte Název a Popis (zobrazí se na stránkách integrací).
Zadejte Spouštěcí slovo příkazu bez lomítka a bez mezer, například weather.
Zadejte URL požadavku a zvolte Metodu požadavku: POST (výchozí) nebo GET.
Volitelně nastavte Uživatelské jméno odpovědi a Ikona odpovědi. Použijí se pouze tehdy, pokud server umožňuje integracím přepsat názvy a ikony (viz Název a ikona).
Zaškrtněte Automatické doplnění, aby se příkaz zobrazil v seznamu, když lidé zadají /, spolu s Nápovědou pro doplňování (jeho argumenty, např. [city]) a Popisem pro doplňování.
Zvolte Uložit a zkopírujte zobrazený token. Váš servis ho použije k ověření, že požadavky pocházejí z vašeho serveru.

Přes API: POST /api/v4/commands s tělem {"team_id", "trigger", "url", "method": "P", "display_name", "description", "auto_complete": true, "auto_complete_hint", "auto_complete_desc", "username", "icon_url"}. Hodnota P označuje metodu POST, G metodu GET. PUT /api/v4/commands/{command_id}/regen_token vydá nový token.

Požadavek, který váš servis přijme

Příkaz POST odešle tělo v formátu formuláře (application/x-www-form-urlencoded); příkaz GET odešle stejná pole v dotazovém řetězci. Token je také v hlavičce Authorization: Token <token>.

Pole	Hodnota
`token`	Token příkazu. Ověřte ho u každého požadavku.
`command`	Spouštěč s lomítkem, například `/weather`.
`text`	Vše, co následuje za spouštěčem, například `Paris`.
`user_id`, `user_name`	Kdo příkaz spustil.
`channel_id`, `channel_name`	Kde byl příkaz spuštěn.
`team_id`, `team_domain`	ID a URL název komunity.
`root_id`	Vlákno, pokud byl příkaz spuštěn v políčku pro odpovědi ve vláknu.
`trigger_id`	Umožňuje vaší odpovědi otevřít dialog (viz Dialogy). Platí pouze po krátkou dobu.
`response_url`	URL pro pozdější odeslání dalších odpovědí (viz Zpožděné odpovědi).
`user_mentions`, `user_mentions_ids`, `channel_mentions`, `channel_mentions_ids`	Osoby a veřejné kanály zmíněné v textu, pokud nějaké jsou. Kanály se počítají bez ohledu na to, zda jsou zapsány jako `#channel-name` nebo `~channel-name`.

Pro spuštění vlastních příkazů musí být nastavena Adresa webu (URL) serveru: Antimatter z ní sestavuje response_url.

Odpověď

Odpovězte kódem 200 s JSON (Content-Type: application/json):

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

Pole	Význam
`response_type`	`ephemeral` (výchozí): odpověď vidí pouze osoba, která příkaz spustila, a po obnovení stránky se nezachová. `in_channel`: odpověď je zveřejněna v kanálu.
`text`, `attachments`	Zpráva, stejně jako u webhooků: text v Markdownu a přílohy, včetně tlačítek a nabídek.
`username`, `icon_url`	Jméno a obrázek k zobrazení, pokud jsou povoleny přepsání. Nastavení samotného příkazu mají přednost před těmito hodnotami.
`channel_id`	Zveřejněte odpověď v jiném kanálu, jehož členem musí být daná osoba.
`goto_location`	URL, která se otevře po spuštění příkazu.
`props`, `type`	Další vlastnosti a vlastní typ příspěvku, jako u webhooků. Odpověď odeslaná do fórového kanálu vyžaduje `props.am_thread_title`, jinak je odmítnuta.
`extra_responses`	Další odpovědi, každá se stejnými poli, zveřejněné po první.
`skip_slack_parsing`	`true` ponechá text beze změny, bez převodu odkazů a zmínek ve stylu Slacku.

Odpověď, která není v JSON, se zobrazí jako dočasná zpráva s jejím tělem jako textem. 204 No Content nezobrazí nic. Jakýkoli stavový kód mimo rozsah 200–299 zobrazí uživateli chybu.

Příklad servisu

Minimální servis pro příkazy v Pythonu, pouze se standardní knihovnou:

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

Pokud služba běží na adrese soukromé sítě, musí ji systémový administrátor povolit v Povolit nespolehlivé interní připojení k (ServiceSettings.AllowedUntrustedInternalConnections).

Zpožděné odpovědi

Pro práci, která trvá déle než časový limit, odpovězte okamžitě (například dočasnou zprávou „Zpracovávám…“), a poté pošlete skutečnou odpověď na response_url. Přijímá stejný JSON jako odpověď a funguje až 5krát do 30 minut od příkazu.

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

Spusťte příkaz přes API

Skripty a boti mohou spustit libovolný příkaz, vestavěný nebo vlastní, jako by ho sami napsali:

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 vypisuje příkazy, které lidé mohou dokončovat v komunitě.

Dokončování

Příkazy vytvořené na stránkách integrací se dokončují podle spouštěče, nápovědy a popisu. Příkazy registrované aplikacemi mohou pomocí AutocompleteData podrobně popsat své podpříkazy a argumenty, od model.NewAutocompleteData(trigger, hint, helpText):

AddCommand(sub) přidá podpříkaz, který je sám o sobě AutocompleteData.
AddTextArgument(helpText, hint, pattern) přidá volný text.
AddStaticListArgument(helpText, required, items) nabízí pevný seznam AutocompleteListItem{Item, Hint, HelpText}.
AddDynamicListArgument(helpText, url, required) se vaší aplikace ptá na návrhy, jak lidé píší. URL je route vaší aplikace, například /plugins/com.example.weather/cities. Přijímá uživatele, kanál a komunitu a vrací JSON seznam {"Item", "Hint", "HelpText"}.

Varianty Named… (AddNamedTextArgument a další) přidávají příznaky --name value. Obě webové rozhraní tato doporučení zobrazují. Hodnotu s mezerami lze uvést do uvozovek, aby se jako jeden argument automaticky dokončila, například --name "my remote": dvojité uvozovky fungují pro všechny příkazy a vlastní příkazy Antimatteru, které přijímají příznaky, přijímají také jednoduché nebo složené uvozovky.

Během zadávání příkazu Fusion zobrazuje příkaz a každý jeho argument jako blok, přičemž právě zadávaný argument je zvýrazněn a doplněn o text nápovědy. Argumenty se načítají z AutocompleteData nebo, pokud chybí, z nápovědy: v nápovědě typu @[username]... #[channel] se slova začínající na @ přiřadí argumentu pro osoby a slova začínající na # argumentu pro kanál, bez ohledu na pořadí; ... znamená, že se argument opakuje, a poslední argument převezme zbytek textu.

Kanály v argumentech

V argumentech příkazu @ navrhuje osoby, # navrhuje kanály a dokončuje je jako #channel-name a ~ je dokončuje jako ~channel-name. Webové rozhraní Antimatteru a mobilní aplikace zapisují odkazy na kanály pomocí #, proto by příkaz, který očekává kanál, měl přijímat obě formy: vestavěné příkazy /join, /mute a /invite to dělají a jejich nápověda uvádí #[channel].