Use the Python API

The Mattermost Notify package comes with a Python API that allows you to send messages to your Mattermost server.

Functional API

There are a handful of toplevel functions that allow you to send messages without much fuzz. The first function to call is wakeup() which will initialize a connection automatically, assuming you have properly set up Mattermost Notify after installing the package.

After that you can use the functions notify_user and notify_channel to send messages and files to users or channels respectively. You can also use the notify function to do either of these things, but you will have to specify the target every time.

Here is a small toy example:

import mattermost_notify as notify

# initialize the connection
notify.wakeup()

# send a message to a user
notify.notify_user("Hello World!", "your_username")

# send a message and a file to a channel
notify.notify_channel("Hello World!", "channel_name", files=["/path/to/file"])

The Notify class

The primary class is the Notify class that you can use to set up a connection to your Mattermost server and send messages. If you prefer having a class object rather than using the toplevel functions, you can use the Notify class, which you will have to set up manually.

Here is an example:

import mattermost_notify as notify

# create a Notify object
client = notify.Notify(token="your_token", url="your_server_url", team_name="your_team_name")

# send a message to a user
client.send_to_user("Hello World!", "your_username")

The Notify class also has a send_to_channel method that allows you to send messages to channels.

# send a message to a channel
client.send_to_channel("Hello World!", "channel_name")

If you want to upload files alongside your message, you can provide a list of file paths to either of these functions using the files argument.

# send a message to a channel with two files
client.send_to_channel("Hello World!", "channel_name", files=["/path/to/file1", "/path/to/file2"])

Standard User or Channel

The functional API supports setting a standard target for messages so that the user does not have to repeat the target in every call. The Notify class supports this feature only for channels.

Here is an example:

import mattermost_notify as notify

# set up and specify that by default messages should go to a specific user
notify.wakeup(always_send_to_user="your_username")

# send a message to the default user (no need to specify the target)
notify.notify("Hello World!")

Updating Messages

You can update messages that have been sent before in order to keep the chat cleaner while still up to date. In order to update a message it needs to be given an id when it is sent. This can be done by providing the id keyword to any of the sending functions or methods. To update it later you can either use the send_update function, the notify function or the Notify.send_update method, depending on what setup you are using.

Here is an example:

# send a message to a user and provide an id
notify.notify_user("Hello World!", "your_username", id="my-test-message")

# update the message
notify.send_update("Hello World! (updated)", id="my-test-message")

The notify function automates this process by checking if a provided id has already been used and if so, updates the message instead of sending a new one.

# send a message to a user and provide an id
notify.notify("Hello World!", user_name="your_username", id="my-test-message")

# update the message
notify.notify("Hello World! (updated)", id="my-test-message")

The Notify class mimics the behavior of the send_update function.

# send a message to a user and provide an id
client.send_to_user("Hello World!", "your_username", id="my-test-message")

# update the message
client.send_update("Hello World! (updated)", id="my-test-message")

By default the message cache is linked to one specific instance of the Notify class. Therefore you can by default only update messages within the _same_ session! Hence it is advisable to integrate the notifications into the same script or jupyter notebook that you want to monitor. However, you can also update messages accross different sessions if you absolutely want to. To do so you will have to export the message hook you want to update to a file and then in the new session (i.e. with the new Notify client) read that file. Then you are able to use send_update again as before.

Here’s an example:

# send a message to a user and provide an id
notify.notify_user("Hello World!", "your_username", id="my-test-message")

# export the message hook to a file
notify.export_hook("my-test-message", "my-test-message.msg")

# -----------------
# in a new session
# -----------------
notify.wakeup()

# read the message hook from the file
notify.import_hook("my-test-message.msg")

# update the message
notify.send_update("Hello World! (updated)", id="my-test-message")

or with the actual methods from the Notify class:

client = notify.Notify(token="your_token", url="your_server_url", team_name="your_team_name")

# send a message to a user and provide an id
client.send_to_user("Hello World!", "your_username", id="my-test-message")

# export the message hook to a file
client.write_message_hook_to_file("my-test-message", "my-test-message.msg")

# -----------------
# in a new session
# -----------------
other_client = notify.Notify(token="your_token", url="your_server_url", team_name="your_team_name")

# read the message hook from the file
other_client.read_message_hook_from_file("my-test-message.msg")

# update the message
other_client.send_update("Hello World! (updated)", id="my-test-message")