Since March 10, 2003 - Version 2.1

MSN Messenger Protocol

Client - Invitations

What are invitations?

MSN Messenger includes a mechanism to allow one client to invite another into an out-of-band session. We've seen invitations to Remote Assistance, NetMeeting, file transfer, and many other things. For some reason, Microsoft chose to make the file transfer mechanism subtly incompatible with all other invitation-types. They're explained in separate parts of this page, and I advise you to implement them in separate parts of your program.

Unique identifiers

A unique identifier is a string uniquely identifying some resource. It must be safe to assume that the same identifier will never be generated twice. Under Windows, there are standard functions to create Globally Unique IDentifiers (GUIDs), which have a strictly defined pattern. However, identifiers needn't resemble GUIDs - any string is acceptable, and matching is case-insensitive. If you're not using Windows, you can generate an identifier from a combination of the current time, the MAC address of the computer's network card, a random number, and the process ID of your program.

File Transfer

File transfer negotiation was first seen in version 3 of the official client, and has been upgraded in version 5 to better handle computers which have problems receiving incoming TCP connections (such as those behind NAT firewalls). The file transfer protocol itself is documented here.

Overview

Alice wants to send a file to Bob, so she sends an invitation to him. This invitation must give a filename and size. If Alice is unable to receive incoming connections, the invitation should mention the lack of connectivity.

Bob replies with a message either accepting or cancelling the file. If he declines, his reply must give a reason (e.g. file rejected). If he accepts, and Alice's invitation stated that she cannot receive incoming connections, he should offer to act as the server in the file transfer. Otherwise, he should simply accept her invitation.

If Bob offered to act as the server, the negotiation is complete. Otherwise, Alice must send a reply accepting Bob's message and offer to act as the server.

The negotiation is now complete. If the file transfer fails, a time-out message may follow.

The message in which the offer to act as the server is made must give an IP address and port, and may give a local IP address and port. If Bob is acting as the server, he must specify that Alice (the sender) is to connect to Bob (the receiver).

Sending Invitation Messages

Each invitation message is sent through a switchboard session as a MSG with MIME-Version: 1.0 and a content-type of text/x-msmsgsinvite; charset=UTF-8. The body of an invitation message is a set of fields. As usual, fields may be sent in any order, and any unrecognised fields must be ignored. The complete set of fields is given below. Fields marked "required" must be sent. Fields marked "optional" may be sent, but the receiver should be prepared to cope with messages that don't include them. In file transfer, the client may ignore all optional fields - versions of the official client below 5.0 always ignore optional fields, versions 5.0 and above never do. The exception to this is that if you send a "Connectivity" field, you must handle the "Sender-Connect" field if it is sent in the reply.

The official client will only negotiate in switchboard sessions with exactly two people in them, so if inviter and invitee don't share such a session, the client sending the invitation must first create one. It is not necessary to reply to an invitation in the same session which it was sent. For example, if Alice and Bob are in a switchboard, Alice sends an invitation to Bob, then Carol enters the switchboard, Bob must send his reply in a different switchboard session.

Protocol

Each message contains one "invitation command". The sequence in which commands must be sent is:

The inviter sends an INVITE command
the invitee ACCEPTs the invitation
If the invitee did not offer to serve, the inviter ACCEPTs
Either client may then send a CANCEL command with a cancel code of FTTIMEOUT, if there is a problem during transfer. For example, the official client will listen for an incoming connection for 30 seconds, then cancel the offer.

Either party can send a CANCEL command at any time after the first message is sent. No further messages should be sent after this.

Common Fields

All messages in a negotiation include the following fields:

Invitation-Command (required): The type of message being sent. See the protocol section, above for valid invitation commands.
Invitation-Cookie (required): A random integer between 1 and 2^32 - 1, uniquely identifying a negotiation (note that a cookie of 0 is invalid). This value is decided by the sender of the INVITE, and must remain constant throughout a negotiation

INVITE Fields

INVITE commands include the following fields:

Application-Name (required): A natural-language description of the class. This can vary - for example, the official client calls the file transfer class File Transfer in English, Filoverføring in Norwegian, and ファイル送信 in Japanese. This should only be used to describe a class to the user - for example, if the Application-GUID isn't recognised
Application-GUID (required): The unique identifier of the class. A class always has the same GUID, and no two classes ever have the same GUID. Strictly speaking, that makes it a CLSID (a GUID used to identify a class). The GUID for file transfer is "{5D3E02AB-6190-11d3-BBBB-00C04F795683}", and for some reason, the official client checks this case-sensitively.
Application-File (required): The name of the file to be sent
Application-FileSize (required): The size in bytes of the file to be sent. If this size differs from the size given during the file transfer session, that value takes priority
Connectivity (optional): If the client knows it cannot receive incoming connections, it should send this with a value of 'N'. The official client decides this based on the initial profile, but you could just as well ask the user if you prefer.

