Componentes e modais

Mensagens de bots podem levar componentes (botões e menus) e abrir modais (formulários). Cada clique ou envio chega ao bot como uma interação e deve ser respondida em 3 segundos.

Componentes de mensagem: botões e menus#

Mensagens enviadas por bots aceitam components: até 5 linhas (row), cada uma com 1 a 5 botões ou exatamente 1 menu (nunca os dois). Funciona em POST /guilds/:g/channels/:c/messages, nos callbacks message e update, nos follow-ups e em PATCH @original. Pessoas não enviam componentes (o campo é ignorado para elas). Um botão ou menu precisa de customId (1 a 100 caracteres, único na mensagem); é ele que volta no INTERACTION_CREATE.

{
  "body": "Escolha uma opção",
  "components": [
    { "type": "row", "components": [
      { "type": "button", "customId": "painel:aceitar", "label": "Aceitar as regras", "style": "success", "emoji": "✅" },
      { "type": "button", "customId": "painel:ajuda", "label": "Ajuda", "style": "secondary" },
      { "type": "button", "label": "Site", "style": "link", "url": "https://vsync.lat" }
    ] },
    { "type": "row", "components": [
      { "type": "select", "customId": "painel:interesses", "placeholder": "Escolha seus interesses", "minValues": 1, "maxValues": 2,
        "options": [
          { "label": "Jogos", "value": "jogos", "emoji": "🎮" },
          { "label": "Música", "value": "musica", "description": "Playlists e bandas" }
        ] }
    ] }
  ]
}

Botões:

Todo botão precisa de label, emoji ou os dois. Um link http:// (por exemplo https://vsync.lat) é recusado com 400.

Menus: placeholder (até 150 caracteres), options (1 a 25) com label e value (1 a 100 caracteres, value único), description (até 100), emoji e default; minValues (padrão 1) e maxValues (padrão 1, no máximo o número de opções). O menu aparece como lista suspensa e a pessoa pode escolher de minValues a maxValues opções.

Erros: componentes inválidos devolvem 400 { "error": "Componentes inválidos: ..." } dizendo o que está errado.

Cliques: quando alguém clica num botão ou escolhe no menu, a API cria uma interação do tipo component e a entrega ao bot (veja a próxima seção). Só dá para clicar em mensagens do próprio bot; componentes disabled recusam o clique. Os valores de um menu são validados antes de chegar ao bot (opções existentes, sem repetir, dentro de minValues e maxValues).

Mensagens efêmeras com componentes: respostas com "ephemeral": true também podem ter components. Só quem recebeu a mensagem consegue clicar, e o clique chega como interação normal, com a mensagem efêmera em data.message. Elas valem enquanto a interação que as criou (15 minutos).

Modais (formulários)#

Um modal é um formulário com 1 a 5 campos de texto. Abra-o respondendo a um comando ou a um clique com o callback modal:

curl -s -X POST $API/interactions/$ID/$ITOKEN/callback -H "Content-Type: application/json" -d '{
  "type": "modal",
  "data": {
    "customId": "feedback:enviar",
    "title": "Enviar feedback",
    "fields": [
      { "customId": "assunto", "label": "Assunto", "style": "short", "maxLength": 100 },
      { "customId": "mensagem", "label": "Mensagem", "style": "paragraph", "placeholder": "Conte a sua ideia", "minLength": 5, "maxLength": 1000 }
    ]
  }
}'

Como funciona:

1. O callback modal conta como a resposta da interação (uma só). Depois dele, follow-ups devolvem 409. A pessoa vê o formulário no app (evento guild-modal na conexão dela); um novo modal do mesmo aplicativo substitui o anterior.
2. Quando ela envia, a API valida no servidor: é a mesma pessoa, no mesmo servidor e canal, dentro de 15 minutos, campos obrigatórios preenchidos e tamanhos dentro de minLength e maxLength. Se algo estiver errado, a API devolve o erro a ela e o bot não vê nada; o modal continua pendente até expirar.
3. Se estiver tudo certo, o modal é consumido (não dá para enviar duas vezes) e o bot recebe INTERACTION_CREATE com type: "modal_submit" e data.fields. Responda em 3 segundos, como em qualquer interação.
4. Um modal_submit não pode abrir outro modal (400).