MXit EVO Agent

Tutorial & Howto Use Guide

What is this?
This new MXit service is intended for website owners who wish to give their visitors an easy and quick way to communicate back to them. This can be achieved by the website owner by just adding a small piece of JavaScript to their website. This JavaScript widget will show your visitors when you are online and available for chatting, and also allow them to chat with you in real time.

Why do I need this?
Well for the following reasons of course:
  • Get feedback from your website visitors in real-time
  • Provide your website visitors with a simpler and faster support channel
  • It is absolutely free-of-charge!
  • You can stay connected to your website from anywhere by using the MXit client. MXit is supported on the PC (Windows, Linux), and most mobile phones (Java-ME based, iPhone, Blackberry, Android)
  • The web widget is very light-weight and cross-platform and cross-browser compatible
  • The web widget is also very customisable with CSS styling and self-provided images

How does it work?
Basically all the work required will be handled by MXit for you. When a visitor visits your website, the small embedded widget on your website will query MXit to determine if you are available for chatting or not. The widget will then show the visitor your presense state as either online/offline/unavailable (more detail in Step 3). Then again when you are online and one of your website visitors starts to chat with you, he will then appear as a new temporary contact in your MXit client. He will then chat to you through a web page sitting on a MXit server and you will again use the MXit client to chat back to him. This makes staying connected to your website very easy because there is a MXit client for most desktop environments and mobile phones.

How do I get it?
You will need to complete the following 5 pretty straight forward steps to enable this service on their website:
  • Step 1: Register with MXit (free registration)
  • Step 2: Add the evoagent service to your MXit account
  • Step 3: Create your presence images
  • Step 4: Add the JavaScript code snippet to your website
  • Step 5: Configure your EVO Agent widget
I will now run through each of the required steps below in a little more detail.

Step 1: MXit Account

You will require a MXit account to use this service. If you already have a MXit account you can skip this step and go directly to Step 2. Otherwise, don't worry, registration is quick and absolutely free-of-charge. (In short MXit is an international instant messanger.) So firstly you will need to download a MXit client. You will also be able to register a new account with any one of the many options of clients available. Here is a quick list:

Get a MXit Client Application:

Windows: You can either use MXit's own PC client called EVO which is a .net (3.5) application or Pidgin which is a cross-platform open-source IM client.
Linux: Download and install Pidgin. There is a very good step-by-step installation guide for creating a MXit account on Pidgin.
Java-ME based Mobile Phone: With your WAP enabled mobile phone, go to the address
iPhone: Search for MXit in the App Store on the phone.
Blackberry: With your blackberry mobile phone go to the address
Android: Search for MXit in the Market on the phone.
Web: MXit can also be installed on a website as a Silverlight widget. The downside to this is it is a little bulky and requires Microsoft .Net and Silverlight frameworks. You can find more information here:

For a full list of supported clients please visit their website
Don't worry, which ever client you choose, registration is very quick and easy and you will be up and running in no time. So download the most appropriate client for you and register an account. You can also use a multiple clients, depending on where you are at the time (very useful).

Step 2: Add the EVO Agent service

Once you have downloaded a MXit client, and have a registered account with them, you need to add the EVO Agent service. To complete this you will need to add a new MXit service contact with the name evoagent. The alias (nickname) you can set to EVO Agent. You can change the alias to whatever you wish, but do not change the contact name, because otherwise it will not work. After adding the service, it should now appear in your contact list. Now chat with this newly added contact, and press 3 (the Show Token option). This will show you the uniquely generated token which you will need in Step 5, so you need to copy and paste this token or write it down somewhere.

Step 3: Create your presence images

The widget requires 3 images, one for each of the 3 presence states you as the agent can be in. Here is a quick explaination of the 3 states:
online badge example
This state means that you are currently logged into MXit and available for chatting. So it will be a good idea to show the visitor with this image that they can click on the image if they wish to chat with you.
unavailable badge example
This state means that you are currently logged into MXit but unavailable for chatting. Your state will be unavailable (or busy) when you have temporarily disabled this service, or if you changed your presence state within the MXit client to either Busy or Away. Another reason for this state is when you have reached your configured amount of maximum concurrent chat sessions. (You can update some settings by chatting to the EVO Agent service as was shown in Step 2.)
But if you only wish to show yourself as online or offline and ignore this middle state, you can just use the same image in the configuration for both the offline and unavailable states. No, its not a hack. :-)
offline badge example
Obviously this state means that you are not currently logged into MXit and that you are unavailable at the present moment. So create an image that will show the visitor that you are currently offline and cannot chat.

After you have created these 3 images, you will need to save them onto your website server.

Step 4: Add the widget to your website

