Skip to content

Hikari Fundamentals#

hikari is the underlying framework arc uses to communicate with Discord. It handles making requests to Discord, serializing & deserializing payloads, maintaining the connection the Gateway (if applicable), and more.

In this guide, you'll learn the basics of how to use hikari with arc, make common requests to Discord's REST API and access your bot's cache.

Wait, what the hell is an API?

An API, or Application Programming Interface, is simply a way for two computers to talk to eachother. It defines standard message formats, endpoints, and the rules of communication (such as ratelimits or errors).

For the purposes of this documentation, that's more or less all you need to know, hikari handles all the low-level details for you.

Think of it this way: if a UI is a way for computers to talk to you, then an API is a way for computers to talk to eachother.

P.S.: REST stands for Representational State Transfer and is simply a way of designing an API. This isn't really important to us however.

Using Discord's REST API#

The most common use for interacting with the REST API directly is if you want to make your bot perform an action, such as creating a channel, kicking someone, or editing guild settings. To perform a REST API call, you need to access your client's rest module.

@client.include
@arc.slash_command("make_channel", "Make a new channel!")
async def make_channel(
    ctx: arc.GatewayContext,
    name: arc.Option[str, arc.StrParams("The channel's name")]
) -> None:
    await client.rest.create_guild_text_channel(ctx.guild_id, name)
    await ctx.respond("Channel created!")

@client.include
@arc.slash_command("make_channel", "Make a new channel!")
async def make_channel(
    ctx: arc.RESTContext,
    name: arc.Option[str, arc.StrParams("The channel's name")]
) -> None:
    await client.rest.create_guild_text_channel(ctx.guild_id, name)
    await ctx.respond("Channel created!")

In this snippet, we use rest.create_guild_text_channel() to create a new text channel in the guild the command is invoked in, with the given name.

Tip

For a full list of all REST API requests you can make, see the hikari reference. This list may be daunting at first, as it lists every single endpoint and their parameters.

Using your client's cache#

Gateway only

This section is only relevant to those using a Gateway client, as REST bots do not have a cache.

While the REST API can be used to fetch data from Discord directly, this is generally not recommended, as it is very slow, consumes ratelimits and is generally inefficient. Instead, you should use your client's cache implementation. To access objects stored in the cache, you need to access your gateway client's cache module.

@client.include
@arc.slash_command("roles", "List all the roles in this guild!")
async def channel_info(ctx: arc.GatewayContext) -> None:
    # This returns a mapping of {role_id: role object}
    roles = client.cache.get_roles_view_for_guild(ctx.guild_id)
    # Concatenate the mentions into a string
    role_mentions = " ".join(role.mention for role in roles.values())

    await ctx.respond(f"The roles in this guild are: {role_mentions}")

Here, we get all roles that exist in the guild the command was invoked in, then respond with their mentions.

Tip

For a full list of all cache methods, see the hikari reference.