mig33 TCP/IP Protocol

Devin Smith <devin (at) devinsmith (dot) com>


Table of Contents

1. About mig33
2. Purpose and Scope
3. Introduction
4. TCP/IP Communication between Client and Server
4.1. Client commands
4.2. Server commands
5. Detailed client packet analysis
5.1. The KEEP_ALIVE packet
5.2. The REGISTER packet
5.3. The LOGIN_1 packet
5.4. The LOGIN_RESP packet
5.5. The GET_CLIST packet
5.6. The SEND_MSG packet
6. Detailed server packet analysis
6.1. The ERROR_MESSAGE packet
6.2. The LOGIN_NOTIFY packet
6.3. The LOGIN_BAD_RESP packet
6.4. The REGISTER_OK packet
6.5. The KEEP_ALIVE_RESP packet
6.6. The LOGIN_CHAL packet
6.7. The LOGIN_OK / MOTD packet
6.8. The CLIST_GROUPS packet
6.9. The CLIST_BUDDIES packet
6.10. The CLIST_TERMINATOR packet
6.11. The CLIST_STATUS_CHANGE packet
6.12. The RECV_MSG packet
6.13. The RECV_SYS_MSG packet

1. About mig33

mig33 is an exciting new instant messaging client for cell phones. It was developed for South Africa by Project Goth Pty Ltd., a private Australian company established to deliver consumers with cheaper mobile communication alternatives using the internet. It now currently works in over 200 different countries and has thousands of registered users. More information is available here: mig33 website .

2. Purpose and Scope

The purpose of this specification is to document the protocol so that alternative clients can be created for systems that can not run the original Java MIDlet. This document covers the version of the protocol that works with version 2.04 and higher of the mig33 Java MIDlet. It may or may not cover past versions. As of the last review date this document only covers the chat portion of mig33.

3. Introduction

All communication using the mig33 protocol occurs between client and server. There is no peer to peer communication (at least not with the chat/instant message protocol).

Before any communication can occur between multiple clients, a client must login to the server. The login process takes place as a 3 way challenge - response system. The client first sends information about itself to the server, including its username. The server then sends a challenge asking the client to respond with a hashcode of the clients password concatenated with a randomly generated string from the server. If the client responds successfully, the login process suceeds and the client can officially start chatting.

After logging in the client will have the option of sending private messages, joining chat rooms, and interacting with groups of users as well as individual users. Like IRC channels, mig33 chat rooms offer the ability for users to kick other users. Unlike IRC, it takes a majority of votes to kick a user out of a chat room. Individual clients can be ignored and blocked. A client can also set its "visibility" to other clients.

The mig33 server can be reached by connecting to gateway.mig33.com. The server listens for mig33 data on ports 25, 80, and 9119. In the case of port 80, the mig33 protocol is "embedded" inside HTTP. It is recommended that mobile users avoid using port 80, due to the higher data usage.

Please note that throughout this document, all numbers are in hexadecimal unless stated otherwise. Integers consisting of more than one byte are stored with the most significant byte first, and the least significant byte last. This is often referred to big endian, network byte order. All text strings are preceded by a four byte long TEXT_LEN field, indicating the length of the string.

4. TCP/IP Communication between Client and Server

General structure of a mig33 TCP packet. All packets from both client and server use this structure:

Table 1. Packet structure

LengthContent (if fixed)NameDescription
1 byte02MAGICIdentifies the packet as a mig33 packet.
2 bytesxx xxCOMMAND1High two bytes part of the command code for type of packet.
2 bytesxx xxCOMMAND2Low two bytes part of the command code for type of packet.
4 bytesxx xx xx xxPACK_LENThe length of the payload after this point.
variable PARAMSVarable length data specific to a certain command.

The PARAMS portion of the packet contains a list of block structures. The structure of each block is as follows:

Table 2. Block structure

LengthNameDescription
2 bytesIDThe ID number of the block.
4 bytesLENGTHThe length of the block.
variableCONTENTThe contents of the block.

4.1. Client commands

The following commands are available for the client to send to the server:

Table 3. Client commands

High command bytesLow command bytesNameDescription
00 02 (2)xx xxKEEP_ALIVEThe keep alive packet.
00 64 (100)00 02 (2)REGISTERThe registration packet
00 C8 (200)00 01 (1)LOGIN_1The initial login packet
00 CA (202)00 02 (2)LOGIN_RESPLogin response to challenge packet sent by server.
01 90 (400)00 03 (3)GET_CLISTGet contact list.
01 F4 (500)00 06 (6)SEND_MSGSend a message to an entity (chat room or contact)

