From 59a611b05a5c0bc99b48ac99259327f5d8c5e07a Mon Sep 17 00:00:00 2001 From: Noah Petherbridge Date: Sat, 12 Aug 2023 22:04:24 -0700 Subject: [PATCH] Update README --- README.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++-- pkg/commands.go | 1 + 2 files changed, 49 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 85b9311..998bd2d 100644 --- a/README.md +++ b/README.md @@ -246,7 +246,7 @@ For better integration with your website, the chat server exposes some data via Current API endpoints include: -* `GET /api/statistics` +## GET /api/statistics Returns basic info about the count and usernames of connected chatters: @@ -257,7 +257,7 @@ Returns basic info about the count and usernames of connected chatters: } ``` -* `POST /api/blocklist` +## POST /api/blocklist Your server may pre-cache the user's blocklist for them **before** they enter the chat room. Your site will use the `AdminAPIKey` parameter that @@ -293,6 +293,52 @@ The JSON response to this endpoint may look like: } ``` +# Webhook URLs + +BareRTC supports setting up webhook URLs so the chat server can call out to _your_ website in response to certain events, such as allowing users to send you reports about messages they receive on chat. + +Webhooks are configured in your settings.toml file and look like so: + +```toml +[[WebhookURLs]] + Name = "report" + Enabled = true + URL = "http://localhost:8080/v1/barertc/report" +``` + +All Webhooks will be called as **POST** requests and will contain a JSON payload that will always have the following two keys: + +* `Action` will be the name of the webhook (e.g. "report") +* `APIKey` will be your AdminAPIKey as configure in the settings.toml (shared secret so your web app can authenticate BareRTC's webhooks). + +The JSON payload may also contain a relevant object per the Action -- see the specific examples below. + +## Report Webhook + +Enabling this webhook will cause BareRTC to display a red "Report" flag button underneath user messages on chat so that they can report problematic messages to your website. + +The webhook name for your settings.toml is "report" + +Example JSON payload posted to the webhook: + +```javascript +{ + "Action": "report", + "APIKey": "shared secret from settings.toml#AdminAPIKey", + "Report": { + "FromUsername": "sender", + "AboutUsername": "user being reported on", + "Channel": "lobby", // or "@username" for DM threads + "Timestamp": "(stringified timestamp of chat message)", + "Reason": "It's spam", + "Comment": "custom user note about the report", + "Message": "the actual message that was being reported on", + } +} +``` + +BareRTC expects your webhook URL to return a 200 OK status code or it will surface an error in chat to the reporter. + # Tour of the Codebase This app uses WebSockets and WebRTC at the very simplest levels, without using a framework like `Socket.io`. Here is a tour of the codebase with the more interesting modules listed first. diff --git a/pkg/commands.go b/pkg/commands.go index 7468016..4b53a7f 100644 --- a/pkg/commands.go +++ b/pkg/commands.go @@ -57,6 +57,7 @@ func (s *Server) ProcessCommand(sub *Subscriber, msg Message) bool { "* `/deop ` to remove operator rights from a user\n" + "* `/shutdown` to gracefully shut down (reboot) the chat server\n" + "* `/kickall` to kick EVERYBODY off and force them to log back in\n" + + "* `/reconfigure` to dynamically reload the chat server settings file\n" + "* `/help` to show this message\n\n" + "Note: shell-style quoting is supported, if a username has a space in it, quote the whole username, e.g.: `/kick \"username 2\"`", ))