Skip to content

Class Bot⚓︎

Here is the reference information for the Bot class, including all its parameters, attributes, and methods.
You can import the Bot class directly from the trueconf package:

from trueconf import Bot

trueconf.Bot ⚓︎

Bot(server, token, web_port=443, https=True, debug=False, verify_ssl=True, dispatcher=None, receive_unread_messages=False)

Initializes a TrueConf chatbot instance with WebSocket connection and configuration options.

Source

trueconf.com/docs/chatbot-connector/en/connect-and-auth/#websocket-connection-authorization

Parameters:

Name Type Description Default
server str

Address of the TrueConf server.

 required
token str

Bot authorization token.

 required
web_port int

WebSocket connection port. Defaults to 443.

 443
https bool

Whether to use HTTPS protocol. Defaults to True.

 True
debug bool

Enables debug mode. Defaults to False.

 False
verify_ssl bool

Whether to verify the server's SSL certificate. Defaults to True.

 True
dispatcher Dispatcher | None

Dispatcher instance for registering handlers.

 None
receive_unread_messages bool

Whether to receive unread messages on connection. Defaults to False.

 False
Note

Alternatively, you can authorize using a username and password via the from_credentials() class method.

authorized_event instance-attribute ⚓︎

authorized_event = Event()

connected_event instance-attribute ⚓︎

connected_event = Event()

debug instance-attribute ⚓︎

debug = debug

dp instance-attribute ⚓︎

dp = dispatcher or Dispatcher()

https instance-attribute ⚓︎

https = https

port instance-attribute ⚓︎

port = 443 if https else web_port

receive_unread_messages instance-attribute ⚓︎

receive_unread_messages = receive_unread_messages

server instance-attribute ⚓︎

server = server

server_name property ⚓︎

server_name

Returns the domain name of the TrueConf server.

Returns:

Name Type Description
str str

Domain name of the connected server.

stopped_event instance-attribute ⚓︎

stopped_event = Event()

token property ⚓︎

token

Returns the bot's authorization token.

Returns:

Name Type Description
str str

The access token used for authentication.

verify_ssl instance-attribute ⚓︎

verify_ssl = verify_ssl

web_port instance-attribute ⚓︎

web_port = web_port

add_participant_to_chat async ⚓︎

add_participant_to_chat(chat_id, user_id)

Adds a participant to the specified chat.

Source

trueconf.com/docs/chatbot-connector/en/chats/#adding-a-participant-to-the-chat

Parameters:

Name Type Description Default
chat_id str

Identifier of the chat to add the participant to.

 required
user_id str

Identifier of the user to be added.

 required

Returns:

Name Type Description
AddChatParticipantResponse AddChatParticipantResponse

Object containing the result of the participant addition.

create_channel async ⚓︎

create_channel(title)

Creates a new channel with the specified title.

Source

trueconf.com/docs/chatbot-connector/en/chats/#creating-a-channel

Parameters:

Name Type Description Default
title str

Title of the new channel.

 required

Returns:

Name Type Description
CreateChannelResponse CreateChannelResponse

Object containing the result of the channel creation.

create_group_chat async ⚓︎

create_group_chat(title)

Creates a new group chat with the specified title.

Source

trueconf.com/docs/chatbot-connector/en/chats/#creating-a-group-chat

Parameters:

Name Type Description Default
title str

Title of the new group chat.

 required

Returns:

Name Type Description
CreateGroupChatResponse CreateGroupChatResponse

Object containing the result of the group chat creation.

create_personal_chat async ⚓︎

create_personal_chat(user_id)

Creates a personal (P2P) chat with a user by their identifier.

Source

trueconf.com/docs/chatbot-connector/en/chats/#creating-a-personal-chat-with-a-user

Parameters:

Name Type Description Default
user_id str

Identifier of the user. Can be with or without a domain.

 required

Returns:

Name Type Description
CreateP2PChatResponse CreateP2PChatResponse

Object containing the result of the personal chat creation.
Note

Creating a personal chat (peer-to-peer) with a server user. If the bot has never messaged this user before, a new chat will be created. If the bot has previously sent messages to this user, the existing chat will be returned.

delete_chat async ⚓︎

delete_chat(chat_id)

Deletes a chat by its identifier.

Source

trueconf.com/docs/chatbot-connector/en/chats/#deleting-chat

Parameters:

Name Type Description Default
chat_id str

Identifier of the chat to be deleted.

 required

Returns:

Name Type Description
RemoveChatResponse RemoveChatResponse

Object containing the result of the chat deletion.

download_file_by_id async ⚓︎

download_file_by_id(file_id, dest_path=None)

Downloads a file by its ID, waiting for the upload to complete if necessary.

