Web AIM Server API Reference

The Web AIM API lets developers incorporate core AIM functionality into any web page, including the ability to sign on, send and receive IMs, and obtain a user's Buddy List. By using the Web AIM API to build their applications, developers can take advantage of AIM's power and large user base, while having the freedom to extend AIM's functionality in innovative new ways. The APIs support both the building of real-time, interactive widgets and one-time queries. Developers can use as much or as little of the platform as they like.

You will need a key to use the Web AIM APIs, which can be obtained from Web AIM Key Registration. If you are interested in using or modifying already-built widgets, visit AIM Whimsicals.

Typical Authenticated Application Flow

The application should not ask for the loginId and password directly. Instead, the application must show pages, usually in an IFRAME, generated by AOL to collect the authentication information. Usually an application will have a button that starts the authentication process, but it can also do parts of it on page load. What follows is the typical flow of an application that needs user authentication.

getToken - A token is required for many of the Web AIM APIs - the first call to getToken will almost always return an error and a redirectURL
Show the redirectURL to the user, usually using an IFRAME, and watch for the URL fragment to contain #AUTHDONE
getToken - The second call to getToken will return a success with a valid token
When using one of the APIs that supports the a= parameter, stop here, and use the token.a value
Some APIs require a session; use startSession to create a session and retrieve an aimsId
startSession - The first call to startSession MAY return a 450 error with redirectURL if the user is required to grant the page consent to access the user's data - Sessions are only needed when real time presence updates or interactive IMs are required
If consent was required, show the redirectURL to the user, usually in an IFRAME, and watch for the URL fragment to contain #CONSENTDONE
startSession - If required, call startSession again
Now any of the APIs that support the aimsId= parameter can be used
Sessions require periodic calls of the fetchEvents URL for outstanding items
endSession - Mark the user offline and clean up server state

Typical Anonymous Application Flow

When building a web AIM API application like WIMZI, that needs to establish an anonymous session, the following application flow should be used. An anonymous session can only interact with the user that created the key.

startSession - Call startSession with the annoymous= parameter and a WIMZI key
Use the returned widgetTitle returned from startSession in the UI
The creatorDisplayName will automatically be returned in the first BuddyList event as the only buddy
Sessions require periodic calls of the fetchEvents URL for outstanding items
Use the returned creatorDisplayName to address IMs
setState - the friendly= option can be used to set a friendly name for the anonymous visitor
endSession - Mark the anonymous user offline and clean up server state

The sections below contain a complete reference to the enumerations, types, and methods of Web AIM API.

Enumerations	Types	Methods
Format Presence State User Type Event Type Typing Status Expression Type Data IM Type Reject Reason IM Channel Client Error PdMode AddBuddyResultCodeValue Preferences PdMode	Capability Location QuietHours LocationAllow SmsSegment Presence Group Expression MyInfoEvent PresenceEvent TypingEventData TypingEvent DataIMEventData DataIMEvent sentDataIMEventData sentDataIMEvent IMEventData IMEvent sentIMEventData sentIMEvent ClientErrorEventData ClientErrorEvent OfflineIMEventData OfflineIMEvent BuddyListEventData BuddyListEvent SessionEndedEvent Event SendImSubCode BuddyFeedItem RankedUsersLocation AddBuddyResultCode IMConversationLocation AIMFightUser PDNameCode PDResultCode	Session Methods startSession fetchEvents deleteEvent endSession startOSCARSession Presence Methods getPresence getBuddyListPresence getPresenceIcon setState setStatus setProfile getProfile IM Methods sendIM sendDataIM rejectDataIM setTyping Expressions Methods getExpression getAsset setExpression uploadExpression Buddylist Editing Methods addBuddy addGroup removeBuddy removeGroup renameGroup setBuddyAttribute setGroupAttribute moveGroup moveBuddy copyBuddyLists deleteUser Preference Methods setPreference getPreference setPermitDeny getPermitDeny Location Based Methods googleEarth.kml getRankedUsersLocations.kml getRankedUsersLocations getIMConversationsLocations.kml getIMConversationsLocations Buddyfeed Methods getUserFeed getBuddylistFeed pushFeed Miscellaneous Methods getVanityInfo getAIMFight addTempBuddy removeTempBuddy getHostBuddyInfo aimStartPage aimExpressionsPage

Enumerations

These enumerations are constants, used by Web AIM types and methods.

Enumeration: Format

The return format of the APIs

Values	Description
json	JSON Format
xml	Simple XML Format
php	Serialized PHP
amf0	Flash binary AMF0 format
amf3	Flash binary AMF3 format

Enumeration: Presence State

The presence state values of an AIM ID. An AIM ID can be in any one of these states.

Values	Description
online	Online State
invisible	Invisible - Only valid in myInfo objects
notFound	For email lookups the address was not found
idle	Idle State
away	Away State
mobile	Mobile State
offline	Offline State

Enumeration: User Type

The type of user

Values	Description
aim	AIM or AOL
icq	ICQ
sms	SMS phone number
interop	Gatewayed from another network

Enumeration: Event Type

Web AIM supports multiple different event types. Each event type needs to be explicitly subscribed to (except for sessionEnded) when calling startSession. Since the different events occur asynchronously, calls to the fetchEvents method will return them.

Subscribing to the buddylist event is what makes the user appear online to everyone else, so not subscribing will cause the user to appear offline to everyone except those IMed. This way it is possible to build a widget that only appears online to those the user is having a conversation with.

Values	Description
myInfo	Information about oneself
presence	Presence changes about a buddy on the Buddy List
buddylist	Buddylist change, replace the current Buddy List with this one
typing	Typing indicator status change
im	Instant Message
dataIM	Data Instant Message
clientError	Client Error
sessionEnded	Session ended, do not call fetchEvents anymore
offlineIM	Offline Instant Message
sentIM	Keep track of IMs sent
sentDataIM	Keep track of data IMs sent

Enumeration: Typing Status

The current IM typing status generated by

Values	Description
none	Previously was in typing or typed status and has erased all their text
typing	Started typing, only send on transition not for every key press
typed	Previously typing and now has stopped typing - recommend only using after typing has stopped for at least 3 seconds

Enumeration: Expression Type

The type of expression data

Values	Description
miniIcon	Small icon - displayed on the Buddy List for users on some clients
buddyIcon	Large icon - displayed in IM window for most clients
arriveSound	Sound associated with the user signing on
departSound	Sound associated with the user signing off
imSound	Sound associated with the user receiving an IM
imChrome	Wallpaper
superBuddy	Super Buddy
immersiveChromeXML	Immersive Wallpaper
imChromeXML	Wallpaper XML
emoticon	Return the zipped emoticons

Enumeration: Data IM Type

The type of IM data, not all of these types must be used

Values	Description
invite	Start a custom session
accept	Accept a custom session
deny	Deny a custom session
data	Send data for a custom session
end	End a custom session

Enumeration: Reject Reason

For reject rendezvous

Values	Description
unsupported	Proposal capability not supported
denied	Not authorized or used declined
malformed	Proposal malformed
timedOut	Attempt to act on proposal timed out
notAvailable	Recipient away or busy
resources	Recipient had internal error
rateLimited	Recipient was rate limited
noData	Recipient had nothing to send
version	Incompatible version
security	Incompatible security setting

Enumeration: IM Channel

Internal channel used for IM

Values	Description
text	Regular text IM
data	Data or Rendezvous IM

Enumeration: Client Error

Reported by client

Values	Description
unsupported	Channel unsupported by client
malformed	Request unrecognizable
channel	Channel specific error

