OrgHelper Bot

This instruc­tion is for v1.1.0. In the future new func­tion­al­i­ties may be added and exit­ing fea­tures may be changed. This doc will be updat­ed accordingly.

Quick start

Invite the bot to your Dis­cord serv­er by fol­low­ing this link: https://discord.com/api/oauth2/authorize?client_id=714175230809210952&permissions=8&scope=bot

Type !help to see the avail­able commands.

Do stuff using text commands:

Set the server's timezone:

!set­time­zone Europe/Moscow

Add some role managers:

!addrole­m­an­ag­er @moscow-manager, @Jack, @Chloe @nyc-member

Sched­ule reminders:

!remind each Sun 15:30 Week­ly call in 30 minutes!

Cre­ate polls:

!poll "The best employ­ee of the week:" "Paul" "Jacob" "Maria"

Detailed guide

OrgHelper - is a Dis­cord bot which help to man­age groups and com­mu­ni­ties (or on Dis­cord lan­guage - "servers" or "guilds").

To use the bot you need to belong to at least one Dis­cord guild, or bet­ter - be its admin­is­tra­tor, because some of the com­mands are avail­able only to guilds admin­is­tra­tors. You can reg­is­ter in Dis­cord here: https://discord.com/

Please note: after some time we are plan­ning to make the bot mul­ti-plat­form. That is, you will be able to use OrgHelper in Slack, Telegram etc. Want this fea­ture to come true soon­er? Ask your kith pro­gram­mers to join devel­op­ment of our open source project, or join your­self. This is our open source project on GitHub: https://github.com/alteh-union/org-helper

How to start using the bot?

To start work­ing with OrgHelper on your serv­er, invite it there using these steps:

  1. Got to link: https://discord.com/api/oauth2/authorize?client_id=714175230809210952&permissions=8&scope=bot
  2. Login into Dis­cord if you have not done it yet
  3. Choose into which guild you need to invite the bot

All set! Now you should be able to see te bot among the mem­bers of your guild. Like here:

How to communicate with the bot?

You can com­mu­ni­cate with the bot using spe­cial mes­sages to it in text channels.

Please note: the bot should have enough per­mis­sions to read your mes­sages and reply to it. By default the bit joins with admin per­mis­sions, but you can deny per­mis­sions for it (that is, for its role, which has the same name as the bot itself) in the whole serv­er or in spe­cif­ic chan­nels. In this case the bot will not be able to work as expected.

To avoid mix­ing up reg­u­lar mes­sages with bot's com­mands, you need to prepend a pre­fix for the com­mands. By default the pre­fix is the excla­ma­tion mark: !

That is, if you write "ping", the bot will ignore the mes­sage, because it will not rec­og­nize it as a com­mand. But if you write "!ping" the bot will reply with "pong!" message:

To see the full list of avail­able com­mands type the spe­cial !help com­mand.

