Talk API

class nc_py_api.talk.Conversation(raw_data: dict)

Talk conversation.

property conversation_id: int

Numeric identifier of the conversation. Most methods that require this should accept this class itself.

property token: str

Token identifier of the conversation which is used for further interaction.

property conversation_type: ConversationType

Type of the conversation, see: ConversationType.

property name: str

Name of the conversation (can also be empty).

property display_name: str

name if non-empty, otherwise it falls back to a list of participants.

property description: str

Description of the conversation (can also be empty) (only available with room-description capability).

property participant_type: ParticipantType

Permissions level of the current user, see: ParticipantType.

property attendee_id: int

Unique attendee id.

property attendee_pin: str

Unique dial-in authentication code for this user when the conversation has SIP enabled.

property actor_type: str

Actor types of chat messages: users, guests, bots, bridged.

property actor_id: str

The unique identifier for the given actor type.

property permissions: AttendeePermissions

Final permissions, combined AttendeePermissions values.

property attendee_permissions: AttendeePermissions

Dedicated permissions for the current participant, if not Custom, they are not the resulting ones.

property call_permissions: AttendeePermissions

Call permissions, if not Custom, these are not the resulting permissions.

Note

If set, they will reset after the end of the call.

property default_permissions: AttendeePermissions

Default permissions for new participants.

property participant_flags: InCallFlags

In call flags of the user’s session making the request.

Note

Available with in-call-flags capability.

property read_only: bool

Read-only state for the current user (only available with read-only-rooms capability).

property listable: ListableScope

Listable scope for the room (only available with listable-rooms capability).

property message_expiration: int

The message expiration time in seconds in this chat. Zero if disabled.

Note

Only available with message-expiration capability.

property has_password: bool

Flag if the conversation has a password.

property has_call: bool

Flag if the conversation has call.

property call_flag: InCallFlags

Combined flag of all participants in the current call.

Note

Only available with conversation-call-flags capability.

property can_start_call: bool

Flag if the user can start a new call in this conversation (joining is always possible).

Note

Only available with start-call-flag capability.

property can_delete_conversation: bool

Flag if the user can delete the conversation for everyone.

property can_leave_conversation: bool

Flag if the user can leave the conversation (not possible for the last user with moderator permissions).

property last_activity: int

Timestamp of the last activity in the conversation, in seconds and UTC time zone.

property is_favorite: bool

Flag if the conversation is favorite for the user.

property notification_level: NotificationLevel

The notification level for the user.

property lobby_state: WebinarLobbyStates

Webinar lobby restriction (0-1).

Note

Only available with webinary-lobby capability.

property lobby_timer: int

Timestamp when the lobby will be automatically disabled.

Note

Only available with webinary-lobby capability.

property sip_enabled: SipEnabledStatus

Status of the SIP for the conversation.

property can_enable_sip: bool

Whether the given user can enable SIP for this conversation.

Note

When the token is not-numeric only, SIP can not be enabled even if the user is permitted and a moderator of the conversation.

property unread_messages_count: int

Number of unread chat messages in the conversation.

property unread_mention: bool

Flag if the user was mentioned since their last visit.

property unread_mention_direct: bool

Flag if the user was mentioned directly (ignoring @all mentions) since their last visit.

Note

Only available with direct-mention-flag capability.

property last_read_message: int

ID of the last read message in a room.

Note

only available with chat-read-marker capability.

property last_common_read_message: int

ID of the last message read by every user that has read privacy set to public in a room.

When the user himself has it set to private the value is 0.

Note

Only available with chat-read-status capability.

property last_message: TalkMessage | None

Last message in a conversation if available, otherwise empty.

Note

Even when given, the message will not contain the parent or reactionsSelf attribute due to performance reasons

property breakout_room_mode: BreakoutRoomMode

Breakout room configuration mode.

Note

Only available with breakout-rooms-v1 capability.

property breakout_room_status: BreakoutRoomStatus

Breakout room status.

Note

Only available with breakout-rooms-v1 capability.

property avatar_version: str

Version of conversation avatar used to easier expiration of the avatar in case a moderator updates it.

