This space left intentionally blank. 
Oscar Protocol Documentation | Random Pidgin Files

Oscar Protocol Specification

Documentation written by Mark Doliner, unless otherwise noted. Much thanks to Adam Fritzler for writing Pidgin's oscar protocol plugin and oscar documentation. A lot of this was written by tracing through the source code of Pidgin's oscar protocol plugin :-). I'm not trying to document oscar completely, I'm really just trying to fill in the gaps left open by other, more useful documentation.

Other, more useful documentation:

Neither I nor this documentation is endorsed by or affiliated with America Online, Inc.

Family 0x0004


Family 0x0004 is used for messaging. As in, normal instant messages sent to other clients through the server. It's also used for various other things that are all basically one client talking to another client through the server. Examples of "various other things" are file transfer negotiation, direct IM negotiation, RTF messages, and old-style ICQ authorization.


This is all documented either by first hand packet captures or by tracing through libfaim.

0x0001 Server Family 0x0004 error message 
0x0006 Client Send an ICBM (Inter-Client Basic Message) 
0x0007 Server Receive an ICBM (Inter-Client Basic Message) 
0x000b Server A reply from a request you sent to another client? 
0x0014 Client Send or receive a mini typing notification message 

Family 0x0007


Family 0x0007 is used for some account administration stuff. Examples are change email address, changing screen name formatting, request account confirmation email, and request account info.

0xffff N/A TLVs 

Family 0x000f


This family is the new search family. I guess it's supposed to replace 0x000a. Why they made a whole fricken new family for it is beyond me. Or, maybe they did it so they can rate limit the searches more (to slow down would-be spammers), and make you connect to a different server.

0x0002 Client Search for other AIM users 
0x0004 Client Request list of interests 
0x0005 Server List of available interests 
0xffff N/A TLVs 

Family 0x0013


This family is used to handle various data which can be stored on the AIM servers. Things that can be stored are your buddy list (with groups and buddy comments), your permit and deny lists, your permit/deny setting, and your visibility setting.


The information is stored as "items." The structure is described here.

Buddy ID#s and group ID#s are arbitrary, though some clients tend to do it sequentially. They cannot, however, be 0x0000, and each ID# must be unique to the item that contains it (ie. two buddies in the same group can not have the same ID#, but two buddies in different groups can have the same ID#. Also, two groups in the list can not have the same ID#)(actually, we're still not clear as an un-muddied lake on this)(it's possible that the ID#s are some kind of hash of the name).

For screen names to show up in your buddy list, you must be using a family version of 3 or later (the most recent is currently 4). If you are using 1 or 2, AIM sends you your buddy list, but where you would normally have "," they send "PleaseUpgrade000." The BID and GID are the same, and the list that's actually stored on the server still contains the screen name--you just have to sign on with a client supporting a newer version of the SSI protocol.

Alex Yacoub had a big part in writing this, and helping figure out the protocol.

0x0001 Server Error 
0x0002 Client Request rights information 
0x0003 Server Rights information (returned after sending 0x0013/0x0003) 
0x0004 Client Request aserver-stored information 
0x0005 Client Request server-stored information 
0x0006 Server Server-stored information (returned after sending 0x0013/0x0005) 
0x0007 Client Activate server-stored information 
0x0008 Client Add an item to the server-stored data 
0x0009 Client Modify an item in the server-stored information 
0x000a Client Delete an item from the server-stored information 
0x000e Server Acknowledgement from add/modify/delete (0x0008/0x0009/0x000a) 
0x000f Server Server-stored information unchanged (returned after sending 0x0005) 
0x0011 Client About to modify list 
0x0012 Client Finished modifying list 
0x0014 Client Grant authorization to a contact without them asking for it 
0x0018 Client Send ICQ authorization request 
0x0019 Server Receive an ICQ authorization request 
0x001a Client Accept or decline an ICQ authorization request 
0x001b Server ICQ authorization request response (accepted or denied) 
0x001c Server Contact added you to their list 
0xffff N/A TLV Set - TLVs for additional data TLV chains for SSI items. 

Family 0x0015

0x0003 Server ICQ information reply 

Family 0x0017


This family is used for login with AIM, but not ICQ (er, I think that's right...), and for new user registration for ICQ.

0x0004 Client Register new ICQ number 
0x0005 Server ICQ registration response 

Family 0x0018


This family is used for information about the email account associated with your screenname. Unbeknowest to many AIM users, but knowest to me, your AIM account semi-comes with an email address. It is I think you might have to activate it, I'm not sure.

0x0006 Client Request somthing 
0x0007 Server Reply to information request 
0xffff N/A TLVs 

All material Copyright © 2000-2014, All Rights Reserved
Linux is a registered trademark of Linus Torvalds.
AIM is a registered trademark of America Online, Inc.
ICQ is a registered trademark of ICQ Inc.
All other trademarks are property of their respective owners.