Fictional Messenger Guide
Fictional Messenger makes it easy to display fictional chats & text messages with the appearance of real-world messaging platforms. It is intended for use in fiction where writers want to display conversations as if they were happing via text messages or chat apps.
Instead of generating static images like similar tools, Fictional Messenger generates HTML and CSS that can be used on Archive Of Our Own, or anywhere else where HTML is permitted.
The HTML that Fictional Messenger generates will still be readable even when CSS isn't available, such as when AO3 work skins are disabled, or for readers using accessibility technologies.
Fictional Messenger will always be 100% free and open source.
We're in beta, so if you run into problems or have questions please let us know in the Discord.
(Check out the Cheat Sheet for a less overwhelmingly verbose shorter guide to FM's syntax.)
Writing Your Chat Conversations
Write your work how you normally do in any common editor like Google Docs, LibreOffice Writer, or Microsoft Word. When you want to add a chat conversation to your work, write it like this:
-- fm: your-config-name --
jane: This is a message from Jane
doe: And this is a message from Doe
-- end --
Conversations should start with -- fm: your-config-name --, and end with -- end -- This is what tells Fictional Messenger what part of your work contains chat messages. (The -- parts can be any number of hyphens, dashes, or minus signs, so it's okay if your editor turns -- into —.)
Put anything you want in the your-config-name part, except for spaces. This tells Fictional Messenger which "conversation config" to use. (You'll create those later.)
If you use the same config name for multiple chat conversations, then they'll use the same settings. This lets you make multiple conversations with the same users and appearance without needing to set up each one separately.
Messages
Inside the conversation, messages start with a username and a colon, followed by any text.
username: Message goes here.
The username part can be a short name for that person. When you set up your conversation config later, you can give a different name for that person. For example, you could type esmerelda: and then have it appear as "Princess Esmerelda Margaret Note Spelling of Lancre."
Usernames can contain any characters expect for spaces and colons.
If writing multiple messages from the same user, you don't need to repeat the username. Just write messages on the following lines.
jane: This is a message from Jane
This is another message from Jane
If you want to write a note to yourself inside a conversation without it appearing in your work, just start a line with two forward slashes.
// This is a comment. It won't appear in your work.
jane: This is a message.
Also, you can put blank lines anywhere to keep long conversations easier to read. The blank lines won't appear in your work.
jane: This is a message.
doe: This is a message after a blank line.
Formatting With Markdown
If you want to add formatting to your messages like bold or italics, or add links or images, you'll need to use Markdown, a simple way of adding formatting to text.
Markdown is pretty simple.
- Italics: Surround text with one asterisk or underscore
*like this*or_this_
- Bold: Use two asterisks or underscores
**like this**or__this__
- Links: Put the link text in square brackets and the URL in parentheses
[link text here](https://example.com)
- Images: Start with an exclamation mark, then put alt text in square brackets and the image URL in parentheses
- (Always be sure to add an alt describing the image for people using screen readers!)
Here's an example in action:
jane: So, _this is in italics_
And **this is bold.**
doe: Here's [a link to an example website](https://example.com).
And here's an image:
[a photo of distant snowy mountains surrounded by clouds](https://picsum.photos/id/1/200.jpg)
Advanced users can use HTML in their messages, too.
jane: <iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ?si=oU7wCNSIdGhgOEm9" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
Using Markdown For An Entire Work
Particularly nerdy authors may choose to write their entire works using Markdown instead of a regular editor.
When using Markdown for everything, just write your conversations inside code fences like this:
```fm: your-config-name
jane: This is a message inside Markdown.
```
Timestamps
Conversations can have optional message timestamps to indicate when messages were sent. Timestamps are very flexible and can be shown as specific dates and times, or as dates and times only relative to previous messages. For example, one could write a message as being sent on Dec. 31st, 1999, at 11:59 PM, or simply sent "an hour ago". Timestamps will appear as specifically as you write them.
Different styles can display timestamps in different formats, but they're all input the same way in conversations.
Timestamps work like this:
[1999-12-31 11:59 pm] jane: This message was sent at the turn of the millennium.
Timestamps can be full dates and times, date and times without years, just times, or just relative time between messages. They can be written before or after the username, but before the colon separating the username from the message.
Dates and times are always written in the format year-month-day hour:minute:second, with optional AM/PM indicators. (24-hour time works too.) Seconds are optional.
Here are some example timestamps:
[1999-12-31 23:59]- Will show as Dec 31, 1999, at 11:59 PM[12-31 23:59]- Will show as Dec 31 at 11:59 PM, in no particular year[11:59 pm]- Will show as11:59 PM, on no particular date
If a timestamp is less specific than one before it, it'll use the previous timestamp as a reference. For example:
[1999-12-31 3:00 pm] jane: It's 3 PM on Dec 31st, 199
[6:00 pm] jane: Now it's 6 PM on the same day
Relative timestamps will base themselves on the previous timestamp. They work like this:
[1:00] jane: It's 1 AM
[+1h] jane: Now it's 2 AM
[+1h 30m] jane: Now it's 3:30 AM
Relative timestamps always start with a + and can add days, hours, minutes, and seconds.
[+1d]: Adds one day[+1h]: Adds one hour[+1m]: Adds one minute[+1s]: Adds one second[+1]: Adds one second[+ 4d 3h 2m 1s]: Adds four days, three hours, two minutes, and one second[+4d3h2m1]: Adds four days, three hours, two minutes, and one second
Timestamps on their own line will set the current conversation time without including a message.
[1999-12-31 11:59 pm]
jane: This message was sent at the turn of the millennium, even if it doesn't have a timestamp of its own
Messages without a timestamp will be automatically given a timestamp 30 seconds after the last timestamp in the conversation. This can be controlled using the message-interval attribute, or mi for short.
[1:00] jane: It's 1:00:00
jane: Now it's 1:00:30
jane: Now it's 1:01:00
[message-interval = 1h]
jane: Now it's 2:01:00
jane: Now it's 3:01:00
[mi=0s]
jane: It's still 3:01:00
The last timestamp in a conversation will set its "conversation timestamp", or the date and time at which the conversation is being displayed.
If the conversation timestamp is left as the timestamp of the last message, then the last message's timestamp will be displayed as "Just now".
jane: This message was "A day ago"
[+1d] jane: This message was "An hour ago"
[+1h] jane: This message was "Just now"
Use a timestamp after the last message in a conversation to make it appear as if it was being read later than the last message:
jane: This message was "A day ago"
[+1d]
Or:
[1999-12-31 23:59] jane: This message was on Dec 31, 1999, 11:59 PM
[2000-12-31 23:59]
Attributes
Attributes can change how conversations or messages are displayed. Most attributes are specific to particular styles, so refer to each styles' documentation to read which attributes are available.
Attributes are written like this:
[name = value] jane: This attribute sets "name" to "value".
It doesn't do anything on its own, but a style could use it to control how this message appears.
There are a few universal attributes that apply to all conversation styles, such as message-interval. Check out the Cheat Sheet for a list.
Using Fictional Messenger
Once you've created a document with some chat conversations in it, select the whole thing and copy it. Then open Fictional Messenger and click the "Get Started" button.
On the "Paste Your Document" page, paste your document into the text box. (Leave the format selector as "Rich Text", unless you're writing your work as plain HTML or Markdown.)
Click "Next". On the "Configure Your Conversations" page, you can change how your conversation will appear. Each "config name" you used inside a -- fm: config-name -- will have its own section on this page.
Choose which style you want your conversations to use by clicking the "Select Style..." button. You'll see a list of styles with descriptions and previews. Click "Select" by the one you want.
Each style has its own selection of settings to control how your conversations will appear. Settings under the "Settings" subsection will apply to the whole conversation. User-specific settings appear under each user's name in the "Users" section.
Under each user's name, you can set that user's "Display Name". This is the name that will appear in your conversation, letting you type a short username and then have it appear as something longer.
Once you've customized each "conversation config", click "Next". You'll be taken to the "Results" page, containing the finished version of your work that can be used in AO3 or other websites.
Under the "Configuration" subsection, make sure to copy your configuration and then paste it into your original document. This way, if you need to make changes to your work, Fictional Messenger will remember your conversation config settings so you don't need to enter them again.
(The --- fm-configs --- section can go anywhere in your document. Fictional Messenger will automatically detect it, and it won't appear in your finished work.)
If you later make more changes to your conversation configs, just replace the old --- fm-configs --- section with the new one.
Publishing
Now that you've rendered your work to HTML, you'll need to publish it. How you do that depends on what you're publishing to.
Archive Of Our Own (AO3)
Publishing to AO3 is pretty simple. Start by creating or editing a work on AO3 like usual. When it's time to input your work, copy the "HTML" section of Fictional Messenger's "Results" page and paste it into the "Work Text" section of your work on AO3.
Conversations in your will now appear, but only as regular text. To make your conversations appear in your chosen styles, you'll need to create a new work skin. You can do so from the "Skins" > "My Work Skins" section of your AO3 settings. (Check out AO3's Guide to Work Skins for detailed instructions.)
Set the work skin's title and description to whatever you want. Your work's name and "Fictional Messenger" would be a reasonable choice.
Copy Fictional Messenger's CSS from the "CSS" section of your "Results" page, and then paste it into the "CSS" section of AO3's "Create Work Skin" page. Then, click Save.
(We'll try to avoid breaking changes either way, but this is still best practice.)
Edit your work and select your new work skin. (Check out the AO3 guide above for detailed instructions.) After you save, you should see your conversations fully styled in your work.
If making changes or adding new chapters to an existing work that uses Fictional Messenger, be sure to pay attention to the "Last Updated" date listed in the "CSS" section of the "Results" page. If the updated date is later than the last modified date on your work skin, you should edit your skin and paste in the new CSS.
If you use Fictional Messenger in a work, consider leaving a link in your end notes.
This work's chat conversations were created with <a href="https://fictional.tools/messenger/?utm-source=user-share" target="_blank">Fictional Messenger</a>.
Other Sites
Other sites will have different steps for publishing your work. If they support HTML, then the "HTML" section of Fictional Messenger's "Results" page can be copied and pasted into that site.
If the site allows custom CSS, consult that site's documentation for instructions on setting that up.
If the site does not allow custom CSS then your conversations will appear in a plain format without styling, but should be perfectly readable.
Plain HTML
If publishing to a plain HTML document, you can just paste in the "HTML" results wherever you'd like in the document. Be sure to include a <style> tag containing Fictional Messenger's CSS.