OSCAR Protocol

This document is covered under the documented license and terms.

The OSCAR protocol specification lets developers build libraries and clients that can speak to the
AIM backend using the same protocol that official native AOL clients use. In general, we
recommend that developers do not build new OSCAR libraries but instead use one of the available
libraries already built, including our SDK available here. AOL does not endorse any third party
library, and regardless of the library used, the client developer must meet the license requirements
documented here.
This document is a work in progress; there are details and sections still missing. Please contact us
about document feedback and fixes. Please note - this address is NOT for asking questions or
support requests. For support questions please visit the forums.
The OSCAR protocol is a binary protocol and is transmitted in network byte order unless otherwise
noted. The application protocol stack consists of TCP for networking, a FLAP layer providing
framing, and SNACs representing the OSCAR protocol messages. Many of the server connections
support TLS between the FLAP and TCP layer if single hop encryption is desired. In most cases, the
binary data stream is formed by appending the elements described below in order with no extra
padding.
There are several servers that make up the AIM backend complex.
[Link]
The [Link] servers provide all the authentication web services, also knows as AOL
Open Auth. The first step to an AIM session is using clientLogin to authenticate the user.
[Link]
The [Link] servers provide access to all the AIM web services. For OpenAIM it provides a
service discovery mechanism for a client to find the correct BOSS server to which it should
connect. It also provides a redirect service for the start page and expressions page.
BOSS
The client spends the most time talking to the Basic OSCAR Service Server, or BOSS for
short. The BOSS server provides all the Buddy notifications, IM routing, and general services.
It also is the gateway to some of the other AIM backend servers. The client's connection to the
BOSS server is very important since it defines the life of the session. If a client gets
disconnected from BOSS, it is considered offline and all session state information is removed.
BART
The Buddy Art, or BART, server provides access to the client for downloading image, sound,
and xml assets for expressions.

A single user can use multiple clients at the same time on the same or different devices. When
building a client, or library, care should be taken to deal with a single user being online multiple
times. In general, all IMs and Buddy notifications will be sent to all instances, although there are
some IM routing rules that come into effect when users are away or idle.
 Introduction
 Datatypes
 UUIDs
 FLAP
 SNAC
 ERRORs
 Foodgroups
 OSERVICE
 Rate Limiting
 Migration
 Secondary Service Requests
 Miscellaneous
 PD - Permit/Deny
 ICBM - Inter Client Basic Message
 INVITE - Invite users to join AIM
 BUDDY - Presence
 FEEDBAG - Host Based Buddy List & Preferences
 BART - Buddy Art
 LOCATE - Get Info
 Authentication
 Single Signon to Web Pages
 Start Page Requirement
 Expressions Requirement
 Examples
 Signon Flow
 IM Flow
 Buddy Info Requirement
 Start Page and Expression Chooser

Common Base Types

The protocol is built on top of some common base types described below; these are the building
blocks for all the other datatypes and SNACs. When encoding or decoding these types, make sure to
use network byte order.

Base Types
Name Size Notes
u08 1 byte Unsigned byte
u16 2 bytes Unsigned two byte short
u32 4 bytes Unsigned four byte int
f32 4 bytes Four byte float
t70 4 bytes Unsigned four byte timestamp, from UNIX EPOCH
UUID 16 bytes Sixteen bytes that represent a UUID also known as a GUID
blob length bytes Used in a TLV, data type and size is defined by external values
empty 0 bytes Used in a TLV, existence of tag causes behavior, the data is ignored

String Types
In general strings are not NULL terminated and are encoded using UTF8. A string is said to
be compressed if all white spaces are removed and all upper case characters are converted to lower
case.
Name Size Notes
string data Inside of TLVs a string inherits its length from the TLV length
string08 u08 + data One byte length followed by that many bytes of data
string16 u16 + data Two byte length followed by that many bytes of data
Datatype: TLV
TLVs are a very common structure used in the OSCAR protocol to represent dynamically typed
data. Parsers should always ignore unknown tags as to not break old clients when new protocol
items are added. Possible values for tags are determined by where the TLV is in the protocol; these
possible values belong to a TLV class. In the wild, the term type is sometimes used interchangeably
with tag, however this document uses tag to reference the integer value associated with the TLV and
type as the datatype associated with that tag.
Name Type Notes
Numeric tag of the data, possible values are defined in the TLV class for the group of
tag u16
TLVs
len u16 Length in bytes of the variable data
The data inside the TLV of len length; usually another datatype is used to represent
value blob
the data - this is described in the TLV class
TLVs are usually used in an array of TLV form, allowing the protocol to easily be expanded.
Having just one TLV without an array does not gain much since it only allows one item to be
described. There are two common methods for adding an array of TLVs to datatypes and SNACs.
An additional method also exists to add an array of TLVs to SNACs. The most common is a
tlvBlock which is a u16 number of TLVs followed by that many TLVs. The less common is a
tlvLBlock which instead of counting the number of TLVs, counts the size of all the TLVs. The third,
which is only available in SNACs, is the tlvRestBlock which says any remaining bytes in the SNAC
are TLVs.
Name Size Notes
tlvBlock u16 + data Two byte number of elements, followed by that many elements
tlvLBlock u16 + data Two byte length of elements, followed by that many bytes of elements

UUID - Universally Unique Identifier

AIM uses UUIDs in several places to express what kind of capabilities a client has and what
features it would like the server to support. The nice thing about UUIDs is there does not have to be
a central registry since they are unique when created. There are many websites and tools out there
that will create a UUID. UUIDs are also sometimes known as GUIDs.
UUIDs are transmitted as 16 bytes of binary data; however in documents they are written down in
string form like 09460000-4C7F-11D1-8222-444553540000.
At some point it was decided that full UUIDs were too verbose for common capabilities, so AIM
uses both full UUIDs and what are called "short UUIDs" or "Short Caps". A "Short Cap" is really a
UUID of the form 0946XXYY-4C7F-11D1-8222-444553540000 where XXYY is the short cap. A
client receives short caps if it asserts the short cap capability. If a client does not assert the short
caps UUID, it will get most caps in long form. Some APIs only take UUIDs In those cases the long
form of a short cap should be sent.
Client and library developers should feel free to create valid new UUIDs, just do not create new
"Short Caps". If developers would like to publish their UUIDs and what they mean, we will be
happy to document them here.
Name UUID Notes
09460000-4C7F-11D1-8222-
SHORT_CAPS Client support short caps
444553540000
09460001-4C7F-11D1-8222-
SECURE_IM Client supports SECURE_IM
444553540000
09460002-4C7F-11D1-8222- Client supports XHTML profile and
XHTML_IM
444553540000 ims instead of AOLRTF
09460101-4C7F-11D1-8222-
RTCVIDEO Client supports SIP/RTP video
444553540000
09460102-4C7F-11D1-8222-
HAS_CAMERA Client has a camera
444553540000
09460103-4C7F-11D1-8222-
HAS_MICROPHONE Client has a microphone
444553540000
09460104-4C7F-11D1-8222-
RTCAUDIO Client supports RTCAUDIO
444553540000
HOST_STATUS_TEXT_ 0946010A-4C7F-11D1-8222- Client supports new status message
AWARE 444553540000 features
0946010B-4C7F-11D1-8222-
RTIM Client support "see as I type" IMs
444553540000
094601FF-4C7F-11D1-8222- Client only asserts caps for services it
SMART_CAPS
444553540000 is participating in
09461343-4C7F-11D1-8222-
FILE_TRANSFER File transfer
444553540000
09461345-4C7F-11D1-8222-
DIRECT_ICBM P2p ims
444553540000
09461348-4C7F-11D1-8222-
FILE_SHARING File sharing
444553540000
0946134D-4C7F-11D1-8222-
SUPPORT_ICQ Client supports talking to ICQ users
444553540000

FLAP - Frame Layer Protocol

FLAP provides the packet framing on top of TCP or TLS layer for the OSCAR protocol. Each
message sent to and from the AIM backend is encapsulated in a FLAP frame that is easily identified
using a 6 byte header followed by a variable length data segment. The payload of a FLAP frame is
in most cases a SNAC.

Datatype: FLAP__Header
The header contains the frame type, a sequence number, and the length of the following data
segment. The sequence number is independently sequential in each direction. Packets from the
server to client have one sequence number, while the packets from the client to server have a
different independently increasing number. If the server receives a sequence number out of order it
will terminate the connection. A common mistake is to use a u08 to represent the sequence number,
which will roll over at 255 and cause the server to disconnect the client.
Name Type Notes
startMarker u08 ASTERISK (literal ASCII ‘*’)
frameType u08 [Class: FLAP__FRAME_TYPE] Frame type
sequenceNumber u16 Initialized to a random value, increments for each send
payloadLength u16 Length of data, does not include the 6 byte header length

Class: FLAP__FRAME_TYPE
There are several different frame types, with the most common being the DATA frame.
Name Value Notes
SIGNON 1 Initialize the FLAP connection
DATA 2 Messages using the FLAP connection, usually a SNAC message
ERROR 3 A FLAP error - rare
SIGNOFF 4 Close down the FLAP connection gracefully
KEEP_ALIVE 5 Send a heartbeat to server to help keep connection open

Class: FLAP__MULTICONN_FLAGS
These flags control how multiple instances are handled by the servers and if current sessions need to
be bumped off when a new session signs on.
Name Value Notes
OLD_CLIENT 0x00 Don't use
RECENT_CLIEN
0x01 This is a recent client that understands multiple instances
T
This is a recent client that understands multiple instances but does not
SINGLE 0x03
want them

TLV Class: FLAP__SIGNON_TAGS

These tags are used in the FLAP signon frame. They appear right after the 4 byte version number.
Name Tag Type Notes
CLIENT_NAME 3 string Yet another client name
LOGIN_COOKIE 6 blob Login cookie returned by startOSCARSession
MAJOR_VERSION 23 u16 Client major version: (1) if the client version is "1.2.3"
MINOR_VERSION 24 u16 Client minor version: (2) if the client version is "1.2.3"
POINT_VERSION 25 u16 Client minor version: (3) if the client version is "1.2.3"
BUILD_NUM 26 u16 Client build number, usually monotonically increasing
[Class:FLAP__MULTICONN_FLAGS] Should almost
MULTICONN_FLAGS 74 u08
always be 0x1
CLIENT_RECONNEC
148 u08 Client claims it is reconnecting because it got knocked off
T

FLAP: FLAP__SIGNON_FRAME
On connection, the server and client each send a FLAP SIGNON frame to initialize the connection.
The sequence number field should be initialized with a random value. The data portion of the frame
contains a 4 byte version number, currently always 1, followed by any TLVs that are required.
Name Type Notes
FLAP header, type will be
header FLAP__Header
FLAP__FRAME_TYPE_SIGNON
flapVersion u32 Always 1
Array of TLV length
tlvs [Class: FLAP__SIGNON_TAGS] TLVs
payloadLength-4
Example in hex: 2a011234000400000001
FLAP: FLAP__KEEPALIVE_FRAME
Many modern operating systems and networks come with firewalls and packet inspectors to protect
the user. Unfortunately, these services and devices have proven to be buggy with long lived
connections. We recommend that a client sends a FLAP KEEP_ALIVE packet to the server every
minute after the connection has gone idle to help keep the connection alive. Please do not send it
more often then once a minute or when the connection is not idle. There is no response to this
message and a client will never receive a KEEP_ALIVE packet from the server.
Name Type Notes
header FLAP__Header FLAP header, type will be FLAP__FRAME_TYPE_KEEP_ALIVE

FLAP: FLAP__DATA_FRAME
A data frame will always just contain a single SNAC.
Name Type Notes
header FLAP__Header FLAP header, type will be FLAP__FRAME_TYPE_KEEP_DATA
snacHeader SNAC__Header SNAC header
snac blob snac described by the SNAC header

FLAP: FLAP__SIGNOFF_FRAME
This FLAP frame type is sent both to the client and server.
 Sent to the client to tell it that it is getting bumped off gracefully. The client should NOT try
to auto reconnect if it receives one of these messages.
 Sent to the server by the client to tell it that it is going away gracefully.
Name Type Notes
header FLAP__Header FLAP header, type will be FLAP__FRAME_TYPE_SIGNOFF

SNAC - Simple Network Atomic Communication

SNACs are used to represent the protocol messages that are sent between the client and backend.
The messages are separated into different categories, called foodgroups. Within each foodgroup
there are different kinds of messages related to the category.

Datatype: SNAC__Header
The FLAP Header will be immediately followed by the SNAC Header that describes what type of
message it is for SNAC messages sent over FLAP. The SNAC Header is a simple 10 byte header
that contains the foodgroup, type, any high level flags, and the requestId. The requestId is used to
link up requests and replies and can also be used to determine the direction of traffic. A client
should never set the high bit of a requestId or use 0. The server will always set the high bit for its
requestId unless it is a reply to a client query, in which case it will use the same requestId as the
request. The flags field tells the client if for the same request there will be multiple replies and if
there are any SNAC Header TLVs.
Name Type Notes
id SNAC__ID Foodgroup and message type
[Class: SNAC__HEADER_FLAGS] Flag
flags u16
s
requestId u32 Used to link requests and replies
Datatype: SNAC__ID
Describes the foodgroup and type this SNAC represents
Name Type Notes
foodgroup u16 Numeric value that represents the foodgroup the SNAC is in
type u16 Numeric value that represent the SNAC type

Class: SNAC__HEADER_FLAGS
These are the flags that let the client know details about the SNAC being received.
Name Value Notes
OPT_TLV_PRESE A tlvLBlock immediately follows the SNAC header before the rest of
0x8000
NT the fields
MORE_REPLIES_ More replies follow this message using the same requestId; the last
0x0001
FOLLOW reply is easily detectable because it will not have this flag set

Errors
Errors are implemented in a common way for all foodgroups each having a SNAC as type 1.

Class: ERROR__CODE
Generic error codes
Name Value Notes
INVALID_SNAC 1 Not a known SNAC
RATE_TO_HOST 2 Exceed the rate limit to server
RATE_TO_CLIENT 3 Exceed the rate limit to the remote user
NOT_LOGGED_ON 4 Remote user is not logged in
SERVICE_UNAVAILABLE 5 Normally available but something is wrong right now
SERVICE_NOT_DEFINED 6 Requested a service that does not exist
OBSOLETE_SNAC 7 This SNAC is known no longer supported
NOT_SUPPORTED_BY_HOS
8 Unknown SNAC
T
NOT_SUPPORTED_BY_CLIE
9 Remote user is on but does not support the request
NT
REFUSED_BY_CLIENT 10 Message is bigger then remote client wants
RESPONSES_LOST 12 Something really messed up
REQUEST_DENIED 13 Server said user or client is not allowed to do this
BUSTED_SNAC_PAYLOAD 14 SNAC is too small or is not in the right format
User or client does not have the correct rights to make the
INSUFFICIENT_RIGHTS 15
request
User is trying to interact with someone blocked by their
IN_LOCAL_PERMIT_DENY 16
own settings
TOO_EVIL_SENDER 17 Sender is too evil
TOO_EVIL_RECEIVER 18 Receiver is too evil
USER_TEMP_UNAVAIL 19 User is migrating or the server is down
NO_MATCH 20 Item was not found
LIST_OVERFLOW 21 Too many items were specified in a list
REQUEST_AMBIGOUS 22 Host could not figure out which item to operate on
TIMEOUT 26 Some kind of timeout
GENERAL_FAILURE 28 General failure
RESTRICTED_BY_PC 31 Restricted by parental controls
REMOTE_RESTRICTED_BY_
32 Remote user is restricted by parental controls
PC

TLV Class: ERROR__TAGS

These are common tags used by error SNACs.
Name Tag Type Notes
FAIL_URL 4 string URL with more detail
ERROR_SUBCODE 8 u16 Foodgroup-specific error code
ERROR_TEXT 27 string String error message text
ERROR_INFO_CLSID 41 UUID UUID specifying format of ERROR_INFO_DATA data
ERROR_INFO_DATA 42 blob Extra information describing error

Foodgroup: OSERVICE
The OSERVICE foodgroup contains basic operations and data types that are common across many
of the foodgroups and even different servers. It is also used for service requests when the client
needs to connect to a second server to perform some other action.

Datatype: OSERVICE__NickwInfo
Common data structure that contains a user's loginId and information about their session.
Name Type Notes
displayId string08 Formated loginId
evil u16 Warning level of user
[Class: OSERVICE__NICK_INFO_TAGS] TLV Block of user
userAttributes tlvBlock
attributes

