teamwire_api.chats¶

AlertType¶

class AlertType(Enum)

Type of Attention Message Alert

ALERT¶

Normal Alert message

ANNOUNCEMENT¶

Announcement message

NOTE¶

Note message

ChatType¶

class ChatType(Enum)

Chat Type

ONE_TO_ONE¶

1:1 chat

GROUP¶

Group chat

Chat¶

class Chat(object)

A chat between users and/or groups of users. The Chat class provides access to all information (title, members, etc.) of a chat and to the messages it contains. It also provides methods to interact with the specific chat it represents, e.g. for sending messages, adding and removing members, etc.

Attributes

tid: unicode. The thread id of the chat
is_alert: boolean. Whether this is an alert chat
allow_sending: boolean, default True. Whether other members of the chat can send messages
allow_mute_notifications: boolean, defaul True. Whether members of the chat can mute notifications
is_closed: boolean. Whether the chat has been closed
type: one from the ChatType enum: either 1:1 or group chat

post¶

 | async post(message='', attachments=None, is_alert=False, reply_to=None, sender_display_name=None, alert_type=None)

coroutine to post a message and/or attachments to the chat

Arguments

message: unicode (optional). The message text to be sent
attachments: list of Attachment objects, or an Attachments object (optional). The attachments to be sent
is_alert: boolean (default: false). Whether the message is an "alert" message
reply_to: Message object or string message ID (optional). Make the message being sent a reply to the Message object or the string message ID contained in the reply_to argument
sender_display_name: unicode. A string representing an external sender name. If set, clients will show this as the sender name, instead of the bot name
alert_type: AlertType. Type of alert (e.g. alert, announcement, note). Defaults to AlertType.ALERT if is_alert is True and alert_type is None

Raises

exceptions.TWNotFoundError if the chat or thread cannot be found exceptions.TWAuthError if the bot is not authorised to send a message to the given chat exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

add_members¶

 | async add_members(users=[], groups=[])

coroutine to add members (users and groups) to the chat

Arguments

users: list of User objects to be added as members of the chat
groups: list of Group objects to be added as members of the chat

Raises

exceptions.TWUpdateMembersNotAllowed if the backend admin disallowed chat members updates exceptions.TWInvalidMembersError if any of referenced members or groups are invalid exceptions.TWAuthError if the bot is not authorized to add members to the chat exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

remove_members¶

 | async remove_members(users=[], groups=[])

coroutine to remove members (users and groups) from the chat

Arguments

users: list of User objects to be removed from the members of the chat
groups: list of Group objects to be removed from the members of the chat

Raises

exceptions.TWUpdateMembersNotAllowed if the backend admin disallowed chat members updates exceptions.TWInvalidMembersError if any of referenced members or groups are invalid exceptions.TWAuthError if the bot is not authorized to remove members from the chat exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

leave¶

 | async leave()

coroutine to make the bot to leave (i.e. unsubscribe from) the chat

Raises

exceptions.TWLeaveChatNotAllowed if the backend admin disallowed leaving chats exceptions.TWAuthError if the bot is not authorized to leave the chat exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

add_admin¶

 | async add_admin(admin)

coroutine to add a user as an administrator of the chat

Arguments

admin: a User object to be added as administrator of the chat

Raises

exceptions.TWNotFoundError if the provided user is not active or has been deleted exceptions.TWAuthError if the bot is not authorized to add admins to the chat exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

remove_admin¶

 | async remove_admin(admin)

coroutine to remove a user from the administrators of the chat

Arguments

admin: a User object to be removed from the administrators of the chat

Raises

exceptions.TWNotFoundError if the provided user is not active or has been deleted exceptions.TWAuthError if the bot is not authorized to remove admins from the chat exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

get_user_members¶

 | get_user_members()

Method to get the list of users that are direct members of the chat (i.e. not the users that are part of the chat, because they are members of a group involved in the chat)

Returns

A list of User objects representing the user members of the chat

get_group_members¶

 | get_group_members()

Method to get the list of groups that are members of the chat

Returns

A list of Group objects representing the group members of the chat

get_admins¶

 | get_admins()

Method to get the list of the administrators of the chat

Returns

A list of User objects representing the administrators of the chat

get_readers¶

 | async get_readers()

coroutine to get the users who have read all the messages of the chat

Returns

a list of User objects of the users who have read all the messages of the chat

Raises

exceptions.TWReadReceiptsDisabled if read receipts have been disabled by the Admin exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

mark_as_read¶

 | async mark_as_read()

coroutine to mark the chat as "read" from the bot

Returns

a list of User objects of the users who have read all the messages of the chat

Raises

exceptions.TWAuthError if the operation is not allowed exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

