Ashley Kleynhans

Improving Mxit Engagement With the Messaging API

Introduction

This is a follow-on from my previous post Mxit Monetisation, and focuses on improving user engagement in your Mxit applications by using the Mxit Messaging API.

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:

$_SERVER['HTTP_X_MXIT_USERID_R']

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):

Example Message
1
2
3
4
5
$message = "(\*) Congratulations to our winners (\*)\n\n";
$message .= "1st place - Michael with 100 points\n";
$message .= "2nd place - Sipho with 50 points\n";
$message .= "3nd place - Carla with 25 points\n\n";
$message .= 'Good Luck! :) $Click here$';

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

(announcement.php) download
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
<?php
/* Require the PHP wrapper for the Mxit API */
require_once ('MxitAPI.php');

/* Function to count the number of users in MongoDB */
function count_users() {
    $mongo = new Mongo('127.0.0.1');
    $collection = $mongo->sampleapp->users;
    $collection->ensureIndex(array('uid' => 1));

    return $collection->count();
}

/* Function to get batches of users from MongoDB */
function get_users($skip=0, $limit=50) {
    $mongo = new Mongo('127.0.0.1');
    $collection = $mongo->sampleapp->users;

    $collection->ensureIndex(array('mxitid'     => 1,
                                   'created_at' => 1));

    $users = $collection->find()->sort(array('created_at' => 1))->skip($skip)->limit($limit);

    return iterator_to_array($users);
}

/* Instantiate the Mxit API */
$api = new MxitAPI($key, $secret);

/* Set up the message */
$message = "(\*) Congratulations to our winners (\*)\n\n";
$message .= "1st place - Michael with 100 points\n";
$message .= "2nd place - Sipho with 50 points\n";
$message .= "3nd place - Carla with 25 points\n\n";
$message .= 'Good Luck! :) $Click here$';

/* Mxit Markup is included in the message, so set ContainsMarkup to true */
$contains_markup = 'true';

/* Count the number of users in the database */
$count = count_users();

/* Initialise the variable that counts how many messages have been sent */
$sent = 0;

/* Keep looping through the user list, until the number of messages sent equals the number of users */
while ($sent < $count) {
    /* Get users in batches of 50 */
    $users = get_users($sent, 50);

    /* The list where the user MxitIDs will be stored */
    $list = array();

    foreach ($users as $user) {
        $list[] = $user['mxitid'];
        $sent++;
    }

    /* If there is a problem getting an access token, retry */
    $access_token = NULL;
    while (is_null($access_token)) {
        /* We are sending a message so request access to the message/send scope */
        $api->get_app_token('message/send');
        $token = $api->get_token();
        $access_token = $token['access_token'];

        // Only attempt to send a message if we have a valid auth token
        if (!is_null($access_token)) {
            $users = implode(',', $list);
            echo "\n$sent: $users\n";

            $api->send_message($app, $users, $message, $contains_markup);
        }
    }
}

echo "\n\nBroadcast to $sent users\n\n";

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.

Comments