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.
- Get a Trove API key by following these instructions.
- Once you have the key insert it in credentials.py.
- Decide on a name for your bot and insert it in the appropriate place in trovebot.py (without the @).
- Sign up for a Twitter account in the name of your bot.
- Go to the Twitter Developer Site and sign in using your bot's details.
- Click on 'Create an App' and fill out and submit the form. You don't need a callback url.
- On the 'Settings' tab under 'Application type' select the radio button next to 'Read and Write'. Click the 'Update' button.
- On the 'Details' tab click the 'Create my access token' button.
- If your access token details don't appear, reload the page.
- 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.
- Go to the Australian Libraries Gateway.
- 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.
- Click on the 'More details' button.
- 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'.
- 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.