From d0df9505b5807b24e561ebbf1a4cb3d38e6f5c3c Mon Sep 17 00:00:00 2001 From: Filip Hoffmann Date: Tue, 5 May 2026 01:36:20 +0200 Subject: [PATCH] readme! --- examples/http_interactions/README.md | 82 +++++++++++++++++++----- examples/http_interactions/gleam.toml | 11 ++-- examples/http_interactions/manifest.toml | 1 - 3 files changed, 70 insertions(+), 24 deletions(-) diff --git a/examples/http_interactions/README.md b/examples/http_interactions/README.md index dae1f7b..8d2e24f 100644 --- a/examples/http_interactions/README.md +++ b/examples/http_interactions/README.md @@ -1,24 +1,72 @@ # http_interactions -[![Package Version](https://img.shields.io/hexpm/v/http_interactions)](https://hex.pm/packages/http_interactions) -[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/http_interactions/) +## Intro +Welcome! This document will help you understand: +- what are HTTP interactions +- why we use HTTP interactions +- how to use HTTP interactions -```sh -gleam add http_interactions@1 -``` -```gleam -import http_interactions +## What? -pub fn main() -> Nil { - // TODO: An example of the project in use -} -``` +HTTP interactions are a way to receive `INTERACTION_CREATE` events through a webhook rather than the gateway. -Further documentation can be found at . +Bots using HTTP interactions can respond to: +- slash command usage +- message command usage +- user command usage +- message component usage +- modal submission -## Development +Bots using HTTP interactions: +- cannot use gateway interactions (will not receive the gateway `INTERACTION_CREATE` events) +- can use the gateway for other events -```sh -gleam run # Run the project -gleam test # Run the tests -``` +Bots that use HTTP interactions and don't use the gateway show up in the member list without a displayed status. + +## Why? + +This is useful for serverless setups where the only event you handle is `INTERACTION_CREATE`, and don't require access to the gateway. + +Right now, in grom, it is the only way to use interactions, seeing as the gateway is in a broken state. + +## How? + +We're going to use wisp to create a webhook handler, register it with Discord, and hopefully have HTTP interactions working by the end of the night. + +Prerequisites: +- a domain you own + - We're going to be creating a public internet-facing API, so you'll need this (and an SSL certificate) +- a deployment environment (self-hosted server, VPS, fly.io, AWS Lambda, etc.) +- a Discord app + - its application ID (grab it from the General Information page) + - We normally take this from the `READY` event, but since we don't have that here, we can just use an environment variable and it'll work the same way. + - its public key (grab it from the General Information page) + - Since our API is facing the internet, we have to make sure only Discord sends our app interactions. + - When you create an application, Discord creates a public/private key pair. + - They use the private key to sign messages sent to our interactions endpoint, and give us the public key to verify the message's authenticity. + - This allows us to make sure that the message was from Discord, and that it was intended for our application. + - its bot token (grab it from the Bot page) + +## So, let's do this: + +Want to understand how the code works? You're in luck - just read it top to bottom. + +There are lots of comments there, and they have code right beside them, so I won't repeat them here. + +## Finalizing: + +So, you know how this works, now it's time to push it to prod. + +Some stuff I like to use: +- Caddy - a reverse proxy (with free SSL certificates from Let's Encrypt) +- Docker - specifically [this guide](https://gleam.run/deployment/linux-server/) (or if you're using fly.io - [this one](https://gleam.run/deployment/fly/)) +- Cloudflare - proxy your API, you'll get a bunch of goodies + +Now, you got it facing the internet, amazing. It's time to let Discord know about it. + +In your bot's General Information page of the Discord Development Portal, +paste in the URL of your interactions endpoint - for example: https://grom.folospior.dev/discord-interactions + +Discord will send you two PING requests, and if those pass, it will display a successful message in the development portal. + +Interactions should now be getting sent straight to your webhook. diff --git a/examples/http_interactions/gleam.toml b/examples/http_interactions/gleam.toml index 2b35f7e..1b6807b 100644 --- a/examples/http_interactions/gleam.toml +++ b/examples/http_interactions/gleam.toml @@ -13,16 +13,15 @@ version = "1.0.0" # https://gleam.run/writing-gleam/gleam-toml/. [dependencies] -gleam_stdlib = ">= 1.0.0 and < 2.0.0" -wisp = ">= 2.2.2 and < 3.0.0" -grom = { path = "../.." } envoy = ">= 1.2.0 and < 2.0.0" gleam_erlang = ">= 1.3.0 and < 2.0.0" -gleam_otp = ">= 1.2.0 and < 2.0.0" -mist = ">= 6.0.3 and < 7.0.0" gleam_http = ">= 4.3.0 and < 5.0.0" +gleam_otp = ">= 1.2.0 and < 2.0.0" +gleam_stdlib = ">= 1.0.0 and < 2.0.0" +grom = { path = "../.." } logging = ">= 1.5.0 and < 2.0.0" -gleam_json = ">= 3.1.0 and < 4.0.0" +mist = ">= 6.0.3 and < 7.0.0" +wisp = ">= 2.2.2 and < 3.0.0" [dev_dependencies] gleeunit = ">= 1.0.0 and < 2.0.0" diff --git a/examples/http_interactions/manifest.toml b/examples/http_interactions/manifest.toml index fec03a5..7d204b8 100644 --- a/examples/http_interactions/manifest.toml +++ b/examples/http_interactions/manifest.toml @@ -39,7 +39,6 @@ packages = [ envoy = { version = ">= 1.2.0 and < 2.0.0" } gleam_erlang = { version = ">= 1.3.0 and < 2.0.0" } gleam_http = { version = ">= 4.3.0 and < 5.0.0" } -gleam_json = { version = ">= 3.1.0 and < 4.0.0" } gleam_otp = { version = ">= 1.2.0 and < 2.0.0" } gleam_stdlib = { version = ">= 1.0.0 and < 2.0.0" } gleeunit = { version = ">= 1.0.0 and < 2.0.0" } -- 2.51.2