This document is intended to explain precisely which blocks are available in the Welcome Channel module, and how you can configure them. This should serve as a reference guide for anyone directly making use of Cozy’s Welcome Channel module, but it will probably apply to other bots that utilize it as well.
The Welcome Channel module is configured by linking to a YAML file somewhere on the Internet. The intention here is for you to update this YAML file whenever you need to modify the contents of a welcome channel, and the bot should pick that change up automatically (or manually if the refresh command is available). This means that the location of the YAML file must not change when you edit it — so you can’t use something like gist.github.com to host your YAML file, as you need to change the link every time you update it. Some potential options you can use include:
It’s important that the link never changes — if it does, you’ll need to configure your channel again every time you update the file!
YAML is intended to be a simple configuration language, readable by people that have no technical background. While it doesn’t quite manage to achieve this, it should be sufficient for any data you’d need to provide to this module.
While explaining how to use YAML directly is out of scope of this document, the following example should give you an idea of the basics:
# Text prefixed with a hash will be treated as a comment and ignored
number: 12345
decimal: 12.345
strings:
simple: Just type your text, like this
quoted: "If the parser is confused, you can quote the text to be explicit"
raw: 'Raw strings allow you to type a single \\, as they don't support escapes'
multi_line: >-
Multi-line strings should be specified using the "folding style" indicator, as shown
here with the block chomping indicator ("-"). This is because a new-line on Discord
always results in a line-break, and you'll want to be able to write longer blocks
of text without breaking them, like this.
To denote a line break, simply use a blank line, like you see above. Blank lines
will be shown as a single line break, so you'll need to use two blank lines to
display a single blank line on Discord.
list:
- List item 1
- List item 2
maps:
key: value
other_key: other value
For more information on multi-line strings, see the YAML Multiline site.
Your YAML file should contain a list of blocks, and nothing else. Your blocks will be sent to Discord in the order you define them in the file.
All blocks require a type key, representing type. Additionally, most blocks require some extra configuration data, which should be provided in the same part of the file.
- type: text
text: "Hello, world!"