Comandes amb barra

Una comanda amb barra personalitzada permet als usuaris escriure /algalot a la caixa de missatges per cridar el teu servei. Antimatter envia la comanda a la teva URL i mostra la teva resposta, ja sigui només a la persona o a tot el canal.

Com funciona una comanda amb barra

1. Algú escriu /weather Paris i l'envia. El text no es publica.
2. Antimatter envia una sol·licitud HTTP a l'URL de la comanda, amb qui l'ha escrita, on i el text després de la paraula activadora.
3. El teu servei respon dins del temps límit de la sol·licitud (30 segons per defecte) amb un missatge.
4. Antimatter mostra la resposta: només a aquesta persona (efímera) o al canal per a tothom.

Les comandes pertanyen a una comunitat, i una paraula activadora és única dins d'aquesta. Les comandes integrades com /join, /msg o /away no es poden substituir. Les aplicacions (plugins) també poden registrar comandes; consulta La part del servidor.

Crea una comanda

Les comandes amb barra personalitzades estan activades per defecte (Activa les comandes amb barra personalitzades a Consola del sistema › Integracions › Gestió d'integracions, ServiceSettings.EnableCommands). Els administradors de comunitat i els administradors del sistema poden crear-les per defecte.

1. Obriu el menú de l’equip, després Configuració de l’equip, feu clic a Integracions al final de les seves pestanyes, després Comandes amb barra i Afegeix una comanda amb barra.
2. Omple el Títol i la Descripció (es mostren a les pàgines d'integracions).
3. Introdueix la Paraula activadora de la comanda, sense barra i sense espais, per exemple weather.
4. Introdueix l'URL de sol·licitud i tria el Mètode de sol·licitud: POST (per defecte) o GET.
5. Opcionalment, estableix un Nom d’usuari de la resposta i una Icona de resposta. Només s'utilitzen quan el servidor permet que les integracions substituïssin noms i icones (consulta Nom i icona).
6. Marca Autocompletar per llistar la comanda quan la gent escriu /, amb una Indicació d’autocompletar (els seus arguments, com ara [city]) i una Descripció d’autocompletar.
7. Tria Desa i copia el token que es mostra. El teu servei l'utilitza per verificar que les sol·licituds provenen del teu servidor.

Mitjançant l'API: POST /api/v4/commands amb {"team_id", "trigger", "url", "method": "P", "display_name", "description", "auto_complete": true, "auto_complete_hint", "auto_complete_desc", "username", "icon_url"}. El mètode és P per a POST o G per a GET. PUT /api/v4/commands/{command_id}/regen_token emet un nou token.

La sol·licitud que rep el teu servei

Una comanda POST envia un cos codificat en format de formulari (application/x-www-form-urlencoded); una comanda GET envia els mateixos camps a la cadena de consulta. El token també es troba a la capçalera Authorization: Token <token>.

La resposta

Respon amb 200 i JSON (Content-Type: application/json):

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

Una resposta que no és JSON es mostra com un missatge efímer amb el cos com a text. 204 No Content no mostra res. Qualsevol estat fora de l'interval 200–299 mostra un error a la persona.

Servei d'exemple

Un servei de comanda mínim en Python, amb només la biblioteca estàndard:

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

Si el servei s'executa en una adreça de xarxa privada, un administrador del sistema ha de permetre-ho a Permet connexions internes no fiables a (ServiceSettings.AllowedUntrustedInternalConnections).

Respostes amb retard

Per a tasques que trugen més temps que el límit de temps, respon de seguida (per exemple, amb un missatge efímer «Hi estic treballant…») i, a continuació, envia la resposta real a response_url mitjançant una sol·licitud POST. Rep el mateix JSON que la resposta i funciona fins a 5 vegades en 30 minuts des de la comanda.

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

Executa una comanda amb la API

Els scripts i els bots poden executar qualsevol comanda, integrada o personalitzada, com si l'haguessin teclejada:

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 llista les comandes que les persones poden autocompletar en una comunitat.

Autocompletat

Les comandes creades a les pàgines d'integracions s'autocompleten amb el seu desencadenador, la pista i la descripció. Les comandes registrades per les aplicacions poden descriure en detall les seves subcomandes i arguments amb AutocompleteData, des de model.NewAutocompleteData(trigger, hint, helpText):

• AddCommand(sub) afegeix una subcomanda, que també és un AutocompleteData.
• AddTextArgument(helpText, hint, pattern) afegeix text lliure.
• AddStaticListArgument(helpText, required, items) ofereix una llista fixa de AutocompleteListItem{Item, Hint, HelpText}.
• AddDynamicListArgument(helpText, url, required) demana a la teva aplicació suggeriments mentre les persones escriuen. L'URL és una ruta de la teva aplicació, com ara /plugins/com.example.weather/cities. Rep l'usuari, el canal i la comunitat, i retorna una llista JSON de {"Item", "Hint", "HelpText"}.

Les variants Named… (AddNamedTextArgument i altres) afegeixen les opcions --name value. Les dues interfícies web mostren aquestes suggeriments. Un valor amb espais es pot entrecomillar perquè s'autocompleti com un sol argument, per exemple --name "my remote": les cometes dobles funcionen per a qualsevol comanda, i les comandades pròpies d'Antimatter que accepten opcions també accepten cometes simples o corbes.

Mentre algú escriu una comanda, Fusion mostra la comanda i cadascun dels seus arguments com a bloc, ressaltant el que s'està escrivint amb el seu text d'ajuda. Els arguments provenen de AutocompleteData o, en absència d'aquest, de la pista: en una pista com @[username]... #[channel], les paraules que comencen per @ van a l'argument de persones i les que comencen per # a l'argument de canals, independentment de l'ordre; ... significa que l'argument es repeteix, i l'últim argument pren la resta del text.

Canals als arguments

Als arguments d'una comanda, @ suggereix persones, # suggereix canals i els completa com a #channel-name, i ~ els completa com a ~channel-name. La interfície web i l'aplicació mòbil d'Antimatter escriuen els enllaços de canals amb #, per tant, una comanda que accepti un canal hauria d'acceptar ambdues formes: les comandes integrades /join, /mute i /invite ho fan, i les seves pistes diuen #[channel].