TLV Class: OSERVICE__NICK_INFO_TAGS

These tags contain information about users and their server state.
Name Tag Type Notes
[Class:OSERVICE__NICK_FLAGS] Flags that
NICK_FLAGS 1 u16
represent the user's state
SIGNON_TOD 3 t70 Signon time
IDLE_TIME 4 u16 Idle time in minutes
MEMBER_SINCE 5 t70 Approximation of AIM membership
REALIPADDRESS 10 u32 Network byte order IP address
Array Client capabilities - if not present use the previous values
CAPS 13
ofUUID received; if present but empty, clear previous values
ONLINE_TIME 15 u32 Online time in seconds
MY_INSTANCE_N Set in first nick info. Identifies the instance number of
20 u08
UM this client
SHORT_CAPS 25 Array of u16 Short form of capabilities
Array
BART_INFO 29 Expressions
ofBART__ID
[Class:OSERVICE__NICK_FLAGS] Upper bytes of
NICK_FLAGS2 31 Array of u08 nick flags, can be any size. nickFlags = NICK_FLAG |
(NICK_FLAGS2 << 16)
BUDDYFEED_TIM
35 t70 Last Buddy Feed update time
E
SIG_TIME 38 t70 Time that the profile was set
AWAY_TIME 39 t70 Time that away was set
Two character country code. Sent from host to client if
GEO_COUNTRY 42 string
country is known

Class: OSERVICE__NICK_FLAGS
Bits specifying a user's characteristics; For compatibility reasons the lower 2 bytes of
NICK_FLAGS are sent in the NICK_FLAGS tag, while the upper bytes are sent in the
NICK_FLAGS2 tag. To form the full nick flags the client needs to combine NICK_FLAGS and
NICK_FLAGS2 shifted to the left 2 bytes. NICK_FLAGS is always a u16, which NICK_FLAGS2
can be any size. Another way to express the math: nickFlags = NICK_FLAG | (NICK_FLAGS2 <<
16)
Name Value Notes
UNCONFIRMED 0x0001 Unconfirmed account
AOL 0x0004 AOL user
AIM 0x0010 AIM user
UNAVAILABLE 0x0020 User is away
ICQ 0x0040 ICQ user; AIM bit will also be set
WIRELESS 0x0080 On a mobile device
IMF 0x0200 Using IM Forwarding
BOT 0x0400 Bot user
ONE_WAY_WIRELE
0x1000 One way wireless device
SS
NO_KNOCK_KNOC Do not display the "not on your Buddy List" knock-knock as
0x00040000
K the server took care of it or the sender is trusted
FORWARD_MOBIL
0x00080000 If no active instances forward to mobile
E

Datatype: OSERVICE__Version
Description of a foodgroup and the version of that foodgroup the client wants to use when
communicating with the backend.
Name Type Notes
foodgroup u16 Foodgroup that the version represents
Version of the foodgroup implementation; should be 4 for OSERVICE, 3 for
version u16
FEEDBAG, 1 for all others
tool_id u16 Should be 41 for all Open AIM clients
tool_versio
u16 Any version number the developer would like, usually the build number
n

SNAC: OSERVICE__ERROR - Foodgroup:1 Type:1

Error SNAC for the OSERVICE foodgroup.
Name Type Notes
code u16 [Class: ERROR__CODE] Error code
errorTLVs Rest of SNAC array of TLV [Class: ERROR__TAGS] Optional error parameters

SNAC: OSERVICE__HOST_ONLINE - Foodgroup:1 Type:3

This is the very first SNAC sent from the server to the client after the FLAP signon frames are sent.
The groups array specifies the SNAC groups supported by the server. Attempted use of any other
group by the client will result in a terminated connection. In all cases, the client is not allowed to
transmit any SNACs until it has received this message.
Name Type Notes
groups Rest of SNAC array of u16 All foodgroups the server supports

SNAC: OSERVICE__CLIENT_ONLINE - Foodgroup:1 Type:2

This message is sent by the client once it has initialized the server state (set preferences, Buddy
Lists, locate information, capabilities) and is ready to be announced as being online by the server.
The client may have used groups not in groupVersions during initialization, but once this SNAC has
been received by the server, SNACs in groups not specified in groupVersions will be rejected. Other
users will not see this user online until this SNAC is sent.
Name Type Notes
Rest of SNAC array All foodgroups the client wants to
groupVersions
of OSERVICE__Version support

Rate Limiting
To protect the server and other users from abusive clients, the server implements SNAC rate
limiting. Rate limiting is done with a simple formula that calculates the average time between
SNACs over the last few SNACs sent from the client to the server. A client can optionally subscribe
to notifications about its rates so that it can warn the user ahead of time or show UI about the rates.
Even if the client does not subscribe, it will receive notifications when the rate limit has been
reached and the server has started dropping SNACs. If the client continues to send SNACs, it will
eventually be disconnected.
All SNACs are assigned to a Rate Class which controls the parameters to the rate limit forumla.
Most SNACs are in the most lenient rate class by default, with SNACs like IM sending being in
more strict classes. The rate formula is currentAvg = ((currentAvg * (windowSize -1)) +
delta)/windowSize. The currentAvg falling below certain thresholds causes the server to warn the
client that it is about to be rate limited or disconnected. Once a client is rate limited, its average has
to fall above the clear threshold before it can start sending SNACs again.
The actual parameters for the formula are not published in this document since they can change
from time to time and are different depending on the current warning level and other things. A client
can average around one IM every two seconds without being rate limited.
SNAC: OSERVICE__RATE_PARAMS_QUERY - Foodgroup:1 Type:6
This SNAC is sent by the client to query for the current rate limit parameters.
This SNAC has no fields and is always empty.

Datatype: OSERVICE__Rate_Parameters
Describes the rate parameters for a single rate class.
Name Type Notes
classId u16 Rate class being described
windowSize u32 Number of events to count
clearThreshold u32 Once rate limited the average has to reach this value in order to clear
alertThreshold u32 Server will tell the client it is getting close to the limit
limitThreshold u32 SNACs will be dropped below this value
disconnectThreshold u32 Server will disconnect below this value
currentAverage u32 Current value for the class; higher is better
The maximum rate value; if the current value rises about this value it
maxAverage u32
should be reset
lastArrivalDelta u32 Last message was received this long ago
droppingSNACs u08 Is the server dropping SNACs for this rate class

Datatype: OSERVICE__Rate_Class_Members
Describes all the SNACs in a single rate class.
Name Type Notes
id u16 Rate class being described
numMembers u16 Number of SNACs in this rate class
snacIds Array of SNAC__ID length numMembers SNACs in this rate class

SNAC: OSERVICE__RATE_PARAMS_REPLY - Foodgroup:1 Type:7

Contains response to the RATE_PARAMS_QUERY. The first part of the SNAC contains the rate
classes. The second part contains the list of members within each class.
Name Type Notes
Number of different rate
numClasses u16
classes
Array of OSERVICE__Rate_Parameters length
rateParameters Controlling parameters
numClasses
Array of OSERVICE__Rate_Class_Members length Which SNACs are in what
rateMembers
numClasses rate class

SNAC: OSERVICE__RATE_ADD_PARAM_SUB - Foodgroup:1 Type:8

Subscribe to any rate parameter changes among the specified class IDs. If there was no prior
subscription for a given class ID, an immediate notification will be queued.
Name Type Notes
classIds Rest of SNAC array of u16 Rate class IDs the to which the client wants to subscribe
SNAC: OSERVICE__RATE_DEL_PARAM_SUB - Foodgroup:1 Type:9
Cancels any rate parameter subscriptions for the specified class IDs.
Name Type Notes
classIds Rest of SNAC array of u16 Rate class IDs from which the client wants to unsubscribe

SNAC: OSERVICE__RATE_PARAM_CHANGE - Foodgroup:1 Type:10

This contains an array of class rate parameters that have changed since last query or notification.
The server will also generate one of these notifications whenever the client has taken a negative
transition through an alert threshold.
Name Type Notes
[Class: OSERVICE__RATE_CODE] New
rateCode u16
rate code from server
Rest of SNAC array
rateParameters New rate parameters
ofOSERVICE__Rate_Parameters

Class: OSERVICE__RATE_CODE
These are the codes used in RATE_PARAM_CHANGE to describe the state of the rate class.
Name Value Notes
CHANGE 1 Rate parameters have changed
Rate limit warning reached; if client does not slow down LIMIT state will be
WARNING 2
hit
LIMIT 3 Rate limit reached; if client does not slow down client will be disconnected
CLEAR 4 Rate limit cleared; client can send SNACs normally now

Migration
The AIM backend supports the concept of migration so AOL can perform maintenance to backend
servers without effecting a user's sessions. The server will initiate the migration and tell the client it
needs to migrate to a different server. The client acknowledges that it is ready to be migrated to the
server. The server then tells the client where to reconnect to start its session up again.

SNAC: OSERVICE__PAUSE - Foodgroup:1 Type:11

This is sent by the server when it needs to migrate the client. The client should cease transmitting
SNACs and generate aOSERVICE__PAUSE_ACK SNAC to acknowledge it is ready. If the client
ignores the PAUSE it will be kicked off after a short time period.
This SNAC has no fields and is always empty.

SNAC: OSERVICE__PAUSE_ACK - Foodgroup:1 Type:12

This is sent by the client to acknowledge the receipt and processing of
a OSERVICE__PAUSE SNAC request.
This SNAC has no fields and is always empty.

TLV Class: OSERVICE__MIGRATE_TAGS

These are the codes used in MIGRATE_GROUPS to describe where the client should recconnect.
Name Tag Type Notes
RECONNECT_HER
5 string IPaddress followed by optional colon and port, [Link]:5190
E
LOGIN_COOKIE 6 string Binary opaque data
SSL_CERTNAME 141 string Certname to use for SSL validation
[Class:OSERVICE__SERVICE_RESPONSE_SSL_STATE] SS
SSL_STATE 142 u08
L state

SNAC: OSERVICE__MIGRATE_GROUPS - Foodgroup:1 Type:18

This SNAC commands the client to reconnect to the server specified by the included
RECONNECT_HERE TLV. The client needs to present the LOGIN_COOKIE to sign in so that it
can reacquire the services which were previously PAUSE'd by the server and PAUSE_ACK'd by the
client. All groups currently provided on the existing connection are migrated to the new location.
The client should drop the existing connection since services will no longer be available from it.
Name Type Notes
allGroups u16 Will be zero
Rest of SNAC array [Class: OSERVICE__MIGRATE_TAGS] Information about
tlvAuthData
of TLV where to reconnect

SNAC: OSERVICE__RESUME - Foodgroup:1 Type:13

In certain situations the server may abort a migration after having told the client to PAUSE. In that
case, it will send this SNAC to tell the client that it is back in business.
This SNAC has no fields and is always empty.

Secondary Service Requests

There are other backend servers that a client may need to connect to for more advanced commands.
To connect to a secondary server, a client sends up a SERVICE REQUEST and receives a
SERVICE RESPONSE back with the connection information. The secondary servers include:
 BART - For downloading Buddy Art

TLV Class: OSERVICE__SERVICE_REQUEST_TAGS

These are the tags the client uses to control what type of service request it wants.
Name Tag Type Notes
USE_SSL 140 empty No value; if present use SSL

Class: OSERVICE__SERVICE_RESPONSE_SSL_STATE
This describes what type of SSL connection the client and backend have.
Name Value Notes
NOT_USED 0 SSL is not supported or not requested for this connection
USE 1 SSL is being used
RESUME 2 SSL is being used and SSL resume is supported if desired
TLV Class: OSERVICE__SERVICE_RESPONSE_TAGS
This class provided information about where the client should connect for the service.
Name Tag Type Notes
GROUP_ID 13 u16 Foodgroup for which this response is for
RECONNECT_HER
5 string IP address followed by optional colon and port, [Link]:5190
E
LOGIN_COOKIE 6 string Binary opaque data
SSL_CERTNAME 141 string Certname to use for SSL validation
[Class:OSERVICE__SERVICE_RESPONSE_SSL_STATE] SS
SSL_STATE 142 u08
L state

SNAC: OSERVICE__SERVICE_REQUEST - Foodgroup:1 Type:4

This SNAC requests that the specified service (foodgroup) be provided to it in a way further
specified by qualifyingParameters. The server will either reject the request via an error reply or
accept it and reply with a SERVICE_RESPONSE. Note that this is a request for new service; this is
not like the MIGRATE case where the current FLAP connection might be dropped.
Name Type Notes
foodgroup u16 Group being requested
Rest of SNAC [Class: OSERVICE__SERVICE_REQUEST_TAGS] Mo
qualifyingParameters
array of TLV difiers for the request, such as a TLS request

SNAC: OSERVICE__SERVICE_RESPONSE - Foodgroup:1 Type:5

This SNAC contains information about connecting to the new server. It is the response from the
server to a service request.
Name Type Notes
Rest of SNAC array [Class: OSERVICE__SERVICE_RESPONSE_TAGS] How to
connectInfo
ofTLV connect to the new server

Miscellaneous
SNAC: OSERVICE__NICK_INFO_QUERY - Foodgroup:1 Type:14
This is a query to find out one's current info. The server will send a NICK_INFO_UPDATE.
This SNAC has no fields and is always empty.

SNAC: OSERVICE__NICK_INFO_UPDATE - Foodgroup:1 Type:15

This SNAC is sent by the server whenever significant parts of a user's NickwInfo change. It can
also be requested by the client by sending a OSERVICE__NICK_INFO_QUERY. If more than one
OSERVICE__NickwInfo is contained in this SNAC, the first entry describes the overall state of the
user and is followed by entries for each online instance for the user.
Name Type Notes
info Rest of SNAC array of OSERVICE__NickwInfo Updated info
SNAC: OSERVICE__EVIL_NOTIFICATION - Foodgroup:1 Type:16
This is a notice that the user's evil level has changed. The NickwInfo field is optional and is only
present if it is not anonymous.
Name Type Notes
New evil level - max is 1000; if the value goes down then it is an
newEvil u16
update and not a evil
OSERVICE__NickwI
vilifier Optional; user who eviled the receiver of the SNAC
nfo

SNAC: OSERVICE__IDLE_NOTIFICATION - Foodgroup:1 Type:17

This SNAC is sent by the client to inform the server of the user's idle state. A non-zero idleTime
indicates that the user is idle and specifies the number of seconds since the user's last keyboard or
mouse input. A zero idleTime indicates that the user is active. If the client is not capable of
detecting the user's idle state it should not send this SNAC. In order to prevent excessive load on the
server, the client should not send this SNAC with a non-zero idleTime more often that once every
10 minutes. Once the server receives this SNAC it will automatically increment it as time goes by.
Name Type Notes
idleTime u32 Client's idle time when changing states

SNAC: OSERVICE__SET_NICKINFO_FIELDS - Foodgroup:1 Type:30

This allows the client to set some of the fields in NickwInfo that are sent to every client. These
fields need to be reasserted after a migration. The fields that can be set include STATUS and
NICK_FLAGS2 (some flags ignored).
Name Type Notes
tlvs Rest of SNAC array of TLV [Class: OSERVICE__NICK_INFO_TAGS] TLVs to set

SNAC: OSERVICE__BART_REPLY - Foodgroup:1 Type:33

This reply is used to tell the client that a BART item needs to be uploaded or changed.
Name Type Notes
replyIds Rest of SNAC array of BART__ID BART IDs and their status on the BART server

SNAC: OSERVICE__BART_QUERY2 - Foodgroup:1 Type:34

This query sees if the BART IDs are available; OSERVICE__BART_REPLY2 is sent as a response.
Name Type Notes
ids Rest of SNAC array of BART__ID BART ids to query

SNAC: OSERVICE__BART_REPLY2 - Foodgroup:1 Type:35

This SNAC is sent on initial login about items in the personality section of the Feedbag. It is also
used in response to a OSERVICE__BART_QUERY2.
Name Type Notes
Rest of SNAC array Information on BART IDs that were
reply_ids
of BART__QUERY_REPLY_ID queried
Foodgroup: BUDDY
The BUDDY foodgroup is used to send clients notifications about the state of other users in their
Buddy List. This can also include information about other users that the client has expressed a
temporary interest in. These temporary interests are only valid for the duration of the client's
session.

