Making Requests

Requests are how most bot actions are done. Stuff like sending messages, creating channels and managing users. AckCord represents every request as an object you construct. There are many ways to send an request, but the most common are through the end action on controllers, and using RequestsHelper. To create a request object, you can either just construct it normally, or use the syntax package.

import ackcord.requests._
import ackcord.syntax._

client.onEventSideEffects { implicit c => 
  {
    case APIMessage.ChannelCreate(_, channel: TextGuildChannel, _, _) =>
      //There is also CreateMessage.mkContent for this specific pattern
      val constructManually = CreateMessage(channel.id, CreateMessageData(content = "Hello World"))
      val usingSyntax = channel.sendMessage(content = "Hello World")
  }
}

Next you need to send the request. For this example we will use RequestsHelper. This object can be found on the client. That also means it’s time to move away from onEventSideEffects. Even though sending requests can never return option, the run command will return an OptFuture[A]. OptFuture[A] is a wrapper around Future[Option[A]]. This is done due to the many cache lookup methods that return Options. When your event handler returns OptFuture[Unit], you’re recommended to use DiscordClient#onEventAsync and ActionBuilder#asyncOpt instead.

client.onEventAsync { implicit c => 
  {
    case APIMessage.ChannelCreate(_, channel: TextGuildChannel, _, _) =>
      client.requestsHelper.run(channel.sendMessage(content = "Hello World")).map(_ => ())
  }
}

The RequestsHelper object also contains lots of small helpers to deal with OptFuture[A] and requests.

client.onEventAsync { implicit c => 
  {
    case msg: APIMessage.ChannelCreate =>
      import client.requestsHelper._
      for {
        //optionPure lifts an Option into the dsl
        guildChannel <- optionPure(msg.channel.asGuildChannel)
        guild        <- optionPure(guildChannel.guild)
        //runOption runs an Option[Request].
        msg          <- runOption(guild.textChannels.headOption.map(_.sendMessage("FIRST")))
        //Running a request without using the extra syntax
        _            <- run(CreateMessage.mkContent(msg.channelId, "Another message"))
      } yield ()
  }
}