Not yet described in detail

Table 4. Undocumented client commands

High command bytesLow command bytesNameDescription
02 BC (700)00 04 (4) Possibly related to list of chat rooms.
02 BF (703)00 05 (5) Chat related. Join room?

4.2. Server commands

The following commands can be sent from the server to the client, either as a response to a client command, or to notify the client of some event.

Table 5. Server commands

High command bytesLow command bytesNameDescription
00 00 (0)00 00 (0)ERROR_MESSAGEA packet that notifies the client of an error.
00 00 (0)00 01 (1)LOGIN_NOTIFYA packet that notifies the client that the server is down, or under going maintanence.
00 00 (0)00 02 (2)LOGIN_BAD_RESPLogin failure message when Client sends a bad LOGIN_RESP packet.
00 01 (1)00 02 (2)REGISTER_OKThe message that the server sends when registration (the REGISTER packet) is successful.
00 03 (3)xx xxKEEP_ALIVE_RESPThe keep alive response packet.
00 C9 (201)00 01 (1)LOGIN_CHALLogin challenge sent from server to client after receiving LOGIN_1 packet.
00 CB (203)00 02 (2)LOGIN_OK / MOTDLogin OK message with message of the day
01 91 (401)00 03 (3)CLIST_GROUPSPacket sent with groups after requesting contact list.
01 92 (402)00 03 (3)CLIST_BUDDIESPacket sent with buddies after requesting contact list.
01 93 (403)00 03 (3)CLIST_TERMINATORPacket sent to tell mig33 that the contact list is sent.
01 94 (404)00 00 (0)CLIST_STATUS_CHANGEPacket sent to tell mig33 that the status of someone on your buddy list has changed.
01 F4 (500)00 00 (0)RECV_MSGReceive a message from an entity. (Chatroom or contact)
01 F6 (502)00 00 (0)RECV_SYS_MSGReceive a system message

5. Detailed client packet analysis

This section goes through the individual packets that the client can send.

5.1. The KEEP_ALIVE packet

The keep alive packet contains no data. The low command bytes contain the sequence number. This sequence number always seems to start at 4. A keep alive packet must be sent every 60 seconds. Each time it is sent the sequence number is increased by one.

5.2. The REGISTER packet

A client must send this packet if they wish to register a new account with mig33.

Table 6. REGISTER contents

LengthContent (if fixed)NameDescription
2 bytes00 04MARK_CELLUsed to mark the beginning of a cellphone telephone number string.
4 bytesxx xx xx xxCELLNUM_LENThe length of a celular phone number (include country code)
variable CELLNUMThe cellphone number without dashes or dots. Example 1-310-555-5554 would be "13105555554"
2 bytes00 03MARK_PASSWORDUsed to mark the beginning of a password string block.
4 bytesxx xx xx xxPASSWORD_LENThe length of the password you wish to use during registration.
variable PASSWORDThe password
2 bytes00 02MARK_USERNAMEUsed to mark the beginning of a username string block
4 bytesxx xx xx xxUSERNAME_LENThe length of the username you are registering.
variable USERNAMEThe username you are registering.
2 bytes00 01X1Unknown. Ending marker?
4 bytes00 00 00 01UNKNOWN_LENUnknown but always 00 00 00 01.
1 byte01X5Unknown. Always 01.

5.3. The LOGIN_1 packet

The initial packet sent to a server.

Table 7. LOGIN_1 contents

LengthContent (if fixed)NameDescription
2 bytes00 09X1Unknown marker.
4 bytes00 00 00 04X2Unknown.
4 bytes00 00 00 01X3Unknown.
2 bytes00 08MARK_PLATThe marker for the platform block of the packet
4 bytesxx xx xx xxTEXT_LEN1The length of the J2ME platform string
variable J2ME_PLATThe J2ME platform. Some examples in the wild:
  • MPP

  • Nokia6300/04.71

  • Unknown