SNAC: BUDDY__ERROR - Foodgroup:3 Type:1

These are the error SNACs for the BUDDY foodgroup.
Name Type Notes
code u16 [Class: ERROR__CODE] Error code
errorTLVs Rest of SNAC array of TLV [Class: ERROR__TAGS] Optional error parameters

SNAC: BUDDY__RIGHTS_QUERY - Foodgroup:3 Type:2

This SNAC is optionally sent by the client to discover the client's and user's rights. This SNAC is
usually sent before the OSERVICE__CLIENT_ONLINE SNAC.
Name Type Notes
Rest of SNAC array [Class: BUDDY__RIGHTS_QUERY_TAGS] Qualifying
tlvs
of TLV parameters for query

TLV Class: BUDDY__RIGHTS_QUERY_TAGS

These are tags the client uses to inform the server of options for the BUDDY foodgroup.
Name Tag Type Notes
[Class:BUDDY__RIGHTS_QUERY_FLAGS] Flags that govern feature
FLAGS 5 u16
support

Class: BUDDY__RIGHTS_QUERY_FLAGS
These are the flags the client uses to inform the server what kinds of features it supports.
Name Value Notes
BART_SUPPORTED 0x0001 Want to receive BART items
Want to receive ARRIVE/DEPART for all users on a Buddy
INITIAL_DEPARTS 0x0002
List, even those offline
OFFLINE_BART_SUPPO Want to receive BART items for offline buddies, excluding
0x0004
RTED location
REJECT_PENDING_BU If set and INITIAL_DEPARTS is set, use REJECT on pending
0x0008
DDIES buddies instead of DEPART

SNAC: BUDDY__RIGHTS_REPLY - Foodgroup:3 Type:3

This is the response the server sends to a BUDDY__RIGHTS_QUERY SNAC.
Name Type Notes
Rest of SNAC array [Class: BUDDY__RIGHTS_REPLY_TAGS] TLVs with rights
tlvs
of TLV information
TLV Class: BUDDY__RIGHTS_REPLY_TAGS
This class contains information from the server about the BUDDY foodgroup.
Name Tag Type Notes
MAX_BUDDIES 1 u16 Number of loginIds the user can have on their Buddy List
Number of online users who can simultaneously watch this
MAX_WATCHERS 2 u16
user
MAX_TEMP_BUDDIE
4 u16 Number of temporary buddies
S

SNAC: BUDDY__REJECT_NOTIFICATION - Foodgroup:3 Type:10

In the event that one or more of the loginIds specified in the user's Buddy List are overloaded with
watchers, the "interest" expressed by our user in those nicknames may be rejected and one or more
of these notifications are sent.
Name Type Notes
loginIds Rest of SNAC array of string08 Names being rejected

SNAC: BUDDY__ARRIVED - Foodgroup:3 Type:11

This notification, potentially batched, indicates that one or more users on the client's Buddy List has
signed on or updated their information. Due to nature of the server architecture, expect redundant
arrived notifications for a given user which may, or may not contain updated information. Also,
offline users with status messages or BART items may be sent as "arrived", so always check the
NICK_FLAGS to see if the user is online; NICK_FLAGS will be zero if offline.
Name Type Notes
arrivedInfos Rest of SNAC array of OSERVICE__NickwInfo User's state being updated

SNAC: BUDDY__DEPARTED - Foodgroup:3 Type:12

This potentially batched notification indicates that one or more users on the client's Buddy List has
signed off.
Name Type Notes
arrivedInfos Rest of SNAC array of OSERVICE__NickwInfo User's state being updated

SNAC: BUDDY__ADD_TEMP_BUDDIES - Foodgroup:3 Type:15

This SNAC adds one or more loginIds to the client's temporary Buddy List. Temporary buddies are
used when the user does not want to add a loginId to their Buddy List, but the client has a desire to
find out about updates in real time. For example, when IMing a user not on the Buddy List,
temporary buddies are used for displaying state in the IM window. Redundant additions are ignored
and if any error is encountered during the processing of the SNAC, the whole transaction is backed
out -- nobody is added to the Buddy List. When the client disconnects, the temporary list is
automatically cleared. If a Buddy requires authorization then an offline or REJECT SNAC will be
received.
Name Type Notes
loginIds Rest of SNAC array of string08 Names to add to the list to watch
SNAC: BUDDY__DEL_TEMP_BUDDIES - Foodgroup:3 Type:16
This SNAC deletes one or more users from the client's temporary Buddy List. If any error is
encountered during the processing of the SNAC, the whole transaction is backed out -- nobody is
deleted from the list.
Name Type Notes
loginIds Rest of SNAC array of string08 names to remove from the list being watched

Foodgroup: PD
The PD foodgroup is used for the control of Permit/Deny settings for the user

SNAC: PD__ERROR - Foodgroup:9 Type:1

This is the error SNAC for the PD foodgroup.
Name Type Notes
code u16 [Class: ERROR__CODE] Error code
errorTLVs Rest of SNAC array of TLV [Class: ERROR__TAGS] Optional error parameters

TLV Class: PD__RIGHTS_REPLY_TAGS

This class contains information from the server about the PD foodgroup.
Name Tag Type Notes
MAX_PERMITS 1 u16 Number of permit entries a user is allowed
MAX_DENIES 2 u16 Number of deny entries a user is allowed
MAX_TEMP_PERMITS 3 u16 Number of temporary permit entries a client is allowed

SNAC: PD__RIGHTS_QUERY - Foodgroup:9 Type:2

This is a query sent to the server by the client to discover what some of its rights are with respect to
the PD SNAC group.
This SNAC has no fields and is always empty.

SNAC: PD__RIGHTS_REPLY - Foodgroup:9 Type:3

This SNAC is the response to the PD__RIGHTS_QUERY SNAC.
Name Type Notes
Rest of SNAC array [Class: PD__RIGHTS_REPLY_TAGS] TLVs with rights
tlvs
of TLV information

SNAC: PD__ADD_TEMP_PERMIT_LIST_ENTRIES - Foodgroup:9 Type:10

This SNAC adds one or more entries to the temporary permit list. A loginId in this list will bypass
the Feedbag permit/deny lists and always be permitted.
Name Type Notes
loginIds Rest of SNAC array of string08 Names to add from the temporary allow list

SNAC: PD__DEL_TEMP_PERMIT_LIST_ENTRIES - Foodgroup:9 Type:11

This SNAC deletes one or more entries in the temporary permit list.
Name Type Notes
loginIds Rest of SNAC array of string08 Names to remove from the temporary allow list

Foodgroup: LOCATE
The LOCATE foodgroup allows the discovery and setting of personalization features such as AIM
signatures and away messages. The AIM signature has been surfaced under many different names in
AIM products, such as AIM Profile, AIM Buddy Info, and AIM Get Info.

SNAC: LOCATE__ERROR - Foodgroup:2 Type:1

This is the error SNAC for the LOCATE foodgroup.
Name Type Notes
code u16 [Class: ERROR__CODE] Error code
errorTLVs Rest of SNAC array of TLV [Class: ERROR__TAGS] Optional error parameters

TLV Class: LOCATE__RIGHTS_REPLY_TAGS

This class contains information from the server about the LOCATE foodgroup.
Name Tag Type Notes
MAX_SIG_LEN 1 u16 Maximum signature length for this user
MAX_CAPABILITIES_LEN 2 u16 Number of full UUID capabilities allowed
MAX_FIND_BY_EMAIL_LIS Maximum number of email addresses to look up at
3 u16
T once
MAX_CERTS_LEN 4 u16 Largest CERT length for end to end encryption
MAX_SHORT_CAPABILITIE
5 u16 Number of short UUID capabilities allowed
S

SNAC: LOCATE__RIGHTS_QUERY - Foodgroup:2 Type:2

This query is sent to the server by the client to discover what some of its rights are with respect to
the PD SNAC group.
This SNAC has no fields and is always empty.

SNAC: LOCATE__RIGHTS_REPLY - Foodgroup:2 Type:3

This is the response to the LOCATE__RIGHTS_QUERY SNAC.
Name Type Notes
Rest of SNAC array [Class: LOCATE__RIGHTS_REPLY_TAGS] TLVs with rights
tlvs
of TLV information

TLV Class: LOCATE__TAGS

These are the possible tags for the SET_INFO and GET_INFO SNACs.
Name Tag Type Notes
SIG_TYPE 1 string Signature's MIME type
SIG_DATA 2 string Signature data, also called the get info profile
UNAVAILABLE_TYP 3 string Away message MIME type
E
UNAVAILABLE_DAT
4 string Away message data
A
Array
CAPABILITIES 5 Capabilities of the client
of UUID
SIG_TIME 10 t70 Time the signature was set
UNAVAILABLE_TIM
11 t70 Time the away message was set
E
SUPPORT_HOST_SI
12 u08 If true, enable server based profiles
G
HTML_INFO_TYPE 13 string Host based Buddy Info MIME type
Host based Buddy Info data that the client should
HTML_INFO_DATA 14 string
display in a browser window

SNAC: LOCATE__SET_INFO - Foodgroup:2 Type:4

The client may set SIG, UNAVAILABLE, and CAPABILITIES type and data tags with this SNAC.
A tag with no data clears the SIG, UNAVAILABLE message, or CAPABILITIES.
Name Type Notes
[Class: LOCATE__TAGS] Information to set or replace - empty tags will cause
infoData TLV
that data to be cleared; tags not present will cause no change

Class: LOCATE__QUERY_TYPE
This class specified which fields the client wants returned when doing a USER INFO QUERY2.
Name Value Notes
SIG 0x00000001 The AIM signature
UNAVAILABLE 0x00000002 The away message
CAPABILITIES UUID array; short caps will be represented in
CAPABILITIES 0x00000004
long form
CERTS 0x00000008 The CERT Blob
HTML_INFO 0x00000400 Return HTML formatted Buddy Info page

SNAC: LOCATE__USER_INFO_QUERY2 - Foodgroup:2 Type:21

This SNAC is sent by the client to perform the basic locate query on a user. A client should only use
this SNAC when it needs to display information to a user and should not call on every Buddy
arrive. Either a LOCATE__USER_INFO_REPLY or a LOCATE__ERROR will be generated.
Name Type Notes
[Class: LOCATE__QUERY_TYPE] What data should be
type2 u32
returned
loginId string08 User for which to the information requested

SNAC: LOCATE__USER_INFO_REPLY - Foodgroup:2 Type:6

This is the usual response to a LOCATE__USER_INFO_QUERY2 SNAC.
Name Type Notes
info OSERVICE__NickwInfo Generic nick with info about user
locateInfo Rest of SNAC array of TLV [Class: LOCATE__TAGS] Fields requested in the query

SNAC: LOCATE__FIND_LIST_BY_EMAILS - Foodgroup:2 Type:19

This is a query sent to the server that looks up a list of users by their email address and returns one
NickwInfo for each email account queried. There can be only one outstanding query at a time. The
maximum number of emails is specified in the LOCATE__RIGHTS_REPLY.
 If the user has multiple accounts online, a random full NickwInfo is returned.
 If the user has no accounts online, a random NickwInfo with just the displayId filled in is
returned.
 If the user does not have an account, or their accounts are marked as not to be returned, then
their email address is not included in the array of results. Since this is the case, it is possible
to have an empty SNAC returned.
Name Type Notes
emails Rest of SNAC array of string16 List of email addresses to look up

SNAC: LOCATE__FIND_LIST_REPLYS - Foodgroup:2 Type:20

This SNAC provides the results of the LOCATE__FIND_LIST_BY_EMAILS.
Name Type Notes
Rest of SNAC array Information about all the email addresses that
infos
of LOCATE__NickwInfo_Email were queried

Datatype: LOCATE__NickwInfo_Email
This is the data structure that makes it easy to link a NickwInfo and an email address.
Name Type Notes
info OSERVICE__NickwInfo Info for loginId that matched the email address
email string16 Email address requested

Foodgroup: ICBM
ICBM, or Inter Client Basic Message, is a foodgroup focused around protocol messages that are
sent between users or clients.
Name Size Notes
ICBM__Cookie 8 byte Opaque data used to link conversations

Class: ICBM__CHANNELS
Messages sent between users are sent on a specific channel that narrow down how they should be
processed and possible rate size parameters.
Name
Value Notes
IM 1 Normal IM channel; all clients are expected to understand this channel
RENDEZVOUS 2 For rendezvous negotiations and sending data between clients

Class: ICBM__PARAMETER_FLAGS
These are flags the client uses to inform the server what kinds of features it supports for the ICBM
channel.
Name Value Notes
CHANNEL_MSGS_ALLOW
0x00000001 Wants ICBMs on this channel
ED
MISSED_CALLS_ENABLE
0x00000002 Wants MISSED_CALLS on this channel
D
EVENTS_ALLOWED 0x00000008 Wants CLIENT_EVENTs
SMS_SUPPORTED 0x00000010 Aware of sending to SMS
OFFLINE_MSGS_ALLOWE Support offline IMs; client is capable of storing and
0x00000100
D retrieving

Class: ICBM__ERROR_SUBCODE
These are subcodes used with standard errors.
Name Value Notes
REMOTE_IM_OFF 1 Used with NOT_LOGGED_ON
REMOTE_RESTRICTED Used with NOT_LOGGED_ON; the remote side denied
2
_BY_PC because of parental controls
NEED_SMS_LEGAL_TO User tried to send a message to an SMS user and is required to
3
_SEND accept the legal text first
SMS_WITHOUT_DISCL Client tried to send a message to an SMS user without the
4
AIMER character counter being displayed
SMS_COUNTRY_NOT_A Client tried to send a message to an SMS user but the SMS
5
LLOWED matrix said the country code combination not permitted
SMS_UNKNOWN_COUN Client tried to send to an SMS user but the server could not
8
TRY determine the country
CANNOT_INITIATE_IM 9 An IM cannot be initiated by a BOT
IM_NOT_ALLOWED 10 An IM is not allowed by a consumer BOT to a user
CANNOT_IM_USAGE_L An IM is not allowed by a consumer BOT due to reaching a
11
IMITED generic usage limit, not common
CANNOT_IM_DUSAGE_ An IM is not allowed by a consumer BOT due to reaching the
12
LIMITED daily usage limit
CANNOT_IM_MUSAGE_ An IM is not allowed by consumer BOT due to reaching the
13
LIMITED monthly usage limit
OFFLINE_IM_NOT_ACC
14 User does not accept offline IMs
EPTED
OFFLINE_IM_EXCEED_
15 Exceeded max storage limit
MAX

SNAC: ICBM__ERROR - Foodgroup:4 Type:1

This is the error SNAC for the ICBM foodgroup.
Name Type Notes
code u16 [Class: ERROR__CODE] Error code
errorTLVs Rest of SNAC array of TLV [Class: ERROR__TAGS] Optional error parameters
SNAC: ICBM__ADD_PARAMETERS - Foodgroup:4 Type:2
This SNAC is typically sent prior to sending the CLIENT_ONLINE so that the server is properly
initialized with the clients' preferences, although it can be sent at any time to update the situation.
The default flag settings allow everything and have missed call notifications turned on. The default
values for the other values may be obtained from the server by issuing a PARAMETER_QUERY.
The minInterICBMInterval is the minimum spacing the server will allow between ICBMs sent to
the client. This is used in conjunction with maxIncomingICBMLen to limit the impact that
incoming ICBMs can have on the client's total available bandwidth. The "channel" field specifies to
which channel these parameters apply. There are a maximum number of channel "slots" available to
a client. The exact number can be obtained via a PARAMETER_QUERY. A channel number of 0
(zero) is the reserved channel number to be used to set the default parameters for all channels.
Therefore, the channel 0 parameters will be applied to all channels unless channel specific
parameters are supplied via the ADD_PARAMETERS call which overrides the defaults. The
maximum number of slots does not apply to channel 0.
Name Type Notes
[Class: ICBM__CHANNELS] To which channel these parameters
channel u16
apply, or 0 for the defaults
icbmFlags u32 [Class: ICBM__PARAMETER_FLAGS] Controlling flags
Maximum size of an ICBM the client wants to receive; the range is
maxIncomingICBMLen u16
from 80 to 8000
When receiving an ICBM, the maximum evil level of the sender;
maxSourceEvil u16
the range is from 0 to 999
When sending an ICBM, the maximum evil level of destination;
maxDestinationEvil u16
the range is from 0 to 999
minInterICBMInterval u32 How often the client wants to receive ICBMs in milliseconds

