README.md

   1 # [Mattermost API](https://api.mattermost.com/) bindings
   2 ([Read on github](https://github.com/someone-somenet-org/mattermost-python-api))
   3
   4 In productive use on a 6k+ users E10 instance at https://mattermost.fsinf.at
   5 + Used to manage channels, users and everything.
   6 + Some api-endpoints are #UNTESTED.
   7   + Some are not handled/#NOT_IMPLEMENTED (yet).
   8     + Some dont seem to make any sense to ever implement at all. Why do they even exist?
   9     + Others may be out of scope (I cannot test E20-stuff)
  10 + Beware: I love to rebase git. :)
  11
  12 ## If you use this or find this stuff useful, consider paying me a beer/club-mate :)
  13 + ``btc: bc1q9vxqzd58683ky9c2yaddaxx3wrxakggfa0dmdt``
  14 + ``eth: 0x839326860d74cf61f03719c5c63db3ae5d2b443f``
  15 + ``bch: qqxpm8py3flkaqdt4ehatzvx250634fuvgsgvft6z4``
  16 + ``doge: DLeQq2u7gdnidaNwEtj9fYrstUaU4banNg``
  17 + ``xmr: 47WwuQssrZRHLXYBRoEPmqhyG8e4PxorwWn1Xvyg6QShKAjZ83UHWJmYd9PFkpH6vPQFgNbnKvaRz1EzoQHSeeQvEGQ6ihA``
  18
  19
  20 ## Setup
  21 ``pip3 install --user --upgrade mattermost``
  22
  23
  24 ## Usage
  25 ```
  26 import mattermost
  27
  28 # login
  29 mm = mattermost.MMApi("https://mattermost.example.com/api")
  30 mm.login("user@example.com", "my-pw")
  31 # alternatively use a personal-access-token/bot-token.
  32 # mm.login(bearer="my-personal-access-token")
  33
  34
  35 # do stuff (print info about your user)
  36 import pprint
  37 pprint.pprint(mm.get_user())
  38
  39
  40 # do other stuff (print info about an not-existing user)
  41 try:
  42     pprint.pprint(mm.get_user("not-existing-user-id", exc=True))
  43 except mattermost.ApiException as e:
  44     print(e)
  45
  46
  47 # custom endpoint call (get server config)
  48 cfg = mm._get("/v4/config")
  49
  50 # do something (enable plugins)
  51 cfg["PluginSettings"]["Enable"] = True
  52
  53 # custom endpoint call (put server config)
  54 mm._put("/v4/config", data=cfg)
  55
  56
  57 # logout
  58 mm.revoke_user_session()
  59 ```
  60
  61
  62 ### Websocket usage
  63 ```
  64 import mattermost
  65 import mattermost.ws
  66
  67 # login
  68 mm = mattermost.MMApi("https://mattermost.example.com/api")
  69 mm.login("user@example.com", "my-pw")
  70
  71
  72 # define a websocket handler
  73 def webs_handler(mmws, event_data):
  74     import pprint
  75     pprint.pprint(mmws)
  76     pprint.pprint(event_data)
  77
  78 # connect to websocket and start processing events
  79 mmws = mattermost.ws.MMws(webs_handler, mm, "wss://mattermost.example.com/api/v4/websocket")
  80 ```
  81
  82 To close the websocket connection - there is no way to restart, create a new instance of MMws:
  83 + ``mmws.close_websocket()``
  84
  85
  86 ### Manually calling the API
  87 Some endpoints are not handled (yet). You can manually call these endpoints. Available private functions:
  88 + ``_get(endpoint, raw=False, exc=False)``
  89 + ``_put(endpoint, data=None, exc=False)``
  90 + ``_post(endpoint, data=None, multipart_formdata=None, exc=False)``
  91 + ``_delete(endpoint, data=None, exc=False)``
  92
  93
  94 ### stdin2channel
  95 You can pipe ``STDIN`` to a channel:
  96 + ``echo "message" | python3 -m mattermost.stdin2channel https://localhost:8065/api 'user@example.com' 'my-pw' 'channel_id'``
  97 **This leaks your credentials to everyone on your system!** Only use this in trusted dev-envs.
  98
  99
 100 ## Endpoints
 101 Ordered by https://api.mattermost.com/
 102 <!-- grep -E "(^#\+)|(def\s+[^_])" mattermost/__init__.py | sed -nEe 's/^#\+/+/p' -e 's/^\s+def\s+([^(]+)\(self,?\s*(.*\)):?(.*$)/  + **``\1 (\2\3``**/p' -e 's/^\s+#def\s+(.*NOT_IMPLEMENTED.*$)/  + *``\1``*/' >> README.md -->
 103 + **LOGIN/LOGOUT**
 104   + **``login (login_id=None, password=None, token=None, bearer=None)``**
 105   + **``logout (**kwargs)``**
 106 + **USERS**
 107   + *``create_user() #NOT_IMPLEMENTED``*
 108   + **``get_users (in_team=None, not_in_team=None, in_channel=None, not_in_channel=None, group_constrained=None, without_team=None, sort=None, **kwargs)``**
 109   + **``get_users_by_ids_list (user_ids_list, **kwargs) #UNTESTED``**
 110   + **``get_users_by_group_channel_ids_list (group_channel_ids_list, **kwargs) #UNTESTED``**
 111   + **``get_users_by_usernames_list (usernames_list, **kwargs)``**
 112   + *``search_users() #NOT_IMPLEMENTED``*
 113   + *``autocomplete_users() #NOT_IMPLEMENTED``*
 114   + *``get_user_ids_of_known_users() #NOT_IMPLEMENTED``*
 115   + *``get_total_count_of_users_in_system() #NOT_IMPLEMENTED``*
 116   + **``get_user (user_id=None, **kwargs)``**
 117   + *``update_user() #NOT_IMPLEMENTED: # use patch_user``*
 118   + *``deactivate_user() #NOT_IMPLEMENTED``*
 119   + **``patch_user (user_id, props=None, **kwargs)``**
 120   + *``update_user_roles() #NOT_IMPLEMENTED``*
 121   + *``update_user_active_status() #NOT_IMPLEMENTED``*
 122   + *``get_user_profile_image() #NOT_IMPLEMENTED``*
 123   + *``set_user_profile_image() #NOT_IMPLEMENTED``*
 124   + *``delete_user_profile_image() #NOT_IMPLEMENTED``*
 125   + *``get_user_default_profile_image() #NOT_IMPLEMENTED``*
 126   + **``get_user_by_username (username, **kwargs)``**
 127   + *``reset_user_password() #NOT_IMPLEMENTED``*
 128   + *``update_user_mfa() #NOT_IMPLEMENTED``*
 129   + *``generate_user_mfa_secret() #NOT_IMPLEMENTED``*
 130   + **``demote_a_user (user_id, **kwargs)``**
 131   + **``promote_a_guest (user_id, **kwargs)``**
 132   + *``check_user_mfa() #NOT_IMPLEMENTED``*
 133   + *``update_user_password() #NOT_IMPLEMENTED``*
 134   + *``send_user_password_reset_mail() #NOT_IMPLEMENTED``*
 135   + *``get_user_by_email() #NOT_IMPLEMENTED``*
 136   + **``get_user_sessions (user_id=None, **kwargs)``**
 137   + **``revoke_user_session (user_id=None, session_id=None, **kwargs)``**
 138   + *``revoke_all_user_sessions() #NOT_IMPLEMENTED``*
 139   + *``attach_mobile_device_to_user_session() #NOT_IMPLEMENTED``*
 140   + *``get_user_audit() #NOT_IMPLEMENTED``*
 141   + *``admin_verify_user_email_() #NOT_IMPLEMENTED``*
 142   + *``verify_user_email_() #NOT_IMPLEMENTED``*
 143   + *``send_user_email_verification() #NOT_IMPLEMENTED``*
 144   + *``switch_user_login_method() #NOT_IMPLEMENTED``*
 145   + *``create_user_access_token() #NOT_IMPLEMENTED``*
 146   + *``get_user_access_tokens() #NOT_IMPLEMENTED``*
 147   + *``revoke_user_access_token() #NOT_IMPLEMENTED``*
 148   + *``get_user_access_token() #NOT_IMPLEMENTED``*
 149   + *``disable_user_access_token() #NOT_IMPLEMENTED``*
 150   + *``enable_user_access_token() #NOT_IMPLEMENTED``*
 151   + *``search_user_access_tokens() #NOT_IMPLEMENTED``*
 152   + *``update_user_auth_method() #NOT_IMPLEMENTED``*
 153   + *``record_user_action_custom_tos() #NOT_IMPLEMENTED``*
 154   + *``fetch_user_latest_accepted_custom_tos() #NOT_IMPLEMENTED``*
 155   + *``revoke_all_users_all_sessions() #NOT_IMPLEMENTED #MM, ARE YOU INSANE?!``*
 156 + **BOTS** #NOT_IMPLEMENTED
 157 + **TEAMS**
 158   + *``create_team() #NOT_IMPLEMENTED``*
 159   + **``get_teams (include_total_count=None, **kwargs)``**
 160   + **``get_team (team_id, **kwargs)``**
 161   + *``update_team() #NOT_IMPLEMENTED``*
 162   + *``delete_team() #NOT_IMPLEMENTED``*
 163   + *``patch_team() #NOT_IMPLEMENTED``*
 164   + *``update_team_privacy() #NOT_IMPLEMENTED``*
 165   + *``restore_team() #NOT_IMPLEMENTED``*
 166   + *``get_team_by_name() #NOT_IMPLEMENTED``*
 167   + *``search_teams() #NOT_IMPLEMENTED``*
 168   + *``exists_team() #NOT_IMPLEMENTED``*
 169   + *``get_teams_for_user() #NOT_IMPLEMENTED``*
 170   + **``get_team_members (team_id, **kwargs)``**
 171   + **``add_user_to_team (team_id, user_id, **kwargs)``**
 172   + *``add_user_to_team_from_invite() #NOT_IMPLEMENTED``*
 173   + *``add_multiple_users_to_team() #NOT_IMPLEMENTED WHY?!``*
 174   + *``get_team_members_for_a_user() #NOT_IMPLEMENTED WHY NOT NAMING STUFF USEFULLY?!``*
 175   + **``get_team_member (team_id, user_id, **kwargs)``**
 176   + **``remove_user_from_team (team_id, user_id, **kwargs)``**
 177   + *``get_team_members_by_id() #NOT_IMPLEMENTED``*
 178   + *``get_team_stats() #NOT_IMPLEMENTED``*
 179   + *``regenerate_team_invite_id() #NOT_IMPLEMENTED``*
 180   + *``get_team_icon() #NOT_IMPLEMENTED``*
 181   + *``set_team_icon() #NOT_IMPLEMENTED``*
 182   + *``remove_team_icon() #NOT_IMPLEMENTED``*
 183   + *``update_team_members_roles() #NOT_IMPLEMENTED``*
 184   + **``update_team_members_scheme_roles (team_id, user_id, props, **kwargs)``**
 185   + *``get_team_unreads_for_user() #NOT_IMPLEMENTED``*
 186   + *``get_team_unreads() #NOT_IMPLEMENTED``*
 187   + *``invite_users_to_team_by_email() #NOT_IMPLEMENTED``*
 188   + **``invite_guests_to_team_by_email (team_id, guest_email, channels, message, **kwargs)``**
 189   + *``invalidate_invites_to_team_by_email() #NOT_IMPLEMENTED``*
 190   + *``import_team() #NOT_IMPLEMENTED``*
 191   + *``get_team_invite_info() #NOT_IMPLEMENTED``*
 192   + *``set_team_scheme() #NOT_IMPLEMENTED``*
 193   + *``get_team_members_minus_group_members() #NOT_IMPLEMENTED``*
 194   + **``get_team_channels (team_id, **kwargs) #This belongs here, not to channels!``**
 195 + **CHANNELS**
 196   + *``get_all_channels() #NOT_IMPLEMENTED NOT USEFUL AT ALL!``*
 197   + **``create_channel (team_id, name, display_name, purpose=None, header=None, chan_type="O", **kwargs)``**
 198   + **``create_dm_channel_with (other_user_id, **kwargs)``**
 199   + **``create_group_channel_with (other_user_ids_list, **kwargs) #UNTESTED``**
 200   + *``search_all_private_and_public_channels() #NOT_IMPLEMENTED``*
 201   + *``search_all_users_group_channels() #NOT_IMPLEMENTED``*
 202   + *``get_team_channels_by_id() #NOT_IMPLEMENTED``*
 203   + *``get_timezones_of_users_in_channel() #NOT_IMPLEMENTED``*
 204   + **``get_channel (channel_id, **kwargs)``**
 205   + **``update_channel (channel_id, props, **kwargs)``**
 206   + **``patch_channel (channel_id, props, **kwargs)``**
 207   + **``get_channel_posts_pinned (channel_id, **kwargs)``**
 208   + **``search_channel (team_id, term, **kwargs)``**
 209   + **``get_channel_by_name (team_id, channel_name, include_deleted=None, **kwargs)``**
 210   + **``get_channel_members (channel_id, **kwargs)``**
 211   + **``add_user_to_channel (channel_id, user_id, **kwargs)``**
 212   + **``get_channel_member (channel_id, user_id, **kwargs)``**
 213   + **``remove_user_from_channel (channel_id, user_id, **kwargs)``**
 214   + **``update_channel_members_scheme_roles (channel_id, user_id, props, **kwargs)``**
 215   + **``get_channel_memberships_for_user (user_id, team_id, **kwargs)``**
 216   + **``get_channels_for_user (user_id, team_id, **kwargs)``**
 217 + **POSTS**
 218   + **``create_post (channel_id, message, props=None, filepaths=None, root_id=None, **kwargs)``**
 219   + **``create_ephemeral_post (channel_id, message, user_id, **kwargs)``**
 220   + **``get_post (post_id, **kwargs)``**
 221   + **``delete_post (post_id, **kwargs)``**
 222   + **``patch_post (post_id, message=None, is_pinned=None, props=None, **kwargs)``**
 223   + **``get_posts_for_channel (channel_id, **kwargs)``**
 224 + **FILES**
 225   + **``upload_file (channel_id, filepath, **kwargs)``**
 226   + **``get_file (file_id, **kwargs)``**
 227 + **PREFERENCES** #NOT_IMPLEMENTED
 228 + **STATUS** #NOT_IMPLEMENTED
 229 + **EMOJI** #NOT_IMPLEMENTED
 230 + **REACTIONS**
 231   + **``create_reaction (user_id, post_id, emoji_name, **kwargs)``**
 232 + **WEBHOOKS**
 233   + **``create_outgoing_hook (team_id, display_name, trigger_words, callback_urls, channel_id=None, description=None, trigger_when=0, **kwargs)``**
 234   + **``list_outgoing_hooks (team_id, channel_id=None, **kwargs)``**
 235   + **``delete_outgoing_hook (hook_id, **kwargs)``**
 236 + **COMMANDS**
 237   + **``create_slash_command (team_id, trigger, url, **kwargs)``**
 238   + **``list_custom_slash_commands_for_team (team_id, **kwargs)``**
 239   + **``update_slash_command (data, **kwargs)``**
 240   + **``delete_slash_command (command_id, **kwargs)``**
 241 + **OPENGRAPH** #NOT_IMPLEMENTED
 242 + **SYSTEM** #NOT_IMPLEMENTED
 243 + **BRAND** #NOT_IMPLEMENTED
 244 + **OAUTH** #NOT_IMPLEMENTED
 245 + **SAML** #NOT_IMPLEMENTED
 246 + **LDAP** #NOT_IMPLEMENTED
 247 + **GROUPS** #NOT_IMPLEMENTED
 248 + **COMPLIANCE** #NOT_IMPLEMENTED
 249 + **CLUSTER** #NOT_IMPLEMENTED
 250 + **ELASTICSEARCH** #NOT_IMPLEMENTED
 251 + **BLEVE** #NOT_IMPLEMENTED
 252 + **DATARETENTION** #NOT_IMPLEMENTED
 253 + **JOBS** #NOT_IMPLEMENTED
 254 + **PLUGINS** #NOT_IMPLEMENTED
 255 + **ROLES** #NOT_IMPLEMENTED
 256 + **SCHEMES** #NOT_IMPLEMENTED
 257 + **INTEGRATION_ACTIONS**
 258   + **``open_dialog (trigger_id, response_url, dialog, **kwargs)``**
 259 + **TERMS_OF_SERVICE** #NOT_IMPLEMENTED