If the file is already in the READY state, it will be downloaded immediately. If the file is in the NOT_AVAILABLE state, the method will exit without downloading. In other cases, the bot will wait for the upload to finish and then attempt to download the file.

Parameters:

Name Type Description Default
file_id str

Unique identifier of the file on the server.

 required
dest_path str

Path where the file should be saved. If not specified, a temporary file will be created using NamedTemporaryFile (with prefix tc_dl_, suffix set to the original file name, and delete=False to keep the file on disk).

 None

Returns:

Type Description
Path | None

Path | None: Path to the downloaded file, or None if the download failed.

edit_message async ⚓︎

edit_message(message_id, text, parse_mode=TEXT)

Edits a previously sent message.

Source

trueconf.com/docs/chatbot-connector/en/messages/#editing-an-existing-message

Parameters:

Name Type Description Default
message_id str

Identifier of the message to be edited.

 required
text str

New text content for the message.

 required
parse_mode ParseMode | str

Text formatting mode. Defaults to plain text.

 TEXT

Returns:

Name Type Description
EditMessageResponse EditMessageResponse

Object containing the result of the message update.

edit_survey async ⚓︎

edit_survey(message_id, title, survey_campaign_id, survey_type=NON_ANONYMOUS)

Edits a previously sent survey.

Source

trueconf.com/docs/chatbot-connector/en/surveys/#editing-a-poll-message

Parameters:

Name Type Description Default
message_id str

Identifier of the message containing the survey to edit.

 required
title str

New title of the survey.

 required
survey_campaign_id str

Identifier of the survey campaign.

 required
survey_type SurveyType

Type of the survey (anonymous or non-anonymous). Defaults to non-anonymous.

 NON_ANONYMOUS

Returns:

Name Type Description
EditSurveyResponse EditSurveyResponse

Object containing the result of the survey update.

forward_message async ⚓︎

forward_message(chat_id, message_id)

Forwards a message to the specified chat.

Source

trueconf.com/docs/chatbot-connector/en/messages/#forwarding-a-message-to-another-chat

Parameters:

Name Type Description Default
chat_id str

Identifier of the chat to forward the message to.

 required
message_id str

Identifier of the message to be forwarded.

 required

Returns:

Name Type Description
ForwardMessageResponse ForwardMessageResponse

Object containing the result of the message forwarding.

from_credentials classmethod ⚓︎

from_credentials(server, username, password, dispatcher=None, receive_unread_messages=False, verify_ssl=True, **token_opts)

Creates a bot instance using username and password authentication.

Source

trueconf.com/docs/chatbot-connector/en/getting-started/#authorization

Parameters:

Name Type Description Default
server str

Address of the TrueConf server.

 required
username str

Username for authentication.

 required
password str

Password for authentication.

 required
dispatcher Dispatcher | None

Dispatcher instance for registering handlers.

 None
receive_unread_messages bool

Whether to receive unread messages on connection. Defaults to False.

 False
verify_ssl bool

Whether to verify the server's SSL certificate. Defaults to True.

 True
**token_opts Unpack[TokenOpts]

Additional options passed to the token request, such as web_port and https.

 {}

Returns:

Name Type Description
Bot Self

An authorized bot instance.

Raises:

Type Description
RuntimeError

If the token could not be obtained.

get_chat_by_id async ⚓︎

get_chat_by_id(chat_id)

Retrieves information about a chat by its identifier.

Source

trueconf.com/docs/chatbot-connector/en/chats/#retrieving-chat-information-by-id

Parameters:

Name Type Description Default
chat_id str

Identifier of the chat.

 required

Returns:

Name Type Description
GetChatByIDResponse GetChatByIdResponse

Object containing information about the chat.

get_chat_history async ⚓︎

get_chat_history(chat_id, count, from_message_id=None)

Retrieves the message history of the specified chat.

Source

trueconf.com/docs/chatbot-connector/en/messages/#retrieving-chat-history

Parameters:

Name Type Description Default
chat_id str

Identifier of the chat.

 required
count int

Number of messages to retrieve.

 required
from_message_id str | None

Identifier of the message to start retrieving history from. If not specified, the history will be loaded from the most recent message.

 None

Returns:

Name Type Description
GetChatHistoryResponse GetChatHistoryResponse

Object containing the result of the chat history request.

Raises:

Type Description
ValueError

If the count number is less than 1.

get_chat_participants async ⚓︎

get_chat_participants(chat_id, page_size, page_number)

Retrieves a paginated list of chat participants.

Source

trueconf.com/docs/chatbot-connector/en/chats/#retrieving-the-list-of-chat-participants

Parameters:

Name Type Description Default
chat_id str

Identifier of the chat.

 required
page_size int

Number of participants per page.

 required
page_number int