SNAC: ICBM__DELETE_PARAMETERS - Foodgroup:4 Type:3

These are the delete all parameters for a given channel. This action is allowed for all channels other
than zero. This would typically be used if a client ran out of parameter slots and needed to free one
up.
Name Type Notes
channel u16 Channel to delete the parameters set with ADD_PARAMETERS

SNAC: ICBM__PARAMETER_QUERY - Foodgroup:4 Type:4

This SNAC requests the PARAMETER_REPLY from the server. This is typically used prior to
sending the CLIENT_ONLINE in order to determine the default parameter settings for all channels.
It is not required.
This SNAC has no fields and is always empty.

SNAC: ICBM__PARAMETER_REPLY - Foodgroup:4 Type:5

This SNAC is sent by the server in response to a PARAMETER_QUERY - see the
ADD_PARAMETERS for more information.
Name Type Notes
maxSlots u16 Represents the maximum number of parameter slots available
icbmFlags u32 [Class: ICBM__PARAMETER_FLAGS] Controlling flags
Maximum size of an ICBM the client wants to receive; the range is
maxIncomingICBMLen u16
from 80 to 8000
When receiving an ICBM, the maximum evil level of the sender;
maxSourceEvil u16
the range is from 0 to 999
When sending an ICBM, the maximum evil level of the
maxDestinationEvil u16
destination; the range is from 0 to 999
minInterICBMInterval u32 How often the client wants to receive ICBMs in milliseconds

Class: ICBM__IM_SECTION_ENCODINGS
An IM can be encoded in the following different forms:
Name Value Notes
ASCII 0 ANSI ASCII -- ISO 646
UNICODE 2 ISO [Link]-2 Unicode
LATIN_1 3 ISO 8859-1

Datatype: ICBM__IM_SECTION
An IM can be broken up into multiple sections and encodings. Most clients do not do this anymore
and use a single section; however old AOL clients did this to save bandwidth. :) Anyone remember
those days?
Name Type Notes
encoding u16 [Class: ICBM__IM_SECTION_ENCODINGS] Encoding of the data
language u16 Language of the data for old clients; new clients should just use 0
The IM text; array of u16 if encoding is
data blob
ICBM__IM_SECTION_ENCODINGS_UNICODE, otherwise u08

TLV Class: ICBM__IM_DATA_TAGS

These are the tags inside the IM_DATA TLV of an IM channel ICBM; order matters. For the
IM_CHANNEL there should be one IM_CAPABILITIES followed by one or more IM_TEXT tags.
Name Tag Type Notes
ICBM__IM_SECTIO The actual IM text; there can be multiple of
IM_TEXT 0x0101
N these
IM_CAPABILITIES 0x0501 u08 Old client support; should just be the value 1
MIME_ARRAY 0x0D01 u16 Short caps

Class: ICBM__RENDEZVOUS_MESSAGE
This is a type of rendezvous/data message.
Name Value Notes
PROPOSE 0 Propose a rendezvous
CANCEL 1 Cancel a proposal you generated
ACCEPT 2 Accept a proposal someone else generated

Class: ICBM__RENDEZVOUS_CANCEL_REASONS
These are the reasons a proposal is cancelled.
Name Value Notes
UNKNOWN 0 Reason not specified
USER_CANCEL 1 Recipient user declined
TIMEOUT 2 Timeout
ACCEPTED_ELSEWHERE 3 Proposal was accepted by a different instance of the user

TLV Class: ICBM__RENDEZVOUS_TAGS

These are the tags inside the DATA TLV of the RENDEZVOUS channel in ICBM.
Name Tag Type Notes
CHANNEL 1 u16 ICBM channel on which the rendezvous is to occur
IP_ADDR 2 u32 IP address proposed for the rendezvous
PROPOSER_IP_
3 u32 IP address of the proposing client
ADDR
VERIFIED_IP_A IP address of the proposing client as seen by server; NOTE -
4 u32
DDR this TLV may only be added by the server
PORT 5 u16 Port value of the client for rendezvous
DOWNLOAD_U
6 string URL for downloading software to support the service
RL
Same as DOWNLOAD_URL, but added by server if the
VERIFIED_DOW
8 string service is well known; Note - this TLV may only be added by
NLOAD_URL
the server
Identifies which proposal this is in the rendezvous
conversation; the initial proposal has sequence_num 1;
SEQUENCE_NU NOTE - this tag is required in *all* rendezvous *proposal*
10 u16
M payloads and may only occur in proposal payloads; each
proposal applying to a given rendezvous cookie increments
the sequence_num by one
[Class:ICBM__RENDEZVOUS_CANCEL_REASONS] Re
CANCEL_REAS
11 u16 ason for cancelling a rendezvous; this tag must be present in
ON
all RENDEZVOUS_CANCEL payloads.
INVITATION 12 string Text inviting the other player to join
INVITE_MIME_
13 string Charset used by the data
CHARSET
INVITE_MIME_
14 string Language used by the data
LANG
REQUEST_HOST
15 empty Requests that the server check caps for recipient
_CHECK
REQUEST_USE_ Requests that the Rendezvous Server be used as a transport
16 empty
ARS for the data
REQUEST_SECU
17 empty Requests that SSL be used for the connection
RE
MAX_PROTOCO
18 u16 Maximum application protocol version supported
L_VERSION
MIN_PROTOCO
19 u16 Minimum application protocol version supported
L_VERSION
COUNTER_REA 20 u16 Reason for a counter proposal
SON
INVITE_MIME_
21 string Content-type used by the data
TYPE
IP_ADDR_XOR 22 u32 IP_ADDR ^ 0xFFFFFFFF
PORT_XOR 23 u16 PORT ^ 0xFFFF
Array of
ADDR_LIST 24 List of "IP port" pairs to try
string08
SESSION_ID 25 string Identifier for session
ROLLOVER_ID 26 string Identifier of session to rollover
SERVICE_DATA 10001 blob Service specific data

Datatype: ICBM__IM_RENDEZVOUS
There are three different types of rendezvous messages - propose, cancel, and accept.
PROPOSE
This is the message that a client sends to the server to propose a rendezvous with another
client. The tag values to be used in the TLV are the ones specified in
RENDEZVOUS_TLV_TAGS. Proposals typically specify either a
RENDEZVOUS__CHANNEL or a RENDEZVOUS_IP_ADDR/PORT pair. If neither is
specified, the systems which are rendezvousing must know out-of-band how to connect to
each other (e.g., a server IP_ADDR compiled into a third party client). If specifying
RENDEZVOUS_IP_ADDR, the client may also specify PROPOSER_IP_ADDR which is the
IP address that it identifies itself by, as found by a call to get_local_host. If
PROPOSER_IP_ADDR is used, VERIFIED_IP_ADDR is added by the server before sending
the RENDEZVOUS_PROPOSAL_TO_CLIENT. VERIFIED_IP_ADDR may not be
specified by the client in RENDEZVOUS_PROPOSAL_TOHOST. Likewise, if
DOWNLOAD_URL is specified and the service UUID matches a well known service, the
server may add VERIFIED_DOWNLOAD_URL. The client may not specify
VERIFIED_DOWNLOAD_URL itself.
Additionally, the client can send any tags specific to a given service as long as the tag values
fall outside the reserved range defined above.
NOTE: Reserved tag values MUST be at the beginning of the TLV. The server will stop
parsing the TLV as soon as it encounters the first non-reserved tag.
CANCEL
This message is sent by the sender of a RENDEZVOUS_PROPOSAL_TOCLIENT in order
to indicate a desire to cancel the rendezvous. Note that due to timing issues, the cancel may
arrive at the other client after the other client has acted on the rendezvous proposal. In other
words, cancel is an advisory message only. The sender should take other precautions to
prevent a rendezvous attempt from succeeding (e.g., shut down any systems which are
listening, etc.).
ACCEPT
This message is sent by the recipient of a PROPOSE in order to indicate that it has completed
the rendezvous. It may contain modifications to the original PROPOSE TLVs indicating
different levels of feature support (e.g., version negotiation).

Name Type Notes

[Class: ICBM__RENDEZVOUS_MESSAGE] What kind of
type u16
rendezvous message is this
Opaque data generated by conversation initiator and used to link up
cookie ICBM__Cookie
the conversation and errors
service UUID Identifies type of data message being exchanged
Rest of SNAC array [Class: ICBM__RENDEZVOUS_TAGS] Message data and
params
ofTLV parameters

TLV Class: ICBM__TAGS

These are the TLV tags used in TOHOST and TOCLIENT SNACs.
Name Tag Type Notes
[Class:ICBM__IM_DATA_TAGS] Message data for
the IM channel only; unlike other TLVs the order of
IM_DATA 2 Array of TLV TLVs inside this tag does matter - it should be the
CAPABILITIES item followed by multiple IM_TEXT
items
Host will acknowledge this ICBM upon sending it to
REQUEST_HOS
3 empty the destination client; this does NOT mean the
T_ACK
destination user received it
This message is an auto response; this tag is not
AUTO_RESPON
4 empty allowed with either the REQUEST_HOST_ACK or
SE
STORE tags
ICBM__IM_REN
DATA 5 Message data for all other channels
DEZVOUS
If the user is offline then store this message for
delivery the next time the user logs in when possible;
STORE 6 empty
AIM and ICQ use complex privacy rules that control
if an offline IM delivery is allowed or not
Used in TO_CLIENT only, it is added by the server if
WANT_EVENTS 11 empty
the sender wants client events
If desired BART items can be sent with the ICBM, the
BART 13 BART__ID client should override the ones in NickwInfo with
these
SEND_TIME 22 t70 Time when the server received the offline IM
FRIENDLY_NA For WIMZI this is the friendly name of the
23 string
ME anonymous user
ANONYMOUS 24 empty This is an anonymous IM

SNAC: ICBM__CHANNEL_MSG_TOHOST - Foodgroup:4 Type:6

This is the basic inter-client message after which the group was named (Inter-Client Basic
Messages). Once at the server, the SNAC is reformatted into a CHANNEL_MSG_TOCLIENT
before it is sent to the destination user.
Name Type Notes
Opaque data generated by conversation initiator and used to link
cookie ICBM__Cookie
up the conversation and errors
channel u16 [Class: ICBM__CHANNELS] Channel the message is on
destLoginId string08 Destination loginId, who should receive the message
Rest of SNAC [Class: ICBM__TAGS] Message data and parameters; it must
icbmTlvs
array ofTLV contain either the IM or DATA tag
SNAC: ICBM__CHANNEL_MSG_TOCLIENT - Foodgroup:4 Type:7
This is the CHANNEL_MSG_TOHOST after it has been reformatted by the server and sent to the
destination client.
Name Type Notes
Opaque data generated by conversation initiator and used to link
cookie ICBM__Cookie
up the conversation and errors
channel u16 [Class: ICBM__CHANNELS] Channel the message is on
OSERVICE__Nick
info Information about the sender of the message
wInfo
icbmTlvs TLV [Class: ICBM__TAGS] Actual message

Class: ICBM__EVIL_REQUEST_FLAGS
These are the flags that control how EVIL should work.
Name Value Notes
ANONYMOUS 0x0001 Do not reveal my loginId to the evilee.

SNAC: ICBM__EVIL_REQUEST - Foodgroup:4 Type:8

This requests that the specified loginId is sent an EVIL notification . If the request is marked as
anonymous, less EVILing may be done. The result of the evil request is returned in an
EVIL_REPLY (or an error). One may only EVIL another user if that user has "recently" sent the
EVILing user a CHANNEL_MSG and the other user started the conversation. To implement this
rule, the server keeps a short list of users who have recently sent messages to a given user. If the
user to be EVILed has rolled off this list, or was never on it, the EVIL request is denied via
ERR_REQUEST_DENIED.
Name Type Notes
[Class: ICBM__EVIL_REQUEST_FLAGS] What kind of EVIL to
evilFlags u16
perform
evilLoginId string08 Who to try to EVIL

SNAC: ICBM__EVIL_REPLY - Foodgroup:4 Type:9

The reply tells the requester, the sender of an EVIL_REQUEST SNAC, how much EVIL, if any,
was applied to the recipient and provides an updated accounting of their total EVIL if
evilDeltaApplied is non-zero.
Name Type Notes
evilDeltaApplied u16 How much EVIL was applied to the requestee
updatedEvilValue u16 Requestee's new EVIL value

Class: ICBM__MISSED_CALL_REASONS
These are the reasons sent to a receiver why they could not receive an IM from a sender.
Name Value Notes
TOO_LARGE 0x0001 Sender's message was too large
RATE_EXCEEDED 0x0002 Sender exceeded the receiver's rate limit
EVIL_SENDER 0x0004 Message rejected because sender is EVIL
EVIL_RECEIVER 0x0008 Message rejected because receiver is EVIL

Datatype: ICBM__Missed_Call
This represents a single missed IM from a sender, sent to the potential receiver.
Name Type Notes
channel u16 Channel on which the missed message was
OSERVICE__NickwInf
senderInfo Information about the sender
o
numMissed u16 How many messages were dropped
[Class: ICBM__MISSED_CALL_REASONS] Why the IM
reason u16
failed

SNAC: ICBM__MISSED_CALLS - Foodgroup:4 Type:10

When the server is unable to send one or more messages to the client, the server sends this SNAC to
the client to let it know that it missed some messages ("calls"). It does this at the earliest possible
time (e.g., at the first available time slot allowed by minInterICBMInterval). So if user A sends a
message to user B, and the server denies sending to user B because of size, user A gets an error and
user B gets a missed call.
Name Type Notes
Rest of SNAC array Information about the messages that were
missedCallArray
of ICBM__Missed_Call missed

Class: ICBM__RENDEZVOUS_NAK
Sent in ICBM__CLIENT_ERR errorInfo field
Name Value Notes
PROPOSAL_UNSUPPORTED 0 Proposal UUID not supported
PROPOSAL_DENIED 1 Not authorized, or user declined
PROPOSAL_IGNORED 2 DO NOT USE; 'ignores' should no-op
BUSTED_PARAMETERS 3 Proposal malformed
PROPOSAL_TIMED_OUT 4 Attempt to act on proposal (e.g. connect) timed out
ONLINE_BUT_NOT_AVAILABLE 5 Recipient away or busy
INSUFFICIENT_RESOURCES 6 Recipient had internal error
RATE_LIMITED 7 Recipient was ratelimited
NO_DATA 8 Recipient had nothing to send
VERSION_MISMATCH 9 Incompatible versions
SECURITY_MISMATCH 10 Incompatible security settings
SERVICE_SPECIFIC_REASON 15 Service-specific reject defined by client

Class: ICBM__CLIENT_ERRORS
The following are Inter-Client error codes.
Name Value Notes
UNSUPPORTED_CHA
1 Receiving client does not understand the channel
NNEL
BUSTED_ICBM_PAYL
2 Receiving client thinks the payload is busted
OAD
CHANNEL_SPECIFIC_ See ICBM__RENDEZVOUS_NAK which will be inside the
3
ERROR errorInfo for values for ICBM__CHANNEL_RENDEZVOUS

SNAC: ICBM__CLIENT_ERR - Foodgroup:4 Type:11

This is one of the few SNACs that can be sent to the server and received by a client. This is because
the message is basically forwarded from the source client, to the server, to the destination client.
This SNAC may only be sent as a programmatic response to an inter-client message. It is used to
indicate that there was some problem with the original message received by the sender. If this
SNAC is not immediately generated as a response, the client loses the right to send it at all and
attempts to send it will be rejected by the server.
As transmitted, "cookie", "channel", and "loginId" are to be those which were presented in the inter-
client message being rejected. As received, "loginId" has been changed to indicate the source of the
error.
It is not allowed to respond to a CLIENT_ERR SNAC with another CLIENT_ERR SNAC.
Receiving a CLIENT_ERR SNAC does not grant the right to EVIL.
Name Type Notes
ICBM__Cook Opaque data generated by conversation initiator and used to link up the
cookie
ie conversation and errors
channel u16 [Class: ICBM__CHANNELS] Channel the message is on
loginId string08 Destination loginId when sending and the source loginId when received
code u16 [Class: ICBM__CLIENT_ERRORS] Error code
errorInfo blob Optional error info

TLV Class: ICBM__ACK_TLV_TAGS

These are the TLV tags used in HOST_ACK SNACs. New tags may be defined for future use
Name Tag Type Notes

SNAC: ICBM__HOST_ACK - Foodgroup:4 Type:12

