Chat Gateway Protocol

The chat gateway is a text protocol on Battle.net™ that was deprecated in 2005. It has since been disabled entirely; sending the protocol byte for this protocol causes the server to disconnect the client. The information below is retained for completeness and historic purposes.

Getting Started

To signal the server to use the chat gateway for communicating, the user must send 0x03 as the first byte after connecting. All subsequent messages from here use human-readable text terminated by an end-of-line character sequence (0x0D 0x0A, also known as \r\n).

The normal SID-style messages from the game protocol (0x01) are invalid here, the user will be disconnected and temporarily IP-banned for violating the protocol if the client transmits game protocol messages over the chat gateway.

Key Facts

The chat gateway does not create or join games.

Users of the chat gateway protocol are assigned the Chat icon and product id. Anyone using the chat gateway will always have the flag 0x10 (known as the UDP Plug) because they do not use UDP.

The chat gateway is restricted to the following channels:

• Blizzard Tech Support
• Open Tech Support
• Public Chat
• The Void

All other channels are restricted, including Blizzard Chat.

In the chat gateway, user flags are printed in padded 4-character hexadecimal numbers (ex. 0010). They are not padded to the full length of the UINT32 flag field (ex. 00000010).

Channel flags are not received and they cannot be retrieved, but it is assumed channel flags would follow the same format as user flags since they reuse the same field on the game protocol.

All product ids in the chat gateway are seen as their normal UINT32 field. As an example, a user may receive a 1001 USER message with the product of STAR. This is identical to the product ids in SID_CHATEVENT, with exception to that they are not reversed (ex. RATS). The same applies for every other product id. Statstrings are unavailable when using the chat gateway.

Handshake Messages

The purpose of the handshake process for the chat gateway protocol is to authenticate the user and put them into chat.

After the protocol byte (0x03), the user should send 0x04 terminated by end-of-line to signal the login process.

The server will send the following to signal the user to enter their credentials:

Enter your login name and password.

After the user sends their username terminated by end-of-line, the user should receive:

Username: the-username-entered

The user should now send their password in plaintext terminated by end-of-line, then the user should receive:

Password:

There is no character after the colon symbol (:), not even a space character.

The server will now verify the user's credentials, and will send a success or failure message.

The server will transparently convert passwords to lowercase before verification. This is to adhere to the game protocol login process, where the games do the lowercasing instead.

Login Failure

The following is received if the server rejected the user's login credentials:

Incorrect username/password.

This message could be received if the user does not exist or the password does not match the one on the server.

The server expects the user to repeat the login process by submitting their username again, skipping the transmission of 0x04.

Login Success

The following is received if the user's credentials were verified and the user has logged on:

Connection from [1.2.3.4]

The example value 1.2.3.4 represents the user's IP address as seen by the server.

This message is followed by message ids 2010, 1007, 1001, and then 1018 respectively.

Messages

When the user sends a message after handshake, the server will interpret it identically as the text field in SID_CHATCOMMAND and every message is subject to the same restrictions of that game protocol-style message.

When the user receives a message from the server, they follow a specific formatting. That formatting is detailed further below.

The general idea of the specific formatting is as such:

<id> <name> <message-data>

Each field in the message is separated by a space character. The name accompanies the id, and can safely be discarded for parsing. The message data may have additional spaces. If there is no message data, there is also no space character after the name.

Message ids are padded 4-character decimal numbers. They closely resemble user flags' formatting, but they are not hexadecimal.

Ids in the range of 1000-1999 are assumed to be reserved for chat events, and they follow the same base set of ids as the event ids of SID_CHATEVENT.

Ids in the range of 2000-2255 are assumed to be reserved for normal SID-style messages that have been converted to text-style, such as SID_ENTERCHAT (known as message id 2010 here).

You can get a better idea of how these ids work by reading further below.

1001 USER <username> <flags> [<product>]

• This message is received after message id 1007, and each one of these messages represent a user in the channel.
• The brackets [ and ] are part of the protocol.

1002 JOIN <username> <flags> [<product>]