And if you need to know more details about a par­tic­u­lar com­mand (espe­cial­ly about its argu­ments). For exam­ple, "!help add­role" (you don't need to type the pre­fix twice).

Please note: pre­fix ! and Eng­lish lan­guage are default set­tings. The bot can use oth­er lan­guages (e.g. Russ­ian) and oth­er pre­fix­es (which is need­ed to avoid con­flicts with oth­er bots on the same serv­er). If the bot does not react on your com­mands, per­haps you changed some­thing in the set­tings. In this case you can type "!help" (that is, with the default pre­fix and default lan­guage). Bot will under­stand it no mat­ter which pre­fix and lan­guage you set.

Command arguments

Most of the com­mands, except some prim­i­tive ones, have argu­ments, which make your requests to the bot more specific.

For exam­ple, the fol­low­ing com­mand adds 2 roles (mod­er­a­tor and edi­tor) to the same mem­ber called ServerAdmin:

!add­role @ServerAdmin @moderator, @editor

Here the argu­ments are:

  1. @ServerAdmin - the men­tion of the user with dis­play name Server­Ad­min (the men­tion is made by prepend­ing @ before the nick­name). Instead of 1 men­tion you could spec­i­fy a list of mem­ber here, com­ma separated
  2. @moderator, @editor - the list of role, com­ma sep­a­rat­ed, which need to be assigned to the member

How do you know what are the command's argu­ments? Type "!help add­role" to see the defin­tions of the arguments.

here is an exam­ple of argu­ments for !addrole­m­an­ag­er command:

Please note: most of argu­ments have at least 2 names (alias­es), and you can use any of them, of course if you call argu­ments by name at all.

There are two ways of spec­i­fy­ing the argu­ment val­ues for com­mands: by names and sequen­tial­ly with­out names.

By names

Exam­ples:

!addrole­m­an­ag­er -s @ServerAdmin -r @moderator

!remind -t 2h -c #Москва -m Не забудьте сдать отчётность!

Advan­tages:

Strict­ly sep­a­rat­ed val­ues, can­not mess up sev­er­al arguments

No need to know the order of arguments

More clear input

Can skip some argu­ments - they will be set to the default values

Dis­ad­van­tages:

Longer nota­tion

Need to know the argu­ment names

Sequen­tial­ly

Exam­ples:

!addrole­m­an­ag­er @ServerAdmin @moderator

!remind 2h Не забудьте сдать отчётность!

Advan­tages:

Short­er notation

No need to know the argu­ment names

Dis­ad­van­tages:

Need to know the order of arguments

Can mess up the val­ues in typed incor­rect­ly (depends on the argu­ment data types)

Some argu­ments can­not be entered in this mode - they will be just set to the default values

You can use either of the meth­ods at a time of typ­ing a com­mand, but you can­not mix them up in one com­mand call.

We try to cov­er as much cas­es as pos­si­ble with the sequen­tial method, but some­times it's impos­si­ble because of log­i­cal rea­sons. in such cas­es you have to use the input by names.

For exam­ple, the bot allows to sched­ule reminders from any text-chan­nel to any text-chan­nel, but what will hap­pen if we try to imple­ment this with­in the sequen­tial method? We will get some­thing like this:

!remind at Sun 12:45 #gen­er­al All-hands meet­ing in 30 minutes!

A human can under­stand that #genar­al here is a text chan­nel where the reminder should work, but for a bot it's impos­si­ble to deter­mine: is it the tar­get chan­nel or the begin­ning of the mes­sage to be reminded?

In such ambigu­ous cas­es the sequen­tial input is restrict­ed (more pre­cise­ly, some of the ambigu­ous argu­ments are ignored by the bot), and the only way to spec­i­fy all argu­ments is the input by names (see the exam­ple above).

Main features

Precise role management

Dis­cord sup­ports a sin­gle ver­ti­cal hier­ar­chy line of roles. Like this:

What's the prob­lem here?

Sup­pose you man­age not a small group, but a large com­mu­ni­ty rep­re­sent­ed in sev­er­al regions or coun­tries. Typ­i­cal­ly in such regions you will have region­al man­agers and reg­u­lar mem­bers. And it's log­i­cal that you will want to allow region­al lead­ers to man­age roles with­in their regions.

Usu­al­ly admins grant a native Dis­cord per­mis­sion called "Man­age roles". In such cas­es peo­ple with the per­mis­sion will be able to man­age all roles which are below them in the hier­ar­chy. But what will you get? Some­thing like this:

admins

man­agers-us

man­agers-mex­i­co

man­agers-cana­da

mem­bers-us

mem­bers-mex­i­co

mem­bers-cana­da

Here peo­ple with role "man­agers-us" get per­mis­sion to man­age, first­ly, reg­u­lar mem­bers in all regions, and sec­ond­ly, man­agers in Mex­i­co in Cana­da, which is def­i­nite­ly not what you wanted.

And here comes OrgHelper with its pre­cide role management.

Instead of grant­i­ng the native gen­er­al "Man­age roles" per­mis­sion, you give cer­tain peo­ple or cer­tain roles an abil­i­ty to man­age only cer­tain roles.

For exam­ple,

!addrole­m­an­ag­er @managers-us @members-us

In this case peo­ple with role @managers-us to ask the bot to add or remove the @members-us role via !add­role и !remove­role com­mands. Like here:

!add­role @Maria @members-us

!remove­role @John, @Jack @members-us

To remove the per­mis­sion you can use com­mand !removerole­m­an­ag­er:

!removerole­m­an­ag­er @managers-us @members-us

Also you can assign cer­tain peo­ple as role man­agers. Например:

!addrole­m­an­ag­er @ServerAdmin @members-us

To view cur­rent role man­agers per­mis­sions use the fol­low­ing command:

!per­mis­sions role

Please note: only guild admins cn use the !addrole­m­an­ag­er and !removerole­m­an­ag­er com­mands. Also admins bypass the per­mis­sion check to add/rremove roles. That is, they can use com­mands !add­role and !remove­role by default.

Reminders

This func­tion­al­i­ty will come in handy for peo­ple who main­tain sin­gle or recur­rent events in the guild.

Admins (and also mem­bers who got the nec­es­sary per­mis­sion using !per­mitrem­mind com­mand) can sched­ule reminders using !remind com­mand. For example:

!remind 2h Don't for­get about your dai­ly report!

!remind -t each Mon 15:30 -c #NYC -m Don't for­get about your dai­ly report!

In the first case a sin­gle-shot reminder will be sched­uled, and will be trig­gered after 2 hours of send­ing the com­mand in the same text chan­nel where it was request­ed, and with text "Don't for­get about your dai­ly report!".

In the sec­ond case, a recur­rent reminder will be sched­uled to be trig­gered each Mon­day at 15:30 to post "Don't for­get about your dai­ly report!" in the #NYC text channel.

Please note: if you don't spec­i­fy the tiezone in the com­mand, the time­zone will be tak­en from the user set­tings in the serv­er (set via !set­my­time­zone com­mand), or from the serv­er-wide set­ting (set via !set­time­zone), or will be set to UTC time­zone, in the order of descend­ing pri­or­i­ty. Don't for­get to set the tome­zone for your serv­er or for you individually!

Active reminders can be viewed via !reminders com­mand. You can also view reminders only for a spe­cif­ic chan­nel. Fox example:

!remiders #NYC

(the last vari­ant is espe­cial­ly use­ful if you don't have per­mis­sion to man­age remon­ders serv­er-wise so can check it only for par­tic­u­lar channels)

You can can­cel reminders by their iden­ti­fiers. First­ly, get the list of the reminders and then use !deletere­minder com­mand with the respec­tive iden­ti­fi­er. Fox example:

Users with admin priv­i­leges can­not sched­ule reminders by default. But you can give them such right using !per­mitrem­ind com­mand. For example:

!per­mitrem­ind @Chloe

!per­mitrem­ind @Stacy #reports

In the first case @Chloe will get the per­mis­sion to cre­ate reminder for any chan­nel, and in the sec­ond user @Stacy will get the per­mis­sion only for chan­nel #reports.

You can revoke the per­mis­sion using !denyre­mind com­mand. For example:

!denyre­mind @Chloe

!denyre­mind @Stacy #reports

You can view the list of cur­rent reminders per­mis­sions using command:

!per­mis­sions remind

Please note: only serv­er admin­is­tra­tors can use !per­mitrem­ind and !denyre­mind com­mands. Also admins bypass the relat­ed per­mis­sion check. E.g. they can use com­mands !remind, !reminders and !deletere­minder by default.

Please note: the bot does not allow to have more than 50 active reminders for a guild.

Polls

Works sim­i­lar­ly to the Sim­ple Poll bot. Cre­ate a poll in a form of an emo­ji group, where each emo­ju rep­re­sents a vari­ant of choice. Users can vote for the vari­ants by click­ing on the respec­tive emojies.

Polls are cre­at­ed using !poll com­mand with at least 1 argu­ment (the ques­tion). If there are more argu­ments then they are con­sid­ered as answer vari­ants, and in this case a mul­ti-choice poll is cre­at­ed instead of a yes/no poll.

Please note: the bot dis­tin­guish argu­ments by spaces in this com­mand, if the spaces are not with­in quotes. So if you use phras­es for questions/answers - put them inside quotes so the bot con­sid­er them whole as one argument.

Exam­ples:

Turns into:

Turns into:

Cleaning chats

Allows to clean a text chan­nel with one com­mand, for a giv­en peri­od of time or the whole channel.

Exam­ples:

!clean -c #NYC -t 2h -s silent

Cleans mes­sages added to the NYC chan­nel in the last 2 hours "silent­ly" (that is, doesn't print the result message).

!clean today

Cleans all mes­sages in the cur­rent chan­nel print­ed today.

!clean all

Cleans all mes­sages in the cur­rent chan­nel for all time.

Please note: the com­mand requires the native "man­age mes­sages" per­mis­sion from the caller.

The time argu­ment uses time defin­tions with var­i­ous units sep­a­rat­ed by spaces. For exam­ple, this is a valid time argument:

1y 4M 3d 4h 5m 6s

mean­ing: 1 year, 4 months, 3 days, 4 hours, 5 min­utes, 6 sec­onds (and all that gets con­vert­ed into mil­lisec­onds and gets summed up to cal­cu­late the point of time down until which the bot needs to clean messages).

Moderation

The Bot has the fol­low­ing com­mands to imme­di­atel­ly mod­er­ate chats: warn, kick, ban. Examples:

!warn @Mike For being rude

!kick @Stacey For bad language

!ban @StupidBot, @MerchBot For con­stant spam

The "kick" and "ban" com­mands obvi­ous­ly kick and ban men­tioned mem­bers from the serv­er respectively.

Please note: the Bot should have enough per­mis­sions to kick/ban men­tioned mem­bers, oth­er­wise the mod­er­a­tion com­mands will not work.

The "warn" com­mand adds a warn­ing into the Bot data­base. Lat­er the warn­ings of the respec­tive users can be seen using the "warn­ings" com­mand. Exist­ing warn­ings can be removed via "delete­warn­ing" com­mand by their iden­ti­fiers (the ids can be retrieved from the result of the "warn­ings" command).

The main point of "warn" is that you can set­up auto­mat­ic ban for users who receive enough warn­ings. To do so, use the "set­banon­warn­ings" com­mand. Like here:

!set­banon­warn­ings 3

!warn @Godzilla For smash­ing the buildings

!warn @Godzilla For crash­ing the people

!warn @Godzilla For not hav­ing a valid visa

- User Godzil­la gets banned with rea­son "Got too many warnings"

To dis­able ban on warn­ings, sim­ply type it with­out any argu­ment or with "0" as the argu­ment, like here:

!set­banon­warn­ings

Anoth­er use­ful point of the mod­er­a­tion com­mands is that their result can be saved to a spe­cial men­tioned text chan­nel for future ref­er­ences. To enable the mod­er­a­tion log­ging, use the "set­mod­er­logs" command:

!set­mod­er­logs on

To select the text chan­nel for log­ging, use the "set­mod­er­logschan­nel" command:

!set­mod­er­logschan­nel #mod­er­a­tion-logs

Please note: the Bot should have enough per­mis­sions to write mes­sages into the channel.

If no chan­nel was spec­i­fied, but the mod­er logs were enabled, then the bot will try to cre­ate a text chan­nel with name "mod­er-logs" and will start to log mes­sages there.

Customization

All users in guild where OrgHelper is present can set set­tings relat­ed to the bot. E.g. set their time­zone, so the bot under­stand what time they actu­al­ly mean in their reminders; and their lan­guage, to com­mu­ni­cate with the bot easier.

These are the com­mand allow­ing to work with indi­vid­ual set­tings on the server:

!myset­tings (shows the list of cur­rent user settings)

!set­my­lo­cale (sets the user lan­guage or deletes the set­ting if the argu­ment is empty)

!set­my­time­zone (sets the user time zone or deletes the set­ting if the argu­ment is empty)

If a user set­ting is not set, then the bot uses a serv­er-wide set­ting value.

Serv­er-wide set­tings can be man­aged only by admins.

These are the com­mands for work­ing with serv­er-wide settings:

!set­tings (shows the list of cur­rent settings)

!addbad­words (adds words to the bad list)

!bad­words (shows the list of bad words)

!remove­bad­words (removes words from the bad list)

!set­cen­sor­ing (enables or dis­ables the censoring)

!set­lo­cale (sets the serv­er locale/language)

!set­time­zone (sets the serv­er default time zone)

!set­pre­fix (sets the pre­fix of com­mands; can be almost any­thing, like $ or azaza)

!set­banon­warn­ings (defines how many warn­ings should be received by the user to ban him/her)

!set­mod­er­logschan­nel (sets the text chan­nel where the mod­er­a­tion logs will be populated)

!set­mod­er­logs (enables or dis­ables the mod­er­a­tion logs)

Please note: the Bot uses set­ting val­ues in the order of descend­ing pri­or­i­ty (that is, picks a val­ue with low­er pri­or­i­ty if does not find such set­ting at a high­er pri­or­i­ty lev­el): first­ly it checks the user set­tings, then the serv­er-wise set­tings, then uses the hard­cod­ed default val­ue (for exam­ple, the hard­cod­ed default lan­guage is English).

Image making

The Bot is capa­ble of mak­ing images from giv­en source images and tem­plates. For example:

The high qual­i­ty result images can be tak­en from Dis­cord by tap­ping on the result image and then the "Open orig­i­nal" link:

The image mak­ing itself can be launched by the "makeim­age" command:

!makeim­age <template_name> <base image URL> <title text> <font size for the title>

The last para­me­ter can be ommit­ed, because typ­i­cal­ly tem­plates are designed to look good only with a cer­tain font size, which can be pre­de­fined in the tem­plate itself.

An exam­ple usage is:

$makeim­age it_2lines https://storage.ruptly.tv/thumbnails/20200625-006/UNN1XBL4Uc1qf7wX/large_UNN1XBL4Uc1qf7wX.jpg "Таксисты Uber в США\nотстояли право на социальные гарантии"

Please note: make sure you have legal per­mis­sions to use the base image of your choice. The Bot devel­op­ers are not respon­si­ble for user's ille­gal copy­ing or mod­i­fy­ing of images via the Bot's tools. Also, if you are allowed to use an image only with a ref­er­ence to its source, then please men­tion that source along with the result image.

You can split the title into sev­er­al lines at cer­tain places in the string by enter­ing "\n" in that places (like in the exam­ple above). Here \n stands for the "new line" sym­bol wide­ly used in com­put­er science.

Templates for image making

The tem­plates them­selves are guild-wide and can be uploaded either by admin­is­tra­tors of the guild or by des­ig­nat­ed per­sons who have the "imagetem­plate" permission.

The per­mis­sion can be grant­ed by the "per­mitim­agetem­plate" command:

!per­mitim­agetem­plate @Peter, @editors

and revoked with the "deny­im­agetem­plate" command:

!deny­im­agetem­plate @Peter

As usu­al, the exist­ing per­mis­sions can be list­ed with the "per­mis­sions" command.

The per­sons capa­ble of manip­u­lat­ing the tem­plates can use the fol­low­ing 3 com­mands to add, list and remove templates:

!addim­agetem­plate template_name

!lis­tim­agetem­plates

!deleteim­agetem­plate template_name

The "addim­agetem­plate" com­mand adds the giv­en tem­plate to the Bot's DB and assigns the giv­en name to it. It's pos­si­ble to write the tem­plate con­tent itself as the last argu­ment of the com­mand, although it's not rec­om­mend­ed, because the count of sym­bols in Dis­cord mes­sages is lim­it­ed by 2000, and because it's obvi­ous­ly inconvenient.

So, instead of wrtit­ing the con­tent as an argu­ment, make a .txt file with the con­tent on your local machine, and attach the file to the mes­sage with the "addim­agetem­plate" com­mand. Like here:

The for­mat of con­tent is described in a sec­tion below.

The "lis­tim­agetem­plates" com­mand lists the tem­plate names, which may be need­ed for 2 rea­sons: to find out which name needs to be used in the "makeim­age" com­mand and to delete unused templates.

Please note: the "lis­tim­agetem­plates" com­mand is avail­able to all mem­bers, because the "makeim­age" com­mand also does not have any restric­tions, and user of "makeim­age" need to know which tem­plates are avail­able in the guild.

Please note: there is a hard lim­it of 30 tem­plates per guild in the Bot. So if you reach it, you will need to delete some least need­ed exist­ing tem­plates before adding new ones.

Use the "deleteim­agetem­plate" com­mand to remove an unused tem­plate by its name:

Content of image templates

To design the tem­plates your­self it's bet­ter to have an idea of 2 things: the JSON for­mat and image manip­u­la­tion pro­grams like Pho­to­shop or GIMP.

Although the tem­plates for­mat is quite sim­ple it's still maybe chal­leng­ing to cre­ate one with­out help of per­sons expe­ri­enced in JSON/Javascipt and/or image manipulation.

If you don't have an expe­ri­ence in that things but want to learn cre­at­ing tem­plates, then one of the best ways to do it is to take an exist­ing tem­plates (see below) and tweak cer­tain para­me­ters in there to see how it affects the result. That is, learn by example.

Each image tem­plate of the Bot is defined as a JSON object con­tain­ing instruc­tions for the pro­gram on how to manip­u­late the base image in order to cre­ate a result image.

The instruc­tions are trans­formed by the Bot and in the end are fed to the JIMP library (which is a JS prim­i­tive ana­log of GIMP) and to the text-to-image library (when work­ing with text lay­ers). So a lot of para­me­ter names in the tem­plate just match the required para­me­ter names in the 2 men­tioned libraries.

The two libraries manip­u­late with the giv­en image and text lay­ers, com­pose them into a sin­gle lay­er accord­ing to the instruc­tions and pro­vide the result image out of it.

Here is an exam­ple of tem­plate for 2-line titles used by the Alteh Union in the social networks:

{
"input": {
"type": "fixed",
"width": 1280,
"height": 720
},
"fonts": [
{
"url": "https://github.com/dharmatype/Bebas-Neue/raw/master/fonts/BebasNeue(2014)ByFontFabric/BebasNeue-Bold.ttf",
"name": "Bebas Neue Bold"
}
],
"items": [
{
"type": "image",
"url": "http://alteh.org/wp-content/uploads/2020/08/tmpl_it_2lines_under_text.png",
"align": "bot­tom",
"autoscale": true,
"blend": {
"mode": "mul­ti­ply"
}
},
{
"type": "text",
"mar­gin": {
"left": 0,
"right": 0,
"top": 64,
"bot­tom": 0
},
"style": {
"font­Size": 72,
"line­Height": 80,
"tex­tAl­ign": "cen­ter",
"fontWeight": "bold",
"font­Fam­i­ly": "Bebas Neue Bold",
"bgCol­or": "trans­par­ent",
"text­Col­or": "black"
},
"blur": 5
},
{
"type": "text",
"mar­gin": {
"left": 0,
"right": 0,
"top": 64,
"bot­tom": 0
},
"style": {
"font­Size": 72,
"line­Height": 80,
"tex­tAl­ign": "cen­ter",
"fontWeight": "bold",
"font­Fam­i­ly": "Bebas Neue Bold",
"bgCol­or": "trans­par­ent",
"text­Col­or": "black"
},
"blur": 5
},
{
"type": "text",
"mar­gin": {
"left": 0,
"right": 0,
"top": 64,
"bot­tom": 0
},
"style": {
"font­Size": 72,
"line­Height": 80,
"tex­tAl­ign": "cen­ter",
"fontWeight": "bold",
"font­Fam­i­ly": "Bebas Neue Bold",
"bgCol­or": "trans­par­ent",
"text­Col­or": "white"
}
},
{
"type": "image",
"url": "http://alteh.org/wp-content/uploads/2020/08/tmpl_it_2lines_stripes.png",
"align": "bot­tom",
"autoscale": true,
"blend": {
"mode": "over­lay"
}
},
{
"type": "image",
"url": "http://alteh.org/wp-content/uploads/2020/08/tmpl_it_1line_vin.png",
"align": "bot­tom",
"autoscale": true,
"blend": {
"mode": "over­lay"
}
}
]
}

Here, the over­all object con­tains 3 main blocks (prop­er­ties) - "input", "fonts" and "items".

The "input" object defines what to do with the base image (the one which URL will be pro­vid­ed by the users in the "makeim­age" com­mand). So far only one type of manip­u­la­tion is sup­port­ed - "fixed" resize to the giv­en width and height. If the aspect ratio of the orig­i­nal image is dif­fer­ent than the men­tioned in the tem­plate, then the exceed­ing parts will be cut off after resizing.

The "fonts" is an array of fonts to be used in the tem­plate. The fonts need to be acces­si­ble by http/https pro­to­col in an exter­nal resource/website. One good exam­ple of such web­site is GitHub, where some good and free-to-use fonts are pub­lished (see the exam­ple above). Besides the URL, a "font fam­i­ly" name needs to be pro­vid­ed, so lat­er you can use that name as the font ref­er­ence. You can pro­vide any name you want, but in gen­er­al, it's bet­ter to name the font the same as the font cre­ators sug­gest­ed. Any­way, before import­ing the font into the sys­tem, the Bot will prepend the guild id and the source name (e.g. "Dis­cord") to the name, so it does not con­flict with fonts with the same name from the oth­er guilds. You don't need to know the pre­fix as it will be used inter­nal­ly only.

Right now there is no pos­si­bil­i­ty to use mul­ti­ple text strings in the tem­plate, so the only rea­son to import mul­ti­ple fonts is to print the same mes­sage mul­ti­ple times with dif­fer­ent fonts (for exam­ple, the title itself and it's shadow/reflection - see the exam­ple above).

Please note: the Bot's devel­op­ers are not respon­si­ble for users who import font files which they are not allowed to use or share. It's your respon­si­bil­i­ty to use only fonts for which you have a valid license. In gen­er­al, it's rec­om­mend­ed to refer only free-to-use fonts (for exam­ple, dis­trib­uted under OFL).

The "items" block is an array of addi­tion­al lay­ers which need to be append­ed to the base image. That's where the mag­ic happens.

All items in the tem­plate are applied in order from the top one to the bot­tom one (that's the oppo­site to what hap­pens in GIMP or Pho­to­shop UI).

The items can be nest­ed. That is, an image lay­er can have its own "items" block as an array of oth­er image and/or text. This may be need­ed if you have some lay­er sig­nif­i­cant­ly small­er than the whole base image, and you need to do some manip­u­la­tions rel­a­tive only to that lim­it­ed rec­tan­gle. Or if it's con­ve­nient for you to set alignment/margins rel­a­tive to a cer­tain lay­er, not to the whole base image.

An item can be either a text or an image. The type must be explic­it­ly men­tioned in the block.

Attributes of "image" template items

If the item is an image, then the fol­low­ing prop­er­ties can be used:

url - the URL to the image on an acces­si­ble pub­lic resource. For exam­ple, "https://mywebsite.org/uploads/stipe_under_title.png". The Bot should have per­mis­sions to read the file. E.g. don't refer to a file which is pro­tect­ed by a pass­word etc. Also, make sure the file does not change its name/address dynam­i­cal­ly, oth­er­wise it may become inac­ces­si­ble when a user tries to make an image with your template.

autoscale (true/false) - will try to scale the image to the largest size that fits inside the base rectangle

align (top/left/bottom/right) - will align the lay­er to one of the base image sides. If set to "bot­tom", will align the left side to the left edge of the base. If set to "right", will align the top side to the top edge. If not set, then will just scale the lay­er to fit the base image.

blend - must be an object (enclosed in the curly brack­ets - {}) with a sin­gle prop­er­ty - mode. The "mode" prop­er­ty should be one of the JIMP sup­port­ed blend modes (cur­rent­ly it's srcOv­er, dstOver, mul­ti­ply, screen, over­lay, dark­en, light­en, hard­Light, dif­fer­ence, exclu­sion). If not spec­i­fied, then just adds the cur­rent lay­er on top of the pre­vi­ous lay­ers with lin­ear alpha-blending.

rotate - rotates the lay­er clock­wise by the giv­en num­ber of degrees.

shear - shears the lay­er ver­ti­cal­ly by the giv­en num­ber of pix­els. If the num­ber is pos­i­tive, then shears the right edge to the top. If the num­ber is neg­a­tive, then shears the right edge to the bot­tom. The left edge is not displaced.

blur - blurs the lay­er by the giv­en num­ber of pix­els. One of the usage of this para­me­ters is to cre­ate con­trast shadows.

Attributes of "text" template items

If the item is a text, then the fol­low­ing prop­er­ties can be used:

mar­gin - an object with the fol­low­ing prop­er­ties: left, right, top, bot­tom. Each prop­er­ty defines how far from the cor­re­spond­ing edge of the base image the text lay­er should be. The dis­tance is set in per­cents of the base lay­er size.

style - an object with what­ev­er prop­er­ties are sup­port­ed by the "text-to-image" library. The most com­mon and use­ful prop­er­ties are:

(style) font­Fam­i­ly - the name of the font fam­i­ly (see the "fonts" block).

(style) font­Size - the font size in pixels.

(style) line­Height - the line height in pix­els. Does not mat­ter for a sin­gle line texts, but mat­ter for mul­ti­line texts as the dis­tance between the top edge of the pre­vi­ous line and the top edge of the cur­rent line.

(style) tex­tAl­ign (left, right, cen­ter) - the align­ment of the text line with­in the text box.

(style) fontWeight (nor­mal, bold) - defines if the bold ver­sion needs to be used or not.

(style) bgCol­or - the back­ground col­or. Use "trans­par­ent" to make the text box trans­par­ent. Also can use known col­or names like "white", "black" etc., or a col­or code, like "#000".

(style) text­Col­or - the text col­or. You can use known col­or names like "white", "black" etc., or a col­or code, like "#111".

rotate - rotates the lay­er clock­wise by the giv­en num­ber of degrees.

shear - shears the lay­er ver­ti­cal­ly by the giv­en num­ber of pix­els. If the num­ber is pos­i­tive, then shears the right edge to the top. If the num­ber is neg­a­tive, then shears the right edge to the bot­tom. The left edge is not dis­placed. If you use the text on top of some image-wide stripe, and want to shear both of them, then set the left and right mar­gins of the text lay­er to 0. In this case you can use the same amount of shear on both the lay­ers and the hor­i­zon­tal lines will remain par­al­lel after shearing.

blur - blurs the lay­er by the giv­en num­ber of pix­els. One of the usage of this para­me­ters is to cre­ate con­trast shadows.

Template limitations

There are some lim­i­ta­tions relat­ed to image mak­ing, most­ly need­ed to make sure the Bot does not get down due to high workload.

The max num­ber of tem­plates in a guild is 30.

The max num­ber of fonts to be down­loaded by a guild is 20.

The max com­plex­i­ty of a tem­plate is 200. The com­plex­i­ty is cal­cu­lat­ed as the sum of all prop­er­ties of all JSON objects and array on all lev­els of depth.

The max length of a template's text is 10000 symbols.

The max size of a font file to be down­loaded is 4194304 bytes.

The max width of the result pic­ture is 1920.

The max height of the result pic­ture is 1920.

The tar­get JPG qual­i­ty when mak­ing the result image is 95.

How to design a template

You can use any method of design­ing an image tem­plate, as long as the tem­plate has the valid for­mat described above.

How­ev­er, one of the most effec­tive meth­ods is design­ing it in Photoshop/GIMP pro­gram, then export­ing the lay­ers one by one as stand­alone images, then upload­ing them to your (or any oth­er pub­licly avail­able) web­site, and then writ­ing the text of the tem­plate with ref­er­ences to the uploaded files.

Here is how an Alteh Union 1-line tem­plate was created:

1) First­ly, cre­ate a project using your image manip­u­la­tion pro­gram (Pho­to­shop, GIMP or oth­er). In this case we are using GIMP, because it's free, open source and is not infe­ri­or to Pho­to­shop in a lot of aspects:

1.1) Decide which size the result image will have and make sure the can­vas in GIMP has the same size (in this case it's 1280 on 720).

1.2) Load an exam­ple of the base image (it will not be export­ed along with oth­er lay­ers, but it will help you to see how your results will look like), resize it so it fits the canvas.

1.3) Add what­ev­er addi­tion­al lay­ers you need. This may include the stipe behind the text, your logo, some water­mark, vignette etc. Refer to man­u­als of the par­tic­u­lar soft­ware pro­gram on how to cre­ate such layers.

1.4) Note how lay­ers are posi­tioned rel­a­tive­ly to each oth­er or to the whole can­vas. You will need which infor­ma­tion when wrtit­ing the template's text. In the most sim­ple case, all lay­ers (except the base) just fit the can­vas (e.g. in this case they all are 1280x720), so you don't need to decide how to posi­tion them.

1.5) Decide which blend mode will be used for each lay­er. For exam­ple, here the vignette has the "nor­mal" blend mode, the main stripe behind the text has the "mul­ti­ply" mode, and the thin white stripes on the edges of the pur­ple stripe have the "over­lay" mode.

1.6) Decide which font you will use for the title. Note that the font should be acces­si­ble by the Bot lat­er, so don't just use fonts from your local machine which are not uploaded any­where in the web. Also make sure you use only fonts you are allowed to use and share.

