Setting up Tootbot (Heroku)

Instead of setting up Tootbot locally on your own computer or server, you can now run Tootbot for free in the cloud using Heroku. This guide will walk you through the whole process.

If you already have Tootbot running locally, and you want to move your bot to Heroku, use these instructions instead.

Important notes

There are some differences between running Tootbot locally and running it on Heroku. Most people won't mind these limitations, but it's important to keep them in mind:

• You can't modify the Tootbot script. If you need to change how Tootbot works, you should set up Tootbot locally instead. Heroku doesn't allow you to modify scripts running in the cloud, unless you install the Heroku command line application. You can still change all of Tootbot's settings.
• Cache works differently. The Heroku version of Toobot uses a Redis database for storing Reddit links that have been posted, instead of adding them to the cache.csv file.

If that all sounds good to you, continue on!

Applying for a Twitter developer account

Due to Twitter's recent changes to API access, you now have to apply for a developer account if you want your bot to post to Twitter. This doesn't take much effort on your part, but you will have to wait a day or two to be accepted. This step is not necessary if you only want to post to Mastodon.

1. Sign in with the Twitter account you want to use with the bot.
2. Once logged in, go apply for a developer account.
3. When asked "Who are you requesting access for?", click the checkbox for "I am requesting access for my own personal use".
4. Twitter will ask you to explain how you will use the APIs. Type something like this:

1. I'm using Twitter's APIs to repost images from reddit.com to Twitter.
2. I am not analyzing any tweets.
3. I will be occasionally posting images to Twitter. The tool using the API will not interact with users in any way.
4. No Twitter content will be displayed.

Once you submit your application, you have to wait for approval from Twitter. You should receive an email in the next day or two. Continue on with this guide once you receive approval.

Deploying to Heroku

Next, you need to create a Heroku account, if you don't have one already. You only need a free account. If you already have an account, go ahead and sign in.

Once you're logged in, enter payment information on this page. This is required for the Redis addon, but you will not be charged because Tootbot uses the free development tier.

Once you've saved payment information, click the button below to deploy a Tootbot application:

Configuring Tootbot

You should see a 'Create new App' page that looks like this:

You can set the 'App name' to whatever you want, but it's best to give it the same name as the social media account for easy reference. Below that are the 'Config vars', which are all of Tootbot's settings. Each setting is explained on that page, so just read the descriptions above the text boxes.

Come back to this guide once you reach the Reddit and Imgur settings at the bottom.

Setting up Reddit API access

1. Log into Reddit, go to your app preferences, and click the 'Create a new application' button at the bottom.
2. Select 'script' as the application type, and click the 'Create app' button.
3. You should see a Reddit agent string (underneath 'personal use script') and an agent secret. Paste the agent string into the REDDIT_AGENT box, and paste the agent secret into the REDDIT_SECRET box.

Setting up Imgur API access

The Imgur API is used to obtain the direct image URLs from Imgur page/gallery/album links.

1. Sign into Imgur with your account, or make one if you haven't already.
2. Register an application here and choose 'OAuth 2 authorization without a callback URL' as the app type.
3. Imgur will give you a Client ID and Client Secret. Paste the Client ID into the IMGUR_ID box, and paste the client secret into the 0 IMGUR_SECRET box.

Creating the Heroku app

Once you've configured all the settings and pasted in the API keys for Reddit and Imgur, click the Deploy app button at the very bottom of the page. Once the installation process is done (all the circles have a checkmark), click the Manage app button.

Setting up Twitter API access (if Twitter posting is enabled)

1. Go to the application dashboard and click the 'Crete an app' button.
2. Fill out the required text boxes and click 'Create' at the bottom.
3. Click the 'Permissions' tab, and make sure the Access permission says 'Read and write'
4. Click the 'Keys and tokens' tab, and click the 'Create' button underneath 'Access token & access token secret'.

Now that you have all the API keys, you need to save them in Heroku.

1. Go to the Heroku dashboard and click on the Tootbot app you just made.
2. Click the Settings tab, and click the Reveal Config Vars button. At the bottom of the variables list are two blank boxes, one for KEY and one for VALUE.
3. Paste TWITTER_ACCESS_TOKEN in the KEY box, then paste the Twitter Access Token you just got in the VALUE box. Then click the Add button.
4. Paste TWITTER_ACCESS_TOKEN_SECRET in the KEY box, then paste the Twitter Access Token Secret you just got in the VALUE box. Then click the Add button.
5. Paste TWITTER_CONSUMER_KEY in the KEY box, then paste the Twitter Consumer Key you just got in the VALUE box. Then click the Add button.
6. Paste TWITTER_CONSUMER_SECRET in the KEY box, then paste the Twitter Consumer Secret you just got in the VALUE box. Then click the Add button.

Setting up Mastodon API access (if Mastodon posting is enabled)

1. Log into a Mastodon account and click on the settings gear above the compose window.
2. In the settings, click 'Development', then click the 'New Application' button.
3. Enter a name (it can be anything) and click the 'Submit' button at the bottom of the page. You don't need to mess with any other options on the page.
4. Click the application you just created and copy the Access Token.

Now that you have the access token, you need to save it into Heroku.

1. Go to the Heroku dashboard and click on the Tootbot app you just made.
2. Click the Settings tab, and click the Reveal Config Vars button. At the bottom of the variables list are two blank boxes, one for KEY and one for VALUE.
3. Paste MASTODON_ACCESS_TOKEN in the KEY box, then paste the Access Token you just got in the VALUE box. Then click the Add button.
4. Paste MASTODON_INSTANCE_DOMAIN in the KEY box, then paste the domain name of the Mastodon instance you're using (e.g. mastodon.social, no 'https' or slashes) in the VALUE box. Then click the Add button.
5. Paste MASTODON_SENSITIVE_MEDIA in the KEY box, then type false in the VALUE box. If you want all media attachments on Mastodon to be marked as sensitive, type true instead. Then click the Add button.

Turning on Tootbot

Now that all your settings and API keys are configured, you can turn on Tootbot. Click on the Overview tab, and click the Configure Dynos link. Then click the pencil icon on the right, click the switch (so it's turned on), and click Confirm.

Tootbot should now be running. You can see Tootbot's messages by clicking the More button on the top right and selecting View logs.

If you ever want to change Tootbot's settings, just go back to the Settings tab, click the Reveal Config Vars button, and click the pencil icon next to whatever option you want to change. To see the description/usage instructions for each option, just look at the deploy page again.

You have to reboot Tootbot each time you change a setting. The easiest way to reboot Tootbot is to click the More button on the top right of the Heroku dashboard and select Restart all dynos.

Once you're done making a bot account with Tootbot, please add it to the list of accounts using Tootbot! Also make sure to subscribe to the Tootbot updates feed via email or with an RSS reader, so you'll be notified when a new version is available.