Page number.

 required

Returns:

Name Type Description
GetChatParticipantsResponse GetChatParticipantsResponse

Object containing the result of the participant list request.

get_chats async ⚓︎

get_chats(count=10, page=1)

Retrieves a paginated list of chats available to the bot.

Source

trueconf.com/docs/chatbot-connector/en/chats/#retrieving-the-list-of-chats

Parameters:

Name Type Description Default
count int

Number of chats per page. Defaults to 10.

 10
page int

Page number. Must be greater than 0. Defaults to 1.

 1

Returns:

Name Type Description
GetChatsResponse GetChatsResponse

Object containing the result of the chat list request.

Raises:

Type Description
ValueError

If the page number is less than 1.

get_file_info async ⚓︎

get_file_info(file_id)

Retrieves information about a file by its identifier.

Source

trueconf.com/docs/chatbot-connector/en/files/#retrieving-file-information-and-downloading-the-file

Parameters:

Name Type Description Default
file_id str

Identifier of the file.

 required

Returns:

Name Type Description
GetFileInfoResponse GetFileInfoResponse

Object containing information about the file.

get_message_by_id async ⚓︎

get_message_by_id(message_id)

Retrieves a message by its identifier.

Source

trueconf.com/docs/chatbot-connector/en/messages/#retrieving-a-message-by-its-id

Parameters:

Name Type Description Default
message_id str

Identifier of the message to retrieve.

 required

Returns:

Name Type Description
GetMessageByIdResponse GetMessageByIdResponse

Object containing the retrieved message data.

get_user_display_name async ⚓︎

get_user_display_name(user_id)

Retrieves the display name of a user by their TrueConf ID.

Source

trueconf.com/docs/chatbot-connector/en/contacts/#retrieving-the-display-name-of-a-user-by-their-trueconf-id

Parameters:

Name Type Description Default
user_id str

User's TrueConf ID. Can be specified with or without a domain.

 required

Returns:

Name Type Description
GetUserDisplayNameResponse GetUserDisplayNameResponse

Object containing the user's display name.

has_chat_participant async ⚓︎

has_chat_participant(chat_id, user_id)

Checks whether the specified user is a participant in the chat.

Source

trueconf.com/docs/chatbot-connector/en/chats/#checking-participant-presence-in-chat

Parameters:

Name Type Description Default
chat_id str

Identifier of the chat.

 required
user_id str

Identifier of the user. Can be with or without a domain.

 required

Returns:

Name Type Description
HasChatParticipantResponse HasChatParticipantResponse

Object containing the result of the check.

remove_message async ⚓︎

remove_message(message_id, for_all=False)

Removes a message by its identifier.

Source

trueconf.com/docs/chatbot-connector/en/messages/#deleting-a-message

Parameters:

Name Type Description Default
message_id str

Identifier of the message to be removed.

 required
for_all bool

If True, the message will be removed for all participants. Default to False (the message is removed only for the bot).

 False

Returns:

Name Type Description
RemoveMessageResponse RemoveMessageResponse

Object containing the result of the message deletion.

remove_participant_from_chat async ⚓︎

remove_participant_from_chat(chat_id, user_id)

Removes a participant from the specified chat.

Source

trueconf.com/docs/chatbot-connector/en/chats/#removing-a-participant-from-the-chat

Parameters:

Name Type Description Default
chat_id str

Identifier of the chat to remove the participant from.

 required
user_id str

Identifier of the user to be removed.

 required

Returns:

Name Type Description
RemoveChatParticipantResponse RemoveChatParticipantResponse

Object containing the result of the participant removal.

reply_message async ⚓︎

reply_message(chat_id, message_id, text, parse_mode=TEXT)

Sends a reply to an existing message in the chat.

Source

trueconf.com/docs/chatbot-connector/en/messages/#reply-to-an-existing-message

Parameters:

Name Type Description Default
chat_id str

Identifier of the chat where the reply will be sent.

 required
message_id str

Identifier of the message to reply to.

 required
text str

Text content of the reply.

 required
parse_mode ParseMode | str

Text formatting mode. Defaults to plain text.

 TEXT

Returns:

Name Type Description
SendMessageResponse SendMessageResponse

Object containing the result of the message delivery.

run async ⚓︎

run(handle_signals=True)

Runs the bot and waits until it stops. Supports handling termination signals (SIGINT, SIGTERM).

Parameters:

Name Type Description Default
handle_signals bool

Whether to handle termination signals. Defaults to True.

 True

Returns:

Type Description
None

None

send_document async ⚓︎

send_document(chat_id, file_path)

Sends a document to the specified chat.

Files of any format are supported. A preview is automatically generated for the following file types: .jpg, .jpeg, .png, .webp, .bmp, .gif, .tiff, .pdf

