Talk Bot API

class nc_py_api.talk_bot.TalkBotMessage(raw_data: dict)[source]

Talk message received by bots.

property message_type: str

The type of message like Join, Leave, Create, Activity, etc.

property actor_id: str

One of the attendee types followed by the / character and a unique identifier within the given type.

For the users it is the Nextcloud user ID, for guests a sha1 value.

property actor_display_name: str

The display name of the attendee sending the message.

property object_id: int

The message ID of the given message on the origin server.

It can be used to react or reply to the given message.

property object_name: str

For normal written messages message, otherwise one of the known system message identifiers.

property object_content: ObjectContent

Dictionary with a message and parameters keys.

property object_media_type: str

text/markdown when the message should be interpreted as Markdown, otherwise text/plain.

property conversation_token: str

The token of the conversation in which the message was posted.

It can be used to react or reply to the given message.

property conversation_name: str

The name of the conversation in which the message was posted.

class nc_py_api.talk_bot.TalkBot(callback_url: str, display_name: str, description: str = '')[source]

A class that implements the TalkBot functionality.

enabled_handler(enabled: bool, nc: NextcloudApp) → None[source]

Handles the app on/off event in the context of the bot.

Parameters:

  • enabled – Value that was passed to /enabled handler.

  • nc – NextcloudApp class that was passed /enabled handler.

send_message(message: str, reply_to_message: int | TalkBotMessage, silent: bool = False, token: str = '') → tuple[Response, str][source]

Send a message and returns a “reference string” to identify the message again in a “get messages” request.

Parameters:

  • message – The message to say.

  • reply_to_message –

    The message ID this message is a reply to.

    Note

    Only allowed when the message type is not system or command.

  • silent – Flag controlling if the message should create a chat notifications for the users.

  • token – Token of the conversation. Can be empty if reply_to_message is TalkBotMessage.

Returns:

Tuple, where fist element is httpx.Response and second is a “reference string”.

Raises:
react_to_message(message: int | TalkBotMessage, reaction: str, token: str = '') → Response[source]

React to a message.

Parameters:

  • message – Message ID or TalkBotMessage to react to.

  • reaction – A single emoji.

  • token – Token of the conversation. Can be empty if message is TalkBotMessage.

Raises:
delete_reaction(message: int | TalkBotMessage, reaction: str, token: str = '') → Response[source]

Removes reaction from a message.

Parameters:

  • message – Message ID or TalkBotMessage to remove reaction from.

  • reaction – A single emoji.

  • token – Token of the conversation. Can be empty if message is TalkBotMessage.

Raises:
class nc_py_api.talk_bot.ObjectContent[source]

Object content of TalkBotMessage.

message: str
parameters: dict
nc_py_api.talk_bot.get_bot_secret(callback_url: str) → bytes | None[source]

Returns the bot’s secret from an environment variable or from the application’s configuration on the server.