Mga Slash Command

Pang-aalok ng custom slash command ang pagpapa-type ng /something sa message box upang tumawag sa iyong service. Ipinapadala ng Antimatter ang command sa iyong URL at ipinapakita ang iyong sagot, maaaring sa isang tao lamang o sa buong channel.

Paano gumagana ang slash command

1. May nag-type ng /weather Paris at ipinadala ito. Hindi ipinost ang text.
2. Ipinapadala ng Antimatter ang HTTP request sa URL ng command, kasama ang sinumang nag-type, saan, at ang text pagkatapos ng trigger.
3. Sasagutin ng iyong service ang request sa loob ng request timeout (30 segundo ang default) gamit ang mensahe.
4. Ipinapakita ng Antimatter ang sagot: sa iisang tao lamang (ephemeral) o sa channel para sa lahat.

Ang mga command ay kinalipat ng isang community, at ang trigger word ay unique sa loob nito. Ang mga built-in commands tulad ng /join, /msg o /away ay hindi maaaring palitan. Maaari ring magparehistro ng commands ang mga Apps (plugins); tingnan ang The server part.

Paggawa ng command

Naka-on by default ang mga custom slash command (Enable Custom Slash Commands sa System Console › Integrations › Integration Management, ServiceSettings.EnableCommands). Maaari ng mga community admin at system admin na gumawa ng mga ito by default.

1. Buksan ang iyong avatar sa itaas na kanang sulok, tapos Integrations › Slash commands, tapos Add Slash Command.
2. Punan ang Title at Description (ipinapakita sa mga pahina ng integrations).
3. Ilagay ang Command Trigger Word, nang walang slash at walang spaces, halimbawa weather.
4. Ilagay ang Request URL at piliin ang Request Method: POST (ang default) o GET.
5. Pwede mong i-set ang Response Username at Response Icon. Ginagamit lamang ito kapag pinapayagan ng server na palitan ng mga integrations ang mga pangalan at icon (tingnan ang Pangalan at icon).
6. Tikman ang Autocomplete upang i-list ang command kapag nagta-type ng /, kasama ang Autocomplete Hint (ang mga arguments nito, tulad ng [city]) at Autocomplete Description.
7. Piliin ang Save, at i-copy ang token na ipinapakita. Ginagamit nito ng iyong service upang siguraduhin na mula sa iyong server ang mga request.

Sa pamamagitan ng API: POST /api/v4/commands gamit ang {"team_id", "trigger", "url", "method": "P", "display_name", "description", "auto_complete": true, "auto_complete_hint", "auto_complete_desc", "username", "icon_url"}. Ang P ay para sa POST, at ang G ay para sa GET. Ang PUT /api/v4/commands/{command_id}/regen_token ay naglalabas ng bagong token.

Ang hiling na tinatanggap ng iyong serbisyo

Ang POST command ay nagpapadala ng form-encoded na katawan (application/x-www-form-urlencoded); ang GET command ay nagpapadala ng mga parehong field sa query string. Nakapaloob din ang token sa Authorization: Token <token> header.

Ang sagot

Sagutin ang 200 gamit ang JSON (Content-Type: application/json):

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

Ang sagot na hindi JSON ay ipapakita bilang ephemeral na mensahe na may katawan bilang teksto. Ang 204 No Content ay walang ipapakita. Ang anumang status na nasa labas ng 200–299 ay ipapakita sa tao ang isang error.

Halimbawang serbisyo

Isang minimal na command service sa Python, gamit lamang ang standard library:

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

Kung ang service ay tumatakbo sa isang private network address, dapat ay pahintulutan nito ng isang system admin sa Allow untrusted internal connections to (ServiceSettings.AllowedUntrustedInternalConnections).

Mga hinala na sagot

Para sa mga gawain na mas matagal kaysa sa timeout, sagutin agad (halimbawa, gamit ang ephemeral na "Working on it…"), tapos i-POST ang tunay na sagot sa response_url. Tinatanggap nito ang parehong JSON ng response, at gumagawa hanggang 5 beses sa loob ng 30 minuto mula sa command.

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

Paggamit ng command gamit ang API

Ang mga script at bot ay maaaring gumamit ng anumang command, built-in o custom, parang sila ang nagsulat nito:

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"}'

Ang GET /api/v4/teams/{team_id}/commands/autocomplete ay naglilista ng mga command na maaaring i-autocomplete ng mga tao sa isang community.

Autocomplete

Ang mga command na nabuo sa mga integrations pages ay nag-a-autocomplete gamit ang kanilang trigger, hint, at description. Ang mga command na narehistro ng mga app ay maaaring ilarawan nang detalyado ang kanilang subcommands at arguments gamit ang AutocompleteData, mula sa model.NewAutocompleteData(trigger, hint, helpText):

• Ang AddCommand(sub) ay nagdadagdag ng isang subcommand, na isang AutocompleteData rin.
• Ang AddTextArgument(helpText, hint, pattern) ay nagdadagdag ng libreng text.
• Ang AddStaticListArgument(helpText, required, items) ay nag-aalok ng isang fixed list ng AutocompleteListItem{Item, Hint, HelpText}.
• Ang AddDynamicListArgument(helpText, url, required) ay humihingi ng mga mungkahi mula sa iyong app habang nagsusulat ang mga tao. Ang URL ay isang route ng iyong app, tulad ng /plugins/com.example.weather/cities. Tinatanggap nito ang user, channel, at community, at nagbabalik ng isang JSON list ng {"Item", "Hint", "HelpText"}.

Ang mga Named… variants (AddNamedTextArgument at iba pa) ay nagdadagdag ng mga --name value flags. Ipinapakita ng parehong web interfaces ang mga mungkahi na ito.

Habang nagta-type ng command ang isang tao, ipapakita ng Fusion ang command at bawat isa sa kanyang mga argumento bilang isang block, na ang kasalukuyang tinata-type ay naka-highlight kasama ang kanyang help text. Mula sa AutocompleteData ang mga argumento, o kung wala ito, mula sa hint: sa isang hint tulad ng @[username]... #[channel], ang mga salitang nagsisimula sa @ ay pumupunta sa argumento ng tao, at ang mga nagsisimula sa # ay pumupunta sa argumento ng channel, anuman ang kanilang pagkakasunod; ang ... ay nangangahulugang paulit-ulit ang argumento, at ang huling argumento ay tumatanggap ng natitirang teksto.

Mga channel sa mga argumento

Sa mga argumento ng isang command, ang @ ay nag-aalok ng mga tao, ang # ay nag-aalok ng mga channel at nagkumpleto sila bilang #channel-name, at ang ~ ay nagkumpleto sila bilang ~channel-name. Sinusulat ng web interface at mobile app ng Antimatter ang mga link ng channel gamit ang #, kaya ang isang command na tumatanggap ng channel ay dapat tanggapin ang parehong anyo: ginagawa ito ng built-in /join, /mute at /invite, at ang kanilang mga hint ay nagsasabi ng #[channel].