09 · Explore o restante da API
Experimentos executáveis sem misturar demonstrações com regras de chamados.
A etapa 6 habilita /lab e dois menus de contexto. No Discord em português, a localização do nome pode aparecer como /laboratorio; o router continua usando o nome canônico lab.
Nem toda API melhora o bot quando colocada no fluxo principal. Cobrar um SKU, criar um poll ou pedir cinco tipos de campo em cada chamado tornaria a experiência pior. O laboratório oferece experimentos reais separados, e o mapa da API explica as variantes que não precisam virar uma função artificial do atendimento.
Opções resolvidas e grupos
Seção intitulada “Opções resolvidas e grupos”Execute /lab options inspect. O SubCommandGroup adiciona um nível ao caminho: lab options inspect. Escolha usuário, cargo, canal, mentionable, anexo e número. Os getters retornam os objetos em resolved enviados pelo Discord, não fazem buscas REST escondidas.
UserOption e MemberOption não são equivalentes: o usuário identifica uma conta; o membro traz dados daquele servidor e pode não estar presente no payload. Mentionable distingue usuário de cargo. Attachment oferece metadados e URL, mas o exemplo não baixa arquivos enviados pelo usuário. URLs assinadas de anexos podem expirar; salvá-las em JSON não é guardar o arquivo.
Menus de contexto
Seção intitulada “Menus de contexto”Clique com o botão direito em usuário ou mensagem e abra Apps → Inspect user/Inspect message. Esses comandos não têm opções slash nem descrição. O alvo está em ApplicationCommandData().TargetID; os dados resolvidos estão nos mapas nativos do discordgo. Leia o alvo correto em vez de supor que ele é sempre o autor da interação.
Layouts e escape hatches
Seção intitulada “Layouts e escape hatches”/lab layout combina Section, Thumbnail, Gallery e um botão discordgo encapsulado por Raw. Uma Section precisa de acessório. A galeria usa o avatar do próprio usuário para evitar depender de um link externo arbitrário.
/lab embed responde com um embed legado em uma mensagem separada. Não misture esse payload com Container/Text/Gallery V2. Raw não pula a validação nem torna suportado um componente que o Discord ou discordgo não entende.
Formulários além de texto
Seção intitulada “Formulários além de texto”/lab form demonstra StringSelect, UserSelect, RoleSelect, ChannelSelect e FileUpload dentro de Fields. Modal tem no máximo cinco componentes de topo, por isso não adicionamos mais campos. Form().Strings lê os IDs/valores selecionados; Files resolve os metadados dos arquivos. RequireStrings/RequireFiles retornam erro se a entrada necessária faltar. O exemplo responde com contagens e não persiste nem baixa esses dados.
MentionableSelect é a alternativa quando um mesmo menu deve aceitar usuário ou cargo. DefaultValues, Placeholder, MinValues, MaxValues, Disabled, emojis e opções default refinam a interface sem alterar o fluxo de roteamento. Teste uma variante por vez para entender o payload resultante.
package bot
import ( "fmt" "strings"
"github.com/bwmarrin/discordgo" dk "github.com/freitaseric/discordkit")
// The optional lab keeps API experiments out of the ticket domain.func labCommands() []*dk.CommandBuilder { return []*dk.CommandBuilder{ dk.Command("lab", "Explore outras APIs", dk.SubCommandGroup("options", "Opções tipadas", dk.SubCommand("inspect", "Inspecione valores resolvidos", dk.UserOption("user", "Usuário"), dk.RoleOption("role", "Cargo"), dk.ChannelOption("channel", "Canal").ChannelTypes(discordgo.ChannelTypeGuildText), dk.MentionableOption("mentionable", "Usuário ou cargo"), dk.AttachmentOption("file", "Arquivo"), dk.NumberOption("weight", "Peso").Min(0).Max(10))), dk.SubCommand("layout", "Veja seções e mídia"), dk.SubCommand("form", "Experimente seleções e upload"), dk.SubCommand("embed", "Veja um embed legado"), ).NameLocalizations(map[discordgo.Locale]string{discordgo.PortugueseBR: "laboratorio"}), dk.UserCommand("Inspect user"), dk.MessageCommand("Inspect message"), }}func (b *Bot) registerLab(r *dk.Router) error { handlers := map[string]dk.Handler{ "lab options inspect": func(c *dk.Context) error { lines := []string{"## Valores resolvidos"} if u, ok := c.UserOption("user"); ok { lines = append(lines, "Usuário: "+u.ID) } if m, ok := c.MemberOption("user"); ok { lines = append(lines, fmt.Sprintf("Cargos do membro: %d", len(m.Roles))) } if role, ok := c.Role("role"); ok { lines = append(lines, "Cargo: "+role.ID) } if ch, ok := c.Channel("channel"); ok { lines = append(lines, "Canal: "+ch.ID) } if m, ok := c.Mentionable("mentionable"); ok { if m.User != nil { lines = append(lines, "Mentionable usuário: "+m.User.ID) } if m.Role != nil { lines = append(lines, "Mentionable cargo: "+m.Role.ID) } } if a, ok := c.Attachment("file"); ok { lines = append(lines, fmt.Sprintf("Arquivo: %s (%d bytes)", safe(a.Filename), a.Size)) } if n, ok := c.Float("weight"); ok { lines = append(lines, fmt.Sprintf("Peso: %.2f", n)) } return c.Ephemeral(message(dk.Text(strings.Join(lines, "\n")))) }, "lab layout": func(c *dk.Context) error { avatar := c.User().AvatarURL("128") return c.Ephemeral(message(dk.Container( dk.Section(dk.Text("## Seu perfil"), dk.Text("Uma seção combina texto com um acessório.")).Accessory(dk.Thumbnail(avatar).Description("Seu avatar")), dk.Separator().Large().Divider(true), dk.Gallery(dk.MediaItem(avatar).Description("Avatar do solicitante")), dk.Row(dk.Raw(discordgo.Button{Label: "Documentação", Style: discordgo.LinkButton, URL: "https://discordkit.freitaseric.com"})), ).AccentColor(0x38D9B0))) }, "lab embed": func(c *dk.Context) error { return c.Ephemeral(dk.MessageSpec{Embeds: []*discordgo.MessageEmbed{{Title: "Embed legado", Description: "Não combine embeds com layouts V2.", Color: 0x38D9B0}}}) }, "lab form": func(c *dk.Context) error { form, err := dk.Form("/lab/form", "Formulário de laboratório", dk.Field("Categoria", dk.StringSelect("category").Options(dk.SelectOption("Dúvida", "question"), dk.SelectOption("Problema", "issue")).Required()), dk.Field("Pessoas", dk.UserSelect("people").MinValues(0).MaxValues(2)), dk.Field("Cargos", dk.RoleSelect("roles").MinValues(0).MaxValues(2)), dk.Field("Canal", dk.ChannelSelect("channel").ChannelTypes(discordgo.ChannelTypeGuildText).MinValues(0).MaxValues(1)), dk.Field("Arquivo opcional", dk.FileUpload("evidence").Required(false).MaxValues(1)), ).Build() if err != nil { return err } return c.ShowModal(form) }, "Inspect user": func(c *dk.Context) error { data := c.Interaction.ApplicationCommandData() u := data.Resolved.Users[data.TargetID] if u == nil { return c.EphemeralText("Usuário não resolvido.") } return c.EphemeralText("ID do usuário: " + u.ID) }, "Inspect message": func(c *dk.Context) error { data := c.Interaction.ApplicationCommandData() m := data.Resolved.Messages[data.TargetID] if m == nil { return c.EphemeralText("Mensagem não resolvida.") } return c.EphemeralText("ID da mensagem: " + m.ID) }, } for path, h := range handlers { if err := r.Command(path, h); err != nil { return err } } return r.Modal("/lab/form", func(c *dk.Context) error { category, err := c.Form().RequireStrings("category") if err != nil { return err } people, _ := c.Form().Strings("people") roles, _ := c.Form().Strings("roles") channels, _ := c.Form().Strings("channel") files, _ := c.Form().Files("evidence") return c.EphemeralText(fmt.Sprintf("Categoria: %s · pessoas: %d · cargos: %d · canais: %d · arquivos: %d. Nada foi salvo ou baixado.", strings.Join(category, ","), len(people), len(roles), len(channels), len(files))) })}Inspecione uma sincronização antes de aplicá-la
Seção intitulada “Inspecione uma sincronização antes de aplicá-la”Com uma sessão aberta, o trecho abaixo substitui temporariamente a chamada de sync em main. A revisão dos nomes e tipos deve acontecer antes de qualquer exclusão:
remote, err := session.ApplicationCommands(session.State.User.ID, cfg.GuildID)if err != nil { return err }plan := dk.DiffCommands(remote, commands, false)slog.Info("sync preview", "create", len(plan.Create), "update", len(plan.Update), "delete", len(plan.Delete))DiffCommands calcula um plano a partir de duas listas já disponíveis, sem rede. SyncPlan.Empty indica ausência de mudanças. Delete: true deve ser uma decisão consciente para uma aplicação que você controla inteiramente.
Quando recorrer ao discordgo
Seção intitulada “Quando recorrer ao discordgo”Use c.Session para endpoints fora do ciclo de resposta, como editar uma mensagem pública antiga por canal/ID. MessageSpec.MessageEdit(channelID, messageID) converte o payload; Session.ChannelMessageEditComplex envia. Confira a permissão do bot, valide o destino e passe discordgo.WithContext(c.Context()) quando aplicável.
Evite responder à mesma interação diretamente via Session.InteractionRespond: isso passa por fora do controle de estado do Context. Use ModalOf quando já tiver componentes nativos de um modal; prefira Form/Field nos novos exemplos.
Confira: execute os quatro comandos de laboratório, os dois menus de contexto e envie o formulário com/sem arquivo opcional. O arquivo de chamados deve permanecer inalterado.
Exercício: troque o select de cargos por MentionableSelect, leia os valores e explique como distinguir os tipos usando os dados resolvidos. Não transforme uma seleção visual em autorização de equipe.