From 46bb0b20ae76171a090d567ecdc7b8bc2927175c Mon Sep 17 00:00:00 2001
From: Nick Ninov <n.ninov99@gmail.com>
Date: Fri, 7 Aug 2026 23:59:17 +0300
Subject: [PATCH] bot: Real time contact requests

- Related to https://github.com/status-im/status-python-sdk/issues/32
---
 docs/account.md       | 22 +++++++++++++++++++++-
 status_sdk/account.py | 10 ++++++++++
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/docs/account.md b/docs/account.md
index dae4254..e402240 100644
--- a/docs/account.md
+++ b/docs/account.md
@@ -519,7 +519,6 @@ Listen for new incoming messages **in real time**. This method yields raw messag
 
 ```python
 from status_sdk import Account
-import datetime
 # For terminal readability only
 from rich import print as rprint
 from rich.pretty import Pretty
@@ -537,6 +536,27 @@ for msg in account.listen_messages():
 
 **Note**: If you receive multiple messages at once, `contacts` and `chats` will grow.
 
+#### `listen_contact_requests()`
+
+Listen for incoming contact requests **in real time**.
+
+```python
+from status_sdk import Account
+# For terminal readability only
+from rich import print as rprint
+from rich.pretty import Pretty
+
+account = Account()
+params = {
+    "name": "status-app-bot",
+    "password": "SNTPUMP"
+}
+account.login(**params)
+
+for request in account.listen_contact_requests():
+    rprint(Pretty(request))
+```
+
 #### `add_contact(public_key, display_name=None)`
 
 Send a contact request or approve an existing contact request. The mode depends on how the contact shows up in [`contacts`](./account.md#contacts). Best practice would be to look at the the following [`contacts`](./account.md#contacts) keys:
diff --git a/status_sdk/account.py b/status_sdk/account.py
index eba4df0..4c999ac 100644
--- a/status_sdk/account.py
+++ b/status_sdk/account.py
@@ -695,6 +695,16 @@ class Account:
             self.logger.warning(f"Could not delete Message {id}... {error.get('message')}")
         return not bool(error)
 
+    def listen_contact_requests(self) -> Generator:
+        """
+        Listen for new contact requests. Can be used for real time processing.
+        """
+        for message in self.signal.listen("local-notifications"):
+            event: dict = message.get("event", {})
+            category = event.get("category")
+            if category == "contactRequest":
+                yield message
+
     def listen_messages(self) -> Generator:
         """
         Listen for new **RAW** messages continuously. Can be used for real time processing.