Note

Only available with avatar capability.

property is_custom_avatar: bool

Flag if the conversation has a custom avatar.

Note

Only available with avatar capability.

property call_start_time: int

Timestamp when the call was started.

Note

Only available with recording-v1 capability.

property recording_status: CallRecordingStatus

Call recording status..

Note

Only available with recording-v1 capability.

property status_clear_at: int | None

Unix Timestamp representing the time to clear the status.

Note

Available only for one-to-one conversations.

property status_icon: str

The icon picked by the user (must be one emoji).

property status_message: str

Message of the status.

property status_type: str

Status type, on of the: online, away, dnd, invisible, offline.

class nc_py_api.talk.Participant(raw_data: dict)

Conversation participant information.

property attendee_id: int

Unique attendee id.

property actor_type: str

The actor type of the participant that voted: users, groups, circles, guests, emails.

property actor_id: str

The unique identifier for the given actor type.

property display_name: str

Can be empty for guests.

property participant_type: ParticipantType

Permissions level, see: ParticipantType.

property last_ping: int

Timestamp of the last ping. Should be used for sorting.

property participant_flags: InCallFlags

Current call flags.

property permissions: AttendeePermissions

Final permissions, combined AttendeePermissions values.

property attendee_permissions: AttendeePermissions

Dedicated permissions for the current participant, if not Custom, they are not the resulting ones.

property session_ids: list[str]

A list of session IDs, each one 512 characters long, or empty if there is no session.

property breakout_token: str

Only available with breakout-rooms-v1 capability.

property status_icon: str

The icon picked by the user (must be one emoji).

property status_message: str

Message of the status.

property status_type: str

Status type, on of the: online, away, dnd, invisible, offline.

class nc_py_api.talk.TalkMessage(raw_data: dict)

Talk message.

property message_id: int

Numeric identifier of the message. Most methods that require this should accept this class itself.

property token: str

Token identifier of the conversation which is used for further interaction.

property actor_type: str

Actor types of the chat message: users, guests, bots, bridged.

property actor_id: str

Actor id of the message author.

property actor_display_name: str

A display name of the message author.

property timestamp: int

Timestamp in seconds and UTC time zone.

property system_message: str

Empty for the normal chat message or the type of the system message (untranslated).

property message_type: str

Currently known types are “comment”, “comment_deleted”, “system” and “command”.

property is_replyable: bool

True if the user can post a reply to this message.

Note

Only available with chat-replies capability.

property reference_id: str

A reference string that was given while posting the message to be able to identify the sent message again.

Note

Only available with chat-reference-id capability.

property message: str

Message string with placeholders.

See Rich Object String.

property message_parameters: dict

Message parameters for the message.

property expiration_timestamp: int

Unix time stamp when the message expires and show be removed from the client’s UI without further note.

Note

Only available with message-expiration capability.

property parent: list

To be refactored: Description here.

property reactions: dict

An array map with relation between reaction emoji and total count of reactions with this emoji.

property reactions_self: list[str]

When the user reacted, this is the list of emojis the user reacted with.

property markdown: bool

Whether the message should be rendered as markdown or shown as plain text.

class nc_py_api.talk.TalkFileMessage(raw_data: dict, user_id: str)

Subclass of Talk Message representing message-containing file.

to_fs_node() → FsNode

Returns usual FsNode created from this class.

property actor_display_name: str

A display name of the message author.

property actor_id: str

Actor id of the message author.

property actor_type: str

Actor types of the chat message: users, guests, bots, bridged.

property expiration_timestamp: int

Unix time stamp when the message expires and show be removed from the client’s UI without further note.

Note

Only available with message-expiration capability.

property is_replyable: bool

True if the user can post a reply to this message.

Note

Only available with chat-replies capability.

property markdown: bool

Whether the message should be rendered as markdown or shown as plain text.

property message: str

Message string with placeholders.

See Rich Object String.

property message_id: int

Numeric identifier of the message. Most methods that require this should accept this class itself.

property message_parameters: dict

Message parameters for the message.

property message_type: str

