Message Sending

Available Functionality

messaging arbitrary conversation

# calling from command or handler body (i.e. from an asyncio.coroutine)
yield from bot.coro_send_message( "<conv id>"|Conversation, 
                                  "<string>"|[ChatMessageSegment], 
                                  context=None, 
                                  image_id=None )

# calling from a conventional function
# note: this is a non-blocking call
asyncio.async(
    self.coro_send_message( "<conv id>"|Conversation,
                            "<string>"|[ChatMessageSegment],
                            context=None,
                            image_id=None )
).add_done_callback(lambda future: future.result())

# calling from a conventional function without asyncio
# note: the underlying call is non-blocking
bot.send_message( "<conv id>"|Conversation, 
                  "<string>"|[ChatMessageSegment],
                  context=None,
                  image_id=None )

• drop-in replacements for:
  • bot.send_message_parsed(conversation, html, context=None)
  • bot.send_html_to_conversation(conversation_id, html, context=None)
  • bot.send_message_segments(conversation, segments, context=None, image_id=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
      • special note: bot.send_message() sends any string-based messages as plain-text (without html and markdown parsing) by default for historical reasons - standard parsing behaviour can be switched on with the context parameter
    • 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

# calling from command or handler body (i.e. from an asyncio.coroutine)
yield from bot.coro_send_to_user( '<user id>', 
                                  '<string>', 
                                  context=None )

# calling from a conventional function
# note: this is a non-blocking call
asyncio.async(
    self.coro_send_to_user( "<user id>",
                            "<string>",
                            context=None )
).add_done_callback(lambda future: future.result())

• 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

# calling from command or handler body (i.e. from an asyncio.coroutine)
yield from bot.coro_send_to_user_and_conversation(
    "<chat id>", 
    "<conv id>", 
    "<private html>", 
    public_html=False
    context=None)

# calling from a conventional function
# note: this is a non-blocking call
asyncio.async(
    self.coro_send_to_user_and_conversation( 
        "<chat id>",
        "<conv id>",
        "<private html>",
        "<public html>",
        context=None )
).add_done_callback(lambda future: future.result())

• 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.

toggle HTML and Markdown messages

context["parser"] = True # parse HTML and Markdown
context["parser"] = False # send message as plain-text

For historical reasons, send_message() sends messages as plain-text by default. HTML/Markdown parsing can be forced on by overriding the default context:

send_message(conv_id, message, context={ "parser": True })

All other modern message sending functions have HTML and Markdown parsing switched on by default.

---

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