Source

trueconf.com/docs/chatbot-connector/en/files/#file-transfer

Parameters:

Name Type Description Default
chat_id str

Identifier of the chat to send the document to.

 required
file_path str

Path to the document file.

 required

Returns:

Name Type Description
SendFileResponse SendFileResponse

Object containing the result of the file upload.

send_message async ⚓︎

send_message(chat_id, text, parse_mode=TEXT)

Sends a message to the specified chat.

Source

trueconf.com/docs/chatbot-connector/en/messages/#sending-a-text-message-in-chat

Parameters:

Name Type Description Default
chat_id str

Identifier of the chat to send the message to.

 required
text str

Text content of the message.

 required
parse_mode ParseMode | str

Text formatting mode. Defaults to plain text.

 TEXT

Returns:

Name Type Description
SendMessageResponse SendMessageResponse

Object containing the result of the message delivery.

send_photo async ⚓︎

send_photo(chat_id, file_path, preview_path)

Sends a photo to the specified chat with preview (optional).

Supported image formats: .jpg, .jpeg, .png, .webp, .bmp, .gif, .tiff

Source

trueconf.com/docs/chatbot-connector/en/files/#file-transfer

Parameters:

Name Type Description Default
chat_id str

Identifier of the chat to send the photo to.

 required
file_path str

Path to the image file.

 required
preview_path str | None

Path to the preview image.

 required

Returns:

Name Type Description
SendFileResponse SendFileResponse

Object containing the result of the file upload.

Examples:

>>> bot.send_photo(chat_id="a1s2d3f4f5g6", file_path="/path/to/image.jpg", preview_path="/path/to/preview.webp")

send_sticker async ⚓︎

send_sticker(chat_id, file_path)

Sends a WebP-format sticker to the specified chat.

Source

trueconf.com/docs/chatbot-connector/en/files/#file-transfer

Parameters:

Name Type Description Default
chat_id str

Identifier of the chat to send the sticker to.

 required
file_path str

Path to the sticker file in WebP format.

 required

Returns:

Name Type Description
SendFileResponse SendFileResponse

Object containing the result of the file upload.

Raises:

Type Description
TypeError

If the file does not have the MIME type 'image/webp'.

send_survey async ⚓︎

send_survey(chat_id, title, survey_campaign_id, reply_message_id=None, survey_type=NON_ANONYMOUS)

Sends a survey to the specified chat.

Source

trueconf.com/docs/chatbot-connector/en/surveys/#sending-a-poll-message-in-chat

Parameters:

Name Type Description Default
chat_id str

Identifier of the chat to send the survey to.

 required
title str

Title of the survey displayed in the chat.

 required
survey_campaign_id str

Identifier of the survey campaign.

 required
reply_message_id str

Identifier of the message being replied to.

 None
survey_type SurveyType

Type of the survey (anonymous or non-anonymous). Defaults to non-anonymous.

 NON_ANONYMOUS

Returns:

Name Type Description
SendSurveyResponse SendSurveyResponse

Object containing the result of the survey submission.

shutdown async ⚓︎

shutdown()

Gracefully shuts down the bot, cancels the connection task, and closes active sessions.

This method: - Cancels the connection task if it is still active; - Closes the WebSocket session or self.session if they are open; - Clears the connection and authorization events; - Sets the stopped_event flag.

Returns:

Type Description
None

None

start async ⚓︎

start()

Starts the bot by connecting to the server and listening for incoming events.

Note

This method is safe to call multiple times — subsequent calls are ignored if the connection is already active.

Returns:

Type Description
None

None

subscribe_file_progress async ⚓︎

subscribe_file_progress(file_id)

Subscribes to file transfer progress updates.

Source

trueconf.com/docs/chatbot-connector/en/files/#subscription-to-file-upload-progress-on-the-server

Parameters:

Name Type Description Default
file_id str

Identifier of the file.

 required

Returns:

Name Type Description
SubscribeFileProgressResponse SubscribeFileProgressResponse

Object containing the result of the subscription.
Note

If the file is in the UPLOADING status, you can subscribe to the upload process to be notified when the file becomes available.

unsubscribe_file_progress async ⚓︎

unsubscribe_file_progress(file_id)

Unsubscribes from receiving file upload progress events.

Source

trueconf.com/docs/chatbot-connector/en/files/#unsubscribe-from-receiving-upload-event-notifications

Parameters:

Name Type Description Default
file_id str

Identifier of the file.

 required

Returns:

Name Type Description
UnsubscribeFileProgressResponse UnsubscribeFileProgressResponse

Object containing the result of the unsubscription.
Note

If necessary, you can unsubscribe from file upload events that were previously subscribed to using the subscribe_file_progress() method.