Currently known types are “comment”, “comment_deleted”, “system” and “command”.

property parent: list

To be refactored: Description here.

property reactions: dict

An array map with relation between reaction emoji and total count of reactions with this emoji.

property reactions_self: list[str]

When the user reacted, this is the list of emojis the user reacted with.

property reference_id: str

A reference string that was given while posting the message to be able to identify the sent message again.

Note

Only available with chat-reference-id capability.

property system_message: str

Empty for the normal chat message or the type of the system message (untranslated).

property timestamp: int

Timestamp in seconds and UTC time zone.

property token: str

Token identifier of the conversation which is used for further interaction.

class nc_py_api._talk_api._TalkAPI(session: NcSessionBasic)

Class provides API to work with Nextcloud Talk, avalaible as nc.talk.<method>.

config_sha: str

Sha1 value over Talk config. After receiving a different value on subsequent requests, settings got refreshed.

modified_since: int

Used by get_user_conversations, when modified_since param is True.

property available: bool

Returns True if the Nextcloud instance supports this feature, False otherwise.

property bots_available: bool

Returns True if the Nextcloud instance supports this feature, False otherwise.

get_user_conversations(no_status_update: bool = True, include_status: bool = False, modified_since: int | bool = 0) → list[Conversation]

Returns the list of the user’s conversations.

Parameters:

• no_status_update – When the user status should not be automatically set to the online.

• include_status – Whether the user status information of all one-to-one conversations should be loaded.

• modified_since –

  When provided only conversations with a newer lastActivity (and one-to-one conversations when includeStatus is provided) are returned. Can be set to True to automatically use last modified_since from previous calls. Default = 0.

  Note

  In rare cases, when a request arrives between seconds, it is possible that return data will contain part of the conversations from the last call that was not modified( their last_activity will be the same as talk.modified_since).

list_participants(conversation: Conversation | str, include_status: bool = False) → list[Participant]

Returns a list of conversation participants.

Parameters:

• conversation – conversation token or Conversation.

• include_status – Whether the user status information of all one-to-one conversations should be loaded.

create_conversation(conversation_type: ConversationType, invite: str = '', source: str = '', room_name: str = '', object_type: str = '', object_id: str = '') → Conversation

Creates a new conversation.

Note

Creating a conversation as a child breakout room will automatically set the lobby when breakout rooms are not started and will always overwrite the room type with the parent room type. Also, moderators of the parent conversation will be automatically added as moderators.

Parameters:

• conversation_type – type of the conversation to create.

• invite – User ID(roomType=ONE_TO_ONE), Group ID(roomType=GROUP - optional), Circle ID(roomType=GROUP, source=’circles’, only available with the circles-support capability).

• source – The source for the invite, only supported on roomType = GROUP for groups and circles.

• room_name – Conversation name up to 255 characters(not available for roomType=ONE_TO_ONE).

• object_type – Type of object this room references, currently only allowed value is “room” to indicate the parent of a breakout room.

• object_id – ID of an object this room references, room token is used for the parent of a breakout room.

rename_conversation(conversation: Conversation | str, new_name: str) → None

Renames a conversation.

set_conversation_description(conversation: Conversation | str, description: str) → None

Sets conversation description.

set_conversation_fav(conversation: Conversation | str, favorite: bool) → None

Changes conversation favorite state.

set_conversation_password(conversation: Conversation | str, password: str) → None

Sets password for a conversation.

Currently, it is only allowed to have a password for public conversations.

Parameters:

• conversation – conversation token or Conversation.

• password – new password for the conversation.

Note

Password should match the password policy.

set_conversation_readonly(conversation: Conversation | str, read_only: bool) → None

Changes conversation read_only state.

set_conversation_public(conversation: Conversation | str, public: bool) → None

Changes conversation public state.

set_conversation_notify_lvl(conversation: Conversation | str, new_lvl: NotificationLevel) → None

Sets new notification level for user in the conversation.

get_conversation_by_token(conversation: Conversation | str) → Conversation

Gets conversation by token.

delete_conversation(conversation: Conversation | str) → None