This SNAC is sent by the server upon receipt of any CHANNEL_MSG_TOHOST which includes
the optional REQUEST_HOST_ACK TLV. "Cookie", "channel", and "loginId" should be provided
in the inter-client message being acknowledged.
Name Type Notes
Opaque data generated by conversation initiator and used to link up
cookie ICBM__Cookie
the conversation and errors
channel u16 [Class: ICBM__CHANNELS] Channel the message is on
loginId string08 Destination loginId that should receive the message
Rest of SNAC array
ackTlvs [Class: ICBM__ACK_TLV_TAGS] Extra TLVs in the response
ofTLV

SNAC: ICBM__OFFLINE_RETRIEVE - Foodgroup:4 Type:16

This requests CHANNEL_MSG_TOCLIENT messages be generated for each of the stored ICBMs.
Any message retrieved is deleted.
This SNAC has no fields and is always empty.

SNAC: ICBM__OFFLINE_RETRIEVE_REPLY - Foodgroup:4 Type:23

The server successfully processed the request to retrieve all the offline messages.
This SNAC has no fields and is always empty.

Class: ICBM__EVENTS
These are the codes used in the CLIENT_EVENT SNAC.
Name Value Notes
NONE 0 Default state; only sent if the user was typing but erased the message
TYPED 1 Indicates that the user was typing but has stopped for at least 2 seconds
Indicates the message is being actively composed; only send once when
TYPING 2
switching to this state, do NOT send for every character
RESERVED 3 Reserved
Indicates that the user closed the IM window; can be an issue in multiple
CLOSED 15
instance environments

SNAC: ICBM__CLIENT_EVENT - Foodgroup:4 Type:20

This SNAC is sent as a control message, sent by a client to inform the recipient of an event. At this
time the only events defined are NONE, TYPED, and TYPING. The client should send events only
after receiving a message that indicates events are desired. This is another SNAC that is both sent
and received by the client.
Name Type Notes
ICBM__Cook Opaque data generated by conversation initiator and used to link up the
cookie
ie conversation and errors
channel u16 [Class: ICBM__CHANNELS] Channel the message is on
loginId string08 Destination loginId when sending and the source loginId when received
event u16 [Class: ICBM__EVENTS] What event is happening

Foodgroup: INVITE
This is the foodgroup for inviting users to join AIM.

TLV Class: INVITE__TAGS

These are the tags used when inviting a user to join the AIM service.
Name Tag Type Notes
EMAIL 17 string Email address to invite
PERSONALIZED_TEXT 21 string Personalized message to send in an invite

SNAC: INVITE__ERROR - Foodgroup:6 Type:1

This is the error SNAC for the INVITE foodgroup.
Name Type Notes
code u16 [Class: ERROR__CODE] Error code
errorTLVs Rest of SNAC array of TLV [Class: ERROR__TAGS] Optional error parameters

SNAC: INVITE__REQUEST - Foodgroup:6 Type:2

This SNAC contains a request to send an invite to join AIM to a given email address. The server
will perform a lookup on the email address and if already a member will return an error.
Name Type Notes
[Class: INVITE__TAGS] Email and message to
inviteTLVs Rest of SNAC array of TLV
send

SNAC: REQUEST_ACK - Foodgroup:6 Type:3

This SNAC is sent in reply to a successful REQUEST.
This SNAC has no fields and is always empty.

Foodgroup: FEEDBAG
A Feedbag is the stored Buddy List and server based preferences for an AIM user. The client has
direct access to manipulate the Feedbag in any way it sees fit, including corrupting it. The server
has some checks in place to prevent destruction, but a client developer must be careful not to
corrupt things.
Class
All the entries in the Feedbag are assigned a class, which defines the characteristics of how
they should behave. The class is represented by a numeric classId with each entry.
Item
An item is a generic term that is used for any entry that can be added to a user's Feedbag. An
item can be a group, a Buddy, a preference, a permit/deny entry, or anything else. All items
have a name (which can be empty), a groupId, an itemId, a classId, and attributes with
groupId and itemId being unique. The groupId and itemId can have values between 0 and
32767; values between 32768 and 65535 are reserved. The client is responsible for picking
new groupId and itemIds.
Group
A group is a special type of item that is always represented by using an itemId of 0 and classId
of GROUP. All items live inside of a group, with items that use a groupId of 0 being called in
the Root Group. All group items have an ORDER attribute that describes how the items in the
group should be ordered, since the order in Feedbag can be random.

Sample:
groupId itemId classId Name Attributes
0 0 GROUP(0) ORDER(200):321 10
0 1805 DENY(3) spimmer123
0 4046 BART(20) 5 BART_INFO(213): 00052b000013b9
PD_MODE(202): 04
0 12108 PDINFO(4) PD_MASK(203): ffffffff
PD_FLAGS(204): 00000001
10 0 GROUP(1) Friends ORDER(200): 110 147
10 110 BUDDY(0) ChattingChuck
10 147 BUDDY(0) example@[Link]
321 0 GROUP(1) Empty Group ORDER(200):
Feedbag Implementation Notes
Basics
A Feedbag consists of zero or more items. Feedbags are interpreted by the server and the client. All
strings in Feedbag are UTF8 encoded.
It is mandated that only users or the server shall delete information from the user's Feedbag. A client
may not delete, or "forget", information if it does not support or recognize the information; deleting
corrupt items is permitted.
For instance, a user loads a special Buddy tagging plugin on a machine at home but does not have
this plugin at work. Changes made to the user's Feedbag (aka, Buddy List) at work shall not delete
(or "forget") the user's Buddy tagging plugin attributes from the Feedbag.
Finally, subject to the rules outlined below, all items in the Feedbag are optional. If a client does not
see an item or attribute on an item, it should adopt a sensible default. For example, if the PDINFO
item is not present, the client should assume permit-all mode.

Root Group
In any Feedbag that contains groups there should exist a 'root group' that has an empty name, group
id 0, item id 0, and a class id 1 (GROUP). This root group contains the group ordering in an
ORDER attribute. If the root group does not exist and a group is to be added, the client should
create the root group first. The Root Group should never be deleted by the client.
Note that some classes of items can only be in the root group and some classes of items can only be
in regular groups. For example, buddies can only be in regular groups but permit/deny entries can
only be in the root group. See the class enumerations for more information where items can exist.

Ordering of Feedbag
For a FEEDBAG__REPLY, the items in the Feedbag are guaranteed to be ordered. They are sorted
by group id and then by item id. Thus, the root group is first, followed by groupless items (permits,
denies, etc.), followed by the group with the lowest group id, followed by its items, followed by the
next group, etc.

Display of Buddy List

A client can offer several methods for sorting the display of the Buddy List. One of the offered
methods should be the "Natural Order" which is calculated by using the ORDER attribute of each
group. A client should NOT use the order of items in the Feedbag for display, since the items can be
in random order. If a user reorders their Buddy List, only the ORDER attribute needs to be changed;
the itemIds should stay the same.

Naming rules
The root group must have "" for its name.
Regular groups must have unique names independent of case (e.g., if you have a group "abc", you
can also have "a b c" but not "aBc"). This is the way the old client worked, so we need to keep it
this way.
Items in the root group must have unique compressed names for their class (e.g., if you have an
item "abc" with class==PERMIT, you cannot have "aBc" or "a b c" with class==PERMIT, but you
could have "abc" with class==DENY).
Classes limited to a single item, such as Buddy-prefs and pdinfo, should have "" for the name of the
item.
Items in groups must have unique compressed names in the group (e.g., if you have a Buddy "abc"
in a group, you cannot have a Buddy "a bc").

Preventing corruption
In an effort to prevent corruption of the order attribute, when the client adds a Buddy/group, the
client should only send the INSERT/UPDATE for the group/root after the INSERT for the
Buddy/group returns its STATUS. This way if there is a failure, the ORDER can be fixed before it is
sent in the INSERT/UPDATE. In cases where a group and a Buddy are added, this can mean
sending the Buddy INSERT, waiting for the STATUS, sending the group INSERT, waiting for the
STATUS, then sending the root INSERT/UPDATE.

Optimizations
The client should strive to optimize its transactions with the server. This means that even if several
item attributes are changed by the user, the client should send only one UPDATE_ITEM.
Additionally, the client should avoid sending redundant transactions such as an INSERT followed
by an UPDATE (the INSERT alone will be sufficient) or an INSERT followed by a DELETE
(nothing should be sent), or an UPDATE followed by a DELETE (just send the DELETE).

Class: FEEDBAG__RIGHTS_QUERY_FLAGS
These are the flags used in FEEDBAG__RIGHTS_QUERY to determine how Feedbag is treated.
Name Value Notes
INTERACTION_SUPPORTED 0x0001 Client supports interactions
AUTHORIZATION_SUPPORTED 0x0002 Client supports Buddy authorization
DOMAIN_SN_SUPPORTED 0x0004 Client supports a@[Link]
ICQ_NUM_SUPPORTED 0x0008 Client supports 1234567890
SMS_NUM_SUPPORTED 0x0010 Client supports +17035551212
ALIAS_ATTR_SUPPORTED 0x0020 Client supports alias attribute
SMARTGRP_SUPPORTED 0x0040 Client supports smart groups

TLV Class: FEEDBAG__RIGHTS_QUERY_TAGS

These are the types used in the Feedbag rights query.
Name Tag Type Notes
[Class:FEEDBAG__RIGHTS_QUERY_FLAGS] Flags that govern feature
FLAGS 11 u16
support

SNAC: FEEDBAG__ERROR - Foodgroup:19 Type:1

This is the error SNAC for the Feedbag foodgroup.
Name Type Notes
code u16 [Class: ERROR__CODE] Error code
errorTLVs Rest of SNAC array of TLV [Class: ERROR__TAGS] Optional error parameters
SNAC: FEEDBAG__RIGHTS_QUERY - Foodgroup:19 Type:2
This SNAC issues a query to the server for the client's Feedbag rights and to let the system know
what kind of Feedbag support it wants. This should be called before
the FEEDBAG__QUERY SNAC and before the OSERVICE__CLIENT_ONLINE. This is useful to
figure out how many items are allowed for each class type.
Name Type Notes
Rest of SNAC array [Class: FEEDBAG__RIGHTS_QUERY_TAGS] Qualifying
tlvs
of TLV parameters

TLV Class: FEEDBAG__RIGHTS_REPLY_TAGS

This class provides information from the server about the Feedbag foodgroup.
Name Tag Type Notes
Maximum size of all the attributes on a single
MAX_ITEM_ATTRS 3 u16
item
Array of
MAX_ITEMS_BY_CLASS 4 Maximum number of items per class
u16
MAX_CLIENT_ITEMS 5 u16 Total number of items with classId > 1024
Maximum length of name in Item that the
MAX_ITEM_NAME_LEN 6 u16
database supports
MAX_RECENT_BUDDIES 7 u16 How many RECENT_BUDDIES are allowed
INTERACTION_BUDDIES 8 u16 Top N interactions are buddies
INTERACTION_HALF_LIF
9 u32 Half life in 2^(-age/half_life) in seconds
E
INTERACTION_MAX_SCO
10 u32 Upper limit in interaction score
RE
MAX_BUDDIES_PER_GRO
12 u16 How many BUDDIES are allowed per group
UP
MAX_MEGA_BOTS 13 u16 How many BOT BUDDIES are allowed
MAX_SMART_GROUPS 14 u16 How many smart groups are allowed

SNAC: FEEDBAG__RIGHTS_REPLY - Foodgroup:19 Type:3

This is the response to the FEEDBAG__RIGHTS_QUERY SNAC.
Name Type Notes
Rest of SNAC array [Class: FEEDBAG__RIGHTS_REPLY_TAGS] TLVs with rights
tlvs
of TLV information

SNAC: FEEDBAG__QUERY - Foodgroup:19 Type:4

This SNAC is sent to query the Feedbag data stored on the server. This query only needs to be done
for the initial connection and should not be done after a migration.
This SNAC has no fields and is always empty.

Datatype: FEEDBAG__INTERACTION_INFO
The server tracks the last interaction time and generates a score with time decay for a frequency
display.
Name Type Notes
lastUpdate t70 The last interaction with this Buddy
score f32 The score; higher means more interactions

Class: FEEDBAG__CLASS_IDS
Class index constants:
 (R) means items of class should only be in the root group
 (G) means items of class should only be in regular groups
 (B) means items of class can be anywhere
Name Value Notes
BUDDY 0 (G) Names for Buddy List
GROUP 1 (R) Group Name
PERMIT 2 (R) Names for Permit List
DENY 3 (R) Names for Deny List
PDINFO 4 (R) PDMODE/PDMASK/PDFLAGS
BUDDY_PREFS 5 (R) Buddy List preferences
(R) Users not in the Buddy List; use this to store aliases or other
NONBUDDY 6
information for future use
(R) Client-specific preferences; name is name of client, e.g., "AIM
CLIENT_PREFS 9
Express"
(R) Timestamp; when a record of this class is inserted or updated in the
Feedbag, the server always adds a TIME_T attribute (overriding any
DATE_TIME 15 that may have been provided) containing the current date and time (or
one second greater than the old value, if required to keep the value
increasing)
BART 20 (R) BART IDs; name is the BART Type
(R) Order attribute lists recent buddies in the least to most recently used
RB_ORDER 21
order
PERSONALITY 22 (R) Collection of BART ids
AL_PROF 23 (R) Information about Account Linking prefrences
AL_INFO 24 (R) Account linking information
INTERACTION 25 (R) Non-Buddy interaction record
VANITY_INFO 29 (R) Vanity information kept at user logoff
FAVORITE_LOCA
30 (R) User's favorite locations
TION
BART_PDINFO 31 (R) BART PDMODE
CUSTOM_EMOTI
36 ICQ Custom Emoticons with BART_LIST attributes
CONS
MAX_PREDEFIN
36 Dummy value; Set to highest used ID
ED
MIN 1024 (B) Values above this are valid indexes

Class: FEEDBAG__PD_MODE
The permit deny system can be in the following different modes.
Name Value Notes
PERMIT_ALL 1 Allow anyone
DENY_ALL 2 Deny everyone
PERMIT_SOME 3 Permit folks listed
DENY_SOME 4 Deny folks listed
PERMIT_ON_LIST 5 Allow folks on the Buddy List

Class: FEEDBAG__WEB_PD_MODE
These are the different modes that control anonymous web queries.
Name Value Notes
Only show my anonymous queries on web pages when user is in Allow All
PD_MODE 0
or Deny Some mode [DEFAULT]
PERMIT_AL
1 Permit anonymous queries always
L
DENY_ALL 2 Deny anonymous queries always

Class: FEEDBAG__PD_FLAGS
This class changes how the permit deny settings work.
Name Value Notes
The permit/deny settings should apply also to the IM permit/deny settings.
If not set, the IM permit/deny settings can be different and is controlled by
APPLIES_IM 0x0001
sending IMs to $im_off & $im_on. This is turned on for AIM users no
matter the setting.
HIDE_WIRE
0x002 Hide the fact that the user is on a wireless device from other users
LESS