1.7) Write an exam­ple title using the font at the place where you want to place it. Test it with the num­ber of lines you intend the tem­plate to be. Although not always, but typ­i­cal­ly for each num­ber of lines you will need to cre­ate a sep­a­rate tem­plate, because you will need, for exam­ple, to resize the stripe behind the font etc.

1.8) Note where the text is locat­ed rel­a­tive­ly to the can­vas or oth­er lay­ers. You will need to cal­cu­late the mar­gin in per­cents, to place the text prop­er­ly in the tem­plate. Also note the font size.

2) Export all the lay­ers as stanalone PNG images, except the lay­ers relat­ed to texts (e.g. the text itself and its shad­ow) and except the base exam­ple image.

To export an image lay­er, tem­porar­i­ly change its blend mode to "nor­mal", then either copy it to a new project with the can­vas size match­ing the layer's size, or, if the base can­vas size already match­es the lay­er size, then just make all oth­er lay­ers invis­i­ble and export it right from the main project.

Here is how the main stipe was pre­pared for export:

3) Upload the export­ed stanalone images to a pub­licly avail­able web­site from which you will use it in your tem­plate. For exam­ple, it can be your Word­Press web­site, or even a social net­work (in the lat­ter case be cau­sios, because the direct links to images may be dynam­ic on such websites).