2 bytes00 07MARK_VERSTRINGThe marker for the mig33 version string.
4 bytes00 00 00 09TEXT_LEN29 for the length of "J2MEv2.04" or "J2MEv3.00" or "J2MEv3.02".
9 bytesxx xx xx xx xx xx xx xx xxMIDLET_VERSIONThe bytes of the string "J2MEv2.04" or "J2MEv3.00" or "J2MEv3.02"
2 bytes00 05MARK_USERNAMEThe marker for the username string.
4 bytesxx xx xx xxTEXT_LEN3the length of your username.
variable USERNAMEthe bytes of your username.
2 bytes00 03MARK_VERSIONMarker for the version number as a short.
4 bytes00 00 00 02VERSION_NUM_LENThe length of the version number. sizeof(uint16_t).
2 bytesxx xxVERSION_NUMThe version number in a short. It should be either:
  • 00 CC (204)

  • 01 2C (300)

  • 01 2E (302)

2 bytes00 02X9Unknown.
4 bytes00 00 00 01X10Unknown.
1 bytexxX1101 for version 204, 02 for version 300 and above.
2 bytes00 01X12Unknown
4 bytes00 00 00 02X13Unknown.
2 bytes00 01X14Unknown

5.4. The LOGIN_RESP packet

The login response to challenge packet sent by server.

Table 8. LOGIN_RESP contents

LengthContent (if fixed)NameDescription
2 bytes00 01MARK_HASHCODEA marker used to indicate that this block is for the hash code.
4 bytes00 00 00 04HASHCODE_LENThe length of the hash code
4 bytesxx xx xx xxHASHCODEThe 4 byte calculated hash code of the server's HASH_STRING concatenated with the client's password.

HASHCODE is calclated by taking the server's HASH_STRING, then concatenating it with the client's password (in all lowercase) and running it through a hash code function. The function is the same used from Java's String hashCode() method.

5.5. The GET_CLIST packet

Get contact list. It has no parameters.

5.6. The SEND_MSG packet

This packet is created to send a message to a mig33 entity (either a chat room or contact).

Table 9. SEND_MSG contents

LengthContent (if fixed)NameDescription
2 bytes00 08MARK_MSGA marker to indicate that this block contains the message.
4 bytesxx xx xx xxMSG_LENThe length of the message you are going to send
variable MSGA string containing the message to send
2 bytes00 06X2Unknown.
4 bytes00 00 00 02X3Unknown.
2 bytes00 01X4Unknown.
2 bytes00 04MARK_DESTINATIONA marker to indicate that this block contain the destination entity.
4 bytesxx xx xx xxDESTINATION_LENThe length of the destination's name
variable DESTINATIONThe name of the destination. Either a chat room or mig33 contact
2 bytes00 03X6Unknown
4 bytes00 00 00 01X7Unknown
1 byte03X8Unknown
2 bytes00 02MARK_USERA marker used to indicate that this block contains your username.
4 bytesxx xx xx xxUSER_NAME_LENThe length of your user name.
variable USER_NAMEYour user name
2 bytes00 01X10Unknown.
4 bytes00 00 00 01X11Unknown.
1 byte01X12Unknown.

6. Detailed server packet analysis

This section goes through the individual packets that the server can send.

6.1. The ERROR_MESSAGE packet

The error message packet is sent back to the client to inform the client that an error has occurred.

Table 10. ERROR_MESSAGE contents

LengthContent (if fixed)NameDescription
2 bytes00 02MARK_ERRORA marker to indicate that this block contains an error string.
4 bytesxx xx xx xxERROR_LENThe length of the error string.
variable ERROR_STRINGThe error string.
2 bytes00 01MARK_UNKNOWNUnknown.
4 bytes00 00 00 02UNKNOWN_LENUnknown
2 bytes00 01UNKNOWNUnknown.

6.2. The LOGIN_NOTIFY packet

Login notify message to inform client that server is experiencing difficulties.

Table 11. LOGIN_NOTIFY contents

LengthContent (if fixed)NameDescription
2 bytes00 02X1Unknown marker.
4 bytesxx xx xx xxTEXT_LEN1The length of the notification string.
variable NOTICE_STRINGThe notification string

6.3. The LOGIN_BAD_RESP packet

Login failure message when Client sends a bad LOGIN_RESP packet.

Table 12. LOGIN_BAD_RESP contents

LengthContent (if fixed)NameDescription
2 bytes00 02X1Unknown.
4 bytesxx xx xx xxTEXT_LEN1The length of the error string.
variable ERROR_STRINGA string indicating the error.
2 bytes00 01X2Unknown.
4 bytes00 00 00 02X3Unknown.
2 bytes00 01X4Unknown.

6.4. The REGISTER_OK packet