Class: FEEDBAG__BUDDY_PREFS
These are all the server based preferences and their defaults.
Name Value Notes
DISPLAY_LOGIN 0 [1] Whether or not to display Buddy List at login
DISPLAY_EBUDDY 1 [1] Whether or not to display the EBuddy group
PLAY_ENTER 2 [1] Whether or not to play a sound when a Buddy enters
PLAY_EXIT 3 [1] Whether or not to play a sound when a Buddy exits
VIEW_IMSTAMP 4 [1] Whether or not to display the timestamp in IMs
VIEW_SMILEYS 5 [1] Whether or not to display :) as a graphic
ACCEPT_ICONS 6 [1] Accept Buddy icons
RESERVED 7 [1] Legacy pref
KNOCK_NONAOLIMS 8 [1] Want knock-knocks for IMs from non-AOL users
[1] Want knock-knocks for IMs from people not on your
KNOCK_NONLISTIMS 9
Buddy List
DISCLOSE_IDLE 10 [1] Let other users know if you are idle
ACCEPT_CUSTOMBART 11 [0] Accept non-official icons, chromes
ACCEPT_NONLISTBART 12 [0] Accept icon, chromes, from non-buddies (official
only)
ACCEPT_BGS 13 [1] Accept IM window backgrounds
ACCEPT_CHROMES 14 [1] Accept IM window chromes
ACCEPT_BLSOUNDS 15 [1] Accept Buddy List arrive/depart sounds
ACCEPT_IMSOUNDS 16 [1] Accept IM sounds
NO_SEE_RECENT_BUDDIES 17 [0] Use does not see RECENT BUDDIES group
ACCEPT_SMS_LEGAL 18 [0] User has accepted to SMS legal agreement
ENTER_DOES_CRLF 20 [0] Enter does not send IM
PLAY_IM_SOUND 21 [1] Play sound on IM receipt
DISCLOSE_TYPING 22 [1] Send typing notifications
ACCEPT_SUPERICONS 24 [1] Accept 'super-buddies'
ACCEPT_BLRICHTEXT 25 [1] Display rich-text screennames in Buddy List
REDUCE_IM_SOUND 26 [1] Attenuate IM sounds after first sound
CONFIRM_DIRECT_IM 27 [1] Confirm with local user before starting DIM
ONE_TABBED_IM_WINDOW 28 [1] Show all IMs in one tabbed window
BUDDYINFO_ON_MOUSEOV
29 [1] Popup information when mouse pauses above Buddy
ER
DISCLOSE_BUDDY_MATCHE
30 [1] Let other users know if they have Buddy matches
S
[0] For server use only; clients use
CATCH_IMS 31
CATCH_IMS_FOR_CLIENT
SHOW_FRIENDLY_NAME 32 [1] Show alias instead of screenname?
DISCLOSE_RADIO 33 [1] Buddies know when user listening to AOL radio
SHOW_CAPABILIITES 34 [1] Show capabilities in the Buddy List
SHOW_BUDDYLIST_FILTER 35 [1] Show Buddy List filter
SHOW_AWAY_IDLE 36 [1] Show away and idle buddies
SHOW_MOBILE 37 [1] Show mobile buddies
SORT_BUDDYLIST 38 [0] Keep Buddy List sorted A-Z
CATCH_IMS_FOR_CLIENT 39 [0] IM catcher window enabled?
NEW_MESSAGE_SMALL_NO
40 [1] show small notification after new message arrives
TIFICATION
NO_FREQUENT_BUDDIES 41 [0] User does not see FREQUENT BUDDIES group
BLOG_AWAY_MESSAGES 42 [0] Send away messages to journals ?
BLOG_AIMSIG_MESSAGES 43 [0] Send AIM signature to journals ?
BLOG_NOCOMMENTS 44 [0] User allows comments ?
FRIEND_OF_FRIEND 45 [0] Allow Friend of Friend queries
FRIEND_GET_CONTACT_LIS
46 [0] Allow friend to get my Buddy List
T
COMPAD_INIT 47 [0] ICQ Compad Init
[1] Send Buddy Feed; Young Teens(YT)/Kids Only(KO)
SEND_BUDDYFEED 48
- KO default to OFF
BLK_SEND_IM_WHILE_AWA
49 [0] Block send IM while away
Y
SHOW_BUDDYFEED 50 [1] Show What is New indicator
[0] Do not save vanity related information (IM sent, idle,
NO_SAVE_VANITY_INFO 51
etc.)
ACCEPT_OFFLINE_IM 52 [1] Accept Offline IMs
SHOW_GROUPS 53 [0] ICQ: Show buddies in groups ?
SORT_GROUP 54 [1] ICQ: Sort groups ?
SHOW_OFFLINE_BUDDIES 55 [1] ICQ: Show/Hide Offline Buddies
EXPAND_BUDDIES 56 [0] ICQ: Show multiline information on some buddies
[0] BUDDY FEED: Does the owner have third party
THIRD_PARTY_FEEDS 57
feeds
NOTIFY_RECEIVED_INVITE 58 [1] Notify at login about received AIMPages invitations
APF_AUTO_ACCEPT 59 [0] Auto accept AIMPages invitations
[0] If APF_AUTO_ACCEPT and
APF_AUTO_ACCEPT_BUDDY 60 APF_AUTO_ACCEPT_BUDDY, auto accept invites
only from buddies
BLOCK_AWAY_MSG_FEED 61 [0] Block feed storage for away messages
BLOCK_AIM_PROFILE_FEED 62 [0] Block feed storage for AIM Profiles
BLOCK_AIM_PAGES_FEED 63 [0] Block feed storage for AIM Pages
BLOCK_JOURNALS_FEED 64 [0] Block feed storage for AOL Journals
BLOCK_LOCATION_FEED 65 [0] Block feed storage for Location data
BLOCK_STICKIES_FEED 66 [0] Block feed storage for Stickies
BLOCK_UNCUT_FEED 67 [0] Block feed storage for Uncut video
BLOCK_LINKS_FEED 68 [0] Block feed storage for Interesting Links
BLOCK_AIM_BULLETIN_FEE
69 [0] Block feed storage for AIM Bulletins
D
SAVE_STATUS_MSG 70 [1] Save status message
APF_NOTIFY_RECEIVED_IN
71 [0] Should email be sent when user invited ?
VITE_BY_EMAIL
SHOW_OFFLINE_GRP 72 [1] Show Offline group
OFFLINE_GRP_COLLAPSED 73 [0] Offline Group is collapsed
FIRST_IM_SOUND_ONLY 74 [0] Only play the sound on the first IM
IMBLAST_INVITE_NOTIFY 75 [1] ALLOWS IMSERV invite notify message

Class: FEEDBAG__BUDALERT_MASK
Masks for when to trigger Buddy alerts or pounces
Name Value Notes
WHEN_ONLINE 0x0001 Trigger when online
WHEN_NOTIDLE 0x0002 Trigger when no longer idle
WHEN_NOTAWAY 0x0004 Trigger when no longer away
DISPLAY_DIALOG 0x0100 Display dialog
PLAY_SOUND 0x0200 Play sound

TLV Class: FEEDBAG__ATTRIBUTES

The following attributes as found in TLVs of Items:
 The range 0-99 is reserved. At this point in time the server will reject any attribute value that
is less than MIN_ATTR. This is intended for later system use.
 The range 100-199 is reserved for attributes that can only be modified by the server. Clients
should not attempt to change or remove these attributes. The server will reject any attribute
value that hasn't been registered in this file.
 The range 200-299 is reserved for attributes that have special meaning and ordinarily are
hidden from the client by some form of abstraction. Clients that fully understand the
meaning of these attributes can modify these attributes. The server will reject any attribute
value that has not been registered in this file.
 The range 300-9999 is reserved for normal, client-modifiable attributes. The server will
reject any attribute value that has not been registered in this file.
 The range 10000-0x7fff is free for use anywhere.
Name Tag Type Notes
MIN_ATTR 100 empty Anything less than this value will be rejected by the server
SHARED 100 empty GROUP: this is a shared group
INVITED 101 empty BUDDY: invited to join the shared group
BUDDY: pending authorization, a client can insert/delete this record, but not
PENDING 102 empty
update
TIME_T 103 t70 Timestamp
DENIED 104 empty BUDDY: Denied authorization
RECENT_BUDDY 106 empty GROUP/BUDDY: Tag to mark the group or Buddy as a recent Buddy
BOT 107 empty GROUP/BUDDY: Tag to mark the group or Buddy as an auto BOT
INTERACTION_IN
INTERACTION 109 BUDDY: Interaction data
FO
BOT 111 empty GROUP/BUDDY: Tag to mark the group or Buddy as a mega BOT
ORDER 200 Array of u16 BUDDY/GROUP Array of IDs, this represents order
[Class:FEEDBAG__BUDDY_PREFS] BUDDY_PREFS: the first 32 of the
BUDDY_PREFS 201 u32
Buddy List preferences
PD_MODE 202 u08 [Class:FEEDBAG__PD_MODE] PD_MODE: permit/deny mode
[Class:OSERVICE__NICK_FLAGS] PD_MODE: permit/deny mask, usually
PD_MASK 203 u32
just 0xffffffff
PD_FLAGS 204 u32 [Class:FEEDBAG__PD_FLAGS] PD_MODE: permit/deny flags
CLIENT_PREFS 205 blob CLIENT_PREFS: blob of client data; name of item should be client
BART: opaque BART data; the item name is the string version of the BART
BART_INFO 213 blob
type
[Class:FEEDBAG__BUDDY_PREFS] BUDDY_PREFS: mask indicating
BUDDY_PREFS_VA
214 u32 which of the first 32 BUDDY_PREFS have actually been set and which are
LID
uninitialized
[Class:FEEDBAG__BUDDY_PREFS] BUDDY_PREFS: For all prefs after
BUDDY_PREFS2 215 Array of u08
the first 32, this is a growing array
BUDDY_PREFS2_V [Class:FEEDBAG__BUDDY_PREFS] BUDDY_PREFS: bitmask indicating
216 Array of u08
ALID which of BUDDY_PREFS2 have actually been set
BART_LIST 217 Array of BART__ID BART: array of complete BART items, the item name is the personality name
ALIAS 305 string BUDDY: alias for Item
COLLAPSED 308 empty GROUP: If present the group is collapsed when initially shown
EMAIL_ADDR 311 string BUDDY: string for user's Email address
PHONE_NUMBER 312 string BUDDY: string for user's normal phone number
CELL_PHONE_NUM
313 string BUDDY: string for user's cell phone number
BER
SMS_PHONE_NUM
314 string BUDDY: string for user's SMS phone number
BER
NOTE 316 string BUDDY: string for "notes" about item
ALERT_PREFS 317 u16 [Class:FEEDBAG__BUDALERT_MASK] BUDDY: alert prefs
IM_SENT 336 u32 VANITY_INFO: Client read only, number of IMs sent
ONLINE_TIME 337 u32 VANITY_INFO: Client read only, number of seconds a user is online
VANITY_INFO: Client read only, number of times a user has the away
AWAY_MSG 338 u32
message set
IM_RECEIVED 339 u32 VANITY_INFO: Client read only, number of IMs received
BUDDYFEED_VIEW 340 t70 BUDDY: When did I last view this person's Buddy Feed ?
WORK_PHONE_NU
344 string BUDDY: string for user's work phone number
MBER
OTHER_PHONE_NU
345 string BUDDY: string for user's other phone number
MBER
[Class:FEEDBAG__WEB_PD_MODE] PDINFO: When to show anonymous
WEB_PD_MODE 351 u08
presence

Datatype: FEEDBAG__Item
This is a single Feedbag item.
Name Type Notes
name string16 UTF8 string of the item's name; maximum length of 97 characters
groupId u16 ID of the group of which the item is part
itemId u16 ID inside the group; if 0 then this is the definition of the group
[Class: FEEDBAG__CLASS_IDS] ID of the class of which this item is a
classId u16
member
[Class: FEEDBAG__ATTRIBUTES] All the attributes for the item; a group
attributes tlvLBlock
must contain the ORDER attribute

SNAC: FEEDBAG__REPLY - Foodgroup:19 Type:6

This is the reply to FEEDBAG_QUERY. A client will need to handle receiving multiple replies
since a Feedbag might not fit in one SNAC, or the server might choose to break it up.
Name Type Notes
numClasses u08 Always 0
numItems u16 Number of items in the Feedbag
Array of FEEDBAG__Item length
items Actual items inside the users Buddy List
numItems
Most recent update time of any item in the
lastUpdate t70
Feedbag

SNAC: FEEDBAG__USE - Foodgroup:19 Type:7

Directs the server to use the specified stored Feedbag information. A USE Feedbag only needs to be
sent on the initial connection and does not need to be sent after a migration.
This SNAC has no fields and is always empty.

SNAC: FEEDBAG__INSERT_ITEMS - Foodgroup:19 Type:8

When this SNAC is sent to the server, the client is requesting that one or more new items are added
to the Feedbag.
When this SNAC is received by the client, either another client or the server has added new items to
the Feedbag. A client will not receive this SNAC for items it just inserted.
Name Type Notes
items Rest of SNAC array of FEEDBAG__Item Items to insert
SNAC: FEEDBAG__UPDATE_ITEMS - Foodgroup:19 Type:9
When this SNAC is sent to the server, the client is requesting to update one or more items. The
client needs to pass up all the attributes for the item, not just the ones it is updating, as the server
will replace them all.
When this SNAC is received by the client, either another client or the server has updated items in
Feedbag. A client will not receive this SNAC for items it just updated.
Name Type Notes
items Rest of SNAC array of FEEDBAG__Item Items to update

SNAC: FEEDBAG__DELETE_ITEMS - Foodgroup:19 Type:10

When this SNAC is sent to the server, the client is requesting that one or more items be deleted
from the Feedbag.
When this SNAC is received by the client, either another client or the server has deleted items from
Feedbag. A client will not receive this SNAC for items it just deleted.
Name Type Notes
items Rest of SNAC array of FEEDBAG__Item Items to delete

Class: FEEDBAG__STATUS_CODES
These are the status codes returned from database operations.
Name Value Notes
SUCCESS 0 Success
DB_ERROR 1 Some kind of database error
NOT_FOUND 2 Item was not found for an update or delete
ALREADY_EXISTS 3 Item already exists for an insert
UNAVAILABLE 5 Server or database is not available
BAD_REQUEST 10 Request was not formed well
DB_TIME_OUT 11 Database timed out
OVER_ROW_LIMIT 12 Too many items of this class for an insert
NOT_EXECUTED 13 Due to other error in same request
AUTH_REQUIRED 14 Buddy List authorization required
BAD_LOGINID 16 Bad loginId
OVER_BUDDY_LIMIT 17 Too many buddies
INSERT_SMART_GROUP 20 Attempt to added a Buddy to a smart group
TIMEOUT 26 General timeout

SNAC: STATUS - Foodgroup:19 Type:14

These are the results of one of the insert/update/delete item SNACs from above. There will be a
status code for each of the items in the original SNAC.
Name Type Notes
Rest of SNAC [Class: FEEDBAG__STATUS_CODES] Results of the operation;
statuses
array of u16 one for each item in original SNAC
SNAC: FEEDBAG__START_CLUSTER - Foodgroup:19 Type:17
The cluster SNACs bracket a set of transactions that should be handled by clients as a group to
avoid "flashing" the user's screen. They help in cases where multiple instances are online, or when
the host is making updates for the client, so the receiving client knows several changes are
happening at once. These SNACs have nothing to do with the actual database transactions. In
particular, non-receipt of an END_CLUSTER does not cause the database transactions to be rolled
back.
Name Type Notes
tlvs Rest of SNAC array of TLV Optional qualifying parameters

SNAC: FEEDBAG__END_CLUSTER - Foodgroup:19 Type:18

See FEEDBAG__START_CLUSTER
This SNAC has no fields and is always empty.

Foodgroup: BART
BART is the system that the AIM clients use to download expressions for their buddies and
themselves. Examples of BART items include Buddy icons, Buddy arrival sounds, and immersive
wallpapers. For some items, the actual assets are downloaded using the BART system and in other
cases, just descriptive XML files are used. Once a BART item is downloaded, it is basically cached
FOREVER by the client, so updating requires publishing a new BART item. This is especially
important when the BART item is an asset. When the BART item is a descriptive XML file, only
the XML file is cached forever and any assets it refers to can use different caching schemes
determined by the client.
All BART items are represented by a BART ID. A BART ID is a 5 byte to 20 byte binary value that
represents the BART item and is sent around by the client and the servers. One simple way to think
of the BART ID is as a compressed URL. When the client receives a BART ID, either from another
client or from the server, it checks its cache or uses the BART server to download the item. The
BART server also has a cache and connects to the various partners to download the assets if it does
not have them. It is expected that each BART ID points to a unique item. The backend will collapse
duplicate items into a single ID. The BART server also will store custom items for some asset types.
Having a Buddy icon with opaque data of 0x0201d20472 means the user has explicitly chosen to
have no Buddy icon. This is different then not having a Buddy icon. This ID should be treated
specially and does not need to be fetched from BART (although BART will return an empty GIF).
This was done so clients could tell when they upgraded from old style Buddy icons to BART Buddy
icons. This special ID should NOT be used for other BART types.

Class: BART__ID_FLAGS
These are the flags used by the client to detect how the BART ID should be processed.
Name Value Notes
CUSTOM 0x01 This is a custom blob; the opaque data will also be 16 bytes
The opaque field is really data the client knows how to process; these items
DATA 0x04
do not need to be downloaded from BART
Used in OSERVICE__BART_REPLY; BART does not know about this ID,
UNKNOWN 0x40
please upload
REDIRECT 0x80 Used in OSERVICE__BART_REPLY; BART says use this ID instead for the
matching type

