python-mxit
Python wrapper for accessing Mxit's public APIs
Installation
pip install mxit
Usage
Authentication
In order to use the Mxit APIs, one needs a client ID and client secret, which can be obtained by registering your app at dev.mxit.com. With these credentials a client object can be created:
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET)
Certain Mxit API calls are publically available, and thus only require app authentication. It is not necessary to specify scope when making these calls through this API wrapper, since it is already done in the respective functions.
Certain Mxit API calls require user authentication. The user would thus need to be redirected to Mxit's auth site, where permission will be granted by the user for the requested scope(s). The auth site will then redirect the user back to a specified url with a code attached in the query string. This code is then used to obtain the auth token for the following API calls. For this flow the url where the auth site needs to redirect back to needs to be specified when instantiating the client:
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET, redirect_url='http://example.org')
client.oauth.get_user_token(SCOPE, RECEIVED_CODE)
The auth site url to redirect the user to can be obtained with the following call (where SCOPE is the required scope(s) for the API calls to be made):
client.oauth.auth_url(SCOPE)
After the user has granted the desired permissions and the user redirected back the the url as specified, the auth token can be fetched as follows:
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET, redirect_url='http://example.org')
client.oauth.get_user_token(SCOPE, RECEIVED_CODE)
From here the client has access to the api calls allowed by the specified scope.
Messaging API
send_message
Send a message (from a Mxit app) to a list of Mxit users
User authentication required: NO
Required scope: message/send
Parameters
- app_mxit_id (required)
- target_user_ids (required)
- message (required)
- contains_markup (optional)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET)
client.messaging.send_message("example_app_mxit_id", ["mxit_user_id_1", "mxit_user_id_2" ], "This is a test message")
send_user_to_user_message
Send a message (from a Mxit user) to a list of Mxit users
User authentication required: YES
Required scope: message/user
Parameters
- from_user_id (required)
- target_user_ids (required)
- message (required)
- contains_markup (optional)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET, redirect_uri="http://example.org")
client.oauth.get_user_token("message/user", RECEIVED_AUTH_CODE)
client.messaging.send_user_to_user_message("example_mxit_user_id", ["mxit_user_id_1", "mxit_user_id_2" ], "This is a test user to user message")
User API
get_user_id
Retrieve the Mxit user's internal "user ID"
User authentication required: NO
Required scope: profile/public
Parameters
- mxit_id (required)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET)
user_id = client.users.get_user_id("example_mxit_id")
get_status
Retrieve the Mxit user's current status
User authentication required: NO
Required scope: profile/public
Parameters
- mxit_id (required)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET)
status = client.users.get_status("example_mxit_id")
set_status
Set the Mxit user's status
User authentication required: YES
Required scope: status/write
Parameters
- message (required)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET, redirect_uri="http://example.org")
client.oauth.get_user_token("status/write", RECEIVED_AUTH_CODE)
client.users.set_status("Some awesome status")
get_display_name
Retrieve the Mxit user's display name
User authentication required: NO
Required scope: profile/public
Parameters
- mxit_id (required)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET)
display_name = client.users.get_display_name("example_mxit_id")
get_avatar
Retrieve the Mxit user's avatar
User authentication required: NO
Required scope: profile/public
Parameters
If output_file_path is set, the file will be saved at that path, otherwise the file data will be returned.
- mxit_id (required)
- output_file_path (optional)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET)
client.users.get_avatar("example_mxit_id", output_file_path="/path/to/avatar.png")
data = client.users.get_avatar("example_mxit_id")
set_avatar
Set the Mxit user's avatar
User authentication required: YES
Required scope: avatar/write
Parameters
The avatar can either be sent as a bytestream in data or as a filepath in input_file_path.
- data (optional)
- input_file_path (optional)
- content_type (optional)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET, redirect_uri="http://example.org")
client.oauth.get_user_token("avatar/write", RECEIVED_AUTH_CODE)
client.users.set_avatar(input_file_path="/path/to/avatar.png")
delete_avatar
Delete the Mxit user's avatar
User authentication required: YES
Required scope: avatar/write
Parameters
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET, redirect_uri="http://example.org")
client.oauth.get_user_token("avatar/write", RECEIVED_AUTH_CODE)
client.users.delete_avatar()
get_basic_profile
Retrieve the Mxit user's basic profile
User authentication required: NO
Required scope: profile/public
Parameters
- user_id (required)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET)
basic_profile = client.users.get_basic_profile("example_user_id")
get_full_profile
Retrieve the Mxit user's full profile
User authentication required: YES
Required scope: profile/private
Parameters
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET, redirect_uri="http://example.org")
client.oauth.get_user_token("profile/private", RECEIVED_AUTH_CODE)
full_profile = client.users.get_full_profile()
update_profile
Update the Mxit user's profile
User authentication required: YES
Required scope: profile/write
Parameters
- about_me (optional)
- display_name (optional)
- email (optional)
- first_name (optional)
- gender (optional)
- last_name (optional)
- mobile_number (optional)
- relationship_status (optional)
- title (optional)
- where_am_i (optional)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET, redirect_uri="http://example.org")
client.oauth.get_user_token("profile/write", RECEIVED_AUTH_CODE)
client.users.update_profile(email="test@test.com", relationship_status=3)
add_contact
Add a contact on Mxit
User authentication required: YES
Required scope: contact/invite
Parameters
contact_id can either be the mxit ID of a service or a Mxit user
- contact_id (required)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET, redirect_uri="http://example.org")
client.oauth.get_user_token("contact/invite", RECEIVED_AUTH_CODE)
client.users.add_contact("example_contact_id")
get_contact_list
Retrieve the Mxit user's full contact list
User authentication required: YES
Required scope: graph/read
Parameters
list_filter options can be found in mxit.CONTACT_LIST_FILTER
. The following options are available: "all", "friends", "apps", "invites", "connections", "rejected", "pending", "deleted", "blocked"
- list_filter (required)
- skip (optional)
- count (optional)
- scope (optional)
Example
from mxit import Mxit, CONTACT_LIST_FILTER
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET, redirect_uri="http://example.org")
client.oauth.get_user_token("graph/read", RECEIVED_AUTH_CODE)
client.users.get_contact_list(CONTACT_LIST_FILTER['all'])
get_friend_suggestions
Retrieve the Mxit user's full profile
User authentication required: YES
Required scope: graph/read
Parameters
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET, redirect_uri="http://example.org")
client.oauth.get_user_token("graph/read", RECEIVED_AUTH_CODE)
client.users.get_friend_suggestions()
get_gallery_folder_list
Retrieve a list of the Mxit user's gallery folders
User authentication required: YES
Required scope: content/read
Parameters
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET, redirect_uri="http://example.org")
client.oauth.get_user_token("content/read", RECEIVED_AUTH_CODE)
client.users.get_gallery_folder_list()
create_gallery_folder
Create a new folder in the Mxit user's gallery
User authentication required: YES
Required scope: content/write
Parameters
- folder_name (required)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET, redirect_uri="http://example.org")
client.oauth.get_user_token("content/write", RECEIVED_AUTH_CODE)
client.users.create_gallery_folder("example folder name")
delete_gallery_folder
Delete a folder in the Mxit user's gallery
User authentication required: YES
Required scope: content/write
Parameters
- folder_name (required)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET, redirect_uri="http://example.org")
client.oauth.get_user_token("content/write", RECEIVED_AUTH_CODE)
client.users.delete_gallery_folder("example folder name")
rename_gallery_folder
Rename a folder in the Mxit user's gallery
User authentication required: YES
Required scope: content/write
Parameters
- old_folder_name (required)
- new_folder_name (required)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET, redirect_uri="http://example.org")
client.oauth.get_user_token("content/write", RECEIVED_AUTH_CODE)
client.users.rename_gallery_folder("old example folder name", "new example folder name")
delete_gallery_file
Delete a file in the Mxit user's gallery
User authentication required: YES
Required scope: content/write
Parameters
- file_id (required)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET, redirect_uri="http://example.org")
client.oauth.get_user_token("content/write", RECEIVED_AUTH_CODE)
client.users.delete_gallery_file("example_file_id")
rename_gallery_file
Rename a file in the Mxit user's gallery
User authentication required: YES
Required scope: content/write
Parameters
- file_id (required)
- new_file_name (required)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET, redirect_uri="http://example.org")
client.oauth.get_user_token("content/write", RECEIVED_AUTH_CODE)
client.users.rename_gallery_file("example_file_id", "new file name")
upload_gallery_file
Upload a file to a folder in the Mxit user's gallery
User authentication required: YES
Required scope: content/write
Parameters
The file can either be sent as a bytestream in data or as a filepath in input_file_path.
- folder_name (required)
- file_name (required)
- data (optional)
- input_file_path (optional)
- prevent_share (optional)
- content_type (optional)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET, redirect_uri="http://example.org")
client.oauth.get_user_token("content/write", RECEIVED_AUTH_CODE)
client.users.upload_gallery_file("example folder name", "example file name", input_file_path="/path/to/image.png", content_type="image/png")
get_gallery_item_list
Get the item listing in a given folder in the Mxit user's gallery
User authentication required: YES
Required scope: content/read
Parameters
- folder_name (required)
- skip (optional)
- count (optional)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET, redirect_uri="http://example.org")
client.oauth.get_user_token("content/read", RECEIVED_AUTH_CODE)
client.users.get_gallery_item_list("example folder name")
get_gallery_file
Get a file in the Mxit user's gallery
User authentication required: YES
Required scope: content/read
Parameters
If output_file_path is set, the file will be saved at that path, otherwise the file data will be returned.
- file_id (required)
- output_file_path (optional)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET, redirect_uri="http://example.org")
client.oauth.get_user_token("content/read", RECEIVED_AUTH_CODE)
client.users.get_gallery_file("example_file_id", output_file_path="/path/to/image.png")
data = client.users.get_avatar("example_file_id")
upload_file_and_send_file_offer
Upload a file of any type to store and return a FileId once file offer has been sent.
User authentication required: NO
Required scope: content/send
Parameters
The file can either be sent as a bytestream in data or as a filepath in input_file_path.
- file_name (required)
- user_id (required)
- data (optional)
- input_file_path (optional)
- auto_open (optional)
- prevent_share (optional)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET)
user_id = client.users.get_user_id("example_mxit_id")
client.users.upload_file_and_send_file_offer("example_file_name", user_id, input_file_path="/path/to/image.png")
send_file_offer
Upload a file of any type to store and return a FileId once file offer has been sent.
User authentication required: NO
Required scope: content/send
Parameters
- file_id (required)
- user_id (required)
- scope (optional)
Example
from mxit import Mxit
client = Mxit(MXIT_CLIENT_ID, MXIT_CLIENT_SECRET)
user_id = client.users.get_user_id("example_mxit_id")
client.users.send_file_offer("example_file_id", user_id)