CANCEL Fields

Only one field is required by CANCEL commands - Cancel-Code. This is a short reason for cancellation. You should treat this as a free-form string, but the general-purpose codes which have been encountered in the official client are:

FAIL: The receiving client does not know any of the specified Session-protocols
FTTIMEOUT: There was an error transferring the file itself
OUTBANDCANCEL: The switchboard window in which the INVITE message was sent is closing
REJECT: The principal has declined the invitation
REJECT_NOT_INSTALLED: The client does not support that application GUID
TIMEOUT: The client sending an INVITE has got bored of waiting for your ACCEPT (or the principal has cancelled the request)

ACCEPT Fields

The following field exists in all ACCEPT commands:

Launch-Application (required): Instructs the other client (not) to launch an external application. Since file transfer is handled internally by the official client, this is normally "FALSE". I don't know under what condition you would set this to "TRUE"

The ACCEPT command with the offer to serve includes these fields:

IP-Address (required): The primary IP address for the client to connect to. The official client gets the address of your network's Internet gateway from the initial profile.
IP-Address-Internal (optional): The secondary IP address for the client to connect to (if the primary address failed). Recent versions of the official client put the address of your network card here.
Port (required): The primary TCP port your server is listening on. This should be 6891. Some versions of the official client will misbehave if you use a different address. This field is the counterpart to "IP-Address".
PortX (optional): The secondary TCP port your server is listening on. This should be 11178. Some versions of the official client will misbehave if you use a different address. This field is the counterpart to "IP-Address-Internal", so include this field if and only if you include that one.
PortX-Internal (optional): If included, this field must be equal to "PortX". This is probably a work-around for older versions of the official client
AuthCookie (required): A random integer between 1 and 2^32 - 1, used in the file transfer session to uniquely identify the file being sent (in case two files are being sent at once)
Sender-Connect (optional): Normally, the computer receiving the file initiates a connection to the sender. If the sender should connect to the receiver (e.g. if the sender is behind a firewall), this is sent with a value of "TRUE"

Example Invitations

Here is an example of a successful file transfer invitation between two clients which support the upgraded invitation method.

>>> MSG 12 N 294 MIME-Version: 1.0 Content-Type: text/x-msmsgsinvite; charset=UTF-8 Application-Name: File Transfer Application-GUID: {5D3E02AB-6190-11d3-BBBB-00C04F795683} Invitation-Command: INVITE Invitation-Cookie: 85366 Application-File: Autoexec.bat Application-FileSize: 187 Connectivity: N

<<< MSG bob@hotmail.com Bob 306 MIME-Version: 1.0 Content-Type: text/x-msmsgsinvite; charset=UTF-8 IP-Address: 81.99.77.64 IP-Address-Internal: 10.5.1.3 Port: 6891 PortX: 11178 AuthCookie: 544120 Sender-Connect: TRUE Invitation-Command: ACCEPT Invitation-Cookie: 227948 Launch-Application: FALSE Request-Data: IP-Address:

Here is an example of a successful file transfer invitation between two clients which do not support the upgraded invitation method. However, there was a problem in the transfer itself.

>>> MSG 4 N 277 MIME-Version: 1.0 Content-Type: text/x-msmsgsinvite; charset=UTF-8 Application-Name: File Transfer Application-GUID: {5D3E02AB-6190-11d3-BBBB-00C04F795683} Invitation-Command: INVITE Invitation-Cookie: 33267 Application-File: readme.txt Application-FileSize: 60904

<<< MSG example@passport.com Tim 179 MIME-Version: 1.0 Content-Type: text/x-msmsgsinvite; charset=UTF-8 Invitation-Command: ACCEPT Invitation-Cookie: 33267 Launch-Application: FALSE Request-Data: IP-Address:

>>> MSG 4 N 238 MIME-Version: 1.0 Content-Type: text/x-msmsgsinvite; charset=UTF-8 Invitation-Command: ACCEPT Invitation-Cookie: 33267 IP-Address: 10.44.102.65 Port: 6891 AuthCookie: 93301 Launch-Application: FALSE Request-Data: IP-Address:

