Reconbot is a notification relay bot for an MMO game Eve Online. It fetches character notifications from the EVE API, filters irrelevant ones out and sends relevant ones to set Slack or Discord channels. Notifications like SOV changes, SOV/POS/POCO/Citadel attacks.
Reconbot was intended to be used as a base for further customizations, or integration with other systems, but it can be run via run.py
as well. Check it out for an example. In this version it can also be run in Docker container, using simple docker-compose
command.
This tool is ready to be used with Eve's ESI API. You will need to register your application on EVE Developers page.
When registering your EVE Application, please pick Authentication & API Access
connection type, and make sure your application requests these permissions:
esi-universe.read_structures.v1
- necessary to fetch names of any linked structures;esi-characters.read_notifications.v1
- necessary to fetch character level notifications.
Reconbot does not provide a way to authenticate an account to an application, so you will need to do so via some other means. First two sections of Fuzzysteve's guide on Using ESI with Google Sheets explain how to do that via Postman.
When registering the application take note of the Client ID
and Secret Key
, as they are necessary for Reconbot to establish communication with ESI API.
Reconbot uses ESI 2.0 API, but the Fuzzysteve's guide uses API v1. Please use below settings for Postman. <>
means that you should insert something there.
- Authorization:
Oauth 2.0
- Auth URL:
https://login.eveonline.com/v2/oauth/authorize
- Access Token URL:
https://login.eveonline.com/v2/oauth/token
- Client ID:
<app client id>
- Client Secret:
<app secret>
- Scope:
esi-universe.read_structures.v1 esi-characters.read_notifications.v1
- State:
<anything, cannot be empty>
Please write refresh token
from the results, it will be used later.
To add a Slack integration, check out this Slack documentation page on Bot Users (or create bot user for your workspace). Take note of the API token.
If you wish to use a Discord webhook:
Webhooks are the easiest way to integrate Reconbot with Discord. Simply follow this Discord guide to create a webhook for your channel. You should now have a URL like this:
https://discordapp.com/api/webhooks/496014874437332490/5783au24jzyEFIaWnfTvJn0gFzh5REEEE3ee3e3eNKeFee3We2cIe_6e7e36ugUj5zEm
Use it with DiscordWebhookNotifier
as seen in run.py
example.
If you wish to use a Discord bot user: (not recommended)
To add a Discord integration, check out this Discord documentation page on Bot accounts.
You will need to create an application and add it to your discord server.
See this guide for more visual step-by-step instructions.
You will need a Token
for your Bot User, and Channel ID
where to post messages in.
Use it with DiscordNotifier
as seen in run.py
example.
This one uses docker-compose, over raw python execution.
- Clone this repository
- Copy
.env.example
to.env
and modify it using your settings. More on that below. Do the same withcharacters.yaml.example
->characters.yaml
. Take character ID from zkillboard, use refresh token from the Postman. Filerun.py
containwhitelist
, which indicates which notification types you're interested in (orNone
to allow all supported types). - Execute
docker-compose up -d --force-recreate --build
and wait for notifications to arrive! After the character gets a notification in-game,reconbot
may take up to 10 minutes to detect the notification. - If you receive no notification (but you believe you should) check
docker container ls
and use that id fordocker logs <id>
. This usually means that the refresh token is invalid, or ESI API is down.
.env
:
WEBHOOK_URL
- discord webhook url from 2. stepSSO_APP_CLIENT_ID
- eve app client id from 1. stepSSO_APP_SECRET_KEY
- eve app secret from 1. stepCONTAINER_NAME
- name of the container which will be used for docker, does not really matter, but must not be emptyMAX_NOTIFICATION_AGE_IN_SECONDS
- the bot will get in game notifications not older that thisDEFAULT_PING_ROLE
- pings will use this handle for default-level pings. Can be empty string, then it will just write without pinging anyone.ESCALATED_PING_ROLE
- same as above, but for escalated-level pings. Currently escalted level pings are:OrbitalReinforced
,OrbitalAttacked
,StructureUnderAttack
,StructureLostShields
,StructureLostArmor
,StructureWentLowPower
,TowerAlertMsg
,WarInvalid
,WarDeclared
. Use@everyone
or@here
for pinging everyone in channel.ADDITIONAL_INFO
- any text that, will be added to escalated level pings.
characters.yaml
:
character_name
- self explanatorycharacter_id
- use zkillboard or similar service to grab id of your characterrefresh_token
- token from postman from 1. step
Reconbot by default will try to evenly spread out checking API keys over the cache expiry window (which is 10 minutes for ESI), meaning that with 2 API keys in rotation an API key will be checked every ~5 minutes (with 10 keys - every minute), which can be useful to detect alliance or corporation-wide notifications more frequently than only once every 10 minutes.
As of writing this tool there is little documentation about the types of notifications available and their contents. The following list has been assembled from working experience, is not fully complete and may be subject to change as CCP changes internals:
- AllWarDeclaredMsg
- DeclareWar
- AllWarInvalidatedMsg
- AllyJoinedWarAggressorMsg
- CorpWarDeclaredMsg
- EntosisCaptureStarted
- SovCommandNodeEventStarted
- SovStructureDestroyed
- SovStructureReinforced
- StructureUnderAttack
- OwnershipTransferred
- OrbitalReinforced
- OrbitalAttacked
- StructureOnline
- StructureDestroyed
- StructureFuelAlert
- StructureWentLowPower
- StructureWentHighPower
- StructureFuelAlert
- StructureAnchoring
- StructureUnanchoring
- StructureServicesOffline
- StructureLostShields
- StructureLostArmor
- TowerAlertMsg
- TowerResourceAlertMsg
- StationServiceEnabled
- StationServiceDisabled
- OrbitalReinforced
- OrbitalAttacked
- SovAllClaimAquiredMsg
- SovStationEnteredFreeport
- AllAnchoringMsg
- InfrastructureHubBillAboutToExpire
- SovAllClaimLostMsg
- SovStructureSelfDestructRequested
- SovStructureSelfDestructFinished
- StationConquerMsg
- MoonminingExtractionStarted
- MoonminingExtractionCancelled
- MoonminingExtractionFinished
- MoonminingLaserFired
- MoonminingAutomaticFracture
- CorpAllBillMsg
- BillPaidCorpAllMsg
- CharAppAcceptMsg
- CorpAppNewMsg
- CharAppWithdrawMsg
- CharLeftCorpMsg
- CorpNewCEOMsg
- CorpVoteMsg
- CorpVoteCEORevokedMsg
- CorpTaxChangeMsg
- CorpDividendMsg
- BountyClaimMsg
- KillReportVictim
- KillReportFinalBlow
- AllianceCapitalChanged
Do you have sample contents of currently unsupported notification types? Consider sharing them by creating an issue, or submit a Pull Request. Any help would be appreciated!