diff --git a/docs/account.md b/docs/account.md index 8c039ec..f444f53 100644 --- a/docs/account.md +++ b/docs/account.md @@ -328,6 +328,8 @@ A message can be **at most 2000 characters long**, matching the limit enforced b | `message` | `str` | Yes | The text message to send. Cannot be longer than **2000 characters**. | | `reply_to_message_id` | `str` | No | The `id` of the message being replied to. Message IDs can be obtained from the `id` key of [`get_messages`](./account.md#get_messageschat_id-start_timestampnone-end_timestampnone) or from a [`listen_messages`](./account.md#listen_messages) event. When omitted (default), the message is sent as a standalone message. | +Returns `str` - the `id` of the message that was just sent. It is the same identifier that appears under the `id` key in [`get_messages`](./account.md#get_messageschat_id-start_timestampnone-end_timestampnone), so it can be passed straight into [`delete_message`](./account.md#delete_messageid) or used as the `reply_to_message_id` of a follow-up message, without having to fetch the chat's messages first. + ```python from status_sdk import Account @@ -340,7 +342,8 @@ account.login(**params) # This is under the assumption you already have a contact / joined a community chat = account.chats[0] -account.send_message(chat["id"], "Hello from my Status bot!") +message_id = account.send_message(chat["id"], "Hello from my Status bot!") +print(f"Sent message: {message_id}") ``` Reply to a message: @@ -416,7 +419,7 @@ You can only delete messages that the logged-in account has sent. Messages sent | Name | Type | Required | Description | |-----|-----|-----|-------------| -| `id` | `str` | Yes | The `id` of the message to delete. Message IDs can be obtained from the `id` key of [`get_messages`](./account.md#get_messageschat_id-start_timestampnone-end_timestampnone). | +| `id` | `str` | Yes | The `id` of the message to delete. Message IDs can be obtained from the `id` key of [`get_messages`](./account.md#get_messageschat_id-start_timestampnone-end_timestampnone), or directly from the return value of [`send_message`](./account.md#send_messagechat_id-message-reply_to_message_idnone). | Returns `bool`. @@ -436,11 +439,9 @@ params = { account.login(**params) chat = account.chats[0] -account.send_message(chat["id"], "Oops, this was a mistake!") +message_id = account.send_message(chat["id"], "Oops, this was a mistake!") -# Messages are returned newest first, so the message just sent is the first one -messages = account.get_messages(chat["id"]) -deleted = account.delete_message(messages[0]["id"]) +deleted = account.delete_message(message_id) print(f"Deleted: {deleted}") ``` diff --git a/docs/community.md b/docs/community.md index d13c79a..8a5f72c 100644 --- a/docs/community.md +++ b/docs/community.md @@ -845,7 +845,7 @@ Send a text message to the channel. Supports **text messages only**, optionally | `message` | `str` | Yes | The text message to send. | | `reply_to_message_id` | `str` | No | The `id` of the message being replied to, from [`get_messages`](./community.md#get_messagesstart_timestampnone-end_timestampnone). When omitted, the message is sent standalone. | -Returns the current `Channel` instance, allowing method chaining. +Returns `str` - the `id` of the message that was just sent, delegated from [`send_message`](./account.md#send_messagechat_id-message-reply_to_message_idnone) on `Account`. It is the same identifier that appears under the `id` key in [`get_messages`](./community.md#get_messagesstart_timestampnone-end_timestampnone), so it can be passed straight into [`delete_message`](./community.md#delete_messageid) or used as the `reply_to_message_id` of a follow-up message, without having to fetch the channel's messages first. ```python from status_sdk import Account, Community @@ -861,7 +861,8 @@ url = "https://status.app/c/G3QAAMQn9ueHRsR3W5Ouuy25fkCxziknAIEkCbYAoC04HjyGeQ6X community = Community(account, url=url) channel = community["general"] -channel.send_message("Hello from my Status bot!") +message_id = channel.send_message("Hello from my Status bot!") +print(f"Sent message: {message_id}") ``` ### `get_messages(start_timestamp=None, end_timestamp=None)` @@ -902,7 +903,7 @@ Delete a message from the channel. You can delete your own messages, and if you | Name | Type | Required | Description | |-----|-----|-----|-------------| -| `id` | `str` | Yes | The `id` of the message to delete, from [`get_messages`](./community.md#get_messagesstart_timestampnone-end_timestampnone). | +| `id` | `str` | Yes | The `id` of the message to delete, from [`get_messages`](./community.md#get_messagesstart_timestampnone-end_timestampnone) or directly from the return value of [`send_message`](./community.md#send_messagemessage-reply_to_message_idnone). | Returns `bool` - `True` if the message was deleted, `False` if the account did not have permission. diff --git a/docs/group-chat.md b/docs/group-chat.md index d9b6e90..ea34b23 100644 --- a/docs/group-chat.md +++ b/docs/group-chat.md @@ -181,7 +181,7 @@ Send a text message to the group chat. This method currently supports **text mes | `message` | `str` | Yes | The text message to send. | | `reply_to_message_id` | `str` | No | The `id` of the message being replied to. Message IDs can be obtained from the `id` key of [`get_messages`](./group-chat.md#get_messagesstart_timestampnone-end_timestampnone). When omitted (default), the message is sent as a standalone message. | -Returns the current `GroupChat` instance, allowing method chaining. +Returns `str` - the `id` of the message that was just sent, delegated from [`send_message`](./account.md#send_messagechat_id-message-reply_to_message_idnone) on `Account`. It is the same identifier that appears under the `id` key in [`get_messages`](./group-chat.md#get_messagesstart_timestampnone-end_timestampnone), so it can be passed straight into [`delete_message`](./group-chat.md#delete_messageid) or used as the `reply_to_message_id` of a follow-up message, without having to fetch the chat's messages first. ```python from status_sdk import Account, GroupChat @@ -194,9 +194,11 @@ params = { account.login(**params) chat = [chat for chat in account.chats if chat["type"] == "group_chat"][0] -group_chat = GroupChat(account, chat["id"])\ - .send_message("Hello from my Status bot #1!")\ - .send_message("Hello from my Status bot #2!") +group_chat = GroupChat(account, chat["id"]) + +first_id = group_chat.send_message("Hello from my Status bot #1!") +# Reply to the message that was just sent, without fetching the chat's messages +second_id = group_chat.send_message("Hello from my Status bot #2!", first_id) ``` Reply to a message: @@ -227,7 +229,7 @@ Delete one of your **own** messages from the group chat. The deletion is propaga | Name | Type | Required | Description | |-----|-----|-----|-------------| -| `id` | `str` | Yes | The `id` of the message to delete. Message IDs can be obtained from the `id` key of [`get_messages`](./group-chat.md#get_messagesstart_timestampnone-end_timestampnone). | +| `id` | `str` | Yes | The `id` of the message to delete. Message IDs can be obtained from the `id` key of [`get_messages`](./group-chat.md#get_messagesstart_timestampnone-end_timestampnone), or directly from the return value of [`send_message`](./group-chat.md#send_messagemessage-reply_to_message_idnone). | Returns `bool`. @@ -249,12 +251,10 @@ account.login(**params) chat = [chat for chat in account.chats if chat["type"] == "group_chat"][0] group_chat = GroupChat(account, chat["id"]) -group_chat.send_message("Oops, this was a mistake!") +message_id = group_chat.send_message("Oops, this was a mistake!") -# Messages are returned newest first, so the message just sent is the first one -messages = group_chat.get_messages() -deleted = group_chat.delete_message(messages[0]["id"]) -account.logger.info(f"Deleted: {deleted}") +deleted = group_chat.delete_message(message_id) +print(f"Deleted: {deleted}") ``` ### `get_messages(start_timestamp=None, end_timestamp=None)` @@ -506,7 +506,7 @@ account.login(**params) chat = [chat for chat in account.chats if chat["type"] == "group_chat"][0] group_chat = GroupChat(account, chat["id"]) -account.logger.info(f"{group_chat.available_slots} slots left") +print(f"{group_chat.available_slots} slots left") ``` This is useful to check before adding members, since the group chat is full when there are no slots left: @@ -539,5 +539,5 @@ chat = [chat for chat in account.chats if chat["type"] == "group_chat"][0] group_chat = GroupChat(account, chat["id"]) if group_chat.is_admin: - account.logger.info("Account is admin!") + print("Account is admin!") ``` diff --git a/examples/agents/tools.py b/examples/agents/tools.py index 493fc09..5190389 100644 --- a/examples/agents/tools.py +++ b/examples/agents/tools.py @@ -221,12 +221,12 @@ class SearchTransactionsTool(StatusBaseTool): class SendMessagesTool(StatusBaseTool): name: str = "send_message" - description: str = "Send a message to the specified chat IT" + description: str = "Send a message to the specified chat ID" args_schema: Type[BaseModel] = models.MessageInput def _run(self, chat_id: str, message: Optional[str], start_date: Optional[models.DateStr], end_date: Optional[models.DateStr]) -> str: - self.account.send_message(chat_id, message) - return f"Message was sent successfully in chat ID {chat_id}!" + message_id = self.account.send_message(chat_id, message) + return f"Message [{message_id}] was sent successfully in chat ID {chat_id}!" class SendTransactionTool(StatusBaseTool): diff --git a/status_sdk/account.py b/status_sdk/account.py index 59137e3..5cb2a30 100644 --- a/status_sdk/account.py +++ b/status_sdk/account.py @@ -621,7 +621,7 @@ class Account: return balance.copy() - def send_message(self, chat_id: str, message: str, reply_to_message_id: Optional[str] = None): + def send_message(self, chat_id: str, message: str, reply_to_message_id: Optional[str] = None) -> str: """ Send a message to the given chat. @@ -629,6 +629,9 @@ class Account: - `chat_id` - the chat ID can be found in `self.chats` - `message` - the message that will be sent. Currently only text messages are supported - `reply_to_message_id` - the `id` of the message to reply to, as it appears in `self.get_messages()`. If not provided, the message is sent as a standalone message. + + Output: + - The message ID """ self.info if len(message) > 2_000: @@ -645,6 +648,8 @@ class Account: if error: raise exceptions.InvalidContactError(error["message"]) + return response["result"]["messages"][0]["id"] + def delete_message(self, id: str) -> bool: """ Delete one of your own messages from a chat. diff --git a/status_sdk/community/channel.py b/status_sdk/community/channel.py index 26ba9c5..88b1fca 100644 --- a/status_sdk/community/channel.py +++ b/status_sdk/community/channel.py @@ -163,10 +163,10 @@ class Channel: - `reply_to_message_id` - the `id` of the message to reply to, as it appears in `self.get_messages()`. If not provided, the message is sent as a standalone message. Output: - - the `GroupChat` itself, so calls can be chained + - The message ID """ - self.__account.send_message(self.id, message, reply_to_message_id) - return self + return self.__account.send_message(self.id, message, reply_to_message_id) + def get_messages(self, start_timestamp: Optional[datetime.datetime] = None, end_timestamp: Optional[datetime.datetime] = None) -> list[dict]: """ diff --git a/status_sdk/group_chat.py b/status_sdk/group_chat.py index 1c62431..014a687 100644 --- a/status_sdk/group_chat.py +++ b/status_sdk/group_chat.py @@ -56,7 +56,7 @@ class GroupChat: self.__account.logger.info(f"Created group chat {name} [{self.id}]") return self - def send_message(self, message: str, reply_to_message_id: Optional[str] = None): + def send_message(self, message: str, reply_to_message_id: Optional[str] = None) -> str: """ Send a message to the group chat. @@ -65,10 +65,10 @@ class GroupChat: - `reply_to_message_id` - the `id` of the message to reply to, as it appears in `self.get_messages()`. If not provided, the message is sent as a standalone message. Output: - - the `GroupChat` itself, so calls can be chained + - The message ID """ - self.__account.send_message(self.id, message, reply_to_message_id) - return self + return self.__account.send_message(self.id, message, reply_to_message_id) + def get_messages(self, start_timestamp: Optional[datetime.datetime] = None, end_timestamp: Optional[datetime.datetime] = None) -> list[dict]: """