For the presense images to appear on your website to show your visitors if your online and available to chat with them, you will need to add a widget to your website pages. The widget is just a light-weight piece of JavaScript which will just check if your available to chatting and then display the correct badge. It will also generate the correct link for your website visitor to follow if they want to chat to you. So just copy the following JavaScript code and paste it into your webpage or website template.

JavaScript which should be embedded on your website:
<!-- EVO Agent Widget: start -->
<script src="" type="text/javascript"> </script>
<script type="text/javascript">
    mxit_name = 'Your Name';
    mxit_ref = 'my-website';
    mxit_online_badge = '/images/online_badge.png';
    mxit_unavailable_badge = '/images/unavailable_badge.png';
    mxit_offline_badge = '/images/offline_badge.png';
<!-- EVO Agent Widget: end -->

Now you might wonder were is the best place to put this code snippet on your webpage right. Well the best place to put it is actually there where you want it to be displayed on the page. But you will see in Step 7 when we look at customisation that you can manipilate the whole widget's look and feel by using CSS (style sheets). So just hold on a little longer.

Step 5: Configure the EVO Agent widget

Now that you have the widget on your webpage, you will need to configure it. All the underlined fields in the above code snippet are configurable and must be updated by you. Here is the list of all the configurable variables and their respective meanings:

token: This is the unique token generated by the evoagent service. So you need to replace the XXX with the token you copied in Step 2.
mxit_name: This is the display name you wish to show your visitors when they are chatting with you. So if it is your personal blog, use your real name here, or if this widget will be running on your company website then use your company name.
mxit_ref: This is just a string which will be shown to you as a reference for when a visitor chats with you. Its purpose is to help you identify from where the chat originated from. So you can use the website's domain name here, or the page name, but don't make it too long because it will also be used as the temporary contact's name in your contact list.
mxit_online_badge: This is the location (path + filename) of the image for the online presence you created in Step 3.
mxit_unavailable_badge: This is the location (path + filename) of the image for the unavailable presence you created in Step 3. Alternatively you could also just use the same image here as the offline presence because in both states visitors will not be able to chat with you so in theory its as good as if you were offline anyway.
mxit_offline_badge: This is the location (path + filename) of the image for the offline presence you created in Step 3.

Remember to upload your modified webpage to your website server. Well done, your EVO Agent web widget should now be fully functional! Don't worry yet about the look and feel as we will get to customisation and styling in Step 7.

Step 6: Testing your EVO Agent widget (optional but advisable)

Its a good idea to make sure that you have configured it correctly before your visitors find error messages on your website. So open the webpage where you have added the widget to in Step 4 within your favorite web browser, and then see if it shows you one of the images you created in Step 3. If not there's most probably a problem somewhere. The following is a list of the most common errors and how to fix them:

Error Possible Cause
You see the error message: Invalid Token It means that the token you configured within your widget in Step 5 is incorrect. You will need to double check the token again which was generated for you by the EVO Agent service in Step 2. The tokens must be exactly the same or it will not work.
Any other type of error message. Just double check the JavaScript code snippet you copied and pasted in Step 4. Make sure you only updated the values which are actually underlined, and that all the quotes are still intact as shown.
No error message, but also no image. Ensure that the presence image files you created in Step 3 is accessable on your webserver and properly configured in Step 5.

Remember to test both online and offline states. Thus first log into MXit and refresh your webpage. Make sure that you see the online presence image. Log out of MXit, and refresh your webpage again. Now make sure that you see the offline presence image. If you saw both images then congratulations, you have suceessfully configured the EVO Agent widget!

Step 7: Customising your EVO Agent widget (optional)

MXit already put the widget in its own CSS classes to make it easy for you to customise the look and feel of the widget. Here is the CSS code you can add to your website to customise your widget.

CSS styling classes used by the EVO Agent widget
<style type="text/css">
    #mxit_widget_container {
    .mxit_status_online {
    .mxit_status_offline {
    .mxit_status_unavailable {

The most important class here is the mxit_widget_container one which is the main CSS class used by the widget. All output generated by the widget will be put inside this container. So you can only customise this one class if you wish. But for more control I also show you the other classes, one for each of the 3 presence states you can be in at any time. This step is really not nessacery but it could give you the power to do magic with the look and feel of the widget. Unfortunately CSS is beyond the scope of this tutorial, but try to google for some good examples!


Personally I give MXit five out of five stars for giving their users this very useful and free service. I can see that it will become a big hit with webites worldwide. Adding a live chat widget to your website makes your site just so much more dynamic and cutting-edge. Also it gives your website a more personal touch, because your visitors can see that you are actually online and in a funny kind of way there with them. It also provides your visitors a quick and easy method for giving you their feedback, comments and ideas around your content, or to ask you questions around it.


-- Comments disabled temporarily due to excessive spamming --