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/#auth

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

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, display_history=False)

Adds a participant to the specified chat.

Optionally allows showing chat history to the newly added participant. The display_history parameter is supported only in TrueConf Server version 5.5.2 and above.

Source

trueconf.com/docs/chatbot-connector/en/chats/#addChatParticipant

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. If no domain is specified, the server domain will be used.

 required
display_history bool

Whether to show previous chat history to the participant. Requires TrueConf Server 5.5.2+. Defaults to False.

 False

Returns:

Name Type Description
AddChatParticipantResponse AddChatParticipantResponse

Object containing the result of the participant addition.
Example 
await bot.add_participant_to_chat(
    chat_id="chat123",
    user_id="user456",
    display_history=True
)

change_participant_role async ⚓︎

change_participant_role(chat_id, user_id, role)

Requires TrueConf Server 5.5.2+.

Changes the role of a participant in the specified group chat.

This method requires that the bot has moderator (admin) or owner rights in the chat.

Supported roles in group chat
  • "owner" — group chat owner
  • "admin" — appointed moderator of the group chat
  • "user" — regular participant of a group chat
It is recommended to use the enumeration class for safer role assignment 
from trueconf.enums import ChatParticipantRole

For a full list of roles in conference, channel, or Favorites chats, see the documentation:

Role descriptions

trueconf.com/docs/chatbot-connector/en/roles-and-users-rules/#which-roles-has-apis

Role permissions matrix

trueconf.com/docs/chatbot-connector/en/roles-and-users-rules/#roles-rules-group-chats

Source

trueconf.com/docs/chatbot-connector/en/chats/#changeParticipantRole

Parameters:

Name Type Description Default
chat_id str

Identifier of the chat where the role should be changed.

 required
user_id str

Identifier of the participant whose role is being updated.

 required
role str | ChatParticipantRole

New role to assign. Must be one of the supported roles listed above.

 required

Returns:

Name Type Description
ChangeParticipantRoleResponse ChangeParticipantRoleResponse

Object containing the result of the role change operation.
Example 
from trueconf.enums import ChatParticipantRole as role

await bot.change_participant_role(
    chat_id="chat123",
    user_id="user456",
    role=role.ADMIN
)

create_channel async ⚓︎

create_channel(title)

Creates a new channel with the specified title.

Source

trueconf.com/docs/chatbot-connector/en/chats/#createChannel

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_favorites_chat async ⚓︎

create_favorites_chat()

Requires TrueConf Server 5.5.2+

Creates a "Favorites" chat for the current user.

This type of chat is a personal space accessible only to its owner. It can be used to store notes, upload files, or test bot features in a private context.

Source

trueconf.com/docs/chatbot-connector/en/chats/#createFavoritesChat

Returns:

Name Type Description
CreateFavoritesChatResponse CreateFavoritesChatResponse

An object containing information about the newly created chat.

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/#createGroupChat

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/#createP2PChat

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/#removeChat

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/#editMessage

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/#editSurvey

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/#forwardMessage

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/connect-and-auth/#connect-and-auth

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/#getChatById

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/#getChatHistory

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/#getChatParticipants

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/#getChats

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/#getFileInfo

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/#getMessageById

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/#getUserDisplayName

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/#hasChatParticipant

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.

me async ⚓︎

me()

Returns the identifier of the bot's personal (Favorites) chat.

If the chat does not exist yet, it will be created automatically. The result is cached to prevent redundant API calls.

Returns:

Name Type Description
str str

Chat ID of the bot's personal Favorites chat.

remove_message async ⚓︎

remove_message(message_id, for_all=False)

Removes a message by its identifier.

Source

trueconf.com/docs/chatbot-connector/en/messages/#removeMessage

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/#removeChatParticipant

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/#replyMessage

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, caption=None, parse_mode=TEXT)

Sends a document or any arbitrary file to the specified chat.

This method supports all file types, including images. However, images sent via this method will be transferred in original, uncompressed form. If you want to send a compressed image with preview support, use send_photo() instead.

The file must be provided as an instance of one of the InputFile subclasses: FSInputFile, BufferedInputFile, or URLInputFile.

Parameters:

Name Type Description Default
chat_id str

The identifier of the chat to which the document will be sent.

 required
file InputFile

The file to be uploaded. Must be a subclass of InputFile.

 required
caption str | None

Optional caption text to be sent with the file.

 None
parse_mode ParseMode | str

Text formatting mode (e.g., Markdown, HTML, or plain text).

 TEXT

Returns:

Name Type Description
SendFileResponse SendFileResponse

An object containing the result of the file upload.
Example 
await bot.send_document(
    chat_id="a1s2d3f4f5g6",
    file=FSInputFile("report.pdf"),
    caption="📄 Annual report **for 2025**",
    parse_mode=ParseMode.MARKDOWN
)

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/#sendMessage

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, preview, caption=None, parse_mode=TEXT)

Sends a photo to the specified chat, with optional caption and preview support.

This method is recommended when sending compressed images with preview support. If you want to send uncompressed images or arbitrary files, use send_document() instead.

The file must be provided as an instance of one of the InputFile subclasses: FSInputFile, BufferedInputFile, or URLInputFile.

Supported image formats include: .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 which the photo will be sent.

 required
file InputFile

The photo file to upload. Must be a subclass of InputFile.

 required
preview InputFile | None

Optional preview image. Must also be an InputFile if provided.

 required
caption str | None

Optional caption to be sent along with the image.

 None
parse_mode ParseMode | str

Formatting mode for the caption (e.g., Markdown, HTML, plain text).

 TEXT

Returns:

Name Type Description
SendFileResponse SendFileResponse

An object containing the result of the file upload.
Example 
await bot.send_photo(
    chat_id="a1s2d3f4f5g6",
    file=FSInputFile("image.jpg"),
    preview=FSInputFile("image_preview.webp"),
    caption="Here's our **team** photo 📸",
    parse_mode=ParseMode.MARKDOWN
)

send_sticker async ⚓︎

send_sticker(chat_id, file)

Sends a sticker in WebP format to the specified chat.

The file must have a MIME type of 'image/webp', otherwise a TypeError will be raised. The file must be an instance of one of the InputFile subclasses: FSInputFile, BufferedInputFile, or URLInputFile.

A preview is automatically generated from the source file, as required for sticker uploads in TrueConf.

Source

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

Parameters:

Name Type Description Default
chat_id str

Identifier of the chat to which the sticker will be sent.

 required
file InputFile

The sticker file in WebP format. Must be a subclass of InputFile.

 required

Returns:

Name Type Description
SendFileResponse SendFileResponse

An object containing the result of the file upload.

Raises:

Type Description
TypeError

If the file's MIME type is not 'image/webp'.
Example 
await bot.send_sticker(chat_id="user123", file=FSInputFile("sticker.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/#sendSurvey

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.

server_name async ⚓︎

server_name()

Returns the domain name of the TrueConf server.

Returns:

Name Type Description
str str

Domain name of the connected server.

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/#subscribeFileProgress

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/#unsubscribeFileProgress

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.