Hello everyone! We’re excited to announce a new update. This time, the bot SDK has been updated to version 23.1.0b13. As usual, you can install it using the following command:
pip install highrise-bot-sdk==23.1.0b13
This version introduces some new features for the bot SDK, such as:
-
Optional Startup Hook: Introducing an optional hook that is triggered during bot startup (
async def before_start(self, tg) -> None:). All bot initialization, including reading from files and setting up database connections, should be done here instead of in the on_connect method. This prevents unnecessary repetition of bot setup processes during each connection. Additionally, the tg object provided here can be used to start background tasks if needed (e.g.,tg.create_task(self.process_buffer())). -
In-Game Conversations and Messages Support: The bot now has access to in-game conversations and messages.
Here’s a brief overview of how Conversations and Messages work in Highrise and how bots can utilize this system:
All Highrise messages are contained within specific conversations, and a message can only be sent to a designated conversation. To initiate communication with someone, a conversation must be created. There are several types of conversations, but bots can only see and interact with direct conversations, which are one-on-one conversations between users and bots. Typically, when you whisper to someone in-game for the first time, a conversation is created.
Bots cannot create conversations independently; they can only respond to messages from other users. This design choice ensures that bots are not used to message users unless the user chooses to participate in a conversation with the bot.
Once a conversation is created and a user has messaged the bot, the bot can send a reply. Bots can send and receive only two types of messages, with the most important one being text messages. Text messages are the most common and straightforward type of Highrise message and can contain any valid in-game text. Please note that all messages are subject to content checks and regular trust and safety procedures.
Additionally, bots can send room invites, which is a special type of text message that generates a room link for a user. This feature can be used to invite users who have initiated conversation with a bot to join a room.
Regarding how conversations function: once a conversation is created, only the initiator is considered an active user or a participant in the conversation. Users typically need to join a conversation to start sending messages, but for bots, this is done automatically. When a bot sends its first message to a conversation, it will automatically join the conversation. Bots also have the ability to leave a conversation, at which point they will be removed from the conversation and no longer have access to it. However, the user will still be able to see all the messages the bot sent.
The following are commands and events that bots can utilize for interacting with the messaging system:
-
Message Handler: Triggered when a bot receives a message from a user (
async def on_message(user_id, conversation_id, is_new_conversation)). It activates when a user sends an in-game message to the bot in either a new or existing conversation. If it’s a new conversation, the is_new_conversation parameter will be set to True, otherwise, it will be False. -
Send Message to User: To be used only for existing conversations, this function will fail if a conversation is not found (
self.highrise.send_message(conversation_id, message, type, room_id)). The bot can send two types of messages: text and invite. Text messages allow the bot to send text to the user, while invite messages are used to invite the user to a room. If the type is invite, the room_id must be provided to generate a room invite for users. -
List Conversations: Returns a list of conversations with the bot (
self.highrise.get_conversations(not_joined, last_id)). There are two types of conversations: joined and unjoined. If not_joined is set to True, only unjoined conversations will be returned,and if set to False, only joined conversations will be returned. The response will also include the number of unjoined conversations that the bot has. This method returns up to 20 conversations, ordered from the newest to the oldest. If last_id is provided, only conversations older than the specified id will be returned. -
List Messages in Conversation: This function returns a list of messages within a conversation (
self.highrise.get_messages(conversation_id, last_id)). Up to 20 messages will be returned, ordered from the newest to the oldest. If last_id is provided, only messages older than the specified id will be returned. The conversation_id must be from a conversation accessible to the bot. -
Leave Conversation: Allows the bot to exit a conversation (
self.highrise.leave_conversation(conversation_id)). The bot will no longer receive messages from the user in that conversation or have the conversation on its list.
Please note that social features have stricter rate limits and will be more heavily throttled than regular in-room messages. This is necessary to prevent bots from becoming spam bots. Keep this in mind while designing bots that use these features.
Current rates for social features can be found in the rates object in session_metadata under the key ‘socials’.
This is a significant update, and upgrading the SDK is highly recommended to take advantage of these new interaction features in the messaging system.
By using these commands and events, developers can create more engaging and user-friendly bots that enhance the overall experience for users within various rooms and conversations. Remember to adhere to the rate limits and throttling guidelines for social features to ensure a smooth and reliable messaging experience between bots and users.