Command Bot for Twitter

What's it for?

• Helps you or your community tweet repetitive content to users.
• Helps your brand's community contribute towards support and miscellaneous tasks.

Performance:

Twitter user @MehowBrains commissioned his crew to get this bot developed, and deployed one for the @THORChain_org community under the @THORChainHammer bot. He's used it religiously over several months, and in July 2020 it helped him amass over 812,000 impressions to his tweets.

Functions:

• You or your community can tweet a content command and get a tweet-back from the the bot with the requested content.
• You or your community can tweet a join role command to be assigned into that user group / role.
• You or your community can tweet a task command and get a tweet-back from the the bot with the requested tasks for the role.
• Admins can manage content, roles, tasks, users and admins by DM'ing the bot.

Use-case examples:

Here's some examples from the @THORChainHammer bot that @MehowBrains deployed:

a) Users often tweet questions to one another "what's the link to the Google sheet which contains the emission schedule?". A bot command can help you or any other users reply to that tweet without actually looking for the link themselves. They'd just tweet something like: @THORChainHammer emissions --- and the bot will reply with the link. You or other users were now able to join-in on supporting the request by simply learning the command. The bot is great for organizing content via custom commands that you name. You can set links to websites, tweets etc. Think of it like having a website at your fingertips. You no longer have to go look for the content, you just need to memorize commands and tweet them out.

b) Users often want to help a community, but don't know what to do or who to ask for directions. Teams are also busy developing stuff, and often the community is left with the role to shill and support. But many of these followers are in fact experts at something usually, whether it be marketing, engineering, design etc. So I wanted to develop an easier way to communicate tasks to followers, without necessarily having to interact with them directly one by one. With the bot, an admin can create a role for his Twitter community i.e. #THORChainMarketers, write a medium article or tweet about the on-going tasks for that role, and link the content to that role. A user would tweet @THORChainHammer tasks THORChainMarketer -- and the bot would reply with the link to the medium post / tweet which highlights the tasks they can be working-on.

---

Bot internals:

The bot really functions as 2 separate bots

• bot.py - which handles all public commands.
• pm.py - which handles all administrative commands.

bot.py is pretty simple. It gets all mentions using standard API. Since this bot is coded in Python, there's a library, Tweepy, that does all behind scenes. Once it gets all mentions, it processes each one. To determine which command it has to execute, it compares based on some standard commands. If none of them matches, then it will look for content in DB. Content is the text that an admin user sets up. Finally, it saves every message ID into the database. When processing mentions it check whether it wasn't already processed or it wasn't generated more than a day ago. If this condition meets, it will process. Otherwise, it will ignore this mention.

pm_bot.py commands work in a similar way, but instead of getting mentions, it will get received private messages for the administrator's commands via DM (or as we call it: PM aka private message).

---

Running the bot:

1. In the tweets.db SQLite database:

   • Create a master admin user by:

     • Creating a new row in the users_by_role table:

       • userid = the Twitter userid for the @handle that'll be the master administrator. That userid for the handle can be found via tools like TwitterID.com.

       • role_id = 1

2. In the bot.py file:

   • Set your Twitter Developer API credentials:

     • consumer_token = ''
     • consumer_secret = ''
     • access_token = ''
     • access_token_secret = ''

   • Set the path where the tweets.db is stored. By default it's set to: /root/command-bot/tweets.db

   • Set the path where you'd like to log exceptions. By default it's set to: /root/command-bot/log

   • Set the link for your admin and public guides (i.e. if users tweet @THORChainHammer help, they'll get a tweet back with the link to the public guide):

     • LINK_TO_ADMIN_HELP_LINK = 'link-to-the-admin-guide-between-the-quotes'
     • LINK_TO_PUBLIC_TWEET_HELP = 'link-to-the-public-guide-between-the-quotes'

3. In the pm_bot.py file:

   • Set the path where you'd like to log exceptions for the pm bot. By default it's set to: /root/command-bot/pm_log

It's recommended that the bot be setup on a VPS for availability.

---

Using the bot:

Administrative commands:

If your handle was set as a master administrator in the tweets.db file, you can DM the bot the following commands to manage it:

• Help:

  • Command: help
  • Replies: Link to the admin guide previous set in the bot.py

• Content:

  • Command: add-content command-name link
  • Command: edit-content command-name new-link
  • Command: remove-content command-name
  • Command: content

• Role:

  • Command: add-role role-name
  • Command: edit-role role-name new-role-name
  • Command: remove-role role-name
  • Command: recruit @handle role-name
  • Command: fire @user-handle role-name
  • Command: role @user-handle

• Tasks:

  • Command: add-task role-name link
  • Command: edit-task role-name new-link
  • Command: remove-task role-name

Public commands:

These commands are available for anyone to tweet:

• Help:

  • Command: @bot-handle-name help
  • Replies: Link to the public guide previous set in the bot.py

• Content:

  • Command: @bot-handle-name command-name

• Role:

  • Command: @bot-handle-name recruit
  • Command: @bot-handle-name join role-name
  • Command: @bot-handle-name quit role-name
  • Command: @bot-handle-name role

• Tasks:

  • Command: @bot-handle-name tasks role-name

• Stalk:

  • Command: @bot-handle-name stalk keyword