Class: BART__ID_TYPES
These are all the different BART ID types that are known about and their restrictions.
Name Value Notes
BUDDY_ICON_SMALL 0 GIF/JPG/BMP, <= 32 pixels and 2k
BUDDY_ICON 1 GIF/JPG/BMP, <= 64 pixels and 7k
STATUS_STR 2 StringTLV format; DATA flag is always set
ARRIVE_SOUND 3 WAV/MP3/MID, <= 10K
RICH_TEXT 4 byte array of rich text codes; DATA flag is always set
SUPERBUDDY_ICON 5 XML
RADIO_STATION 6 Opaque struct; DATA flag is always set
BUDDY_ICON_BIG 12 SWF
STATUS_STR_TOD 13 Time when the status string is set
CURRENT_AV_TRACK 15 XML file; Data flag should not be set
DEPART_SOUND 96 WAV/MP3/MID, <= 10K
IM_CHROME 129 GIF/JPG/BMP wallpaper
IM_SOUND 131 WAV/MP3, <= 10K
IM_CHROME_XML 136 XML
IM_CHROME_IMMERS 137 Immersive Expressions
EMOTICON_SET 1024 Set of default Emoticons
ENCR_CERT_CHAIN 1026 Cert chain for encryption certs
SIGN_CERT_CHAIN 1027 Cert chain for signing certs
GATEWAY_CERT 1028 Cert for enterprise gateway

Datatype: BART__ID
This represents a BART asset and can be thought of as a "Tiny URL" equivalent. Some BART IDs
contain the data while some are pointers to the data and must be downloaded using the BART
server.
Name Type Notes
type u16 [Class: BART__ID_TYPES] Kind of asset this BART ID represents
[Class: BART__ID_FLAGS] Any flags associated with the BART item;
flags u08 DATA is important since it means the BART__ID holds the data and the
BART server is not needed
len u08 Length of the opaque data
Array of u08
opaque Opaque data; if the DATA flag is set then this is the actual data to use
length len

Datatype: BART__IDs_wName
This links a BART ID and a loginId.
Name Type Notes
loginId string08 User who is using the asset
numIds u08 Number of assets being requested
ids Array of BART__ID length numIds BART IDs to fetch

Datatype: BART__QUERY_REPLY_ID
This links a queried BART ID with an error code and a replyId.
Name Type Notes
queryId BART__ID Initial ID that is queried or used
[Class: BART__REPLY_CODES] Result code of the
code u08
query
replyId BART__ID ID that will be used; might be different then queryId

Class: BART__REPLY_CODES
These are the result codes of uploads, downloads, and queries.
Name Value Notes
SUCCESS 0 Operation was a success
INVALID 1 ID is malformed
NOCUSTOM 2 Custom blobs are not allowed for this type
TOSMALL 3 Item uploaded is too small for this type
TOBIG 4 Item uploaded is too big for this type
INVALIDTYPE 5 Item uploaded is the wrong type
BANNED 6 Item uploaded has been banned
NOTFOUND 7 Item downloaded was not found

SNAC: BART__ERROR - Foodgroup:16 Type:1

This is the error SNAC for the BART foodgroup.
Name Type Notes
code u16 [Class: ERROR__CODE] Error code
errorTLVs Rest of SNAC array of TLV [Class: ERROR__TAGS] Optional error parameters

SNAC: BART__UPLOAD - Foodgroup:16 Type:2

This SNAC uploads a custom item to the BART server. Only certain types allow custom items.
Name Type Notes
[Class: BART__ID_TYPES] Type of the item to
type u16
upload
len u16 Size of the custom item
data Array of u08 length len Custom item

SNAC: BART__UPLOAD_REPLY - Foodgroup:16 Type:3

These are the results for an item requested with BART_UPLOAD.
Name Type Notes
[Class: BART__REPLY_CODES] Results of the
code u08
upload
id BART__ID If success, this is the new ID for the item uploaded
SNAC: BART__DOWNLOAD2 - Foodgroup:16 Type:6
This SNAC downloads an asset from the BART server. Multiple downloads can be requested in the
SNAC; however for each item, the server will respond with a separate DOWNLOAD__REPLY2.
Name Type Notes
request Rest of SNAC array of BART__IDs_wName Items to download

SNAC: BART__DOWNLOAD_REPLY2 - Foodgroup:16 Type:7

These are the results for an item requested with DOWNLOAD2.
Name Type Notes
refname string08 Name to which the asset belongs
qr_id BART__QUERY_REPLY_ID Information about the query
len u16 Length of the asset
data Array of u08 length len Asset's data

Authentication
Over the years, the AIM backend has supported several different methods for authentication. The
OpenAIM program only supports the clientLogin method since it makes meeting
the terms requirements easier. The clientLogin method allows the client to collect the user name and
password and make a simple web service call to retrieve authentication credentials. These
credentials are then used in future web service calls to sign requests to help against man in the
middle and reply attacks.
When a client collects the loginId and password for the user it should not normalize them in any
manner. It also should not prevent the user from entering certain characters as the AIM name space
is constantly changing. For example, currently the AIM name space is ASCII based, but in the
future that may change. In general, the client should not perform input checking and instead allow
the backend to reject bad values.
Authentication and requesting the BOSS connection normally requires two web service calls.
1. The clientLogin call checks the key, loginId, and password and performs any rate limit or
captcha challenges.
2. The startOSCARSession call requests a BOSS connection and returns where the client needs
to connect to and a one time use cookie to present to the BOSS server for authentication.
This call requires an OAuth style URL signing which is described along with clientLogin.
Here is an example of the signon process:

Step #1 - Authentication Request

The client should collect the loginId and password for the user. It should not do any length or
character validations. A POST web service call should be made
to [Link] with a POST body
ofk=[KEY]&s=[LOGINID]&pwd=[PASSWORD]&clientVersion=[CLIENTVERSION]&clientNa
me=[clientName] and a content type of application/x-www-form-urlencoded where
[FORMAT]
Format to return the response in; XML, AMF3, PHP, JSON are all supported
[KEY]
Client key obtained from here
[LOGINID]
URI encoded loginId entered by the user
[PASSWORD]
URI encoded password entered by the user
[clientVersion]
A single number representing the client version number for metrics and tracking, usually the
build number
[clientName]
URI encoded friendly name representing the client being used

Step #2 - Authentication Reply

There can be several intermediate replies before a successful authentication is completed. These
include incorrect passwords, need for extra credentials, or the need for the user to complete a
CAPTCHA challenge. To test if a client supports CAPTCHA challenges correctly it can add an
extra parameter of forceRateLimit=true. It is recommended that all clients test CAPTCHA support.
When successfully authenticated, the token->a and sessionSecret need to be extracted from the
results. The sessionSecret is used to generate a sessionKey that will be used on future calls. For
example, the startOSCARSession service, the start page, and the expressions page all require the
sessionKey.
The sessionKey is calculated using
sessionKey = hmac_sha256_base64($sessionSecret, $password);

For example, if the sessionSecret was "AB123FO" and the user's password was "weakpassword",
then the sessionKey would be "ZyCaA1QlF8oBzh0QXeXNCf+7qUItBaiXwk3xOVcFZhY="
Historically some hmac_sha256_base64 do not return valid base64 data. All these APIs require
valid base64 data, so check the implementation being used.

Step #3 - Start OSCAR Session Request

Once successfully authenticated, the client needs to connect to the BOSS server to start the AIM
session. This is done by requesting a BOSS reservation and then connecting to the BOSS server.
Requesting the BOSS reservation is done with a signedstartOSCARSession WIM call. Since the
URL needs to be signed, the parameters are required to be in alphabetical order.
[FORMAT]
Format to return the response in: XML, AMF3, PHP, JSON are all supported
[KEY]
Client key obtained from here
[TOKEN]
The URI encoded token extracted from clientLogin
[clientVersion]
A single number representing the client version number for metrics and tracking
[clientName]
A URI encoded friendly name representing the client being used
[TIME]
The current time, in seconds, since UNIX EPOCH
[USETLS]
Should the connection to BOSS use TLS

$uri = "[Link]
$queryString =
"a=[TOKEN]&clientName=CLIENTNAME]&clientVersion=[CLIENTVERSION]&f=[FORMAT]&k=[KEY]&ts=[TI
ME]&useTLS=[USETLS]";
$hashData= "GET&" . uri_encode($uri) . "&" . uri_encode($queryString);
$digest = hmac_sha256_base64($hashData, $sessionKey);
$url = $uri . "?" . $queryString . "&sig_sha25sig_sha256=$digest";

Step #4 - Start OSCAR Session Reply

On a successful startOSCARSession, the backend will return where the BOSS server is running, the
cookie to present to the BOSS server, and the certname that should be validated when connecting to
BOSS if TLS was selected. At this point the client should connect to BOSS using FLAP or FLAP
over TLS and start sending SNACs back and forth.

Single Signon to Web Pages

Many AIM web pages require authentication before they will display protected content. Since the
user has already authenticated to use the AIM client, we offer a service that allows the
authentication to be transfered from the client to the web page. The API requires an URL be formed
using the credentials from clientLogin and the destination URL and then signed. Full documentation
can be found at client2web site.
Here is a complete example of the single signon process:

Step #1 - Form the client2Web URL

Just like startOSCARSession for authentication, the client2Web URL needs to be signed. The
parameters are required to be in alphabetical order since the URL needs to be signed.
[KEY]
Client key used with clientLogin - for this API the parameter is called devId instead of k
[TOKEN]
URI encoded token extracted from clientLogin
[DESTURL]
URI encoded destination URL to redirect to after establishing web authentication session
[TIME]
The current time in seconds since UNIX EPOCH

$uri = "[Link]
$queryString = "a=[TOKEN]&destURL=[DESTURL]&devId=[KEY]&entryType=client2Web&ts=[TIME]";
$hashData= "GET&" . uri_encode($uri) . "&" . uri_encode($queryString);
$digest = hmac_sha256_base64($hashData, $sessionKey);
$url = $uri . "?" . $queryString . "&sig_sha256=$digest";

Step #2 - Launch a Browser

Using the URL from step one, launch the user's preferred browser with the URL. It is as simple as
that.
AIM Start Page
Supporting the AIM Start Page is one of the available choices to meet the requirements of the terms.
A client that chooses this feature must keep a local preference per loginId if the start page should be
shown or not. The preference must default to on for all loginIds.
So the start page can be fully customized, we require authentication credentials to be passed using
the Single Signon method described above. The client must show the start page to the user if they
have not elected to turn it off.
Showing the start page is a simple operation.
1. Form the start page URL following the instructions documented here.
2. Use the Single Signon method described above to form the full signed URL for the browser.
3. Launch the browser with the full URL.

Expressions Requirement
Supporting expressions is one of the available choices to meet the requirements of the terms. Both
the ability to choose expressions from a web page and the ability to display at least Buddy icons is
required. So the expression chooser can be fully customized, we require authentication credentials
to be passed using the Single Signon method described above.
Showing the expression chooser is simple.
1. Form the expressions URL following the instructions documented here.
2. Use the Single Signon method described above to form the full signed URL for the browser.
3. Launch the browser with the full URL.
Showing Buddy icons for a user requires a little more work.

Step #1 - Finding the icon for a user

First the client will need to discover what the Buddy icon BART ID is for the user. Depending on
display, the client will want to look inside the NickwInfo for either
the ICBM__CHANNEL_MSG_TOCLIENT SNAC or BUDDY__ARRIVED SNAC. The
NickwInfo will contain an array of BART IDs and the client should select the one with
the BART__ID_TYPES for which it is looking.

Step #2 - Connecting to BART

If the client is not already connected to the BART server it will need to do so.
1. Send a OSERVICE__SERVICE_REQUEST to BOSS with the foodgroup of BART.
2. Wait for a OSERVICE__SERVICE_RESPONSE from BOSS.
3. Using the RECONNECT_HERE tag, connect to the BART server.
4. Using the LOGIN_COOKIE tag send a FLAP SIGNON packet, just like connecting to
BOSS.
5. Send a OSERVICE__CLIENT_ONLINE SNAC to the BART server.

Step #3 - Downloading from BART

Once connected to BART, use the BART__DOWNLOAD2 SNAC to download as many assets as
required.
Step #4 - Display Icon
Display the image.

Examples

Signon Flow
Here is a complete signon flow using example loginIds and passwords.

Step #1 - Open Auth Client Login

1. A clientLogin POST request to log the user in.
 URL: [Link]
 POST Data:
k=thekey&s=chattingChuck&pwd=WeakPassword&clientVersion=3&clientName=Cool+Client

2. Assuming correct loginId, password, and no CAPTCHA challenge, a good response will
look like the following:
<response xmlns="[Link]
<statusCode>200</statusCode>

<statusText>OK</statusText>
<data>
<token>
<expiresIn>86400</expiresIn>
<a>
%2FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8E9o
g492eGQi3X0cIrwRfN5SsuA%2BE9nGhXtbQt
%2BHoaa8Fw9yMTuuuks3%2F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3QGjTvi
6tRPsVpmnfSQ%3D</a>

</token>
<sessionSecret>m3UPFGcH5hmKSv24</sessionSecret>
</data>
</response>

3. Extract the token->a element and save for later.

4. Calculate the sessionKey and save for future use, making sure to use a hmac_sha256_base64
that returns entire base64 data. After calculating the sessionKey a secure client should
overwrite the memory where the password was stored.
$sessionKey = hmac_sha256_base64("m3UPFGcH5hmKSv24", "WeakPassword");
= "wEOki901gedaIeJbMAy5k+hv4iJgfvshgM+cWtk+s1g=";

Step #2 - Request BOSS Session and Connect

1. Now that we have the session key, we can request a BOSS server connection. This involves
creating a signed URL.
$uri = "[Link]