In case of Word­Press, login to the admin pan­el, like <your site>/wp-admin, then click on "media files" -> Upload new -> select the file from your local machine -> wait until the upload is com­plet­ed -> note the URL link to the uploaded image - you will need to paste it to your template.

Here is how the stipe from our tem­plate was uploaded:

4) Cre­ate a text file for the tem­plate. Write it accord­ing to the for­mat described in the pre­vi­ous sec­tions. Or take the exam­ple tem­plate men­tioned above and adjust it to your needs.

In the "input" block use the same width and height which your can­vas had.

Use the URL links cre­at­ed on the pre­vi­ous step to the images for cre­at­ing the image layers.

For image lay­ers - set align­ment accord­ing to your obser­va­tions made on step 1.4. If the lay­ers just fit the whole can­vas, then no need to spec­i­fy the align­ment and autore­size, or just set the align­ment to "left".

For font lay­ers - first­ly refer to the font file in your "fonts" block, then add the text lay­er with the ref­er­ence to the font by its name - in the style block -> the font­Fam­i­ly property.

For font lay­ers - set the mar­gin accord­ing to the per­cent­age cal­cu­lat­ed on step 1.8. Typ­i­cal­ly you need to set only the "top" mar­gin, if the text is cen­tered in the image, and also the "left" mar­gin is the text is not cen­tered. The "right" and "bot­tom" mar­gins are only need­ed if you want to lim­it the width and the height of the text.