Deletes a conversation.

Note

Deleting a conversation that is the parent of breakout rooms, will also delete them. ONE_TO_ONE conversations cannot be deleted for them leave_conversation should be used.

leave_conversation(conversation: Conversation | str) → None

Removes yourself from the conversation.

Note

When the participant is a moderator or owner and there are no other moderators or owners left, participant cannot leave conversation.

send_message(message: str, conversation: Conversation | str = '', reply_to_message: int | TalkMessage = 0, silent: bool = False, actor_display_name: str = '') → TalkMessage

Send a message to the conversation.

Parameters:

• message – The message the user wants to say.

• conversation – conversation token or Conversation. Need only if reply_to_message is not TalkMessage

• reply_to_message –

  The message ID this message is a reply to.

  Note

  Only allowed when the message type is not system or command. The message you are replying to should be from the same conversation.

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

• actor_display_name – Guest display name (ignored for the logged-in users).

Raises:

ValueError – in case of an invalid usage.

send_file(path: str | FsNode, conversation: Conversation | str = '') → tuple[Share, str]

Sends a file to the conversation.

receive_messages(conversation: Conversation | str, look_in_future: bool = False, limit: int = 100, timeout: int = 30, no_status_update: bool = True) → list[TalkMessage]

Receive chat messages of a conversation.

Parameters:

• conversation – conversation token or Conversation.

• look_in_future – True to poll and wait for the new message or False to get history.

• limit – Number of chat messages to receive (100 by default, 200 at most).

• timeout – look_in_future=1 only: seconds to wait for the new messages (60 secs at most).

• no_status_update – When the user status should not be automatically set to the online.

delete_message(message: TalkMessage | str, conversation: Conversation | str = '') → TalkMessage

Delete a chat message.

Parameters:

• message – Message ID or TalkMessage to delete.

• conversation – conversation token or Conversation.

Note

Conversation needed only if message is not TalkMessage

react_to_message(message: TalkMessage | str, reaction: str, conversation: Conversation | str = '') → dict[str, list[MessageReactions]]

React to a chat message.

Parameters:

• message – Message ID or TalkMessage to react to.

• reaction – A single emoji.

• conversation – conversation token or Conversation.

Note

Conversation needed only if message is not TalkMessage

delete_reaction(message: TalkMessage | str, reaction: str, conversation: Conversation | str = '') → dict[str, list[MessageReactions]]

Remove reaction from a chat message.

Parameters:

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

• reaction – A single emoji.

• conversation – conversation token or Conversation.

Note

Conversation needed only if message is not TalkMessage

get_message_reactions(message: TalkMessage | str, reaction_filter: str = '', conversation: Conversation | str = '') → dict[str, list[MessageReactions]]

Get reactions information for a chat message.

Parameters:

• message – Message ID or TalkMessage to get reactions from.

• reaction_filter – A single emoji to get reaction information only for it.

• conversation – conversation token or Conversation.

Note

Conversation needed only if message is not TalkMessage

list_bots() → list[BotInfo]

Lists the bots that are installed on the server.

conversation_list_bots(conversation: Conversation | str) → list[BotInfoBasic]

Lists the bots that are enabled and can be enabled for the conversation.

Parameters:

conversation – conversation token or Conversation.

enable_bot(conversation: Conversation | str, bot: BotInfoBasic | int) → None

Enable a bot for a conversation as a moderator.

Parameters:

• conversation – conversation token or Conversation.

• bot – bot ID or BotInfoBasic.

disable_bot(conversation: Conversation | str, bot: BotInfoBasic | int) → None

Disable a bot for a conversation as a moderator.

Parameters:

• conversation – conversation token or Conversation.

• bot – bot ID or BotInfoBasic.

create_poll(conversation: Conversation | str, question: str, options: list[str], hidden_results: bool = True, max_votes: int = 1) → Poll

Creates a poll in a conversation.

Parameters:

• conversation – conversation token or Conversation.

• question – The question of the poll.

• options – Array of strings with the voting options.

• hidden_results – Should results be hidden until the poll is closed and then only the summary is published.

