Comandos

Registrar, trocar e apagar

await app.rest.listCommands();                        // { commands, truncated }
await app.rest.createCommand({ command, serverId });  // sem serverId = global
await app.rest.updateCommand({ commandId, command });
await app.rest.deleteCommand({ commandId });

Sem serverId, o comando é global — vale em todo servidor onde o App está instalado. Com ele, o comando existe só naquele servidor, o que é o caminho para testar sem expor o comando pela base inteira.

O GET devolve { commands, truncated }: truncated avisa que você passou do que a listagem carrega, e não é paginação — não existe cursor aqui. Ignorá-lo faz o seu App não achar um comando que existe e registrá-lo de novo, que é o defeito que o campo existe para impedir.

Os três tipos

Os dois de menu não têm argumento porque o alvo já é o contexto: quem acionou clicou em alguém, ou numa mensagem, e é isso que chega no data da interação.

A árvore de opções

await app.rest.createCommand({
  command: {
    type: "chat",
    name: "clima",
    description: "o tempo de uma cidade",
    options: [
      { type: "string", name: "cidade", description: "a cidade",
        required: true, autocomplete: true },
      { type: "integer", name: "dias", description: "quantos dias",
        minValue: 1, maxValue: 7 },
    ],
  },
});

Quem pode acionar

requiredPermission tranca um comando numa permissão de cargo. Nulo é sem exigência, e ele não substitui o escopo: o teto da instalação continua valendo, e um comando que exige o que a instalação já não autoriza responde APP_MISSING_SCOPE.

Na leitura existe um terceiro valor: "desconhecida", que quer dizer ninguém. Ele aparece quando o Trivo não sabe o que aquele comando exige, e traduzi-lo para null no seu código abriria o comando para o servidor inteiro — exatamente o contrário do que ele diz.

O vocabulário de permissões, e o cruzamento com os escopos da instalação, estão em Permissões e escopos.

Depois do registro, é uma interação

Alguém aciona o comando e o Trivo abre uma interação com um prazo curto, entregue ao seu App pelo Gateway ou pelo endpoint. O ciclo, os prazos e as oito formas de responder estão em Interações; os botões, seleções, cartões e formulários que cabem na resposta estão em Componentes e formulários.