Write the font size as the size which you used in the image manip­u­la­tion pro­gram. The same is about text col­or. The back­ground most typ­i­cal­ly will be set to "trans­par­ent".

If you need a con­trast shad­ow behind the text, then just copy/paste the text lay­er, and in the new lay­er add the "blur" prop­er­ty and set the text col­or to "black", for example.

5) Test the tem­plate with the Bot by using the com­mands men­tioned in the pre­vi­ous ses­sions ("addim­agetem­plate", "cre­ateim­age"). If the tem­plate does not works as you expect­ed - delete it using the "deleteim­agetem­plate" com­mand, fix the text in your local file, then repeat the step.

Censoring

Allows to auto­mat­i­cal­ly replace uncen­sored (bad) words by some spe­cial symbols.

Before you use it you need to set up the list of bad words using !addbad­words com­mand, com­ma sep­a­rat­ed. For example:

!addbad­words nword, wword

Also the admins of the serv­er will need to enable the cen­sor­ing fea­ture itself with the fol­low­ing command:

!set­cen­sor­ing on

After that, if some­bosy writ­ed a mes­sage with one of the bad words, the bot will replace that mes­sage with a sim­i­lar one, but with bad words masked by spe­cial sym­bols. Like here:

To see the cur­rent list of bad words, use !bad­words com­mand, and to remove words from the list, use !remove­bad­words command.

