Pular para o conteúdo
Documentação DiscordKit

09 · Explore o restante da API

Experimentos executáveis sem misturar demonstrações com regras de chamados.

Abrir texto

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.

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.

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.

/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.

/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.

internal/bot/lab.go
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.

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.


← Anterior: 08 · Teste e opere o bot