Enumeration: PdMode

The permit/deny mode

Values	Description
permitAll	Allow all aimIds
permitSome	Only aimId's tagged with allow
permitOnList	Only aimIds on Buddy List
denySome	Denied tagged aimIds
denyAll	Allow no one
permitAll	Allow all aimIds
permitSome	Only aimId's tagged with allow
permitOnList	Only aimIds on Buddy List
denySome	Denied tagged aimIds
denyAll	Allow no one

Enumeration: AddBuddyResultCodeValue

Result code value

Values	Description
0	Success
3	Already Exists
17	Over Buddy Limit
26	Timeout

Enumeration: Preferences

Various AIM preferences

Values	Description
displayLogin	[1] Display Buddy List at login
displayEBuddy	[1] Whether or not to display the EBuddy group
playEnter	[1] Whether or not to play a sound when a buddy enters
playExit	[1] Whether or not to play a sound when a buddy exits
viewIMTimestamps	[1] Whether or not to display the timestamp in IMs
viewSmilies	[1] Whether or not to display :) as a graphic
acceptIcons	[1] Accept buddy icons
knockNonAOLIMs	[1] Want knock-knocks for IMs from non-AOL users
knockNonListIMs	[1] Want knock-knocks for IMs from people not on your Buddy List
discloseIdle	[1] Let other users know if you are idle
acceptCustomBart	[0] Accept non-official icons, chromes
acceptNonListBart	[0] Accept icon, chromes, from non-buddies (official only)
acceptBgs	[1] Accept IM window backgrounds
acceptChromes	[1] Accept IM window chromes
acceptBLSounds	[1] Accept BL arrive/depart sounds
acceptIMsounds	[1] Accept IM sounds
noSeeRecentBuddies	[0] User does not see RECENT BUDDIES group
acceptSMSLegal	[0] User has accepted to SMS legal agreement
enterDoesCRLF	[0] Enter does not send IM
playIMSound	[1] Play sound on IM receipt
discloseTyping	[1] Send typing notifications
acceptSuperIcons	[1] Accept 'super- buddies'
acceptBLRichText	[1] Display rich-text screennames in Buddy List
reduceIMSound	[1] Attenuate IM sounds after first
confirmDirectIM	[1] Confirm with local user before starting Direct IM
oneTabbedIMWindow	[1] Show all IMs in one tabbed window
buddyInfoOnMouseover	[1] Popup information when mouse pauses above buddy
discloseBuddyMatches	[1] Let other users know if they have buddy matches
catchIMs	[0] For host use only - Clients use CATCH_IMS_FOR_CLIENT
showFriendlyName	[1] Show alias instead of screenname?
discloseRadio	[1] Buddies know when user listening to AOL radio
showCapabilities	[1] Show capabilities in the Buddy List
showBuddyListFilter	[1] Show Buddy List filter
showAwayIdle	[1] Show away and idle buddies
showMobile	[1] Show mobile buddies
sortBuddyList	[0] Keep Buddy List sorted a-z
catchIMsForClient	[0] IM catcher window enabled?
newMessageSmallNotification	[1] show small notification after new message arrives
noFrequentBuddies	[0] User does not see FREQUENT BUDDIES group
blogAwayMessages	[0] Send away messages to journals ?
blogAIMSigMessages	[0] Send AIM signature to journals ?
blogNoComments	[0] User allows comments ?
friendOfFriend	[0] Allow Friend of Friend queries
friendGetContactList	[0] Allow friend to get my Buddy List
compadInit	[0] ICQ Compad Init
sendBuddyFeed	[1] Send buddy feed - Young Teens(YT)/Kids Only(KO) default to OFF
blkSendIMWhileAway	[0] Block send IM while away
showBuddyFeed	[1] Show What is New indicator
noSaveVanityInfo	[0] Do not save vanity related info (IM sent, idle, etc)
acceptOffLineIM	[1] Accept Offline IMs
showGroups	[0] ICQ: Show buddies in groups ?
sortGroup	[1] ICQ: Sort groups ?
showOffLineBuddies	[1] ICQ: Show/Hide offline buddies
expandBuddies	[0] ICQ: Show multiline information on some buddies
thirdPartyFeeds	[0] BUDDY FEED: Does the owner have 3rd party feeds
notifyReceivedInvite	[1] Notify at login about received AIMPages Invitations
apfAutoAccept	[0] Auto accept AIMPages Invitations
apfAutoAcceptBuddy	[0] If APF_AUTO_ACCEPT & APF_AUTO_ACCEPT_BUDDY, Auto accept invites only from buddies
blockAwayMsgFeed	[0] Block feed storage for away messages
blockAIMProfileFeed	[0] Block feed storage for AIM Profiles
blockAIMPagesFeed	[0] Block feed storage for AIM Pages
blockJournalsFeed	[0] Block feed storage for AOL Journals
blockLocationFeed	[0] Block feed storage for Location data
blockStickiesFeed	[0] Block feed storage for Stickies
blockUncutFeed	[0] Block feed storage for Uncut video
blockLinksFeed	[0] Block feed storage for Interesting Links
blockAIMBulletinFeed	[0] Block feed storage for AIM Bulletins
saveStatusMsg	[1] Save status message

Enumeration: PdMode

The permit/deny mode

Values	Description
permitAll	Allow all aimIds
permitSome	Only aimId's tagged with allow
permitOnList	Only aimIds on Buddy List
denySome	Denied tagged aimIds
denyAll	Allow no one
permitAll	Allow all aimIds
permitSome	Only aimId's tagged with allow
permitOnList	Only aimIds on Buddy List
denySome	Denied tagged aimIds
denyAll	Allow no one

Types

Various data types that the methods return.

Type: Capability

A capability allows clients to broadcast what features they are interested in or support. They are represented with UUIDs. When sending or receiving a capability with these APIs, use the 32 character hex encoding of the UUID.

32 character UUID example: 550e8400e29b41d4a716446655440000

Type: Location

The Location Object contains field relating to a user's location.

Type	Field	Description
String	desc	Description
String	street	Street name
String	city	City name
String	country	Country name
String	state	State name
String	postcode	Postal code
String	accuracy	Measure of how accurate (in meters) location is
String	lat	Latitude
String	lon	Longitude
String	accu_string	Description of the accuracy level, ex Street\|City\|State, etc

Type: QuietHours

Quiet hours

Type	Field	Description
String	start	Start time
String	end	End time

Type: LocationAllow

Location Allow

Type	Field	Description
String	aimId	Allowed AIM id
Array of QuietHours	quietHours	Quiet hours

Type: SmsSegment

The SMS Segment Object contains fields relating to segmenting IMs to send to SMS or IM Forwarding users

Type	Field	Description
Integer	single	Number of bytes that can be sent in a single segment message
Integer	initial	Number of bytes in the first segment of a multi-segment IM
Integer	trailing	Number of bytes in second or later segment of a multisegment IM

Type: Presence

The Presence Object contains fields relating to a users' online availability.