$queryString = "a=" .
uri_encode("%2FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtU
aFOTM8E9og492eGQi3X0cIrwRfN5SsuA%2BE9nGhXtbQt
%2BHoaa8Fw9yMTuuuks3%2F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3QGjTvi
6tRPsVpmnfSQ%3D") .
"&clientName=" . uri_encode("Cool Client") .
"&clientVersion=3&f=xml&k=thekey&ts=1203799990";
= "a=
%252FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8E
9og492eGQi3X0cIrwRfN5SsuA%252BE9nGhXtbQt
%252BHoaa8Fw9yMTuuuks3%252F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3Q
GjTvi6tRPsVpmnfSQ%253D&clientName=Cool
%20Client&clientVersion=3&f=xml&k=thekey&ts=1203799990";

$hashData= "GET&" . uri_encode($uri) . "&" . uri_encode($queryString);

= "GET&https%3A%2F%[Link]%2Faim%2FstartOSCARSession&a%3D
%25252FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM
8E9og492eGQi3X0cIrwRfN5SsuA%25252BE9nGhXtbQt
%25252BHoaa8Fw9yMTuuuks3%25252F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5
E3QGjTvi6tRPsVpmnfSQ%25253D%26clientName%3DCool%2520Client%26clientVersion%3D3%26f
%3Dxml%26k%3Dthekey%26ts%3D1203799990"

$digest = hmac_sha256_base64($hashData, $sessionKey);

= "F2U+nrI5cJXVuTVwSOMyH3r6lhsCOspQ9J6XpLxgmAw="

$url = $uri . "?" . $queryString . "&sig_sha25sig_sha256=$digest";

= "[Link]
%252FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8E
9og492eGQi3X0cIrwRfN5SsuA%252BE9nGhXtbQt
%252BHoaa8Fw9yMTuuuks3%252F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3Q
GjTvi6tRPsVpmnfSQ%253D&clientName=Cool
%20Client&clientVersion=3&f=xml&k=thekey&ts=1203799990&sig_sha25sig_sha256=F2U+nrI5cJXVuTV
wSOMyH3r6lhsCOspQ9J6XpLxgmAw=";

2. Assuming no errors, a reply like the following should be received:

<response xmlns="[Link]
<statusCode>200</statusCode>
<statusText>Ok</statusText>

<data>
<host>[Link]</host>
<port>9343</port>

<cookie>yoOR9mTV9hGH2vHNXtDytoHTu4q/yYpzkQzrs9L0GKg9ePe29nfS6J0+mIJD0ibMndzjde1Asumq
Q6q+1pW95IyNHIhLxDm0PKF+aV8Mg05WZ7guQwiaNGPGXOq5qHI4kIyuVFU1kb9suwStkn+awsySalirJ
vTJbnbws2RqEV7MsBNF99MUJl+PEHuvEtqAAPuq0HvUGiFqPLC25D+cTYFmLMRwoQPtqIaHHAlaxo+
kSWDTAKLzXGZ1JS/6Jd1p2HqPaBjCXuawVFpbwJT+DepJojJHGA4YMGh+YxM8dIfG8IH28w3/
cqMZB/RDKaqZX+p0/AH4eqg34+BtYrfq/g==</cookie>

</data>
</response>

3. Open a binary socket connection to the host and port.

4. Save the base64 decoded cookie for use in the FLAP SIGNON Frame.

Step #3 - Send FLAP SIGNON Frame

1. Once connected, the client should send a FLAP__SIGNON_FRAME with the login cookie
and any version information it would like to provide.
Field Size Value
u08 [Link] '*'
u08 [Link] 1 (FLAP__FRAME_TYPE_SIGNON)
u16 [Link] XX
u16 [Link] YY
u32 version 1
u16 tlvs[0].tag 6 (FLAP__SIGNON_TAGS_LOGIN_COOKIE)
u16 tlvs[0].len 256
blob tlvs[0].value base64 decoded $cookie value from Step #2
74
u16 tlvs[1].tag
(FLAP__SIGNON_TAGS_MULTICONN_FLAGS)
u16 tlvs[1].len 1
u08 tlvs[1].value 0x01
2. It should then listen for a FLAP__SIGNON_FRAME from BOSS before continuing.
3. Once it has received the FLAP__SIGNON_FRAME, the client can start sending SNAC
messages to the server.

Step #4 - Send Rights Requests

Once the connection has been established and the FLAP signon frames have been exchanged, the
client can start sending SNACs to the server. Usually the first thing the client sends are all the rights
queries and a FEEDBAG__QUERY SNAC. It can and should send all these requests in parallel for
a quicker login experience.
 Query the BUDDY foodgroup rights:
Field Size Value
u08 [Link] '*'
u08 [Link] 2 (FLAP__FRAME_TYPE_DATA)
u16 [Link] XX
u16 [Link] YY
u16 [Link] 3 (BUDDY)
u16 [Link] 2 (BUDDY__RIGHTS_QUERY)
u16 [Link] 0
u32 [Link] ZZ
u16 tlvs[0].tag 5 (BUDDY__RIGHTS_QUERY_TAGS_FLAGS)
u16 tlvs[0].len 2
u16 tlvs[0].value 0xf
 Query the PD foodgroup rights:
Field Size Value
u08 [Link] '*'
u08 [Link] 2 (FLAP__FRAME_TYPE_DATA)
u16 [Link] XX
u16 [Link] YY
u16 [Link] 9 (PD)
u16 [Link] 2 (PD__RIGHTS_QUERY)
u16 [Link] 0
u32 [Link] ZZ
 Query the LOCATE foodgroup rights:
Field Size Value
u08 [Link] '*'
u08 [Link] 2 (FLAP__FRAME_TYPE_DATA)
u16 [Link] XX
u16 [Link] YY
u16 [Link] 2 (LOCATE)
u16 [Link] 2 (LOCATE__RIGHTS_QUERY)
u16 [Link] 0
u32 [Link] ZZ
 Query the FEEDBAG foodgroup rights:
Field Size Value
u08 [Link] '*'
u08 [Link] 2 (FLAP__FRAME_TYPE_DATA)
u16 [Link] XX
u16 [Link] YY
u16 [Link] 19 (FEEDBAG)
u16 [Link] 2 (FEEDBAG__RIGHTS_QUERY)
u16 [Link] 0
u32 [Link] ZZ
u16 tlvs[0].tag 11 (FEEDBAG__RIGHTS_QUERY_TAGS_FLAGS)
u16 tlvs[0].len 2
u16 tlvs[0].value 0x7f
 Query what the Buddy List and preferences are:
Field Size Value
u08 [Link] '*'
u08 [Link] 2 (FLAP__FRAME_TYPE_DATA)
u16 [Link] XX
u16 [Link] YY
u16 [Link] 19 (FEEDBAG)
u16 [Link] 2 (FEEDBAG__QUERY)
u16 [Link] 0
u32 [Link] ZZ

Step #5 - FEEDBAG Use and Client Online

Once all the rights replies and feedbag replies are received, it is time to tell the server that the client
is ready to proceed.
 First tell the server that the feedbag looks OK and the client is ready to use it.
Field Size Value
u08 [Link] '*'
u08 [Link] 2 (FLAP__FRAME_TYPE_DATA)
u16 [Link] XX
u16 [Link] YY
u16 [Link] 19 (FEEDBAG)
u16 [Link] 7 (FEEDBAG__USE)
u16 [Link] 0
u32 [Link] ZZ
 Next we tell the client we are ready to appear online to everyone else and our version
numbers.
Field Size Value
u08 [Link] '*'
u08 [Link] 2 (FLAP__FRAME_TYPE_DATA)
u16 [Link] XX
u16 [Link] YY
u16 [Link] 1 (OSERVICE)
u16 [Link] 2 (OSERVICE__CLIENT_ONLINE)
u16 [Link] 0
u32 [Link] ZZ
u16 groupVersions[0].foodgroup 1 (OSERVICE)
u16 groupVersions[0].version 4
u16 groupVersions[0].tool_id 41
u16 groupVersions[0].tool_version AA
u16 groupVersions[1].foodgroup 19 (FEEDBAG)
u16 groupVersions[1].version 3
u16 groupVersions[1].tool_id 41
u16 groupVersions[1].tool_version AA
u16 groupVersions[1].foodgroup 3 (BUDDY)
u16 groupVersions[1].version 1
u16 groupVersions[1].tool_id 41
u16 groupVersions[1].tool_version AA
u16 groupVersions[1].foodgroup 2 (LOCATE)
u16 groupVersions[1].version 1
u16 groupVersions[1].tool_id 41
u16 groupVersions[1].tool_version AA
u16 groupVersions[1].foodgroup 6 (INVITE)
u16 groupVersions[1].version 1
u16 groupVersions[1].tool_id 41
u16 groupVersions[1].tool_version AA
u16 groupVersions[1].foodgroup 4 (ICBM)
u16 groupVersions[1].version 1
u16 groupVersions[1].tool_id 41
u16 groupVersions[1].tool_version AA

Step #6 - Online
The client is now considered online, visible to other users, and will start to
receive BUDDY__ARRIVED for any online buddies.
Sending an IM
An IM conversation involves multiple CLIENT_EVENTS and ICBMs. CLIENT_EVENTS are
used to inform the remote user what the sender is doing so the remote user knows they are still
there. Here is a sample session where GabbyGrace is sending IMs to ChattingChuck.

Step #1 - Sending Typing Event

A client can optionally support sending a typing notification to the other user.
Field Size Value
u08 [Link] '*'
u08 [Link] 2 (FLAP__FRAME_TYPE_DATA)
u16 [Link] XX
u16 [Link] YY
u16 [Link] 4 (ICBM)
u16 [Link] 20 (ICBM__CLIENT_EVENT)
u16 [Link] 0
u32 [Link] ZZ
Array of u08 cookie '12345678'
u16 channel 1 (ICBM__CHANNELS_IM)
u08 [Link] 13
Array of u08 [Link] 'ChattingChuck'
u16 event 2 (ICBM__EVENTS_TYPING)

Step #2 - Sending IM
Field Size Value
u08 [Link] '*'
u08 [Link] 2 (FLAP__FRAME_TYPE_DATA)
u16 [Link] XX
u16 [Link] YY
u16 [Link] 4 (ICBM)
u16 [Link] 6 (ICBM__CHANNEL_MSG_TOHOST)
u16 [Link] 0
u32 [Link] ZZ
Array of
cookie '12345678'
u08
u16 channel 1 (ICBM__CHANNELS_IM)
u08 [Link] 13
Array of
[Link] 'ChattingChuck'
u08
u16 icbmTlvs[0].tag 3 (ICBM__TAGS_REQUEST_HOST_ACK)
u16 icbmTlvs[0].len 0
u16 icbmTlvs[1].tag 2 (ICBM__TAGS_IM_DATA)
u16 icbmTlvs[1].len 15
0x0501
u16 icbmTlvs[1].imData[0].tag
(ICBM__IM_DATA_TAGS_IM_CAPABILITIES)
u16 icbmTlvs[1].imData[0].len 1
u08 icbmTlvs[1].imData[0].value 1
u16 icbmTlvs[1].imData[1].tag 0x0101 (ICBM__IM_DATA_TAGS_IM_TEXT)
u16 icbmTlvs[1].imData[1].len 6
icbmTlvs[1].imData[1].encodin
u16 0 (ICBM__IM_SECTION_ENCODINGS_ASCII)
g
icbmTlvs[1].imData[1].languag
u16 0
e
u08 icbmTlvs[1].imData[1].data 'Hi'

Step #3 - Receiving Typing Event

The receiving side of the client event looks identical to the sending side other then the loginId has
been reversed.
Field Size Value
u08 [Link] '*'
u08 [Link] 2 (FLAP__FRAME_TYPE_DATA)
u16 [Link] XX
u16 [Link] YY
u16 [Link] 4 (ICBM)
u16 [Link] 20 (ICBM__CLIENT_EVENT)
u16 [Link] 0
u32 [Link] ZZ
Array of u08 cookie '12345678'
u16 channel 1 (ICBM__CHANNELS_IM)
u08 [Link] 10
Array of u08 [Link] 'GabbyGrace'
u16 event 2 (ICBM__EVENTS_TYPING)

Step #4 - Receiving IM
Field Size Value
u08 [Link] '*'
u08 [Link] 2 (FLAP__FRAME_TYPE_DATA)
u16 [Link] XX
u16 [Link] YY
u16 [Link] 4 (ICBM)
u16 [Link] 7 (ICBM__CHANNEL_MSG_TOCLIENT)
u16 [Link] 0
u32 [Link] ZZ
Array of
cookie '12345678'
u08
u16 channel 1 (ICBM__CHANNELS_IM)
u08 [Link] 10
Array of
[Link] 'GabbyGrace'
u08
u16 [Link] 0
u16 [Link] 1
1
u16 [Link][0].tag
(OSERVICE__NICK_INFO_TAGS_NICK_FLAGS)
u16 [Link][0].len 2
u16 [Link][0].value 0x10
u16 icbmTlvs[0].tag 2 (ICBM__TAGS_IM_DATA)
u16 icbmTlvs[0].len 15
0x0501
u16 icbmTlvs[0].imData[0].tag
(ICBM__IM_DATA_TAGS_IM_CAPABILITIES)
u16 icbmTlvs[0].imData[0].len 1
u08 icbmTlvs[0].imData[0].value 1
u16 icbmTlvs[0].imData[1].tag 0x0101 (ICBM__IM_DATA_TAGS_IM_TEXT)
u16 icbmTlvs[0].imData[1].len 6
icbmTlvs[0].imData[1].encodin
u16 0 (ICBM__IM_SECTION_ENCODINGS_ASCII)
g
icbmTlvs[0].imData[1].languag
u16 0
e
u08 icbmTlvs[0].imData[1].data 'Hi'

Buddy Info Requirement

Buddy Info is one of the available choices to meet the requirements of the terms. It is a straight
forward feature to implement and most users in the target audience enjoy looking at the Buddy Info
of their friends. To implement the feature, the client needs to fetch the HTML from the backend and
display it in an HTML view with javascript enabled. Even if a client does not use this to meet a
license requirement, we still recommend this as a high value end user feature.

Step #1 - Fetching the content

Over the BOSS connection, send a LOCATE__USER_INFO_QUERY2 SNAC with at least the
HTML_INFO type2 set.
For example, to get ChattingChuck's information the following server message would be used:
Field Size Value
u08 [Link] '*'
u08 [Link] 2 (FLAP__FRAME_TYPE_DATA)
u16 [Link] XX
u16 [Link] YY
u16 [Link] 2 (LOCATE)
u16 [Link] 21 (LOCATE__USER_INFO_QUERY2)
u16 [Link] 0
u32 [Link] ZZ
u32 type2 0x00000400
(LOCATE__QUERY_TYPE_HTML_INFO)
u08 [Link] 13
Array of u08 [Link] 'ChattingChuck'

Step #2 - Wait for the response

Wait for a response LOCATE__USER_INFO_REPLY SNAC.
For example the response for the ChattingChuck's query above might be:
Field Size Value
u08 [Link] '*'
u08 [Link] 2 (FLAP__FRAME_TYPE_DATA)
u16 [Link] XX
u16 [Link] YY
u16 [Link] 2 (LOCATE)
u16 [Link] 6 (LOCATE__USER_INFO_REPLY)
u16 [Link] 0
u32 [Link] ZZ
u08 [Link] 13
Array of u08 [Link] 'ChattingChuck'
u16 [Link] 0
u16 [Link] 1
u16 [Link][0].tag 1 (OSERVICE__NICK_INFO_TAGS_NICK_FLAGS)
u16 [Link][0].len 2
u16 [Link][0].value 0
u16 locateInfo[0].tag 13 (LOCATE__TAGS_HTML_INFO_TYPE)
u16 locateInfo[0].len 9
Array of u08 locateInfo[0].value 'text/html'
u16 locateInfo[1].tag 14 (LOCATE__TAGS_HTML_INFO_DATA)
u16 locateInfo[1].len 100
Array of u16 locateInfo[1].value '<html>Stuff</html>'

Step #3 - Display the content

The client should now open (or reuse) an HTML view with javascript enabled and display the
content returned inside the LOCATE__TAGS_HTML_INFO_DATA TLV.

Start Page and Expression Chooser

Displaying either the Start Page or the Expression Chooser using Single Signon is almost exactly
the same. For the example the start page is used, but it is easy to substitute the Expression Chooser.
This example will use the same sessionKey and token as previous examples.
$sessionKey = "wEOki901gedaIeJbMAy5k+hv4iJgfvshgM+cWtk+s1g=";

$destUrl = uri_encode("[Link]

$uri = "[Link]
$queryString = "a=" .
uri_encode("%2FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8
E9og492eGQi3X0cIrwRfN5SsuA%2BE9nGhXtbQt
%2BHoaa8Fw9yMTuuuks3%2F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3QGjTvi6tRPsVp
mnfSQ%3D") .
"&destUrl=$destUrl" .
"&devId=thekey" .
"&entryType=client2Web" .
"&ts=203799990";
= "a=
%252FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8E9og492e
GQi3X0cIrwRfN5SsuA%252BE9nGhXtbQt
%252BHoaa8Fw9yMTuuuks3%252F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3QGjTvi6tR
PsVpmnfSQ%253D&destUrl=http%3A%2F%[Link]%2Faim%2FgetStartPage%3Ff%3Dhtml
%26language%3Den-us&devId=thekey&entryType=client2Web&ts=203799990"

$hashData = "GET&" . uri_encode($uri) . "&" . uri_encode($queryString);

= "GET&http%3A%2F%[Link]%2F_cqr%2Flogin%[Link]&a%3D
%25252FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8E9og49
2eGQi3X0cIrwRfN5SsuA%25252BE9nGhXtbQt
%25252BHoaa8Fw9yMTuuuks3%25252F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3QGjTv
i6tRPsVpmnfSQ%25253D%26destUrl%3Dhttp%253A%252F%[Link]%252Faim%252FgetStartPage
%253Ff%253Dhtml%2526language%253Den-us%26devId%3Dthekey%26entryType%3Dclient2Web%26ts
%3D203799990"

$digest = hmac_sha256_base64($hashData, $sessionKey);

= "8nMlPovQqriZyPvWbftEjz+lPnQRF5A8TDcU79raYc4"

$url = $uri . "?" . $queryString . "&sig_sha256=$digest";

= "[Link]
%252FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8E9og492e
GQi3X0cIrwRfN5SsuA%252BE9nGhXtbQt
%252BHoaa8Fw9yMTuuuks3%252F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3QGjTvi6tR
PsVpmnfSQ%253D&destUrl=http%3A%2F%[Link]%2Faim%2FgetStartPage%3Ff%3Dhtml
%26language%3Den-
us&devId=thekey&entryType=client2Web&ts=203799990&sig_sha256=8nMlPovQqriZyPvWbftEjz+lPnQRF5A8TDc
U79raYc4"

Submitted by Developer Network on March 5, 2008 - 7:38am.