Registration successful message when client sends a proper REGISTER packet.

Table 13. REGISTER_OK contents

LengthContent (if fixed)NameDescription
2 bytes00 01X1Unknown. Possibly a marker for the welcome message.
4 bytesxx xx xx xxWELCOMEMSG_LENThe length of the welcome message
variable WELCOMEMSGThe welcome message

6.5. The KEEP_ALIVE_RESP packet

The KEEP_ALIVE_RESP packet is sent from the server to the client after the server receives a KEEP_ALIVE packet. This packet contains no data. A sequence number is stored in the low command bytes. It seems to always match the sequence number from the last KEEP_ALIVE packet.

6.6. The LOGIN_CHAL packet

The login challenge packet.

Table 14. LOGIN_CHAL contents

LengthContent (if fixed)NameDescription
2 bytes00 02X1Unknown.
4 bytesxx xx xx xxTEXT_LEN1The length of an unknown string.
variable X2An unknown random string.
2 bytes00 01X1Unknown.
4 bytesxx xx xx xxTEXT_LEN2The length of the hashing string.
variable HASH_STRINGThe bytes of the hashing string.

The HASH_STRING is used in the LOGIN_RESP packet sent by the client to generate a proper hash code.

6.7. The LOGIN_OK / MOTD packet

The login OK message with optional message of the day.

Table 15. LOGIN_OK / MOTD contents

LengthContent (if fixed)NameDescription
2 bytes00 0CBLOCK_EXCHANGE_RATEUsed to mark the exchange rate block. Not in all responses.
4 bytesxx xx xx xxEXCHANGE_RATE_LENThe length of the exchange rate message
variable EXCHANGE_RATEThe exchange rate message
2 bytes00 0BX2Unknown.
4 bytesxx xx xx xxCURRENCY_LENLength of the currency field
variable CURRENCYThe currency. "USD" for US dollars.
2 bytes00 0AX3Unknown.
4 bytesxx xx xx xxUNKNOWN_IP_LENAn IPv4 address
variable IP_ADDRESSAn ip address. (e.g. "202.154.106.233")
2 bytes00 09X4Unknown.
4 bytes00 00 00 04X5Unknown.
4 bytes00 00 00 03X6Unknown.
2 bytes00 08X7Unknown.
4 bytes00 00 00 01X8Unknown.
1 byte00X9Unknown.
2 bytes00 06X10Unknown.
4 bytes00 00 00 01X11Unknown.
1 byte00X12Unknown.
2 bytes00 03X13Unknown.
4 bytesxx xx xx xxMOTD_LENLength of the MOTD string
variable MOTDThe message of the day
2 bytes00 02X14Unknown.
4 bytes00 00 00 01X15Unknown.
2 bytes00X16Unknown.
1 byte00 01X17Unknown.
4 bytesxx xx xx xxMOBILE_NUM_LENThe length of the string containing your mobile number
variable MOBILE_NUMYour mobile number including country code without () or dashes

6.8. The CLIST_GROUPS packet

The packet sent after the client requests the contact list. This packet contains the groups on the contact list. Each group is sent in a different packet.

Table 16. CLIST_GROUPS contents

LengthContent (if fixed)NameDescription
2 bytes00 02MARK_GROUPNAMEA marker that indicates this block contains the name of the group.
4 bytesxx xx xx xxGROUPNAME_LENThe length of the name of the group
variable GROUPNAMEThe name of the group. (e.g. "mig33 Contacts")
2 bytes00 01MARK_IDA marker for an unknown block.
4 bytes00 00 00 04ID_LENSeems to always be 4.
4 bytesxx xx xx xxIDAn ID number for this group.

The ID number is used when you get the buddies in the contact list. In block 4 of the contact packet, the ID code will tell you which group a buddy belongs to.

6.9. The CLIST_BUDDIES packet

The packet sent after the client requests the contact list. This packet contains the buddies on the contact list. Each buddy is sent in a different packet.

Table 17. CLIST_BUDDIES contents