Type	Field	Description
String	aimId	Compressed AIM loginId - use this to identify windows; does not change
String	displayId	Display AIM loginId - use this to display an aimId to the end user
String	emailId	Email address of user - only set when doing an email search
String	friendly	Friendly alias - not always set; this is a local friendly name for the user
Presence State	state	State of the aimId
Integer	onlineTime	Seconds online
Integer	idleTime	Minutes idle
Integer	awayTime	Seconds away
Integer	statusTime	Seconds since status message was changed
String	awayMsg	Away message in xhtml form
String	profileMsg	Profile message in xhtml form
String	statusMsg	Status message in utf8 form
String	buddyIcon	Buddy icon URL
String	presenceIcon	Presence icon URL
Integer	memberSince	When user joined AIM
Array of Capability	capabilities	Capabilities of the user
Location	location	Information that the user has provided about their location
String	ipCountry	Country of the user if known. Based on IP address. Only valid in myInfo objects
Boolean	recent	For buddylist events, any buddies in the Recent Buddies group will have this set
Boolean	bot	For buddylist events, any buddies that are BOTs will have this set
Boolean	shared	For buddylist events, any buddies in the a shared buddies group will have this set
SmsSegment	smsSegment	Information about SMS/IMF users
User Type	userType	Type of user

Type: Group

The Group Object is used to subdivide Buddy lists.

Type	Field	Description
String	name	Name of Group
Boolean	collapsed	List of buddies not expanded
Boolean	recent	This group contains Recent Buddies
Boolean	bot	This group contains system added BOTs
Boolean	shared	This is a shared group
Array of Presence	buddies	Array of Users

Type: Expression

The Expression Object points to the personal Expression data described in the Expression Type enumeration - buddy icons, arrival and departure sounds, and wallpaper.

Type	Field	Description
Expression Type	type	Type of the expression
String	id	Id of the expression
String	URL	URL to fetch the binary data for the expression

Type: MyInfoEvent

The MyInfoEvent, when subscribed to, returns the user's personal profile and online availability. Please refer to the Presence datatype section for specific details.

Type	Field	Description
String	type	Will be "myInfo"
Presence	eventData	Presence Event Data

Type: PresenceEvent

The PresenceEvent, when subscribed to, returns another user's personal profile and online availability. Please refer to the Presence datatype section for specific details.

As users on a logged-in AIM member's Buddy List change their Presence information (by logging in and out, changing their away message, etc.), Presence events are sent by the Web AIM API for pickup by the fetchEvents method.

Type	Field	Description
String	type	Will be "presence"
Presence	eventData	Presence Event Data

Type: TypingEventData

The Typing Event Data indicates whether a user is typing or not. Please refer to the Typing Status section for details.

Type	Field	Description
String	aimId	Source user
Typing Status	typingStatus	Status

Type: TypingEvent

The Typing Event is sent when a user's Typing Status changes.

Type	Field	Description
String	type	Will be "typing"
TypingEventData	eventData	Typing Event Data

Type: DataIMEventData

The Data IM Event Data contains the actual data message as well as the source of the message, its type, and a timestamp.

Type	Field	Description
Presence	source	Presence information about the source user
Capability	dataCapability	AIM Capability to which the message was sent
Data IM Type	dataType	Type of Message
String	dataIM	Base64 encoded data sent from the source user
Integer	timestamp	UTC timestamp of when the IM was sent
String	inviteMsg	For invite types, the message if present

Type: DataIMEvent

The IM Event will be retrieved by the fetchEvents method whenever a data IM is received by the user.

Type	Field	Description
String	type	Will be "dataIM"
DataIMEventData	eventData	Data for the Data IM Event

Type: sentDataIMEventData

The Sent Data IM Event Data contains the actual data message as well as the destination of the message, its type, and a timestamp.

Type	Field	Description
Presence	dest	Presence information about the destination user. Actual presence information may not be known
Capability	dataCapability	AIM Capability to which the message was sent
Data IM Type	dataType	Type of Message
String	dataIM	Base64 encoded data sent from the source user
Integer	timestamp	UTC timestamp of when the IM was sent
String	inviteMsg	For invite types, the message if present

Type: sentDataIMEvent

The Sent Data IM Event will be retrieved by the fetchEvents method whenever a data IM is sent by the user.

Type	Field	Description
String	type	Will be "sentDataIM"
sentDataIMEventData	eventData	Data for the Sent Data IM Event

Type: IMEventData

The IM Event Data contains the actual IM message as well as the source of the message, its autoresponse status, and a timestamp.

Type	Field	Description
Presence	source	Presence information about the source user
String	message	IM from the source user
Boolean	autoResponse	Is this an autoresponse IM?
Integer	timestamp	UTC timestamp of when the IM was sent

Type: IMEvent

The IM Event will be retrieved by the fetchEvents method whenever an IM is received by the user.

Type	Field	Description
String	type	Will be "im"
IMEventData	eventData	IM Event Data

Type: sentIMEventData

The Sent IM Event Data contains the actual IM message as well as the destination of the message, its autoresponse status, and a timestamp.

Type	Field	Description
Presence	dest	Presence information about the source user. Actual online status may not be available
String	message	IM to the destination user
Boolean	autoResponse	Is this an autoresponse IM?
Integer	timestamp	UTC timestamp of when the IM was sent

Type: sentIMEvent

The IM Event will be retrieved by the fetchEvents method whenever an IM is sent by the user.

Type	Field	Description
String	type	Will be "sentIM"
sentIMEventData	eventData	Sent IM Event Data

Type: ClientErrorEventData

The Client Error Event Data contains the error data.

Type	Field	Description
Presence	source	Presence information about the source user
String	cookie	Base64 encoded conversation cookie
IM Channel	channel	Channel client reported error on
Client Error	code	Reason code
Reject Reason	rejectReason	For rendezvous rejects
String	errorInfo	Base64 encoded optional error information

Type: ClientErrorEvent

The Client Error Event will be retrieved by the fetchEvents method whenever a client error is received by the user.

Type	Field	Description
String	type	Will be "clientError"
ClientErrorEventData	eventData	Data for the Data IM Event

Type: OfflineIMEventData

The IM Event Data contains the actual IM message as well as the source of the message, its autoresponse status, and a timestamp.

Type	Field	Description
String	aimId	Source user
String	message	IM from the source user
Integer	timestamp	UTC timestamp of when the IM was sent

Type: OfflineIMEvent

The IM Event will be retrieved by the fetchEvents method whenever an IM is received by the user.

Type	Field	Description
String	type	will be "offlineIM"
OfflineIMEventData	eventData	Offline IM Event Data

Type: BuddyListEventData

The BuddyList Event Data contains the user's complete Buddy List, stored as an array of Buddy List groups.

Type	Field	Description
Array of Group	groups	groups inside the Buddy List

Type: BuddyListEvent

The Buddy List Event is sent to fetchEvents when a user first authenticates and gives permission for the API to access his Buddy List.

Type	Field	Description
String	type	Will be "buddylist"
BuddyListEventData	eventData	Presence Event Data

Type: SessionEndedEvent

This is the Session Ended Event from fetchEvents.

Type	Field	Description
String	type	Will be "sessionEnded"

Type: Event

Event Object is a base class to all the different Events above.

Type	Field	Description
Event Type	type	Type of event
String	eventData	Data for event - see all the *Event types above.

Type: SendImSubCode

The subcode data returned with sendIM for mobile.

Type	Field	Description
Integer	subError	suberror code
String	subReason	reason of the failure

Type: BuddyFeedItem

This is the Buddy Feed Data.

Type	Field	Description
String	aimId	Compressed AIM id
String	title	Title
String	link	Link
String	domain	Domain link is on
String	description	Description
String	category	Category
String	pubDate	Date
String	author	Author
String	guid	guid

Type: RankedUsersLocation

Ranked Users Locations Information

Type	Field	Description
String	name	Description of point
Integer	count	Number of users
Float	lat	latitude
Float	lon	longitude

Type: AddBuddyResultCode

The result code returned for each buddy object.

Type	Field	Description
String	buddy	buddy name
AddBuddyResultCodeValue	resultCode	Status code of each buddy as a result of an action