Do dis­able the cen­sor­ing, use:

!set­cen­sor­ing off

Typical problems with the bot

Problems with mentions

For many com­mands the bot uses Dis­cord men­tions as argu­ments. The men­tions formed auto­mat­i­cal­ly by Dis­cord client when a user is typ­ing a user name, role name or chan­nel name. How­ev­er, some­times this autore­place­ment fails so you get a plain text which just looks like a real men­tion but is not it real­ly. If the bot gets such plain text, most typ­i­cal­ly it will con­sid­er as an error.

You can dis­tin­guish a men­tion from a plain text using this signs:

  1. Men­tioned are colored.
  2. While mov­ing the cur­sor over a men­tion, the cur­sor becomes a "hand".
  3. When click­ing on a men­tion, options relat­ed to the user/role/channel appear.

For exam­ple, in this screen @ServerAdmin and @moderator are men­tions, and @Batman is just a plain text:

If you try to exe­cute the above com­mand, you will get an unex­pect­ed result.

To fix this, click on the plain text and start type the actu­al name of the role/user/channel. Typ­i­cal­ly the Dis­cord will show a pop-up dia­log allow­ing to select the relat­ed enti­ty and will auto­mat­i­cal­ly will con­vert this into a men­tion upon selec­tion. And of course, make sure you are spelling the name correctly.