• Similar to message id 1001, this message is received after the user has already entered the channel and another user enters.
• A message could be displayed for this by the user's client (ex. <username> has entered the channel).

1003 LEAVE <username> <flags>

• This message is received when a user leaves the channel.
• The flags field used to be received in conjunction with the username, but was removed.

1004 WHISPER <username> <flags> "<message>"

• This message is received when another user whispers this user.
• The flags field represents the flags of the user that whispered this user.
• The message is not escaped, even though it is surrounded by quotations. Care must be taken if and when parsing this message. The quotes have no effect really, so they can safely be discarded after parsing.

1005 TALK <username> <flags> "<message>"

• Similar to message id 1004, this message is received when another user talks in the channel.
• Also similar to message id 1004, the quotations around the message should be discarded.
• This message is not received when the user themselves talk in the channel, so the user's client must print their user's message for them.

1006 BROADCAST "<message>"

• This is received when a broadcast from the server is sent out (ex. The server will be shutting down for maintenance).
• Contrary to its game protocol counterpart, there is no username received, likely because it's defunct on the game protocol's version of this message.

1007 CHANNEL "<name>"

• This message is received when the user enters a channel.
• Contrary to its game protocol counterpart, there are no channel flags received in this message. It is impossible to identify whether a channel is public, private, or otherwise from this message.

1009 USER <username> <flags> [<product>]

• Similar to message id 1001, this message is received when a user's flags or product change while in the channel, such as when a user is promoted to channel operator.

1010 WHISPER <username> <flags> "<message>"

• This message is received when the user sends a whisper to another user.
• The flags represent the user flags of the user that was whispered to.

1010 WHISPER your friends <flags> "<message>"

• This message is received when the user whispers to their friends instead of an individual user.
• This message is identical to the other message of the same id, except with regard to the username which now contains a space character. Care must be taken if and when parsing this message.

1018 INFO "<message>"

• This message is received when the server sends information (ex. You are JoeUser, using Chat in the channel Public Chat 1.).
• Similar to message id 1004, the quotations around the message should be discarded.

1019 ERROR "<message>"

• This message is received when the server sends an error (ex. That user is not logged on.).
• Similar to message id 1004, the quotations around the message should be discarded.

1023 EMOTE username flags "<message>"

• This message is received when a user sends an emote in the channel.
• The username may be themselves or anyone in the channel.
• Similar to message id 1004, the quotations around the message should be discarded.

2000 NULL

• This message is received when the connection has become idle and the server wishes for the user to respond in some way.
• This is typically received every 30 seconds. Each time the user sends a message, the timer resets.
• Text gateway protocol connections are never disconnected for being idle, so this message really has no purpose. This is the reason a few chat gateway clients send /users or /time commands at certain intervals, the purpose being to keep the connection alive.

2010 NAME <username>

• This is the user's unique name in chat. If the user is logged on more than once, this is the username with a number at the end (ex. JoeUser#2) instead of the actual username (ex. JoeUser).

This ends this section and covers all of the messages that the chat gateway sends and receives.

---

BNETDocs Staff TODO: Clean this part up.

After you have logged on successfully, anything you send is a message or command followed by an end-of-line. If you do not add an end-of-line to your message, it is appended to your last message. So for example, let's say I entered "123" without an end-of-line then entered "456" with an end-of-line, I would of just sent "123456" to the channel, instead of "456."

Telnet's flags are the same as the regular user flags seen everywhere. The only difference is that Telnet's flags are kept to 4 characters instead of 8 characters or a binary UINT32 and the flags are displayed in hexadecimal (ex. 0010 UDP would be 0016 UDP in decimal). Also, flags are prefixed with zero's if they are not equal to 4 digits.

See the related documents for more information about flags and ID's. Telnet uses the same "values" as described in those documents. If you noticed something, SID_CHATEVENT uses the same event ID's as Telnet uses, except for 1013, 0014, and 0015, which are not used in Telnet. Another irony is the packet ID's in Telnet are 4 digits, just like the flags are, so maybe a UINT32 in Telnet is actually 4 text-digits.