Message Sending

Available Functionality

messaging arbitrary conversation

yield from bot.coro_send_message( "<conv id>"|Conversation, 
                                  "<string>"|[ChatMessageSegment], 
                                  context=None, 
                                  image_id=None )

• drop-in replacement for bot.send_message_parsed('<conversation id>', '<string>', context=None) and bot.send_html_to_conversation('<conversation id>', '<string>', context=None)
• parameters:
  • supply target conversation id or Hangups Conversation
  • message can be <string> or list of ChatMessageSegment
    • <string> can contain simple html formatting and basic markdown
    • None can be supplied if there is an image_id
  • use optional context to supply additional instructions and/or metadata
  • supply optional image_id if an image uploaded previously with bot._client.upload_image()
• does not obey /bot optout if the target conversation is a 1-to-1 that has /bot optout active

messaging user via 1-to-1

yield from bot.coro_send_to_user('<user id>', '<string>', context=None)

• replaces bot.send_html_to_user('<user id>', '<string>', context=None)
• if config["autocreate-1to1"]: true, will attempt to create the 1-to-1
• obeys user /bot optout and will output to log if message sending blocked
• sends <string> to specified <user id> as long as the user already has a one-on-one conversation with the bot
• <string> can contain simple html formatting and basic markdown
• the bot must have at least "seen" the user once in another conversation, otherwise this function will emit a WARNING that the user is "not a valid user"
• for info on context, see the next section

send private message to user and (optional) public message simultaneously

yield from bot.coro_send_to_user_and_conversation(
  "<chat id>", 
  "<conv id>", 
  "<private html>", 
  public_html=False
  context=None))

• utility function to simultaneously send a private message (pm) to a user's one-to-one, and a public message to another conversation (usually the group where the user initiated the request)
  • will inform the user publicly if no one-to-one is found or user has /bot optout
  • example behaviour can be seen in /bot help command - help output can be very long, the actual help text is sent privately, with a short teaser sent publicly if command is used in a group
• will automatically handle cases where no one-to-one exists or user is /bot optout of alerts - an appropriate localised message will be displayed publicly
• public_html parameter can be:
  • string containing the public "teaser" message if the function is successful in sending the pm
  • False to disable the public "teaser" message - error messages caused by user opt-out or no one-to-ones will still be relayed publicly unless explicitly disabled with a dict or list-based parameter
  • dict or list containing the public message strings

  public_html = {
    "standard": "I sent you a message privately!",
    "optout": "You are opted-out and I can't send you anything!",
    "no1to1": "I don't have a 1-to-1 with you. Please message me!"
  }
  
  1. setting any key to False will disable that message response
  2. a list can also be supplied in the same sequence as the above dict 
     example - supplying less list items than the keys will result in 
     default messages being used

• for info on context, see the next section

The context Parameter

Most messaging functionality accepts an optional named parameter context, which (if set) is a dict.

The context variable is used by some plugins for advanced pre-processing and/or post-processing of messages. This section outlines useful context keys that can be used by plugin devs.

force Off-The-Record (OTR) flag

context["history"] = True # force history ON for current message
context["history"] = False # force history OFF for current message

This only works for the single message being sent - it does not change the global OTR flag for a chat.

---

Legacy

Functions listed in this section are no longer supported and should not be used in new plugins and extension.

bot.send_html_to_user('<user id>', '<string>', context=None)

• sends <string> to specified <user id> as long as the user already has a one-on-one conversation with the bot
• <string> can contain simple html formatting and basic markdown

bot.external_send_message(conversation_id, text)
bot.external_send_message_parsed(conversation_id, html)

• legacy functionality to send messages to a conversation
• used by some sinks/hooks