>>> MSG 4 N 151 MIME-Version: 1.0 Content-Type: text/x-msmsgsinvite; charset=UTF-8 Invitation-Command: CANCEL Invitation-Cookie: 85366 Cancel-Code: FTTIMEOUT

Other Invitation Types

This section discusses the general invitation mechanism used by everything except file transfer. The official client allows 3rd party programs to register themselves as invitation types (for example, the game "MechWarrior Mercenaries" does this). If you are writing an application and want the official client to support your invitation type, check out MSDN's Messenger API documentation.

Overview

Alice wants to negotiate a session with Bob, so she sends an invitation to him. This invitation must describe the invitation type (e.g. voice conversation) and may include application-specific information Bob will need to know (e.g. the voice conversation protocols supported by Alice's computer).

Bob replies with a message either accepting or cancelling the invitation. If he accepts, his reply must contain his IP address, must request Alice's IP address, and may include information which Alice will require (e.g. his chosen voice conversation protocol). If he declines, his reply must give a reason (e.g. voice transfer not supported).

Alice accepts Bob's reply, and sends a message to that effect. Her reply must contain her IP address.

Depending on the invitation-type, Bob may send a final message with some contextual information.

The negotiation is now complete.

Sending Invitation Messages

Each invitation message is sent through a switchboard session as a MSG with MIME-Version: 1.0 and a content-type of text/x-msmsgsinvite; charset=UTF-8. The body of an invitation message is a set of fields. As usual, fields may be sent in any order, and any unrecognised fields must be ignored. The complete set of fields is given below. Fields marked "required" must be sent. Fields marked "optional" may be sent, but the receiver should be prepared to cope with messages that don't include them. Unlike in file transfer, the client must handle optional fields if they are sent.

The official client will only negotiate in switchboard sessions with exactly two people in them, so if inviter and invitee don't share a private session, the client sending the invitation must first create one. It is not necessary to reply to an invitation in the same session which it was sent. For example, if Alice and Bob are in a switchboard, Alice sends an invitation to Bob, then Carol enters the switchboard, Bob must send his reply in a different switchboard session.

If you wish to invite two people to the same session, you should send two separate invitations.

Protocol

Each message contains one "invitation command". The sequence in which commands must be sent is:

The inviter sends an INVITE command
the invitee ACCEPTs the invitation
The inviter opens a socket to listen for a connection, then ACCEPTs.
The inviter then sends some Context. (only in some invitation-types)

Either party can send a CANCEL command at any time after the first message is sent. No further messages can be sent after this.

Common Fields

All messages in an invitation include the following fields:

Invitation-Command: The type of message being sent. See the protocol section, above for valid invitation commands.
Invitation-Cookie: An integer between 1 and 2^32 - 1, uniquely identifying a negotiation (note that a 0 is an invalid cookie). This value is decided by the sender of the INVITE, and must remain constant throughout a negotiation. The official client selects cookies at random.
Session-ID: A unique identifier for the current MSN Messenger client. This identifies a particular instance of a particular client - each client should generate a new session ID every time it starts, and use the same ID until the program is finished. If the client logs out, then back in again, it should continue using the same session ID.

INVITE Fields

The INVITE command includes the following fields:

Application-Name: A natural-language description of the class. This can vary - for example, the official client calls the file transfer class File Transfer in English, Filoverføring in Norwegian, and ファイル送信 in Japanese. This should be used to describe a class to the user - for example, if the Application-GUID isn't recognised.
Application-GUID: The unique identifier of the class. Despite the name, this can be any identifier, as discussed above. A class always has the same Application-GUID, and no two classes ever have the same GUID. Strictly speaking, that make it a CLSID (a GUID used to identify a class). Unlike with file transfers, this GUID is checked case-insensitively.
Application-URL (optional): A URL with information about downloading the specified application. An application always has the same Application-URL. If the Application-GUID isn't recognised, the client may suggest the user visit the URL. Note: do not automatically load the URL, as an attacker could easily use this force you to load a page which exploits a bug in your web browser.
Session-Protocol: Session protocol(s) supported by sending the client. The official client only supports SM1.
Context-Data (optional): A string used for an application-specific purpose (e.g. negotiating details of the protocol to use)

CANCEL Fields

Only one extra field is required by CANCEL commands - Cancel-Code. This is a short reason for cancellation. You should treat this as a free-form string, but the values supported by the official client are:

FAIL: The receiving client cannot parse an invitation message you sent it (e.g. because it doesn't recognise any of the specified session protocols).
OUTBANDCANCEL: The switchboard window in which the INVITE message was sent is closing.
REJECT: The principal has declined the invitation
REJECT_NOT_INSTALLED: The client does not support that application GUID.
TIMEOUT: The client has got bored of waiting for your reply (or the principal has cancelled the invitation).

First ACCEPT Fields

The first ACCEPT command includes these fields:

Session-Protocol: Selected session protocol (taken from the list given in the INVITE message). If there are no acceptable protocols, the invitation is cancelled with a cancel-code of FAIL.
Context-Data (optional): A string used for an application-specific purpose (e.g. negotiating details of the protocol to use)
Launch-Application: Instructs the other client (not) to launch an external application. Normally "TRUE". I don't know under what condition you would set this to "FALSE".
Request-Data: The value of this field must be "IP-Address:". Requests that the other client send its IP address.
IP-Address: The IP address (and optionally port number) of the computer which will act as client.

Second ACCEPT Fields

The second ACCEPT command includes these fields:

Launch-Application: Instructs the other client (not) to launch an external application. Normally "TRUE". I don't know under what condition you would set this to "FALSE".
IP-Address: The IP address (and optionally port number) of the computer which will act as server.

Context Fields

The Context command includes these fields:

Context-Data: A string used for an application-specific purpose (e.g. negotiating details of the protocol to use)

Example Invitations

Here is an example of a successful voice conversation invitation, from the point-of-view of the invitee.

>>> MSG bob@hotmail.com Bob 353\r\n MIME-Version: 1.0\r\n Content-Type: text/x-msmsgsinvite; charset=UTF-8\r\n \r\n Application-Name: voice conversation\r\n Application-GUID: {02D3C01F-BF30-4825-A83A-DE7AF41648AA}\r\n Session-Protocol: SM1\r\n Context-Data: Requested:SIP_A,;Capabilities:SIP_A,;\r\n Invitation-Command: INVITE\r\n Invitation-Cookie: 1578608\r\n Session-ID: {CD482FDC-AE24-3574-C2A5-493813AD94D1}\r\n \r\n

<<< MSG 16 N 319\r\n MIME-Version: 1.0\r\n Content-Type: text/x-msmsgsinvite; charset=UTF-8\r\n \r\n Invitation-Command: ACCEPT\r\n Context-Data: Requested:SIP_A,;\r\n Invitation-Cookie: 1578608\r\n Session-ID: {A8B34C0E-2EEF-932F-F120-F7492E39CDA9}\r\n Session-Protocol: SM1\r\n Launch-Application: TRUE\r\n Request-Data: IP-Address:\r\n IP-Address: 203.122.147.102\r\n \r\n

>>> MSG bob@hotmail.com Bob 242\r\n MIME-Version: 1.0\r\n Content-Type: text/x-msmsgsinvite; charset=UTF-8\r\n \r\n Invitation-Command: ACCEPT\r\n Invitation-Cookie: 1578608\r\n Session-ID: {CD482FDC-AE24-3574-C2A5-493813AD94D1}\r\n Launch-Application: TRUE\r\n IP-Address: 203.122.147.102:13455\r\n \r\n

<o> Connect to 203.122.147.102:13455 . . .\r\n

Here is an example of a voice conversation invitation which failed because the invitee did not have voice conversation installed:

>>> MSG bob@hotmail.com Bob 353\r\n MIME-Version: 1.0\r\n Content-Type: text/x-msmsgsinvite; charset=UTF-8\r\n \r\n Application-Name: Remote Assistance\r\n Application-GUID: {56b994a7-380f-410b-9985-c809d78c1bdc}\r\n Session-Protocol: SM1\r\n Application-URL: http://www.microsoft.com\r\n Invitation-Command: INVITE\r\n Invitation-Cookie: 3863032\r\n Session-ID: {DF93A302-30D2-DF92-C392-F391049DB9EA}\r\n \r\n

<<< MSG 7 N 162\r\n MIME-Version: 1.0\r\n Content-Type: text/x-msmsgsinvite; charset=UTF-8\r\n \r\n Invitation-Command: CANCEL\r\n Invitation-Cookie: 3863032\r\n Cancel-Code: REJECT_NOT_INSTALLED\r\n \r\n