amoeba / towncrier

Webhook plugin for Decal

TownCrier

A Decal plugin that can send Webhooks in response to ingame events.

TownCrier cannot be used to send info into AC such as sending Discord messages into fellowship chat. I think the idea is interesting but I'd probably start another plugin to build this because of how different it is from how TownCrier is built.

Features

• Supports both GET and POST webhooks with arbitrary query parameters and/or JSON payloads
• Payloads can send extra info such as your character's name, level, unassigned XP, and more. See Variables
• Can trigger webhooks based upon:
  • Common ingame events (death, leveling, etc.)
  • Timed intervals
  • Chat box messages (includes player chat as well as other messages)
• Per-character and shared profiles for triggers (Webhooks are shared by default)
• A minimal command line interface (See @tc ingame)

Installation

Download the latest release installer and run it.

Getting started

To get started using TownCrier, you need to:

2. Create at least one Webhook
3. Create at least one Trigger (Event, Timed, or Chat)

Creating a Webhook

I expect most people using TownCrier probably want to use TownCrier with Discord so below are instructions for doing that:

1. Get a webhook URL from Discord

• Pick a channel on guild/server you're admin on
• Right-click on the channel and select ⚙ Edit Channel
• Select Integrations
• Select Webhooks
• Click CreateWebhook (or New Webhook if you already have one set)
• Optionally, change your webhook's name and channel if you want
• Click Copy Webhook URL to get your webhook URL

2. Create a new TownCrier Webhook using the URL from the previous step

• Go ingame town TownCrier installed and enabled in Decal

• Give your Webhook a name. This must be unique.

• Paste the URL you copied in the previous step into the URL field

• Change Method to POST

• Enter { "content": "@" } in the JSON field. This is specific to Discord.

  Your screen should look something like this:

  

• Click Add Webhook

Note: The @ symbol in the JSON payload field is a special symbol. When TownCrier triggers your Webhook, the @ symbol is replaced by whatever Message or event triggered it. If you set the JSON field in the above examples to { "content": "Hi" }, all your Webhook would ever do is send the text "Hi" to your Discord channel.

Creating a Trigger

Triggers are what cause Webhooks to be sent so your newly-created Webhook won't do anything without setting at least one Trigger up. There are three types of Triggers:

1. Event: Send Webhooks when certain events happen ingame (e.g., you dying)
2. Timer: Send Webhooks at timed intervals
3. Chat: Send Webhooks when you see certain text in chat (doesn't have to be actual chat, just messages in the chat window). What you enter for the Pattern is treated as a Regular Expression by default and supports Variables. When Variables are used, the value is replaced before the regular expression is tested.

The trickiest part of setting up a trigger is using the Message field.

Message

The Message field is optional and gives you a way to customize what's sent to your webhook target. If left blank, a message corresponding to the event that triggered your Webhook will be sent. For example, if your character's name is "Asheron" and you have an Event Trigger for "You log in", when you log in, you're webhook target will be sent the message "Asheron has logged in". If, instead, you set the Message field to "Hey, I logged in", you'd get that message instead.

Variables

In the Message field, you can make use of special variables to send information about your character and the game world. You can use as many variables as you want in each Message and each variable starts with a '$' (e.g., $LOC gives your coordinates).

Available variables are $NAME, $SERVER, $LEVEL, $UXP (unassigned xp), $TXP (total XP), $HEALTH, $STAMINA, $MANA, $VITAE, and $LOC (Your location). For example, a Message of 'Hello, $NAME' would print 'Hello, ' followed by your character's name.

Event and Chat Triggers can also make use of a special variable, $EVENT, that lets you print the text of the event or chat message that triggered the webhook. For example, a Chat trigger with the Pattern 'You say' and a Message of '$EVENT' will send everything you say to your webhook. $EVENT does not apply to TimedTriggers but all other Variables work.

towncrier's Issues

Improve help tab

• Add text about where logs/errors/settings are
• See if I can add a button for GitHub/Discord

Prevent clobbering of settings when running multiple clients

Add support for variables in messages

Instead of just a pre-canned message by Event, allow players to add other info (name, level, current xp, whatever) to the message. This'd work really well with #6 because you'd be able to do stuff like send your current location, level, or XP every hour if you wanted.

Escape double quotes in JSON messages instead of replacing them

Add ability to disable/enable Actions

Figure out why telegram webhook just sends an @

level event doesn't capture level to 275

confirmed with tweek that he didn't see it either

Abstract out row/col/actions into structs or enums or something

Disabled triggers still triggering?

Need to repro first

Add support for custom chat events

Make an installer

Use windows.forms.timer instead of timers.timer

per V. Also,

the solution is to check the frame counter at the start of the timer handler and immediately return if it has not increased since the last fire

Add explanatory image at top of readme

Show a side-by-side ingame screenshot and example (say, Discord) of the result of the webhook

Expand variable substitution to actions

Add more info to death message

The death message currently just shows your death taunt. It could also show info like:

• items lost
• vitae
• some previous lines of chat? Not sure about this but adding more context is possibly an improvement.

Add an option for chat logging

Add rare found to event options

Improve variables tab

Add support for time-based triggers

Instead of reacting to ingame events, webhooks could be triggered at specific times (ala cron).

Allow chat patterns to be regexes or regexlike

Add more standard events

• Rare pack (http://ac.yotesfan.com/weenies/items/30936)
• Server messages from admins

Implement logging throughout the app

Log to messages.txt by default, allow verbosity to be turned on so messages are also printed ingame.

Trim webhook URLs

It looks like you can successfully paste a URL in with a space after it and then you get errors like:

============================================================================
31-07-2019 00:20:22
Error: {"code": 50027, "message": "Invalid Webhook Token"}
Source: 
Stack: 
============================================================================

Add Variables support in Chat Trigger Patterns

e..g, a player can filter messages to just those about themselves. So a rare discovery message doesn't trigger for toons botting in a fellow. e.g., $NAME has discovered

Integrate with Virindi Reporter to display XP/hr in webhooks

I should be able to get Virindi Reporter to dump XP/hr into chat and capture it.

Add support for printing actions/events/webhooks to chat to see them

Add ability to print location in a timer

Check that variables and regexes work correctly

@Schneebs noted that a chat trigger like .*$NAME has discovered.* doesn't work. See what's up.

Format variable outputs appropriately

For example, vitae could have a % automatically added. TXP could have commas (per locale).

Add icons for delete action

Pipe webhook errors into chat or at least indicate failure in chat

Add datetime/date/time as variables

Add support for onlevel event

If the built-in event isn't working, the chat text could work:

You are now level 5! You have 10,300 experience points and 4 skill credits available to raise skills and attributes.

Fix bug in @-replacement between GET and POST requests

I think I messed this up and @'s don't get replaced in the URL if the Method is POST.

Fix bug where disabled timers are started on loading

Add support for regex capture groups

Suggestion from Secret Agent and Sunnuj.

Simplify web request sending into one approach

Hook in enabled/disabled state into action/timer

Update readme

• New features
• Screenshot(s)?

Add validation logic when adding new actions and webhooks

$TIME variable not working

Catch error on creating webhook with duplicate name

Write up three example setups with screenshots

• Discord
• SMS (Zapier?)
• Telegram
• IFTTT (see @Schneebs comment below)
• Email (SendGrid?) (need to add support for auth headers if I do that)

Add event for client crash/exit

I'm not sure if this is doable, maybe just due to my lack of knowledge of the windows api, but

I'm not sure if you see WM_QUIT through decal's wndproc broadcast system but you could hook it yourself and get it that way, or make a service (service shutdown = client done)

Add a command line interface

It'd be useful to be able to trigger a webhook with a custom message. Other plugins could trigger webhooks this way.

Dipose of timers properly

To dispose of the type directly, call its Dispose method in a try/catch block

Consider a webhook send queue to avoid spamming endpoints

Add an about tab

Look at using JSON to serialize settings

Add a worked example with screenshots right in readme "getting started" section.