Type: IMConversationLocation

IM Conversation Location Information

Type	Field	Description
String	name	Description of line
Integer	count	Number of users
Integer	age	How long ago
Float	lat1	latitude1
Float	lon1	longitude1
Float	lat2	latitude2
Float	lon2	longitude2

Type: AIMFightUser

User's AIM Fight information

Type	Field	Description
String	aimId	Compressed AIM id
Integer	score	The users score
Integer	rank	If the user is in the top 5% their numerical rank starting at 1, otherwise 0

Type: PDNameCode

The target name and status code data.

Type	Field	Description
String	aimid	aimid
Integer	statusCode	status code returned for this aimid

Type: PDResultCode

The result code returned for each object.

Type	Field	Description
Integer	pdModeResult	Result of setting pdMode
Array of PDNameCode	allowResults	Status code of each target in pdAllow
Array of PDNameCode	blockResults	Status code of each target in pdBlock
Array of PDNameCode	IgnoreResults	Status code of each target in pdIgnore
Array of PDNameCode	allowRemoveResults	Status code of each target in pdAllowRemove
Array of PDNameCode	blockRemoveResults	Status code of each target in pdBlockRemove
Array of PDNameCode	IgnoreRemoveResults	Status code of each target in pdIgnoreRemove

Methods

This section contains methods supported by the Web AIM API. All of our methods that do not return raw data support both JavaScript Object Notation (JSON) and Simple XML output, so the developer can choose whichever is easier. JSON is a lightweight data-exchange format used by many popular web services. (To learn more about JSON, see JSON.org, as well as the resources linked to from JSON's Wikipedia page.)

Almost every method supports 3 standard parameters:

f (required) to select the format of the returned data
r (optional) to include a request Id that is returned with the results
c (optional) to specify a JSONP callback in the returned results

All of the output is wrapped in shared wrappers which contain the statusCode, statusText, an optional statusDetailCode and if provided in the request, the matching requestId. The HTTP Status Code will always be 200, unless a format parameter is missing, and instead results for the request are contained inside the statusCode field returned in the wrapper.

The JSON standard wrapper looks like this:

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      ...
    }
  }
}

The Simple XML standard wrapper looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>

  <statusText>Ok</statusOk>
  <requestId>123</requestId>
  <data>
     ...
  </data>

</response>

Requests are sent to Web AIM through simple APIs. Each method is appended to the base URL and arguments are passed as parameters. Responses are sent back in Simple XML or JSON formats. If the command sent contained the optional callback parameter 'c', that parameter is prepended to the wrapped JSON literal resulting in a valid JavaScript function call; this is known as JSONP format.

For example, a developer might wish to use the Web AIM API's getToken method to determine whether a visitor has signed in, and if so, obtain an authentication token. The developer takes the base URL for the getToken method, https://api.screenname.aol.com/auth/getToken, and adds his developer key and desired output format, JSON, as parameters. They would like the API response to be parsed by a function, 'authenticate', so they add that as the callback parameter. The full API request looks like this:

https://api.screenname.aol.com/auth/getToken?f=json&k=MYKEY&c=authenticate

If the visitor hasn't signed in, the response from the Web AIM API might look like this:

authenticate({
  "response":{
    "statusCode":401,
    "statusText":"Authentication Required",
    "data":{
        "redirectURL":"http://api.screenname.aol.com/auth/login"
    }
  }
});

This is valid JavaScript. If placed in a script tag and dynamically inserted into the head of the document, it will execute, calling the function specified in the callback parameter - in the above example, 'authenticate'. This is one of JSON's chief advantages; properly padded, it allows developers to dynamically introduce data from other domains without resorting to server-side code.

Since events from the Web AIM API can arrive asynchronously at the client, they are received by performing a long poll on special fetchEvent service. The fetchEvent service waits until there are events ready to be received or a timeout has occured; when a timeout occurs, the caller simply begins a new fetchEvent.

Method: startSession

Start a Web AIM session. Since the AIM server needs to deliver asynchronous events, such as receiving IMs or buddy updates, a session is required for some of the APIs. However most of the APIs do not require a session, so there is no need to create one. After starting a session the AIM Session Id (aimsid) can be used instead of an AOL Authentication Token for most of the APIs. An AOL Authentication Token is required to start a session, which can be obtained with either getToken or clientLogin.

If end user interaction is required, a redirect URL is provide that needs to be shown to the end user in a DHTML control (such as an iframe). This redirection is to request the user's permission to access their Buddy List.

If an iframe is used, the calling code can detect when the end user has completed the interaction by looking for the #CONSENTDONE URL fragment, which the iframe will add to the parent document. The startSession call must be repeated at this point. If the end user does not give permission, the iframe will add the URL fragment #CONSENTCANCEL.

When using a token created with clientLogin the startSession call must be signed. An example of how to calculate sig_sha256 can be found at ClientLogin Example. URL signing requires the computers clock to be accurate or the use of hostTime returned by clientLogin, parameters must be in alphabetical order, and percent-encoding uses upper case characters.

URL: GET http://api.oscar.aol.com/aim/startSession

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	[Required] the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	a	[Required] Use an AOL Authentication Token for authentication, from the getToken call
Event Type	events	[Required] Comma separated list of events to subscribe to, fetchEvents will only return these events. The buddylist event triggers if the user will show up online to other folks or not.
Boolean	encodeData	Base 64 encode the data in imdata events
Capability	assertCaps	Comma separated list of capabilities to assert to other users and to receive from other users
Capability	interestCaps	Comma separated list of capabilities to ONLY receive from other users
Boolean	anonymous	Start an anonymous session
String	friendly	For anonymous sessions, this is an optional friendly name to display
String	language	The language and locale to use in "<lang>-<locale>" format. The lang is the 2 letter language code for I18N (default: en) and the locale is the 2 letter Locale code for I18N (default: us). If not passed in, the language will default to "en-us".
String	clientName	Client name - clientLogin parameter
Integer	clientVersion	Client version - clientLogin parameter
Integer	ts	Epoch timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
Boolean	mobile	Whether this is a mobile session.
Integer	sessionTimeout	Time in seconds before terminating idle web session.
Presence State	view	How we should appear to other users, offline and mobile are not valid in this case

Output Fields

Type	Field	Description
String	fetchBaseURL	Base URL to do fetches with, see fetchEvents method below
String	aimsid	The aimsid to use in other calls
Presence	myInfo	Presence object about logged in user
String	creatorDisplayName	For anonymous sessions, this is the display name to use for the widget creator
String	widgetTitle	For anonymous sessions, this is the widget title to use
String	greetingMsg	For anonymous sessions, this is the greeting msg to use
String	offlineMsg	For anonymous sessions, this is the offline msg to use
String	cssURI	For anonymous sessions, this is the css uri path

Common Status Codes

Status Code	Description
200	Success
408	Timeout of the backend servers
450	Consent required, use the redirectURL and append a k=KEY to it
460	Missing required parameter
462	Parameter error
607	Rate limit signing on, wait a few minutes before trying again

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call