Problems with time arguments

OrgHelper uses a flex­i­ble but a bit com­pli­cat­ed sys­tem to read time arguments.

The bot sequen­tial­ly reads sym­bols in the com­mand either until it finds some word/symbol which can­not be treat­ed as a time defin­tion or until it find a defin­tion which can­not be added to already scanned defintions.

After reach­ing that state the bot con­sid­er read­ing the time argu­ment fin­ished and either throws away the remain­ing part of the string (in case of read­ing args by names) or starts to con­sid­er the remain­ing text as the begin­ning of the next argument.

So, if you don't spec­i­fy the argu­ment prop­er­ly, it may lead to unpre­dictable consequences.

For exam­ple, in this command:

!remind each San­day 15:30 Sub­mit your reports!

The day of week names are Mon­day, Tues­day, Wednes­day, Thirs­day, Firi­day, Sat­ur­day, Sun­day. "San­day" is not a day of week so the bot can­not con­sid­er it as a time def­i­n­i­tions, so it will think that the time def­i­n­i­tion end­ed on word "each" not on "15:30". Hence this whole text "San­day 15:30 Sub­mit your reports!" will be con­sid­ered as the text mes­sage to be remind­ed, while the time defin­tion will con­sists only of the user's time zone. Of course it will lead to unex­pect­ed results. More­over you will prob­a­bly not get an error mes­sage from it, because from the bot point of view your com­mand may look strange, but yet it's syn­tac­ti­cal­ly correct.

So be accu­rate while spec­i­fy­ing time argu­ments. And when you are set­ting up reminders, don't for­get to check if the reminder was set cor­rect­ly using the !reminders command.

Got an idea on how to make the time argu­ments more user-friend­ly? Send the idea to us!

Privacy policy

You can find the bot's pri­va­cy pol­i­cy here: http://alteh.org/orghelper-privacy-policy/

In order to ful­fil the require­ment of the pri­va­cy pol­i­cy, the bot have a spe­cial !myda­ta com­mand, which is avail­able only inside direct mes­sages chan­nel ("DM") with the bot. The com­mand shows what exact data the bot has relat­ed to your user id.