Retrieving and Creating chats

In Teamwire, messages and attachments can be exchanged between users through chats. A chat contains a "thread" of all the messages exchanged and it has several properties, like users, circles, and lists that are members of the chat itself (i.e. all the users who can participate in the chat), a list of chat administrators, and more.

In the SDK, the Chat class provides all the features needed to interact within a single chat. Besides sending messages and attachments in the chat, a bot can perform administrative actions on the chat itself, like inviting members, changing the title, etc.

In previous sections we have seen how each received message contains a reference to its parent chat. In this section we'll explore other ways to retrieve a list of all the chats involving the bot, as well as methods to find a specific chat. We'll also see how new chats can be created by a bot.

Such operations can be performed by interacting with the Connection.chats object.

Listing all the chats where the bot is a member

First of all we are going to try to get a list of all the chats involving the bot itself.

from teamwire_api import Connection

async def list_chats(connection):
    # retrieve all the chats involving the bot
    chats = await connection.chats.get_subscriptions()

    print('Available chats:')

    for chat in chats:
        chat_title = chat.title or "no title"
        print(f'- {chat_title}, ID: {chat.tid}')

with Connection() as connection:
    connection.exec_async(list_chats(connection))

Finding specific chats by thread ID

The following example shows how to get a specific chat, givent its thread ID:

from teamwire_api import Connection

async def get_chat_by_thread_id(connection):
    chat = await connection.chats.get_by_thread_id('7MQKchz6wsSzmWTVnppGAc')

    if chat:
        chat_title = chat.title or "no title"
        print(f'Found chat: {chat_title}, ID: {chat.tid}')
    else:
        print('Chat not found')

with Connection() as connection:
    connection.exec_async(get_chat_by_thread_id(connection))

Finding chats with a given title

Similarly, we can get all the chats with a specific title:

from teamwire_api import Connection

async def get_chat_by_title(connection):
    title = 'test'
    chats = await connection.chats.get_by_title(title)

    if len(chats) == 0:
        print(f'no chats with title "{title}" found')
        return

    print(f'Available chats with title "{title}":')

    for chat in chats:
        print(f'- {chat.tid}')

with Connection() as connection:
    connection.exec_async(get_chat_by_title(connection))

Please note that in this case, chats.get_by_title() returns a list of chats.

Creating chats

Bots can also create new chats. The following example shows how:

from teamwire_api import Connection

async def create_chat(connection):
    # find a recipient user by its id
    user = await connection.users.get_user('rVRCfuQEtkgnZBZEgbHVji')

    # find a recipient circle by its id
    circle = await connection.groups.get_group('45529')

    # chat title
    title = "hello world"

    # initial message
    message = "test message"

    # create the chat
    chat = await connection.chats.create_chat(
        title=title,
        users=[user],       # user recipients
        groups=[circle],    # group recipients
        message=message     # optional first message
    )
    print(f'new chat created with id: {chat.tid}')

with Connection() as connection:
    connection.exec_async(create_chat(connection))

Among other argument the chats.create_chat() method, accepts a title, a list of user recipients, a list of group recipients (circles, and lists) and an initial message to be sent for starting the conversation.

Note

bots can create new chats involving circles only these are set as public in the Teamwire admin dashboard