Example: http://api.oscar.aol.com/aim/startSession?f=json&k=KEY&c=callback&a=AOLAUTHTOKEN

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "fetchBaseURL":"http://10.10.10.10/aim/fetchEvents?seq=10",
      "aimsid":"opaquedata",
      "myInfo":{
        "aimId":"chattingchuck",
        "displayId":"ChattingChuck",
        "friendly":"Chuck my Buddy",
        "state":"away",
        "onlineTime":100,
        "awayTime":10,
        "statusTime":100,
        "awayMsg":"I'm busy right now chatting.",
        "profileMsg":"My name is Chuck, and I live on AIM.",
        "statusMsg":"Look at me!",
        "buddyIcon":"",
        "presenceIcon":"http://o.aolcdn.com/aim/img/away.gif",
        "capabilities":[
        "200A0000A28911D3A52D001083341CFA"
        ],
        "location":{
          "desc":"AOL Office",
          "street":"SULLY RD",
          "city":"STERLING",
          "country":"US",
          "state":"VA",
          "postcode":"20166",
          "accuracy":"100",
          "lat":"38.986750",
          "lon":"-77.430500",
          "accu_string":"Block1"
        },
        "ipCountry":"",
        "smsSegment":{
          "single":,
          "initial":,
          "trailing":
        },
        "userType":"aim"
      },
      "creatorDisplayName":"",
      "widgetTitle":"",
      "greetingMsg":"",
      "offlineMsg":"",
      "cssURI":""
    }
  }
}

Sample XML Output


<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>

  <data>
    <fetchBaseURL>http://10.10.10.10/aim/fetchEvents?seq=10</fetchBaseURL>
    <aimsid>opaquedata</aimsid>
    <myInfo>
      <aimId>chattingchuck</aimId>

      <displayId>ChattingChuck</displayId>
      <friendly>Chuck my Buddy</friendly>
      <state>away</state>
      <onlineTime>100</onlineTime>

      <awayTime>10</awayTime>
      <statusTime>100</statusTime>
      <awayMsg>I'm busy right now chatting.</awayMsg>
      <profileMsg>My name is Chuck, and I live on AIM.</profileMsg>

      <statusMsg>Look at me!</statusMsg>
      <buddyIcon></buddyIcon>
      <presenceIcon>http://o.aolcdn.com/aim/img/away.gif</presenceIcon>
      <capabilities>

      <capability>200A0000A28911D3A52D001083341CFA</capability>
      </capabilities>
      <location>
        <desc>AOL Office</desc>
        <street>SULLY RD</street>

        <city>STERLING</city>
        <country>US</country>
        <state>VA</state>
        <postcode>20166</postcode>

        <accuracy>100</accuracy>
        <lat>38.986750</lat>
        <lon>-77.430500</lon>
        <accu_string>Block1</accu_string>

      </location>
      <ipCountry></ipCountry>
      <smsSegment>
        <single></single>
        <initial></initial>

        <trailing></trailing>
      </smsSegment>
      <userType>aim</userType>
    </myInfo>
    <creatorDisplayName></creatorDisplayName>

    <widgetTitle></widgetTitle>
    <greetingMsg></greetingMsg>
    <offlineMsg></offlineMsg>
    <cssURI></cssURI>
  </data>

</response>

Method: fetchEvents

Fetch outstanding events for an aimsid, waiting up to timeout milliseconds before returning. This URL is never formed on its own - instead, the URL is created by taking the fetchBaseURL returned by startSession or the last fetchEvents call, appending the required format parameter, and then optionally appending a requestId or callback parameters. Appending the aimsid is not necessary; the API automatically adds it to the fetchBaseURL as the first parameter. The client should wait at least timeToNextFetch milliseconds between calls and make sure to use the new fetchBaseURL returned for the next call. Using an old fetchBaseURL will cause previous events to be repeated. A session will be timed out if there isn't an active fetchEvents for more then 30 seconds.

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	aimsid	[Required] Use an AIM Session Id from the startSession call for authentication
Integer	timeout	Timeout in milliseconds that the server will wait before returning. Minimum 500ms, maximum 1 hour. On timeout the server will still respond, there will be no events however.
Boolean	peek	If true, then this fetch will not update the most recent seqNum returned

Output Fields

Type	Field	Description
Integer	timeToNextFetch	Milliseconds to wait before doing the next event fetch
String	fetchBaseURL	Base URL to do next fetch with
Array of Event	events	Events that occured between the last fetch and now, can be empty on timeout

Common Status Codes