pull_chat_feed¶

 | async pull_chat_feed(since=None)

coroutine to get the last messages of the chat, sent and received after a given date/time. Note, this method is deprecated since v1.0 of the SDK

Arguments

since: datetime. Date/Time since when messages should be loaded

Returns

a tuple in the form (messages, last_modified) where messages is a list of Message objects, and last_modified is a datetime object indicating the last time a message hase been received in the chat

Raises

exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

get_messages¶

 | async get_messages(since=None)

coroutine to get the last messages of the chat, sent and received after a given date/time

Arguments

since: datetime. Date/Time since when messages should be loaded. Default: 1 day ago

Returns

a tuple in the form (messages, last_modified) where messages is a list of Message objects, and last_modified is a datetime object indicating the last time a message hase been received in the chat

Raises

exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

new_attachments¶

 | new_attachments()

create a new Attachments object for accumulating attachments to be sent

Returns

an Attachments object

update_title¶

 | async update_title(title)

coroutine to update the title of the chat

Arguments

title: unicode. The new title of the chat

Raises

exceptions.TWNotFoundError if the chat is not found exceptions.TWAuthError if the bot is not authorized to perform the operation exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

set_allow_sending¶

 | async set_allow_sending(allow_sending)

coroutine to allow or disallow non-admin users to send messages

Arguments

allow_sending: boolean. Whether non-admin members of the chat can send messages

Raises

exceptions.TWNotFoundError if the chat is not found exceptions.TWAuthError if the bot is not authorized to perform the operation exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

set_allow_mute_notifications¶

 | async set_allow_mute_notifications(allow_mute_notifications)

coroutine to allow or disallow other users to mute notifications

Arguments

allow_mute_notifications: boolean. Whether members of the chat can mute notifications

Raises

exceptions.TWNotFoundError if the chat is not found exceptions.TWAuthError if the bot is not authorized to perform the operation exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

close¶

 | async close()

coroutine to close the chat

Raises

exceptions.TWCloseChatNotAllowed if the backend admin disallowed closing chats exceptions.TWNotFoundError if the chat is not found exceptions.TWAuthError if the bot is not authorized to perform the operation exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

reopen¶

 | async reopen()

coroutine to reopen the chat

Raises

exceptions.TWNotFoundError if the chat is not found exceptions.TWAuthError if the bot is not authorized to perform the operation exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

load_avatar¶

 | async load_avatar()

Coroutine to load the avatar image of the chat (if set).

Returns a bytes array representation of the loaded image

Raises

exceptions.TWImageLoadError if no avatar has been set for the chat exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

set_avatar¶

 | async set_avatar(image_path)

coroutine to set the chat's avatar image

Arguments

image_path: unicode. The full path to the image to be uploaded as an avatar for the bot

Raises

exceptions.TWImageLoadError if the provided image cannot be found or loaded correctly exceptions.TWAuthError if the bot is not authorized to change the chat avatar image exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

remove_avatar¶

 | async remove_avatar()

coroutine to remove the chat's avatar image

Raises

exceptions.TWImageRemoveError if the the avatar could not be removed exceptions.TWAuthError if the bot is not authorized to remove its avatar exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

get_active_shared_locations¶

 | async get_active_shared_locations()

coroutine to get the total number of currently active shared locations in the chat

Returns

the total number of currently active shared locations in the chat

Raises

exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

stop_sharing_location¶

 | async stop_sharing_location()

coroutine to stop sharing the current location in this chat

Raises

exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

subscribe_live_location_updates¶

 | async subscribe_live_location_updates(handler)

coroutine to subscribe to live-location updates for this chat

Note

this method starts an infinite event loop, which will periodically invoke the handler callback. In order to avoid this to block the normal flow of execution, you can invoke it asynchronously with:

asyncio.get_event_loop().create_task(chat.subscribe_live_location_updates(print_location_update))

Arguments

handler: a function or coroutine that will be invoked each time an update is received. A LiveLocationUpdate object is passed to the function as an argument

Raises

exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

unsubscribe_location_updates¶

 | async unsubscribe_location_updates()

coroutine to unsubscribe from live-location updates for this chat

Raises

exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

send_am_reaction¶

 | async send_am_reaction(message, reaction_type)

coroutine to send a reaction to a message

Arguments

message: Message object. The message we are reacting to
reaction_type: one of ReactionType enum

Returns

an AMReaction object

Raises

exceptions.TWAuthError if the operation is not allowed exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

get_am_reactions¶

 | async get_am_reactions(message)

coroutine to get all reactions to a given attention message

Note

reactions can be retrievet only for proper attention messages (e.g. alerts, announcements, notes)

Arguments

message: Message object

Returns

a list of AMReaction objects