• max_votes – The maximum amount of options a participant can vote for.

get_poll(poll: Poll | int, conversation: Conversation | str = '') → Poll

Get state or result of a poll.

Parameters:

• poll – Poll ID or Poll.

• conversation – conversation token or Conversation.

vote_poll(options_ids: list[int], poll: Poll | int, conversation: Conversation | str = '') → Poll

Vote on a poll.

Parameters:

• options_ids – The option IDs the participant wants to vote for.

• poll – Poll ID or Poll.

• conversation – conversation token or Conversation.

close_poll(poll: Poll | int, conversation: Conversation | str = '') → Poll

Close a poll.

Parameters:

• poll – Poll ID or Poll.

• conversation – conversation token or Conversation.

set_conversation_avatar(conversation: Conversation | str, avatar: bytes | tuple[str, str | None]) → Conversation

Set image or emoji as avatar for the conversation.

Parameters:

• conversation – conversation token or Conversation.

• avatar –

  Squared image with mimetype equal to PNG or JPEG or a tuple with emoji and optional HEX color code(6 times 0-9A-F) without the leading # character.

  Note

  When color omitted, fallback will be to the default bright/dark mode icon background color.

delete_conversation_avatar(conversation: Conversation | str) → Conversation

Delete conversation avatar.

Parameters:

conversation – conversation token or Conversation.

get_conversation_avatar(conversation: Conversation | str, dark=False) → bytes

Get conversation avatar (binary).

Parameters:

• conversation – conversation token or Conversation.

• dark – boolean indicating should be or not avatar fetched for dark theme.

class nc_py_api.talk.ConversationType(value)

Talk conversation types.

ONE_TO_ONE = 1

Direct One to One

GROUP = 2

Group conversation(group chat)

PUBLIC = 3

Group conversation opened to all

CHANGELOG = 4

Conversation that some App start to inform about new features, changes, e.g. changelog.

FORMER = 5

Former “One to one” (When a user is deleted from the server or removed from all their conversations, “One to one” rooms are converted to this type)

class nc_py_api.talk.ParticipantType(value)

Permissions level of the current user.

OWNER = 1

Creator of the conversation

MODERATOR = 2

Moderator of the conversation

USER = 3

Conversation participant

GUEST = 4

Conversation participant, with no account on NC instance

USER_SELF_JOINED = 5

User following a public link

GUEST_MODERATOR = 6

Conversation moderator, with no account on NC instance

class nc_py_api.talk.AttendeePermissions(value)

Final permissions for the current participant.

Note

Permissions are picked in order of attendee then call, then default, and the first which is Custom will apply.

DEFAULT = 0

Default permissions (will pick the one from the next level of: user, call, conversation)

CUSTOM = 1

Custom permissions (this is required to be able to remove all other permissions)

START_CALL = 2

Start call

JOIN_CALL = 4

Join call

IGNORE = 8

Can ignore lobby

AUDIO = 16

Can publish audio stream

VIDEO = 32

Can publish video stream

SHARE_SCREEN = 64

Can publish screen sharing stream

OTHER = 128

Can post chat message, share items and do reactions

class nc_py_api.talk.InCallFlags(value)

Participant in-call flags.

DISCONNECTED = 0

IN_CALL = 1

PROVIDES_AUDIO = 2

PROVIDES_VIDEO = 4

USES_SIP_DIAL_IN = 8

class nc_py_api.talk.ListableScope(value)

Listable scope for the room.

PARTICIPANTS_ONLY = 0

ONLY_REGULAR_USERS = 1

EVERYONE = 2

class nc_py_api.talk.NotificationLevel(value)

The notification level for the user.

Note

Default: 1 for one-to-one conversations, 2 for other conversations.

DEFAULT = 0

ALWAYS_NOTIFY = 1

NOTIFY_ON_MENTION = 2

NEVER_NOTIFY = 3

class nc_py_api.talk.WebinarLobbyStates(value)

Webinar lobby restriction (0-1), if the participant is a moderator, they can always join the conversation.

NO_LOBBY = 0

NON_MODERATORS = 1

