This article is focused on Mobi Portals, and will not be useful if you are using the .NET SDK.
Keep a record of your users
One of the biggest mistakes that people make when building a Mxit application for the first time is not keeping a record of their users.
You will need to keep a record of the userid of each of your users in order to send in-app broadcast messages to your users with the Messaging API. Ensure that you read the Mxit API Terms before you start working with user data, to ensure that you are not in violation of the terms.
The userid is available from HTTP_X_MXIT_USERID_R variable in the server headers, for example in PHP:
You can use whichever database you prefer to store the userid of your users. I generally prefer using MongoDB.
Formatting your message
The Mxit Messaging API supports Mxit Markup. If you make use of Mxit Markup, you must set the ContainsMarkup field to true in the API call.
If you are using the Messaging API for in-app broadcasts, I strongly recommend using Mxit Markup to add a link to the end of your message, for example:
$Click here for menu$
Without the link, most of your users will have trouble getting back to your application unless they are aware of the shortcut commands (.hm/.home/.bk/.back/etc).
You can use newline characters within your message, but depending on the language you are developing your application in, you might need to escape the new line characters.
You can also use emoticons within your message, but will need to escape any Mxit Markup contained within those emoticons.
For example, in PHP (new lines don’t need to be escaped):
1 2 3 4 5
Notice that the asterisks in the first line of the message are escaped. The reason for this is because the asterisk is used in Mxit Markup, and is translated to Mxit Markup unless it is escaped.
Broadcasting to your users
Once you have recorded the userid of your users, you will be able to send your message to your users.
Although you have stored the the userid of your users, some users might remove your application, but currently Mxit don’t provide a tool for developers to determine which users have removed their application. Your message will only be delivered to the users who still have your application as a contact. The users who have removed your application will not receive the message.
You will need to split your broadcast into batches because the Mxit Messaging API only supports sending to a maximum of 500 users at a time. I generally split my broadcasts into batches of 50 users and thus broadcast to 50 users at a time.
The Client Id and Client Secret from your Mobi Portal Dashboard are required for sending messages using the Mxit Messaging API.
I have written a PHP Wrapper for the Mxit Messaging and User APIs, which is used in the following example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
Its a good idea to follow the Mxit “Rules of the Road” for Messaging which state:
Our API gives you the ability to push messages to your application’s users.
Don't use this to spam your users – they will probably remove your
application, or stop paying attention to your messages.