Raises

exceptions.TWAuthError if the operation is not allowed exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

update_am_reaction¶

 | async update_am_reaction(reaction, reaction_type)

coroutine to update a reaction to an attention message

Note

reactions can be retrievet only for proper attention messages (e.g. alerts, announcements, notes)

Arguments

reaction: AMReaction object to be updated with a new reaction
reaction_type: one of ReactionType enum

Raises

exceptions.TWAuthError if the operation is not allowed exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

Chats¶

class Chats(object)

An accessor to the chats involving the bot

get_subscriptions¶

 | async get_subscriptions()

coroutine to get all the chats the bot is subscribed to

Returns

a list of Chat objects

Raises

exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

get_by_thread_id¶

 | async get_by_thread_id(tid)

coroutine to get a chat by its thread id

Arguments

tid: unicode. The thread id of the chat to be retrieved

Returns

a Chat object, None if not found

Raises

exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

get_by_title¶

 | async get_by_title(title)

coroutine to get a list of chats with the provided title

Arguments

title: unicode. The title of the chats to be retrieved

Returns

a list of Chat objects

Raises

exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

create_one2one_chat¶

 | async create_one2one_chat(recipient, message=None, attachment=None)

coroutine to create a new 1:1 chat

1:1 chats are created between two users, and no other users can be invited to the chat, moreover 1:1 chats cannot be left by their members. If a 1:1 chat with the same recipient is already present, that one will be reused. In general, for more flexible chat management, it's advisable that bots only create proper group chats, using the chats.create_chat() method.

Arguments

recipient: User object. The other member of the 1:1 chat
message: unicode. The initial message of the chat
attachment: an Attachment object. The initial attachment of the chat

Note

the message and attachment arguments are optional. If none of them is provided, an empty chat is created.

Returns

the newly created Chat object, or an already existing Chat with the same recipient.

Raises

exceptions.TWInvalidMembersError if any of referenced members or groups are invalid exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

create_chat¶

 | async create_chat(title, users=[], groups=[], message=None, attachment=None, is_alert=False, admins=[], avatar=None, allow_sending=True, allow_mute_notifications=True)

coroutine to create a new group chat. In order to create a 1:1 chat between the bot and the user, please use `chats.create_one2one_chat()"

Arguments

title: unicode. The title of the new chat
users: list of User objects. The user members of the chat
groups: list of Group objects. The group members of the chat
message: unicode. The initial message of the chat
attachment: an Attachment object. The initial attachment of the chat
is_alert: boolean, default False. Whether the chat is an "alert" chat
admins: list of User objects. Members of the chat that that can administer the chat
avatar: optional string. Path to a max 600x600px jpeg image to set as avatar for the chat
allow_sending: boolean, default True. If False only admins can send messages to the chat
allow_mute_notifications: boolean, default True. Whether members of the chat can mute notifications

Note

the message and attachment arguments are optional. If none of them is provided, an empty chat is created.

Returns

the newly created Chat object

Raises

exceptions.TWInvalidMembersError if any of referenced members or groups are invalid exceptions.TWImageLoadError if the avatar image cannot be correctly opened exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

update_shared_location¶

 | async update_shared_location(lat, lon)

coroutine to update the current location for all active location sharing attachments (shared in any thread)

Arguments

lat: double between -90 and +90. The geo latitude of the location
lon: double between 0 and 180. The geo longitude of the location

Raises

exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

get_location_sharing_active_chats¶

 | get_location_sharing_active_chats()

method to get all the chats where the SDK is actively sharing live-location.

This method returns a list of chats where the SDK/bot recently sent a LocationSharingAttachment which is still active (i.e. not expired) and where location sharing has not been explicitly stopped.

Returns

a list of Chat objects where live-location is being actively shared by the SDK

has_location_sharing_active_chats¶

 | has_location_sharing_active_chats()

returns whether the SDK is actively sharing live-location in any chat

Returns

True if live-location is being actively shared by the SDK in any chat, False otherwise

subscribe_am_reaction_updates¶

 | async subscribe_am_reaction_updates(handler)

coroutine to subscribe to attention message reaction updates

Note

this method starts an infinite event loop, which will periodically invoke the handler callback. In order to avoid this to block the normal flow of execution, you can invoke it asynchronously with:

asyncio.get_event_loop().create_task(connection.chats.subscribe_am_reactions_update(print_am_reaction))

Arguments

handler: a function or coroutine that will be invoked each time a reaction is received. An AMReaction object is passed to the function as an argument

Raises

exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

unsubscribe_am_reaction_updates¶

 | async unsubscribe_am_reaction_updates()

coroutine to unsubscribe from attention message reaction updates

Raises

exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems