If you're an organisation that contributes collection records to Trove you can use this code to build your own Twitter bot that responds to user queries and tweets random collection items.

• Python
• python-twitter and its dependencies

To set up your bot you need to create a Twitter account and then generate the necessary authentication keys for both Twitter and Trove.

1. Get a Trove API key by following these instructions.
2. Once you have the key insert it in credentials.py.
3. Decide on a name for your bot and insert it in the appropriate place in trovebot.py (without the @).
4. Sign up for a Twitter account in the name of your bot.
5. Go to the Twitter Developer Site and sign in using your bot's details.
6. Click on 'Create an App' and fill out and submit the form. You don't need a callback url.
7. On the 'Settings' tab under 'Application type' select the radio button next to 'Read and Write'. Click the 'Update' button.
8. On the 'Details' tab click the 'Create my access token' button.
9. If your access token details don't appear, reload the page.
10. Copy the following values to credentials.py: 'Consumer Key', 'Consumer Secret', 'Access Token', and 'Access Token Secret'.

To limit the bot's tweets to your own collection you need to know your organisation's NUC symbol.

1. Go to the Australian Libraries Gateway.
2. Click on 'Find a library' and search for your organisation. Note that there may be more than one entry -- perhaps one for your library and one for your collection or repository.
3. Click on the 'More details' button.
4. Look for the NUC symbol and copy it. It may be just a four letter code, or a four letter code followed by a colon and further letters eg: 'AMOA' or 'AMOA:C'.
5. Copy the NUC symbol to the appropriate place in trovebot.py.

By default the bot will treat every tweet sent to it as a query to be used to search the collection. If you want to use your bot account to have human-mediated conversations, you might want to change this. Set

AUTO_REPLY = False

and tweets will only be treated as queries if they include the hashtag '#q'. You might also want to change the default GREETING string to explain this to users.

You also have the option to change where the link in a collection result will go. By default the links go to Trove. If you set

DEEP_LINK = True

the bot will use the deep link into the original collection database, assuming that one is available.

You don't need anything fancy to host your bot, just a machine permanently connected to the net. If you're deploying to a server, you might need to set the path values in file_locations_prod.py. If that's the case, don't upload file_locations_dev.py.

In a terminal go to the directory containing your bot's files.

To make it reply to queries enter:

python trovebot.py reply

To make it tweet a random collection item enter:

python trovebot.py random

You probably want to set these up to run at regular intervals using something like cron. I tend to run the 'reply' script every five minutes, and the 'random' script every few hours.

• Include the word 'hello' in a message to your bot to receive a greeting and a random collection item.
• Any other message will be treated as a query and will be sent off to the Trove API to look for matching results.
• To receive any old random collection item, just tweet your bot the hashtag '#luckydip' and nothing else.

By default, your bot tweets the first (ie most relevant) matching result back to you. To change this you can:

• Include the hashtag '#luckydip' to receive a random item from the matching results.

By default, the search terms you supply are sent directly to the Trove API without any modification. To change this you can:

• Include the hashtag '#any' to search for items that match any of your search terms. This is the same as adding an 'OR' between your terms.

Built by @wragge using the Trove API and the Twitter API.

Released under CC0 licence.