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 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 |
|---|---|---|
|
|
Enumerations
Enumeration: Format
The return format of the APIs
| Values | Description |
|---|---|
| json | JSON Format |
| xml | Simple XML Format |
| php | Serialized PHP |
| amf0 | Flash AMF0 format |
| amf3 | Flash 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: Event Type
Web AIM supports multiple different event types. Each event type needs to be explicitly subscribed to (except for endSession) when calling startSession. As the different events occur asynchronously, calls to the fetchEvents method will return them.
| 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 |
| endSession | Session ended, do not call fetchEvents anymore |
| offlineIM | Offline Instant Message |
Enumeration: Typing Status
The current IM typing status
| 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 |
Enumeration: Data IM Type
The type of IM data
| 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: IM Channel
Internal channel used for IM
| Values | Description |
|---|---|
| text | Regular text IM |
| data | Data or Rendezvous IM |
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 |
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: 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 |
Type: Group
The Group Object is used to subdivide Buddy lists.
| Type | Field | Description |
|---|---|---|
| String | name | Name of Group |
| Array of Presence | buddies | Array of Users |
Type: Token Information
The Token Object is returned by the getToken method and is used for authentication. The Token Object's authentication string 'a' is only returned by getToken if the AIM user 'loginId' has successfully authenticated.
| Type | Field | Description |
|---|---|---|
| String | a | The AOL Authentication Token |
| Integer | expiresIn | Time until the token will expire |
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: 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: 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: 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: 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 |
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.)
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, 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: getToken
Many of AIM's Web Services support an AOL Authentication Token. A token can be obtained by calling the following URL - note that the base URL is different then the rest of the Web AIM Services. The token is passed on most URLs using the 'a' parameter.
If the end user is not yet authenticated, getToken returns a redirect URL to AOL's Screen Name Service, which needs to be shown to the end user in a DHTML control (such as an iframe). Before displaying the content to the user, add your developer's key to the end of the redirect URL using the k=KEY parameter.
When the end user has completed the authentication, the Screen Name Service will change the URL anchor of the parent document to #AUTHDONE. If the end user cancels authentication, the Screen Name Service will change the URL anchor to #AUTHCANCEL.
Full documentation for AOL Open Authentication is available here.
Both the same key used to create a token and the same referer must be used with all Web AIM API calls
URL: GET https://api.screenname.aol.com/auth/getToken
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 | the loginId of the source user if known - this fills in the loginId field of the login form |
| String | language | the required language and locale of the error/status messages. This is always 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 be extracted from HTTP header (Accept-Language) and if that is not available will default to "en-us". |
Output Fields
| Type | Field | Description |
|---|---|---|
| String | redirectURL | If end user interaction is required, a redirectURL is provided, append the key (k= parameter) before displaying to the user |
| Token Information | token | If token request is successful, the token and other information |
Common Status Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 401 | Authentication required, use the redirectURL |
Example: https://api.screenname.aol.com/auth/getToken?f=json&k=MYKEY&c=callback
Sample JSON Output
{
"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
"redirectURL":"http://www.aol.com/someurl",
"token":{
"a":"opaquedata",
"expiresIn":12345
}
}
}
}
Sample XML Output
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
<redirectURL>http://www.aol.com/someurl</redirectURL>
<token>
<a>opaquedata</a>
<expiresIn>12345</expiresIn>
</token>
</data>
</response>
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 | friendy | 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 required parameter |
| Integer | clientVersion | Client version - clientLogin required parameter |
| Integer | ts | Epoch timestamp - clientLogin required parameter |
| String | sig_sha256 | Signature - clientLogin required parameter. |
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 |
| 607 | Rate limit signing on, wait a few minutes before trying again |
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"
]
},
"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>
</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. |
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 |
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":"endSession",
"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>endSession</type>
<eventData></eventData>
</event>
</events>
</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 |
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 - k is not required |
| String | a | Use an AOL Authentication Token for authentication, from the getToken call |
| String | buddy | [Required] buddy name |
| String | group | [Required] group name to add buddy to |
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: 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 |
| String | buddy | [Required] buddy name |
| String | group | [Required] group name to remove buddy from |
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 |
| String | group | [Required] group name to remove |
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 |
| String | oldGroup | [Required] Name of group to rename |
| String | newGroup | [Required] New name for group |
Common Status Codes
| Status Code | Description |
|---|---|
| 462 | If oldGroup doesn't exist or if newGroup already exists |
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 |
| String | buddy | [Required] buddy name |
| String | friendly | Friendly name |
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 |
| String | group | [Required] group name |
| Boolean | collapsed | Is the group collapsed or not |
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 |
| 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. |
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 |
| 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 |
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 |
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 |
| Boolean | noBumpUser | Is the user going to be bumped offline or not. By default, the user will be bumped off |
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 |
| 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 |
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",
"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"
]
}
]
}
],
"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"
]
}
]
}
}
}
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>
<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>
</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>
</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 |
| 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 |
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",
"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"
]
}
]
}
],
"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"
]
}
]
}
}
}
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>
<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>
</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>
</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 |
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 | friendy | 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 |
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"
]
}
}
}
}
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>
</myInfo>
</data>
</response>
Method: setStatus
Sets the user's status message.
URL: GET http://api.oscar.aol.com/presence/setStatus
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 |
| String | statusMsg | [Required] status message display to other users |
Example: http://api.oscar.aol.com/presence/setStatus?f=json&c=callback&aimsid=AIMSID&statusMsg=mystatus
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: setProfile
Set the AIM buddy info for a user.
URL: GET http://api.oscar.aol.com/presence/setProfile
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 |
| String | profile | [Required] The new AIM Profile, or blank to clear the current AIM Profile |
Common Status Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 460 | Missing required parameter |
Example: http://api.oscar.aol.com/presence/setProfile?f=json&k=MYKEY&c=callback&aimsid=AIMSID&profile="Profile Message"
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: getProfile
Get the AIM Profile message for an aimId .
URL: GET http://api.oscar.aol.com/presence/getProfile
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 |
Output Fields
| Type | Field | Description |
|---|---|---|
| String | profileMsg | AIM Profile Message |
Common Status Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 460 | Missing required parameter |
Example: http://api.oscar.aol.com/presence/getProfile?f=json&k=MYKEY&c=callback&s=ChattingChuck
Sample JSON Output
{
"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
"profileMsg":"Profile Message"
}
}
}
Sample XML Output
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
<profileMsg>Profile Message</profileMsg>
</data>
</response>
Method: sendIM
Send an IM to an AIM user. Requires a valid aimsid from the startSession call or an AOL Authentication Token.
URL: GET http://api.oscar.aol.com/im/sendIM
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 | a | Use an AOL Authentication Token for authentication, from the getToken call |
| String | aimsid | Use an AIM Session Id from the startSession call for authentication - k is not required |
| String | t | [Required] Destination aimId |
| String | message | [Required] utf8 encoded message, limited to 1024 bytes |
| Boolean | autoResponse | Set the auto response flag be set, can not be set with offlineIM |
| Boolean | offlineIM | Deliver as an offline IM when possible if the user isn't online, autoResponse flag can no bet set |
Common Status Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 430 | Sending IMs too fast |
| 450 | Consent required, use the redirectURL and append a k=KEY to it |
| 460 | Missing required parameter |
| 602 | Target user is not available |
| 606 | Message is too large |
Example: http://api.oscar.aol.com/im/sendIM?f=json&k=MYKEY&c=callback&aimsid=AIMSID&msg=Hi&t=ChattingChuck
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: sendDataIM
Send a Data IM to an AIM user. Requires a valid aimsid from the startSession call or an AOL Authentication Token.
URL: GET http://api.oscar.aol.com/im/sendDataIM
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 | a | Use an AOL Authentication Token for authentication, from the getToken call |
| String | aimsid | Use an AIM Session Id from the startSession call for authentication - k is not required |
| String | t | [Required] Destination aimId |
| Capability | cap | [Required] AIM Capability |
| Data IM Type | type | [Required] Type of Message |
| String | data | [Required] Data to send remote AIM user. |
| Boolean | dataIsBase64 | If present, then the data parameter is base64 encoded |
| Boolean | autoResponse | Should the auto response flag be set |
| String | inviteMsg | For the invite message type, and optional invite message can be included |
Common Status Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 430 | Sending IMs too fast |
| 450 | Consent required, use the redirectURL and append a k=KEY to it |
| 460 | Missing required parameter |
| 602 | Target user is not available |
| 605 | Target user doesn't support the capability |
| 606 | Message is too large |
Example: http://api.oscar.aol.com/im/sendDataIM?f=json&k=MYKEY&c=callback&aimsid=AIMSID&data={data}&t=ChattingChuck& cookie=MTIzNDU2NzgK
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: setTyping
Set the current typing status. Only send a typing status on event change - there is no need to send a typing for every key press. Requires a valid aimsid from the startSession call.
URL: GET http://api.oscar.aol.com/im/setTyping
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 |
| String | t | [Required] Destination aimId |
| Typing Status | typingStatus | [Required] The new typing status |
Common Status Codes
| Status Code | Description |
|---|---|
| 200 | Success |
Example: http://api.oscar.aol.com/im/send?f=json&k=MYKEY&c=callback&aimsid=AIMSID&typingStatus=typing&t=ChattingChuck
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: getExpression
Returns the expression information - the personalized icons, sounds, and background images - for an AIM user. This routine supports two extra format parameters, both of which require the type= parameter to be set:
- native - Return the binary data directly. For example with buddy icons can be used to embedded the image using a img tag. The type parameter is required.
- redirect - Similiar to native, except use a redirect to fetch the binary data. This will eventually allow the browser to cache better. The type parameter is required.
URL: GET http://api.oscar.aol.com/expressions/get
Input Parameters
| Type | Field | Description |
|---|---|---|
| Format | f | [Required] The format of the data returned |
| String | c | JSONP callback |
| String | r | Request id |
| String | t | [Required] Target aimId |
| Expression Type | type | The type of expression to return, if missing all expressions are returned. Required for the native and redirect format |
| String | defaultId | If the user doesn't have an expression, use this one instead |
| String | personality | personality name |
| Boolean | noCustom | [Default 0] - if true a custom item isn't returned, instead the defaultId is returned if available |
Output Fields
| Type | Field | Description |
|---|---|---|
| Array of Expression | expressions | In JSON or Simple XML mode description of the expressions |
Sample JSON Output
{
"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
"expressions":[
{
"type":"buddyIcon",
"id":"050201020304",
"URL":"http://api.oscar.aol.com/get"
}
]
}
}
}
Sample XML Output
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
<expressions>
<expression>
<type>buddyIcon</type>
<id>050201020304</id>
<URL>http://api.oscar.aol.com/get</URL>
</expression>
</expressions>
</data>
</response>
Method: getAsset
Get the binary asset, you really probably don't want to use this call since this is ID based and not user based
URL: GET http://api.oscar.aol.com/expressions/getAsset
Input Parameters
| Type | Field | Description |
|---|---|---|
| String | c | JSONP callback |
| String | r | Request id |
| String | f | [Required] native |
| String | t | Target aimId |
| Expression Type | type | [Required] The type of expression to return |
| String | id | [Required] The bart id |
| String | defaultId | If expression doesn't exist, use this one instead |
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: setExpression
Set the expression information - the personalized icons, sounds, and background images - for an AIM user.
URL: GET http://api.oscar.aol.com/expressions/set
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 |
| Expression Type | type | [Required] The type of expression to set |
| String | id | [Required] The id of expression to set |
| String | personality | The name of the specific personality set |
Common Status Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 462 | Parameter error, such as bad type or id |
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: uploadExpression
Upload a custom expression
URL: POST http://api.oscar.aol.com/expressions/upload
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 |
| Expression Type | type | [Required] The type of expression being uploaded |
Output Fields
| Type | Field | Description |
|---|---|---|
| String | id | The id of the expression uploaded, can be used with setExpression |
Common Status Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 462 | Parameter error, such as bad type or id |
Sample JSON Output
{
"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
"id":""
}
}
}
Sample XML Output
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
<id></id>
</data>
</response>
Method: googleEarth.kml
A Google Earth Network Link that contains all different items supported
URL: GET http://api.oscar.aol.com/location/googleEarth.kml
Method: getRankedUsersLocations.kml
A Google Earth Network Link that displays the locations of AIM Fight ranked users.
URL: GET http://api.oscar.aol.com/location/getRankedUsers.kml
Method: getRankedUsersLocations
Return the locations of AIM Fight ranked users. The format parameter f=kml is also supported for Google Earth output
URL: GET http://api.oscar.aol.com/location/getRankedUsers
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 |
| Integer | maxLocations | Max number of locations returned, locations are sorted by number of users |
| String | boundingBox | [bboxWest],[bboxSouth],[bboxEast],[bboxNorth] - Return only items inside the bounding box |
Output Fields
| Type | Field | Description |
|---|---|---|
| Array of RankedUsersLocation | locations | Ranked Users Locations |
Sample JSON Output
{
"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
"locations":[
{
"name":"washington, dc",
"count":100,
"lat":38.910,
"lon":-77.018
}
]
}
}
}
Sample XML Output
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
<locations>
<location>
<name>washington, dc</name>
<count>100</count>
<lat>38.910</lat>
<lon>-77.018</lon>
</location>
</locations>
</data>
</response>
Method: getIMConversationsLocations.kml
A Google Earth Network Link that displays IM conversations initiated in the last minute. The conversations are aged out over time.
URL: GET http://api.oscar.aol.com/location/getIMConversations.kml
Method: getIMConversationsLocations
Return the locations for recently intiated IM conversations. The conversations are aged out over time.
URL: GET http://api.oscar.aol.com/location/getIMConversations
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 |
| Integer | maxLocations | Max number of locations returned, locations are sorted by age and number of users |
| String | boundingBox | [bboxWest],[bboxSouth],[bboxEast],[bboxNorth] - Return only items where one of the two points are inside the bounding box |
Output Fields
| Type | Field | Description |
|---|---|---|
| Array of IMConversationLocation | locations | IM Conversation Locations |
Sample JSON Output
{
"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
"locations":[
{
"name":"washington, dc - los angeles, ca",
"count":10,
"age":0,
"lat1":38.910,
"lon1":-77.018,
"lat2":33.973,
"lon2":-118.249
}
]
}
}
}
Sample XML Output
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
<locations>
<location>
<name>washington, dc - los angeles, ca</name>
<count>10</count>
<age>0</age>
<lat1>38.910</lat1>
<lon1>-77.018</lon1>
<lat2>33.973</lat2>
<lon2>-118.249</lon2>
</location>
</locations>
</data>
</response>
Method: setPreference
Set preferences
URL: GET http://api.oscar.aol.com/preference/set
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 |
| Boolean | Preferences | [Required] The preference to set, the field name isn't Preferences, instead it is a value from the enumeration |
Example: http://api.oscar.aol.com/preference/set?f=json&k=KEY&c=callback&a=AOLAUTHTOKEN&displayLogin=1&showBuddyFeed=0
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: getPreference
Get preferences
URL: GET http://api.oscar.aol.com/preference/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 | 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 |
| Boolean | Preferences | Optional selector of which preferences to return, otherwise all are returned |
Example: http://api.oscar.aol.com/preference/get?f=json&k=KEY&c=callback&a=AOLAUTHTOKEN
Sample JSON Output
{
"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123"