Conversation Tools Plugin

Requires plugin: convtools

The Hangups library implements rudimentary functionality for creating conversations and adding users. This plugin implements a basic set of (admin-only) commands to manage users and chats. It is subject to change.

Admin Commands

Adding User(s)

/bot addusers 
  <user id> 
  [<user id>]*
  [into <conv id>]

• Add specified user(s) into current conversation or specified conversation (with the into parameter)

/bot addme <conv id>

• Add the initiating user into the specified conversation
• Expands internally to /bot addusers <initiating user id> into <conv id>

Creating a Conversation (1-on-1 or Group)

/bot createconversation
  <user id> 
  [<user id>]*
  [group]

• Create a new conversation with the bot and specified user(s)
• If only one user id specified, will attempt to create a 1-to-1 chat, unless group is specified
  • You cannot convert a 1-to-1 conversation into a group chat once created or vice-versa
  • 1-to-1 conversations are unique and can only be created once per user - attempting to recreate it will simply reuse the existing 1-to-1
  • You can create as many group conversations with a single user or multiple users, even if the group contains the same set of users
• Outputs text to the new conversation to raise the chat window on clients

Refreshing a Conversation

/bot refresh
  [conversation] <conv id>
  [without|remove <user id> [<user id>]*]
  [with|add <user id> [<user id>]*]
  [quietly]
  [norename]
  [test]

• Creates a new group conversation based on the list of users from the specified conversation

  • Specify a list of user ids to exclude with without
  • Specify a list of new user ids to include with add

• Outputs:

  • "group refreshed" to the new conversation - this is required to raise the chat window on clients
  • "group has been obsoleted" to the "source" conversation - [ver>=2.7.2] disable this by specifying "quietly"
  • [ver>=2.7.2] refresh statistics such as the number of users removed/added will be output to the initiating conversation

• [ver>=2.7.2] The bot will also automatically rename the new conversation with the old conversation title and add [DEFUNCT] to the old conversation title - this behaviour can be disabled by specifying either "quietly" or "norename"

• [ver>=2.7.2] Specify "test" to check the results of your command without the bot actually doing anything

• [ver<=2.7.1] An authorisation token was required to confirm any action - follow the instructions to copy and paste the token into your command to authorise it.

• Usage Examples:

  # version 2.7.2 and up - conversation keyword is optional
  /bot refresh XYZ with 111 222 333 norename
  /bot refresh XYZ without 111 222 333 quietly
  
  # version 2.7.1 and below
  /bot refresh conversation XYZ with 111 222 333
  /bot refresh conversation XYZ without 111 222 333
  

Kicking Users

Availability: Bot Version 2.7.2 and Up

/bot kick
  <optional conversation id, otherwise use current>
  <user id> [<user id>]*
  [quietly]
  [test]

• This isn't a true "kick" as Hangouts doesn't implement actual in-conversation user management functions. Instead, it expands internally to /bot refresh <conversation id> without <user id> <user id> ...

• If you do not wish to alert the users you are kicking, specify "quietly"

• Specify "test" if you wish to test the command without the bot doing anything

• Usage Examples:

  # same conversation
  /bot kick 111 222 333
  
  # different conversation XYZ, "stealth" kick
  /bot kick XYZ 111 222 333 quietly