class nc_py_api.talk.SipEnabledStatus(value)

SIP enable status.

DISABLED = 0

ENABLED = 1

Each participant needs a unique PIN.

ENABLED_NO_PIN = 2

Only the conversation token is required.

class nc_py_api.talk.CallRecordingStatus(value)

Type of call recording.

NO_RECORDING = 0

VIDEO = 1

AUDIO = 2

STARTING_VIDEO = 3

STARTING_AUDIO = 4

RECORDING_FAILED = 5

class nc_py_api.talk.BreakoutRoomMode(value)

Breakout room modes.

NOT_CONFIGURED = 0

AUTOMATIC = 1

Attendees are unsorted and then distributed over the rooms, so they all have the same participant count.

MANUAL = 2

A map with attendee to room number specifies the participants.

FREE = 3

Each attendee picks their own breakout room.

class nc_py_api.talk.BreakoutRoomStatus(value)

Breakout room status.

STOPPED = 0

Breakout rooms lobbies are disabled.

STARTED = 1

Breakout rooms lobbies are enabled.

class nc_py_api.talk.MessageReactions(raw_data: dict)

One reaction for a message, retrieved with get_message_reactions().

property actor_type: str

Actor types of the chat message: users, guests.

property actor_id: str

Actor id of the message author.

property actor_display_name: str

A display name of the message author.

property timestamp: int

Timestamp in seconds and UTC time zone.

class nc_py_api.talk.BotInfo(raw_data: dict)

Full information about the Nextcloud Talk Bot.

property url: str

URL endpoint that is triggered by this bot.

property url_hash: str

Hash of the URL prefixed with bot- serves as actor_id.

property error_count: int

Number of consecutive errors.

property last_error_date: int

UNIX timestamp of the last error.

property last_error_message: str | None

The last exception message or error response information when trying to reach the bot.

property bot_id: int

Unique numeric identifier of the bot on this server.

property bot_name: str

The display name of the bot shown as author when it posts a message or reaction.

property description: str

A longer description of the bot helping moderators to decide if they want to enable this bot.

property state: int

One of the Bot states: 0 - Disabled, 1 - enabled, 2 - No setup.

class nc_py_api.talk.BotInfoBasic(raw_data: dict)

Basic information about the Nextcloud Talk Bot.

property bot_id: int

Unique numeric identifier of the bot on this server.

property bot_name: str

The display name of the bot shown as author when it posts a message or reaction.

property description: str

A longer description of the bot helping moderators to decide if they want to enable this bot.

property state: int

One of the Bot states: 0 - Disabled, 1 - enabled, 2 - No setup.

class nc_py_api.talk.Poll(raw_data: dict, conversation_token: str)

Conversation Poll information.

property conversation_token: str

Token identifier of the conversation to which poll belongs.

property poll_id: int

ID of the poll.

property question: str

The question of the poll.

property options: list[str]

Options participants can vote for.

property votes: dict[str, int]

Map with ‘option-’ + optionId => number of votes.

Note

Only available for when the actor voted on the public poll or the poll is closed.

property actor_type: str

Actor type of the poll author: users, groups, circles, guests, emails.

property actor_id: str

Actor ID identifying the poll author.

property actor_display_name: str

The display name of the poll author.

property closed: bool

Participants can no longer cast votes and the result is displayed.

property hidden_results: bool

The results are hidden until the poll is closed.

property max_votes: int

The maximum amount of options a user can vote for, 0 means unlimited.

property voted_self: list[int]

Array of option ids the participant voted for.

property num_voters: int

The number of unique voters that voted.

Note

only available when the actor voted on the public poll or the poll is closed unless for the creator and moderators.

property details: list[PollDetail]

Detailed list who voted for which option (only available for public closed polls).

class nc_py_api.talk.PollDetail(raw_data: dict)

Detail about who voted for option.

property actor_type: str

The actor type of the participant that voted: users, groups, circles, guests, emails.

property actor_id: str

The actor id of the participant that voted.

property actor_display_name: str

The display name of the participant that voted.

property option: int

The option that was voted for.