Dialog & Search Commands
Dialog open/search flows and message retrieval commands.
Handler group source
- Handler module:
backend/tg_client/dialogs/commands/handlers/dialogs.py
- Registered commands:
3
- Registry integration:
backend/tg_client/dialogs/commands/registry.py
Command index
| Command |
Handler |
Service / callable |
Success event(s) |
Notes |
| `search_messages_in_chat` |
handle_search_messages_in_chat |
query_service.search_messages_in_chat |
search_messages_in_chat |
single logical response |
| `search_messages_global` |
handle_search_messages_global |
query_service.search_messages_global |
search_messages_global |
single logical response |
| `open_dialog` |
handle_open_dialog |
dialog_service.open_dialog |
dialog_access, pinned_message, forum_topics, message, dialog_empty, pagination_setup, dialog_end |
This is a multi-event streaming command, not a single result envelope. Event order depends on cache state, forum/topic mode, and whether pinned messages are requested. |
Group conventions
- Incoming client requests use the WebSocket
action field and are routed into the owner runtime via publish_command().
- Outbound success/error payloads are wrapped into
chat_update live events.
ctx.send_response() means one logical success event plus a conventional <command>_error event on failure.- Manual
ctx.send() branches indicate streaming or custom event emission; these commands are documented explicitly below.
- Request field types and required flags are inferred from handler/service code because there is no formal request schema object for every command.
Command: search_messages_in_chat
Summary
Search messages in chat.
Location in code
- Handler:
backend/tg_client/dialogs/commands/handlers/dialogs.py::handle_search_messages_in_chat (branch starts near line 14).
- Service:
backend/tg_client/dialogs/tdlib/services/query_service.py::search_messages_in_chat.
- Raw API modules:
backend/tg_client/dialogs/tdlib/api/chats.py, backend/tg_client/dialogs/tdlib/api/dialogs.py, backend/tg_client/dialogs/tdlib/api/messages.py, backend/tg_client/dialogs/tdlib/api/topics.py.
- Normalizer / typed builder:
backend/tg_client/dialogs/tdlib/normalizers/message_result_normalizer.py.
Request
Structure
{
"action": "search_messages_in_chat",
"userbot_id": 1,
"chat_id": -1001234567890,
"query": "invoice",
"limit": 50,
"search_filter": "searchMessagesFilterDocument"
}
Parameters
| Field |
Type |
Required |
Default |
Description |
chat_id |
integer |
required |
— |
Derived from handler payload access in current code. |
query |
string |
optional |
— |
Derived from handler payload access in current code. |
limit |
integer |
optional |
50 |
Derived from handler payload access in current code. |
from_message_id |
integer |
optional |
0 |
Derived from handler payload access in current code. |
offset |
integer |
optional |
0 |
Derived from handler payload access in current code. |
message_thread_id |
integer |
optional |
— |
Derived from handler payload access in current code. |
search_filter |
`string |
object` |
optional |
— |
Accepts a TDLib-style search filter object or a raw filter type string. |
Response variants
- Success event(s):
search_messages_in_chat.
- Error event(s):
search_messages_in_chat_error.
- Result shaping:
backend/tg_client/dialogs/tdlib/normalizers/message_result_normalizer.py.
- Common outbound envelope:
{
"type": "chat_update",
"userbot_id": 1,
"payload": {
"userbot_id": 1,
"type": "search_messages_in_chat",
"result": "<typed payload or TDLib-like result>"
}
}
Errors
| Error |
Type/Code |
When happens |
Notes |
chat_id is required |
string |
Service-side validation or branch guard |
Returned as the error field of the error event. |
| TDLib / transport error |
string |
Raw API call fails or TDLib raises in the transport wrapper |
Forwarded from TdlibBaseClient.tg_call() or returned by the service. |
Flow
TDLibListChatsConsumer.receive_json() forwards the WebSocket action into publish_command().AccountOwnerWorker receives the command envelope and invokes dispatch_command_payload().- Registry handler
handle_search_messages_in_chat processes search_messages_in_chat.
- Service layer executes
backend/tg_client/dialogs/tdlib/services/query_service.py::search_messages_in_chat.
- Raw TDLib wrapper(s):
backend/tg_client/dialogs/tdlib/api/chats.py, backend/tg_client/dialogs/tdlib/api/dialogs.py, backend/tg_client/dialogs/tdlib/api/messages.py, backend/tg_client/dialogs/tdlib/api/topics.py.
- Result normalization / shaping:
backend/tg_client/dialogs/tdlib/normalizers/message_result_normalizer.py.
- Final payload is emitted through
ctx.send() / ctx.send_response() -> send_ws() -> live event publisher.
- Sibling commands in this handler group:
search_messages_global, open_dialog.
Command: search_messages_global
Summary
Search messages global.
Location in code
- Handler:
backend/tg_client/dialogs/commands/handlers/dialogs.py::handle_search_messages_global (branch starts near line 29).
- Service:
backend/tg_client/dialogs/tdlib/services/query_service.py::search_messages_global.
- Raw API modules:
backend/tg_client/dialogs/tdlib/api/chats.py, backend/tg_client/dialogs/tdlib/api/dialogs.py, backend/tg_client/dialogs/tdlib/api/messages.py, backend/tg_client/dialogs/tdlib/api/topics.py.
- Normalizer / typed builder:
backend/tg_client/dialogs/tdlib/normalizers/message_result_normalizer.py.
Request
Structure
{
"action": "search_messages_global",
"userbot_id": 1,
"query": "invoice",
"limit": 50,
"chat_list": {
"@type": "chatListMain"
},
"search_filter": "searchMessagesFilterDocument"
}
Parameters
| Field |
Type |
Required |
Default |
Description |
query |
string |
optional |
— |
Derived from handler payload access in current code. |
limit |
integer |
optional |
50 |
Derived from handler payload access in current code. |
offset_date |
integer |
optional |
0 |
Derived from handler payload access in current code. |
offset_chat_id |
integer |
optional |
0 |
Derived from handler payload access in current code. |
offset_message_id |
integer |
optional |
0 |
Derived from handler payload access in current code. |
chat_list |
`string |
object` |
optional |
— |
Accepts a TDLib-style object or a raw @type string such as chatListMain. |
search_filter |
`string |
object` |
optional |
— |
Accepts a TDLib-style search filter object or a raw filter type string. |
Response variants
- Success event(s):
search_messages_global.
- Error event(s):
search_messages_global_error.
- Result shaping:
backend/tg_client/dialogs/tdlib/normalizers/message_result_normalizer.py.
- Common outbound envelope:
{
"type": "chat_update",
"userbot_id": 1,
"payload": {
"userbot_id": 1,
"type": "search_messages_global",
"result": "<typed payload or TDLib-like result>"
}
}
Errors
| Error |
Type/Code |
When happens |
Notes |
| TDLib / service error |
string |
Raw API call fails or the service returns a transport-shaped error |
Forwarded from TdlibBaseClient.tg_call() or the service layer. |
Flow
TDLibListChatsConsumer.receive_json() forwards the WebSocket action into publish_command().AccountOwnerWorker receives the command envelope and invokes dispatch_command_payload().- Registry handler
handle_search_messages_global processes search_messages_global.
- Service layer executes
backend/tg_client/dialogs/tdlib/services/query_service.py::search_messages_global.
- Raw TDLib wrapper(s):
backend/tg_client/dialogs/tdlib/api/chats.py, backend/tg_client/dialogs/tdlib/api/dialogs.py, backend/tg_client/dialogs/tdlib/api/messages.py, backend/tg_client/dialogs/tdlib/api/topics.py.
- Result normalization / shaping:
backend/tg_client/dialogs/tdlib/normalizers/message_result_normalizer.py.
- Final payload is emitted through
ctx.send() / ctx.send_response() -> send_ws() -> live event publisher.
- Sibling commands in this handler group:
search_messages_in_chat, open_dialog.
Command: open_dialog
Summary
Open a dialog window and stream dialog access, pinned messages, forum topics, message pages, pagination hints, and end markers.
Location in code
- Handler:
backend/tg_client/dialogs/commands/handlers/dialogs.py::handle_open_dialog (branch starts near line 44).
- Service:
backend/tg_client/dialogs/tdlib/services/dialog_service.py::open_dialog.
- Raw API modules:
backend/tg_client/dialogs/tdlib/api/chats.py, backend/tg_client/dialogs/tdlib/api/dialogs.py, backend/tg_client/dialogs/tdlib/api/topics.py.
- Normalizer / typed builder:
backend/tg_client/dialogs/tdlib/normalizers/dialog_normalizer.py.
- Direct raw API in handler:
backend/tg_client/dialogs/tdlib/api/dialogs.py::search_pinned_messages.
- Shared builders used in handler:
backend/tg_client/dialogs/domain/message.py, backend/tg_client/dialogs/domain/channel.py.
Request
Structure
{
"action": "open_dialog",
"userbot_id": 1,
"chat_id": -1001234567890,
"limit": 25,
"offset": 0,
"pinned_limit": 20
}
Request variants
- Top-level open: pass
chat_id with optional limit, offset, pinned_limit.
- Thread open: add
message_thread_id to scope messages to a forum topic.
- Centered window: add
center_message_id and optionally window_before / window_after.
Parameters
| Field |
Type |
Required |
Default |
Description |
chat_id |
integer |
required |
— |
Target chat id. |
from_message_id |
integer |
optional |
0 |
Start history retrieval around this message id. |
message_thread_id |
integer |
optional |
— |
Forum topic / message thread id. |
limit |
integer |
optional |
25 |
Page size for the initial dialog window. |
offset |
integer |
optional |
0 |
Dialog window offset. |
center_message_id |
integer |
optional |
— |
Center the dialog window around one message id. |
window_before |
integer |
optional |
— |
Messages to load before center_message_id when centered mode is used. |
window_after |
integer |
optional |
— |
Messages to load after center_message_id when centered mode is used. |
pinned_limit |
integer |
optional |
20 |
Pinned-message batch size used only for top-level opens without message_thread_id. |
Response variants
- Success event(s):
dialog_access, pinned_message, forum_topics, message, dialog_empty, pagination_setup, dialog_end.
- Error event(s):
dialog_error, pinned_message_error.
- Result shaping:
backend/tg_client/dialogs/tdlib/normalizers/dialog_normalizer.py.
- Notes: This is a multi-event streaming command, not a single result envelope. Event order depends on cache state, forum/topic mode, and whether pinned messages are requested.
- Common outbound envelope:
{
"type": "chat_update",
"userbot_id": 1,
"payload": {
"userbot_id": 1,
"type": "open_dialog",
"result": "<typed payload or TDLib-like result>"
}
}
Errors
| Error |
Type/Code |
When happens |
Notes |
| TDLib / service error |
string |
Raw API call fails or the service returns a transport-shaped error |
Forwarded from TdlibBaseClient.tg_call() or the service layer. |
Flow
TDLibListChatsConsumer.receive_json() forwards the WebSocket action into publish_command().AccountOwnerWorker receives the command envelope and invokes dispatch_command_payload().- Registry handler
handle_open_dialog processes open_dialog.
- Service layer executes
backend/tg_client/dialogs/tdlib/services/dialog_service.py::open_dialog.
- Raw TDLib wrapper(s):
backend/tg_client/dialogs/tdlib/api/chats.py, backend/tg_client/dialogs/tdlib/api/dialogs.py, backend/tg_client/dialogs/tdlib/api/topics.py.
- Result normalization / shaping:
backend/tg_client/dialogs/tdlib/normalizers/dialog_normalizer.py.
- Final payload is emitted through
ctx.send() / ctx.send_response() -> send_ws() -> live event publisher.
- The handler calls
ctx.tdlib.api.dialogs.search_pinned_messages(...) only when from_message_id == 0 and message_thread_id is absent.
- When the service result is not cached, unread message ids are marked viewed through
message_command_service.view_messages(...) after payload streaming.
- Sibling commands in this handler group:
search_messages_in_chat, search_messages_global.
Notes
- The handler calls
ctx.tdlib.api.dialogs.search_pinned_messages(...) only when from_message_id == 0 and message_thread_id is absent.
- When the service result is not cached, unread message ids are marked viewed through
message_command_service.view_messages(...) after payload streaming.