Comandos de Barra

Um comando de barra personalizado permite que as pessoas digitem /algo na caixa de mensagem para chamar seu serviço. O Antimatter envia o comando para sua URL e exibe sua resposta, seja apenas para a pessoa ou para todo o canal.

Como um comando de barra funciona

1. Alguém digita /weather Paris e envia. O texto não é publicado.
2. O Antimatter envia uma requisição HTTP para a URL do comando, com quem digitou, onde e o texto após o gatilho.
3. Seu serviço responde dentro do tempo limite da requisição (30 segundos por padrão) com uma mensagem.
4. O Antimatter exibe a resposta: apenas para essa pessoa (efêmera) ou no canal para todos.

Os comandos pertencem a uma comunidade, e uma palavra de gatilho é única dentro dela. Comandos embutidos, como /join, /msg ou /away, não podem ser substituídos. Aplicativos (plugins) também podem registrar comandos; veja A parte do servidor.

Criar um comando

Os comandos de barra personalizados estão ativados por padrão (Ativar Comandos Slash Personalizados em Console do Sistema › Integrações › Gerenciamento de Integração, ServiceSettings.EnableCommands). Administradores da comunidade e administradores do sistema podem criá-los por padrão.

1. Abra seu avatar no canto superior direito, depois Integrações › Comandos de barra, e depois Adicionar Comando Slash.
2. Preencha o Título e a Descrição (exibidos nas páginas de integrações).
3. Digite a Palavra Gatilho do Comando, sem a barra e sem espaços, por exemplo weather.
4. Digite a URL da solicitação e escolha o Método da Requisição: POST (padrão) ou GET.
5. Opcionalmente, defina um Usuário de Resposta e um Ícone de Resposta. Eles são usados apenas quando o servidor permite que as integrações substituam nomes e ícones (veja Nome e ícone).
6. Marque Autocompletar para listar o comando quando as pessoas digitarem /, com uma Sugestão de Preenchimento Automático (seus argumentos, como [city]) e uma Descrição do preenchimento automático.
7. Escolha Salvar e copie o token exibido. Seu serviço o usa para verificar se as solicitações vêm do seu servidor.

Com a API: POST /api/v4/commands com {"team_id", "trigger", "url", "method": "P", "display_name", "description", "auto_complete": true, "auto_complete_hint", "auto_complete_desc", "username", "icon_url"}. O método é P para POST ou G para GET. PUT /api/v4/commands/{command_id}/regen_token emite um novo token.

A solicitação recebida pelo seu serviço

Um comando POST envia um corpo codificado em formulário (application/x-www-form-urlencoded); um comando GET envia os mesmos campos na string de consulta. O token também está no cabeçalho Authorization: Token <token>.

A resposta

Responda com 200 e JSON (Content-Type: application/json):

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

Uma resposta que não seja JSON é exibida como uma mensagem efêmera com o corpo como seu texto. 204 No Content não exibe nada. Qualquer status fora de 200–299 mostra um erro à pessoa.

Serviço de exemplo

Um serviço de comando mínimo em Python, usando apenas a biblioteca padrão:

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

Se o serviço estiver em um endereço de rede privada, um administrador do sistema deve permiti-lo em Permitir conexão interna não confiável (ServiceSettings.AllowedUntrustedInternalConnections).

Respostas com atraso

Para trabalhos que levam mais tempo que o tempo limite, responda imediatamente (por exemplo, com uma mensagem efêmera "Trabalhando nisso…") e, em seguida, envie a resposta real via POST para response_url. Ela aceita o mesmo JSON da resposta e pode ser usada até 5 vezes dentro de 30 minutos após o comando.

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

Executar um comando pela API

Scripts e bots podem executar qualquer comando, integrado ou personalizado, como se o tivessem digitado:

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 lista os comandos que as pessoas podem autocompletar em uma comunidade.

Autocompletar

Comandos criados nas páginas de integrações são autocompletados com seu gatilho, dica e descrição. Comandos registrados por aplicativos podem descrever seus subcomandos e argumentos em detalhes com AutocompleteData, a partir de model.NewAutocompleteData(trigger, hint, helpText):

• AddCommand(sub) adiciona um subcomando, que é ele mesmo um AutocompleteData.
• AddTextArgument(helpText, hint, pattern) adiciona texto livre.
• AddStaticListArgument(helpText, required, items) oferece uma lista fixa de AutocompleteListItem{Item, Hint, HelpText}.
• AddDynamicListArgument(helpText, url, required) solicita sugestões ao seu aplicativo conforme as pessoas digitam. A URL é uma rota do seu aplicativo, como /plugins/com.example.weather/cities. Ela recebe o usuário, o canal e a comunidade, e retorna uma lista JSON de {"Item", "Hint", "HelpText"}.

As variantes Named… (AddNamedTextArgument e outras) adicionam flags --name value. Ambas as interfaces web exibem essas sugestões.

Enquanto alguém digita um comando, o Fusion exibe o comando e cada um dos seus argumentos como um bloco, com o que está sendo digitado destacado junto com o texto de ajuda. Os argumentos vêm de AutocompleteData ou, na sua ausência, da dica: em uma dica como @[username]... #[channel], as palavras que começam com @ vão para o argumento de pessoas e as que começam com # para o argumento de canais, independentemente da ordem; ... significa que o argumento se repete, e o último argumento recebe o restante do texto.

Canais nos argumentos

Nos argumentos de um comando, @ sugere pessoas, # sugere canais e os completa como #channel-name, e ~ os completa como ~channel-name. A interface web e o aplicativo móvel do Antimatter escrevem links de canais com #, portanto, um comando que recebe um canal deve aceitar ambos os formatos: os comandos integrados /join, /mute e /invite fazem isso, e suas dicas indicam #[channel].