Status Code	Description
200	Ok
460	Missing required parameter
462	Parameter error

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "timeToNextFetch":500,
      "fetchBaseURL":"http://10.10.10.10/aim/fetchEvents?seq=11",
      "events":[
      {
        "type":"sessionEnded",
        "eventData":""
      }
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>

  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <timeToNextFetch>500</timeToNextFetch>

    <fetchBaseURL>http://10.10.10.10/aim/fetchEvents?seq=11</fetchBaseURL>
    <events>
    <event>
      <type>sessionEnded</type>
      <eventData></eventData>

    </event>
    </events>
  </data>
</response>

Method: deleteEvent

To delete an event

URL: GET http://api.oscar.aol.com/aim/deleteEvent

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	aimsid	[Required] Use an AIM Session Id from the startSession call for authentication
Integer	eventNumber	[Required] event number to delete

Common Status Codes

Status Code	Description
200	Ok
401	Authorization required
460	Missing required parameter
462	Parameter error

Example: http://api.oscar.aol.com/aim/deleteEvent?f=json&aimsid=AIMSID&eventNumber=1

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>

  <data>
  </data>
</response>

Method: endSession

To be used when the user logs out or navigates away from the application, endSession ends an Web AIM session and set this session offline. A sessionEnded event will be generated after the last event is retrieved, so the client knows when to stop fetching events. If there isn't a active fetchEvents for more then 30 seconds, the backend will auto end the session.

URL: GET http://api.oscar.aol.com/aim/endSession

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	aimsid	[Required] Use an AIM Session Id from the startSession call for authentication

Common Status Codes

Status Code	Description
200	Success
462	Parameter error

Example: http://api.oscar.aol.com/aim/endSession?f=json&k=MYKEY&c=callback&aimsid=AIMSID

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>

  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: addBuddy

Add a buddy to the buddylist.

URL: GET http://api.oscar.aol.com/buddylist/addBuddy

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication
String	buddy	[Required] buddy name. Can be multipled.
String	group	[Required] group name to add buddy to

Common Status Codes

Status Code	Description
200	Success
462	Parameter error

Example: http://api.oscar.aol.com/buddylist/addBuddy?f=json&c=callback&aimsid=AIMSID&buddy=buddy1&group=groupABC

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>

  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: addGroup

Add an empty group to the buddylist.

URL: GET http://api.oscar.aol.com/buddylist/addGroup

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	[Required] Use an AIM Session Id from the startSession call for authentication
String	group	[Required] group name to add

Common Status Codes

Status Code	Description
200	Success
462	Parameter error

Example: http://api.oscar.aol.com/buddylist/addGroup?f=json&c=callback&aimsid=AIMSID&group=groupABC

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>

  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>

  </data>
</response>

Method: removeBuddy

Remove a buddy from the buddylist.

URL: GET http://api.oscar.aol.com/buddylist/removeBuddy

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	Epoch timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	buddy	[Required] buddy name
String	group	[Required] group name to remove buddy from

Common Status Codes

Status Code	Description
200	Success
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession

Example: http://api.oscar.aol.com/buddylist/removeBuddy?f=json&c=callback&aimsid=AIMSID&buddy=buddy1&group=groupABC

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>

  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: removeGroup

Remove a group from the buddylist when possible, if the group doesn't exist the API still returns SUCCESS

URL: GET http://api.oscar.aol.com/buddylist/removeGroup

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	Epoch timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	group	[Required] group name to remove

Common Status Codes

Status Code	Description
200	Success
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession

Example: http://api.oscar.aol.com/buddylist/removeGroup?f=json&c=callback&aimsid=AIMSID&group=groupABC

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>

  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>

  </data>
</response>

Method: renameGroup

Rename a group in the buddylist.

URL: GET http://api.oscar.aol.com/buddylist/renameGroup

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	Epoch timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	oldGroup	[Required] Name of group to rename
String	newGroup	[Required] New name for group

Common Status Codes

Status Code	Description
200	Success
462	If oldGroup doesn't exist or if newGroup already exists

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession

Example: http://api.oscar.aol.com/buddylist/renameGroup?f=json&c=callback&aimsid=AIMSID&oldGroup=groupABC&newGroup=groupDEF

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>

  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: setBuddyAttribute

Set an attribute for a buddy

URL: GET http://api.oscar.aol.com/buddylist/setBuddyAttribute

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	Epoch timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	buddy	[Required] buddy name
String	friendly	Friendly name

Common Status Codes

Status Code	Description
200	Success
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession

Example: http://api.oscar.aol.com/buddylist/setBuddyAttribute?f=json&c=callback&aimsid=AIMSID&buddy=buddy1&friendly=

Sample JSON Output


{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>

  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: setGroupAttribute

Set an attribute for a group

URL: GET http://api.oscar.aol.com/buddylist/setGroupAttribute

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	Epoch timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	group	[Required] group name
Boolean	collapsed	Is the group collapsed or not

Common Status Codes

Status Code	Description
200	Success
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession

Example: http://api.oscar.aol.com/buddylist/setGroupAttribute?f=json&c=callback&aimsid=AIMSID&group=group&collapsed=

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>

  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: moveGroup

Move a group

URL: GET http://api.oscar.aol.com/buddylist/moveGroup

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	Epoch timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	group	[Required] Group to move. Recent Buddies and Offline groups can't be moved
String	beforeGroup	Move the group before this group, if missing or group does not exist moving to the end.

Common Status Codes

Status Code	Description
200	Success
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>

<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>

  <data>
  </data>
</response>

Method: moveBuddy

Move a buddy inside a group

URL: GET http://api.oscar.aol.com/buddylist/moveBuddy

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	Epoch timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	group	[Required] Group buddy is in
String	buddy	[Required] Buddy to move
String	beforeBuddy	Move the buddy before this buddy, if not specified move the buddy to the end of the group

Common Status Codes

Status Code	Description
200	Success
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>

  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: copyBuddyLists

Copy entire Buddy List and all host based settings from one account to another account. The existing Buddy List and all host based settings of the copy-to account will be completely replaced. This method is tricky in that two tokens must be provided

URL: GET http://api.oscar.aol.com/buddylist/copy

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	[Required] the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	s	Use trusted authentication, the source user
String	a	Use an AOL Authentication Token for authentication, from the getToken call
String	ta	[Required] Target token, where the source users buddylist should be copied to

Common Status Codes

Status Code	Description
200	Success
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call

Example: http://api.oscar.aol.com/buddylist/copy?f=json&k=MYKEY&c=callback&a=SRCTOKEN&ta=TGTTOKEN

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>

<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>

  <data>
  </data>
</response>

Method: deleteUser

Delete user's entire Buddy List with option to bump user offline if the user is online.

URL: GET http://api.oscar.aol.com/buddylist/deleteUser

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	Epoch timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
Boolean	noBumpUser	Is the user going to be bumped offline or not. By default, the user will be bumped off

Common Status Codes

Status Code	Description
200	Success
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>

  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: getPresence

Get the Presence information for one or more target users. Can also be used to retrieve the presence for the entire Buddy List. Can be used with an aimsid, with a token, or anonymously with no aimsid or token. In anonymous mode only users who allow anonymous presence will appear online. The Buddy List query does not work anonymously, for obvious reasons. To reduce the amount of data returned, it is possible to turn some of the fields off.

This method allows both Web AIM Keys and the previously support Presence Keys.

URL: GET http://api.oscar.aol.com/presence/get

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	[Required] either an AIM Web Key or AIM Presence Key from http://dev.aol.com/aim
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	Epoch timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	t	Target aimIds, returns the results in the users section. Multiple t parameters are allowed
String	tw	Wimzi key target, returns the results in the users section. Multiple tw parameters are allowed
Boolean	bl	Not valid for anonymous queries, returns the Buddy List in the groups section
Boolean	emailLookup	[Default 0] - For targets, do an email look up and return presence on valid aimIds
Boolean	notFound	[Default 0] - For email lookups that fail, use a special not found icon instead of offline
Boolean	awayMsg	[Default 0] - Return away messages
Boolean	profileMsg	[Default 0] - Return profile messages
Boolean	presenceIcon	[Default 1] - Return presence icon
Boolean	location	[Default 1] - Return location information
Boolean	capabilities	[Default 0] - Return capability information
Boolean	memberSince	[Default 0] - Return member since information
Boolean	statusMsg	[Default 0] - Return status message information
Boolean	friendly	[Default 0] - Return friendly name

Output Fields

Type	Field	Description
Array of Group	groups	List of buddylist groups
Array of Presence	users	Target aimId, multiple t parameters are allowed

Common Status Codes

Status Code	Description
200	Success
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession

Example: http://api.oscar.aol.com/presence/get?f=json&k=MYKEY&c=callback&aimsid=AIMSID&t=ChattingChuck& awayMsg=1&profileMsg=1

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "groups":[
      {
        "name":"Friends",
        "collapsed":,
        "recent":,
        "bot":,
        "shared":,
        "buddies":[
        {
          "aimId":"chattingchuck",
          "displayId":"ChattingChuck",
          "friendly":"Chuck my Buddy",
          "state":"away",
          "onlineTime":100,
          "awayTime":10,
          "statusTime":100,
          "awayMsg":"I'm busy right now chatting.",
          "profileMsg":"My name is Chuck, and I live on AIM.",
          "statusMsg":"Look at me!",
          "buddyIcon":"",
          "presenceIcon":"http://o.aolcdn.com/aim/img/away.gif",
          "capabilities":[
          "200A0000A28911D3A52D001083341CFA"
          ],
          "location":{
            "desc":"AOL Office",
            "street":"SULLY RD",
            "city":"STERLING",
            "country":"US",
            "state":"VA",
            "postcode":"20166",
            "accuracy":"100",
            "lat":"38.986750",
            "lon":"-77.430500",
            "accu_string":"Block1"
          },
          "ipCountry":"",
          "smsSegment":{
            "single":,
            "initial":,
            "trailing":
          },
          "userType":"aim"
        }
        ]
      }
      ],
      "users":[
      {
        "aimId":"chattingchuck",
        "displayId":"ChattingChuck",
        "friendly":"Chuck my Buddy",
        "state":"away",
        "onlineTime":100,
        "awayTime":10,
        "statusTime":100,
        "awayMsg":"I'm busy right now chatting.",
        "profileMsg":"My name is Chuck, and I live on AIM.",
        "statusMsg":"Look at me!",
        "buddyIcon":"",
        "presenceIcon":"http://o.aolcdn.com/aim/img/away.gif",
        "capabilities":[
        "200A0000A28911D3A52D001083341CFA"
        ],
        "location":{
          "desc":"AOL Office",
          "street":"SULLY RD",
          "city":"STERLING",
          "country":"US",
          "state":"VA",
          "postcode":"20166",
          "accuracy":"100",
          "lat":"38.986750",
          "lon":"-77.430500",
          "accu_string":"Block1"
        },
        "ipCountry":"",
        "smsSegment":{
          "single":,
          "initial":,
          "trailing":
        },
        "userType":"aim"
      }
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>

  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <groups>
    <group>

      <name>Friends</name>
      <collapsed></collapsed>
      <recent></recent>
      <bot></bot>

      <shared></shared>
      <buddies>
      <buddy>
        <aimId>chattingchuck</aimId>
        <displayId>ChattingChuck</displayId>

        <friendly>Chuck my Buddy</friendly>
        <state>away</state>
        <onlineTime>100</onlineTime>
        <awayTime>10</awayTime>

        <statusTime>100</statusTime>
        <awayMsg>I'm busy right now chatting.</awayMsg>
        <profileMsg>My name is Chuck, and I live on AIM.</profileMsg>
        <statusMsg>Look at me!</statusMsg>

        <buddyIcon></buddyIcon>
        <presenceIcon>http://o.aolcdn.com/aim/img/away.gif</presenceIcon>
        <capabilities>
        <capability>200A0000A28911D3A52D001083341CFA</capability>

        </capabilities>
        <location>
          <desc>AOL Office</desc>
          <street>SULLY RD</street>
          <city>STERLING</city>

          <country>US</country>
          <state>VA</state>
          <postcode>20166</postcode>
          <accuracy>100</accuracy>

          <lat>38.986750</lat>
          <lon>-77.430500</lon>
          <accu_string>Block1</accu_string>
        </location>

        <ipCountry></ipCountry>
        <smsSegment>
          <single></single>
          <initial></initial>
          <trailing></trailing>

        </smsSegment>
        <userType>aim</userType>
      </buddy>
      </buddies>
    </group>

    </groups>
    <users>
    <user>
      <aimId>chattingchuck</aimId>
      <displayId>ChattingChuck</displayId>

      <friendly>Chuck my Buddy</friendly>
      <state>away</state>
      <onlineTime>100</onlineTime>
      <awayTime>10</awayTime>

      <statusTime>100</statusTime>
      <awayMsg>I'm busy right now chatting.</awayMsg>
      <profileMsg>My name is Chuck, and I live on AIM.</profileMsg>
      <statusMsg>Look at me!</statusMsg>

      <buddyIcon></buddyIcon>
      <presenceIcon>http://o.aolcdn.com/aim/img/away.gif</presenceIcon>
      <capabilities>
      <capability>200A0000A28911D3A52D001083341CFA</capability>

      </capabilities>
      <location>
        <desc>AOL Office</desc>
        <street>SULLY RD</street>
        <city>STERLING</city>

        <country>US</country>
        <state>VA</state>
        <postcode>20166</postcode>
        <accuracy>100</accuracy>

        <lat>38.986750</lat>
        <lon>-77.430500</lon>
        <accu_string>Block1</accu_string>
      </location>

      <ipCountry></ipCountry>
      <smsSegment>
        <single></single>
        <initial></initial>
        <trailing></trailing>

      </smsSegment>
      <userType>aim</userType>
    </user>
    </users>
  </data>

</response>

Method: getBuddyListPresence

There is no special getBuddyList method, instead the getPresence API can be used with a special bl=1 parameter.

URL: GET http://api.oscar.aol.com/presence/get

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	[Required] either an AIM Web Key or AIM Presence Key from http://dev.aol.com/aim
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	Epoch timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	t	Target aimIds, returns the results in the users section. Multiple t parameters are allowed
Boolean	bl	returns the Buddy List in the groups section

Output Fields

Type	Field	Description
Array of Group	groups	List of buddylist groups
Array of Presence	users	Target aimId, multiple t parameters are allowed

Common Status Codes

Status Code	Description
200	Success
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession

Example: http://api.oscar.aol.com/presence/get?f=json&k=MYKEY&c=callback&a=token&t=ChattingChuck&bl=1

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "groups":[
      {
        "name":"Friends",
        "collapsed":,
        "recent":,
        "bot":,
        "shared":,
        "buddies":[
        {
          "aimId":"chattingchuck",
          "displayId":"ChattingChuck",
          "friendly":"Chuck my Buddy",
          "state":"away",
          "onlineTime":100,
          "awayTime":10,
          "statusTime":100,
          "awayMsg":"I'm busy right now chatting.",
          "profileMsg":"My name is Chuck, and I live on AIM.",
          "statusMsg":"Look at me!",
          "buddyIcon":"",
          "presenceIcon":"http://o.aolcdn.com/aim/img/away.gif",
          "capabilities":[
          "200A0000A28911D3A52D001083341CFA"
          ],
          "location":{
            "desc":"AOL Office",
            "street":"SULLY RD",
            "city":"STERLING",
            "country":"US",
            "state":"VA",
            "postcode":"20166",
            "accuracy":"100",
            "lat":"38.986750",
            "lon":"-77.430500",
            "accu_string":"Block1"
          },
          "ipCountry":"",
          "smsSegment":{
            "single":,
            "initial":,
            "trailing":
          },
          "userType":"aim"
        }
        ]
      }
      ],
      "users":[
      {
        "aimId":"chattingchuck",
        "displayId":"ChattingChuck",
        "friendly":"Chuck my Buddy",
        "state":"away",
        "onlineTime":100,
        "awayTime":10,
        "statusTime":100,
        "awayMsg":"I'm busy right now chatting.",
        "profileMsg":"My name is Chuck, and I live on AIM.",
        "statusMsg":"Look at me!",
        "buddyIcon":"",
        "presenceIcon":"http://o.aolcdn.com/aim/img/away.gif",
        "capabilities":[
        "200A0000A28911D3A52D001083341CFA"
        ],
        "location":{
          "desc":"AOL Office",
          "street":"SULLY RD",
          "city":"STERLING",
          "country":"US",
          "state":"VA",
          "postcode":"20166",
          "accuracy":"100",
          "lat":"38.986750",
          "lon":"-77.430500",
          "accu_string":"Block1"
        },
        "ipCountry":"",
        "smsSegment":{
          "single":,
          "initial":,
          "trailing":
        },
        "userType":"aim"
      }
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>

  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <groups>
    <group>

      <name>Friends</name>
      <collapsed></collapsed>
      <recent></recent>
      <bot></bot>

      <shared></shared>
      <buddies>
      <buddy>
        <aimId>chattingchuck</aimId>
        <displayId>ChattingChuck</displayId>

        <friendly>Chuck my Buddy</friendly>
        <state>away</state>
        <onlineTime>100</onlineTime>
        <awayTime>10</awayTime>

        <statusTime>100</statusTime>
        <awayMsg>I'm busy right now chatting.</awayMsg>
        <profileMsg>My name is Chuck, and I live on AIM.</profileMsg>
        <statusMsg>Look at me!</statusMsg>

        <buddyIcon></buddyIcon>
        <presenceIcon>http://o.aolcdn.com/aim/img/away.gif</presenceIcon>
        <capabilities>
        <capability>200A0000A28911D3A52D001083341CFA</capability>

        </capabilities>
        <location>
          <desc>AOL Office</desc>
          <street>SULLY RD</street>
          <city>STERLING</city>

          <country>US</country>
          <state>VA</state>
          <postcode>20166</postcode>
          <accuracy>100</accuracy>

          <lat>38.986750</lat>
          <lon>-77.430500</lon>
          <accu_string>Block1</accu_string>
        </location>

        <ipCountry></ipCountry>
        <smsSegment>
          <single></single>
          <initial></initial>
          <trailing></trailing>

        </smsSegment>
        <userType>aim</userType>
      </buddy>
      </buddies>
    </group>

    </groups>
    <users>
    <user>
      <aimId>chattingchuck</aimId>
      <displayId>ChattingChuck</displayId>

      <friendly>Chuck my Buddy</friendly>
      <state>away</state>
      <onlineTime>100</onlineTime>
      <awayTime>10</awayTime>

      <statusTime>100</statusTime>
      <awayMsg>I'm busy right now chatting.</awayMsg>
      <profileMsg>My name is Chuck, and I live on AIM.</profileMsg>
      <statusMsg>Look at me!</statusMsg>

      <buddyIcon></buddyIcon>
      <presenceIcon>http://o.aolcdn.com/aim/img/away.gif</presenceIcon>
      <capabilities>
      <capability>200A0000A28911D3A52D001083341CFA</capability>

      </capabilities>
      <location>
        <desc>AOL Office</desc>
        <street>SULLY RD</street>
        <city>STERLING</city>

        <country>US</country>
        <state>VA</state>
        <postcode>20166</postcode>
        <accuracy>100</accuracy>

        <lat>38.986750</lat>
        <lon>-77.430500</lon>
        <accu_string>Block1</accu_string>
      </location>

      <ipCountry></ipCountry>
      <smsSegment>
        <single></single>
        <initial></initial>
        <trailing></trailing>

      </smsSegment>
      <userType>aim</userType>
    </user>
    </users>
  </data>

</response>

Method: getPresenceIcon

This method call is a short cut to the anonymous presence icon for a user or email address, returning a HTTP 302 redirect to the correct standard presence icon.

URL: GET http://api.oscar.aol.com/presence/icon

Input Parameters

Type	Field	Description
String	r	Request id
String	k	[Required] the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	t	Target aimId, only one t or tw is allowed
String	tw	Wimzi key, only one t or tw is allowed
Boolean	emailLookup	For targets, do an email look up and return presence on valid aimIds
Boolean	notFound	For email lookups that fail, use a special not found icon instead of offline

Common Status Codes

Status Code	Description
200	Success
462	Parameter error

Example: <img src="http://api.oscar.aol.com/presence/icon?&k=MYKEY&t=ChattingChuck">

Method: setState

Sets the user's Presence information. The setState method call requires an aimsid from a previous startSession call.

URL: GET http://api.oscar.aol.com/presence/setState

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	aimsid	[Required] Use an AIM Session Id from the startSession call for authentication
Presence State	view	[Required] How we should appear to other users, offline and mobile are not valid in this case
String	away	If setting the state to away, this is the away message display to other users on mouse over
Boolean	encodeData	Base 64 encode the data in imdata events
Capability	assertCaps	Comma separated list of capabilities to assert to other users.
Capability	interestCaps	Comma separated list of capabilities to receive from other users. AssertCaps will also be received from other users.
String	friendly	For anonymous sessions, this is an optional friendly name to display

Output Fields

Type	Field	Description
Presence	myInfo	Information about the logged in user after applying the state change

Common Status Codes

Status Code	Description
200	Success
460	Missing required parameter
462	Parameter error

Example: http://api.oscar.aol.com/presence/setState?f=json&k=MYKEY&c=callback&aimsid=AIMSID&view=away&away=Gone

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "myInfo":{
        "aimId":"chattingchuck",
        "displayId":"ChattingChuck",
        "friendly":"Chuck my Buddy",
        "state":"away",
        "onlineTime":100,
        "awayTime":10,
        "statusTime":100,
        "awayMsg":"I'm busy right now chatting.",
        "profileMsg":"My name is Chuck, and I live on AIM.",
        "statusMsg":"Look at me!",
        "buddyIcon":"",
        "presenceIcon":"http://o.aolcdn.com/aim/img/away.gif",
        "capabilities":[
        "200A0000A28911D3A52D001083341CFA"
        ],
        "location":{
          "desc":"AOL Office",
          "street":"SULLY RD",
          "city":"STERLING",
          "country":"US",
          "state":"VA",
          "postcode":"20166",
          "accuracy":"100",
          "lat":"38.986750",
          "lon":"-77.430500",
          "accu_string":"Block1"
        },
        "ipCountry":"",
        "smsSegment":{
          "single":,
          "initial":,
          "trailing":
        },
        "userType":"aim"
      }
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>

  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <myInfo>
      <aimId>chattingchuck</aimId>

      <displayId>ChattingChuck</displayId>
      <friendly>Chuck my Buddy</friendly>
      <state>away</state>
      <onlineTime>100</onlineTime>

      <awayTime>10</awayTime>
      <statusTime>100</statusTime>
      <awayMsg>I'm busy right now chatting.</awayMsg>
      <profileMsg>My name is Chuck, and I live on AIM.</profileMsg>

      <statusMsg>Look at me!</statusMsg>
      <buddyIcon></buddyIcon>
      <presenceIcon>http://o.aolcdn.com/aim/img/away.gif</presenceIcon>
      <capabilities>

      <capability>200A0000A28911D3A52D001083341CFA</capability>
      </capabilities>
      <location>
        <desc>AOL Office</desc>
        <street>SULLY RD</street>

        <city>STERLING</city>
        <country>US</country>
        <state>VA</state>
        <postcode>20166</postcode>

        <accuracy>100</accuracy>
        <lat>38.986750</lat>
        <lon>-77.430500</lon>
        <accu_string>Block1</accu_string>

      </location>
      <ipCountry></ipCountry>
      <smsSegment>
        <single></single>
        <initial></ini

Open AIM Quick Hits

Build Applications

Examples & Support

Documentation

Topic Centers

Typical Authenticated Application Flow

Typical Anonymous Application Flow

Enumerations

Enumeration: Format

Enumeration: Presence State

Enumeration: User Type

Enumeration: Event Type

Enumeration: Typing Status

Enumeration: Expression Type

Enumeration: Data IM Type

Enumeration: Reject Reason

Enumeration: IM Channel

Enumeration: Client Error

Enumeration: PdMode

Enumeration: AddBuddyResultCodeValue

Enumeration: Preferences

Enumeration: PdMode

Types

Type: Capability

Type: Location

Type: QuietHours

Type: LocationAllow

Type: SmsSegment

Type: Presence

Type: Group

Type: Expression

Type: MyInfoEvent

Type: PresenceEvent

Type: TypingEventData

Type: TypingEvent

Type: DataIMEventData

Type: DataIMEvent

Type: sentDataIMEventData

Type: sentDataIMEvent

Type: IMEventData

Type: IMEvent

Type: sentIMEventData

Type: sentIMEvent

Type: ClientErrorEventData

Type: ClientErrorEvent

Type: OfflineIMEventData

Type: OfflineIMEvent

Type: BuddyListEventData

Type: BuddyListEvent

Type: SessionEndedEvent

Type: Event

Type: SendImSubCode

Type: BuddyFeedItem

Type: RankedUsersLocation

Type: AddBuddyResultCode

Type: IMConversationLocation

Type: AIMFightUser

Type: PDNameCode

Type: PDResultCode

Methods

Method: startSession

Input Parameters

Output Fields

Common Status Codes

Common Status Detail Codes

Example: http://api.oscar.aol.com/aim/startSession?f=json&k=KEY&c=callback&a=AOLAUTHTOKEN

Sample JSON Output

Sample XML Output

Method: fetchEvents

Input Parameters

Output Fields

Common Status Codes

Sample JSON Output

Sample XML Output

Method: deleteEvent

Input Parameters

Common Status Codes

Example: http://api.oscar.aol.com/aim/deleteEvent?f=json&aimsid=AIMSID&eventNumber=1

Sample JSON Output