LengthContent (if fixed)NameDescription
2 bytes00 19MARK_UNKNOWNA marker for an unknown block.
4 bytes00 00 00 01UNKNOWN_LENThe length for some unknown data. Possibly a flag.
1 byte00UNKNOWNAn unknown piece of data. Seems to always be 0?
2 bytes00 03MARK_USERNAMEA marker for the username
4 bytesxx xx xx xxUSERNAME_LENThe length of the username
variable USERNAMEThe username.
2 bytes00 0DMARK_STATUSA marker used to indicate a buddy's status.
4 bytes00 00 00 01STATUS_LENThe length of the status byte.
1 bytexxSTATUSStatus. 0x63 = "Offline", 0x01 = "Online".
2 bytes00 02MARK_GROUP_IDA marker used to indicate which group a buddy is in.
4 bytes00 00 00 04GROUP_ID_LENThe length of the GROUP_ID.
4 bytesxx xx xx xxGROUP_IDThe group ID that this buddy belongs to.
2 bytes00 0CMARK_BUDDY_NAMEA marker used ot indicate the buddies name again.
4 bytesxx xx xx xxBUDDY_NAME_LENThe length of the buddies name.
variable BUDDY_NAMEThe buddy's name.
2 bytes00 01MARK_BUDDY_IDA marker for the buddy ID.
4 bytes00 00 00 04BUDDY_ID_LENThe length of the buddy ID.
4 bytesxx xx xx xxBUDDY_IDThe Buddy ID.

6.10. The CLIST_TERMINATOR packet

The contact list terminator. It has no parameters.

6.11. The CLIST_STATUS_CHANGE packet

The packet sent to notify a client that a buddy's status has changed.

Table 18. CLIST_STATUS_CHANGE contents

LengthContent (if fixed)NameDescription
2 bytes00 02MARK_STATUSA marker that indicates this block contains the status number.
4 bytes00 00 00 01STATUS_LENThe length of the status byte.
1 bytexxSTATUSThe users status. 0x63 = Offline, 0x01 = Online.
2 bytes00 01MARK_BUDDY_IDA marker to indicate the buddy id.
4 bytes00 00 00 04BUDDY_ID_LENThe length of the buddy ID.
4 bytesxx xx xx xxBUDDY_IDThe buddy id who's status has changed.

6.12. The RECV_MSG packet

The packet sent to notify a client that another user sent a message to a chat room or mig33 contact.

Table 19. RECV_MSG contents

LengthContent (if fixed)NameDescription
2 bytes00 08MARK_MSGA marker that indicates this block is the chat message.
4 bytesxx xx xx xxMSG_LENLength of the chat message.
variable MSGThe bytes that make up the chat message.
2 bytes00 06MARK_X1A marker for an unknown block.
4 bytes00 00 00 02X2_LENAn unknown length
2 bytes00 01X3An unknown piece of data.
2 bytes00 04MARK_DESTINATIONA marker for the destination string.
4 bytesxx xx xx xxDESTINATION_LENLength of the string containing the destination.
variable DESTINATIONThe name of the destination. Can be either a chatroom or a user's name.
2 bytes00 03MARK_X4A marker for an unknown block.
4 bytes00 00 00 01X5_LENAn unknown length
1 bytexxX6Unknown. Can be 03 or 01. This may be an indication of whether the message is to a chat room or to a user.
2 bytes00 02MARK_USERA marker for the user who sent the message.
4 bytesxx xx xx xxUSER_LENThe lenght of the username
variable USERThe username that sent the message.
2 bytes00 01MARK_X7An unknown marker.
4 bytes00 00 00 01X8_LENAn unknown length
1 byte01X9Unknown.

6.13. The RECV_SYS_MSG packet

This packet is sent to the client when the server needs to inform the client about some event.

Table 20. RECV_SYS_MSG contents

LengthContent (if fixed)NameDescription
2 bytes00 05MARK_DATAA marker that indicates this block contains the data of the system message.
4 bytesxx xx xx xxDATA_LENLength of the data message.
variable DATAThe bytes that make up the data. Could be a URL.
2 bytes00 04MARK_DESCA marker that indicates this block contains a description of the data in the system mesage.
4 bytesxx xx xx xxDESC_LENLength of the description.
variable DESCThe bytes that make up the decription.
2 bytes00 02MARK_INVOKERA marker that indicates this block contains the invoker of the system message.
4 bytesxx xx xx xxINVOKER_LENLength of the invoker's nick.
variable INVOKERThe bytes that make up the invoker's name
2 bytes00 01MARK_UNKNOWNAn unknown block of data.
4 bytes00 00 00 01UNKNOWN_LENAn unknown length. Seems to always be 1 byte.
1 byte01UnknownSeems to always be 01.

This document was generated on 2007-10-06-07:00 02:21:00-07:00 with DocBook XSL Stylesheets version 1.72.0.