History Bot

This can tweet events over a specific timeline. These can be compressed to a specific time or stretched.

The Code

The bot is written in javascript running on node. you can run your own instance.

To make it run you probably have to point it to your specific json file of events and set up the environment variables for your twitter account and database.

One way would be a bash file like this:

#!/bin/bash
cd /home/historyb/historybot

export HISTBOT_TWITTER_CONSUMER_KEY="..."
export HISTBOT_TWITTER_CONSUMER_SECRET="..."
export HISTBOT_TWITTER_TOKEN_KEY="..."
export HISTBOT_TWITTER_TOKEN_SECRET="..."

export HISTBOT_DB_DB = "..."
export HISTBOT_DB_USER = "..."
export HISTBOT_DB_PSW = "..."
export HISTBOT_DB_PORT = "..."

npm install
jake db:create
npm start

Ans use systemd or whatever to make it run.

List of events

The bot requires a list of events that happen at a specific time which the bot will tweet over a second period of time.

To reduce confusion this documentation will refer to the date and time an event actually happened as an occurrence and the period between the first and last occurrence in the set of events as the duration. The time period over which the tweets happen is the activity of the bot, the representation of an event on twitter during the activity is a tweet.

A very short example of the entire event file looks loke this

{
  "start": "2020-01-01T00:00:00.000Z",
  "end": "2020-12-31T23:59:59.000Z",
  "dateFormat": "yyyy-MM-dd",
  "explicitStartDate": "1920-01-01T00:00:00.000Z",
  "events": [
    {
       "date": "1900-01-01T00:00:00.000Z",
       "text": "Tweet 1"
    },
    {
       "date": "1999-12-31T23:59:59.000Z",
       "text": "Tweet 2"
    },
  ]
}

This would tweet "1900-01-01 Tweet 1" and Januarry first of 2020 and "1999-12-31 Tweet 2" at Decmeber 31st of 2020.

You can find the entire example file for the history of computing in the assets folder.

Event Information

Any event is represented as a json-object which has at least two key/value pairs.

{
   "date": "1927-08-27T00:00:00.000Z",
   "text": "Marvin Minsky is born in New York City. After serving in the US Navy during WWII he is integral to the development of Artificial Intelligence and many other disciplines. He received the Turing Award in 1969."
}

Which would result in a tweet looking like this

The date key represents the date and time of then occurrence, the text is the event description, that will be in the tweet. The format of the date and time in the date-value is based on the dateformat in the event-file header, which is described further below (header information).

It is possible to include links into the text.

{
   "date": "1924-12-03T00:00:00.000Z",
   "text": "John Warner Backus is born in Philadelphia. https://amturing.acm.org/award_winners/backus_0703524.cfm"
}

All Events to be tweeted have to be written into a json file inside the assets folder. All images must be placed into the images folder.

Images

An event may contain a image attribute which contains the name of a file put in the assets/images-folder. png, jpg, jpeg, gif... is fine, anything twitter will upload. keep the images small if possible, 20 mb files are not a good idea.

{
  "date": "1951-04-21T18:00:00.000Z",
  "text": "Whirlwind, the first real-time computer, built at MIT by the team of Jay Forrester for the US Air Defense System, becomes operational.",
  "image": "wirlwind.jpg"
}

Less or more specific Dates

Any event has to be given a specific date to the second. However it will be printed in a format specefied for all events (see below).

Using printDate you can specify what date should be used in the tweet. Alternatively you can provide a deviating format using dateFormat.

Threads

Sometimes several tweets tell a story of an event. We can use threads for that.

All tweets in a thread are tweeted at the same time.

{
  "date": "1955-06-08T18:00:00.000Z",
  "text": "Tim Berners-Lee is born. In 1989 he will propose an Internet-based hypertext publishing system. Mike Sendall, his manager, called it 'vague but exciting'.",
  "thread": {
    "text": "In 2016 Berners-Lee received the Turing Award for inventing the World Wide Web, the first web browser, and the fundamental protocols and algorithms allowing the Web to scale."
  }
}

Threads can also be helpful in adding licensing info for images under creative commons. Make sure only to use images you are allowed to use.

thread elements can contain images and links and also can contain another thread element. They may not contain date, printDate or dateFormat.

Header Information

The json file has five general configuration parameters

• start Time the bot should start tweeting
• end Time the bot should tweet the last tweet
• dateFormat format description for tweets
• explicitStartDate this date would be taken instead of the earliest occurrence
• explicitEndDate this date would be taken instead of the latest occurrence

The elements start and end denote the length of the activity of the twitter bot.

The dateFormat element determines the standard date format that us used to format the date at the beginning of each tweet.

The duration is computed using the occurrence of the first and last event. However, if the duration should start before the first event or end after the last event, the elements explicitStartDate and explicitEndDate can be used.

Date Format

The Bot is using the date-format npm packet and format has to be consistent with its rules.

How to tell stories using twitter

Historic events may sometimes not be uniformly distributed creating a problem when telling them in compressed time. People will be annoyed if a bot tweets every few minutes for long periods of time.

On the other hand, at very exiting times, a high frequency for a short period may be entertaining. In some cases, it may be expected and appreciated.

Try to imagine the stream of tweets being one of many things in a timeline. The bot should not overpower any other users twitter feed.

Long periods of silence, depending on the topic, may not be avoidable but should not be a problem.

Tips and Tricks

• The events in the json file do not have to be chronological. It just helps when reading it. The first event however actually should be the first and the last should be the last... Because of a bug.

Software Released under MIT License

Only the software, not the example dataset nor the images relevant to that dataset (the folder '*'assets') are released under this license.

Copyright (c) 2020 Lukas Ruge

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Licence for the computing.json Dataset

As a collection of facts the data can not be under copyright and is thereby free to use.

Images

Images are from third parties. No permission is granted.