The Web AIM API lets developers incorporate core AIM functionality into any web page, including the ability to sign on, send or 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.
Authentication for APIs
There are five different types of authentication supported, however not all the APIs support all five.
Most of the APIs require the source user to be specfied and authenticated, with each of the types require different parameters to be specified.
- Anonymous - The source user isn't specified, and no extra parameters are required.
- Web Auth Token - The source user is represented by an a= parameter (created by calling getToken), this auth token can only be used by web pages
- Client Auth Token - The source user is represented by an a= parameter (created by calling clientLogin), and the calls must be signed and include a ts= and sig_sha256= parameter.
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 hex characters.
- aimsid - The source user is represented by an aimsid= parameter (created by calling startSession) after obtaining an auth token
- Anonymous aimsid - The source user is represented by an aimsid= parameter (created by calling startSession with anonymous=true) and can only be used with certain APIs
Typical Web Authenticated Application Flow
A web 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
Client Application Flow
It is possible to build a client using the APIs. In that case the developer will want to use clientLogin instead of getToken. Otherwise the flow will be the same as above.
Typical Anonymous Application Flow
When building an anonymous 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
TLS Support
TLS is supported by most APIs using the https protocol and requires the AOL Root Certificate in the certificate store.
Currently the fetchEvents call does NOT support the https protocol.
The sections below contain a complete reference to the enumerations, types, and methods of Web AIM API.
| Enumerations | Types | Methods |
|
|
- Session Methods
- Presence Methods
- IM Methods
- Expressions Methods
- Buddylist Editing Methods
- Preference Methods
- Location Based Methods
- Buddyfeed Methods
- Miscellaneous Methods
|
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 |
| imserv | IMServ group target |
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 |
| bigBuddyIcon | Big buddy icon |
| 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 |
Enumeration: ICBM Errors
Status values for mobile
| Values | Description |
| 0 | No subcode supplied |
| 1 | IMs to recipient blocked |
| 2 | Remote restricted by parental controls |
| 3 | User needs to accept terms and conditions before sending to mobile |
| 4 | Client did not display SMS charging information before trying to send |
| 5 | Cannot send SMS message to destination country |
| 6 | User restricted to closed IM group |
| 7 | User cannot send without payment authorization |
| 8 | Cannot determine country for destination mobile device |
| 9 | IM cannot be initiated by a BOT |
| 10 | IM is not allowed by consumer BOT to recipient |
| 11 | IM is not allowed by consumer BOT due to usage limited |
| 12 | IM is not allowed by consumer BOT due to daily usage limited |
| 13 | IM is not allowed by consumer BOT due to monthly usage limited |
| 14 | User does not accept offline IMs |
| 15 | Exceed max storage limit of offline IMs |
| 16 | Multi file transfer request blocked by host |
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 |
| apfNotifyReceivedInviteByEmail | [0] Should email be sent when user invited |
| showOfflineGrp | [1] Show offline group |
| offlineGrpCollapsed | [0] Offline Group is collapsed |
| firstImSoundOnly | [0] Only play the sound on the first IM |
| imblastInviteNotify | [1] Allows Imserv invite notify message |
| blockpluginsFeed | [0] Block feed storage for plugin uploads |
| enableBeboAlerts | [1] Enable BEBO related alerts |
Enumeration: AvTrackResultCodeValue
Result code value
| Values | Description |
| 0 | Success |
| 1 | Internal Error |
| 2 | Not Found |
| 3 | Timeout |
Enumeration: PDResultCode
Status code from PD operations
| Values | Description |
| 0 | Success |
| 1 | Database Error |
| 2 | Not Found |
| 12 | Over the limit |
| 16 | Invalid Nickname |
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: 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 |
| Boolean | updatedBuddyInfo | Users Buddy Feed has been updated since you last viewed it |
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 |
| Integer | smart | Reference ID for smart buddy group |
| String | imserv | If this is an IMserv group, this will be the name of the imserv |
| 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: Personality
The Personality Object points to the Personality name and contains the Expression data therein.
| Type | Field | Description |
| String | name | Name of the personality |
| Array of Expression | expressions | Expression object contained in the personality |
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: RawMsg
Includes base64 encoded raw IM data
| Type | Field | Description |
| String | ipCountry | Country abbreviation, if known, based on IP lookup |
| String | clientCountry | Country abbreviation that the client asserts when starting a session |
| String | memberCountry | Country abbreviation for AOL member as set when user registered account |
| String | base64Msg | Base64 encoded raw IM data |
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 |
| String | imserv | Name of IMServ if IM is from a IMServ group |
| RawMsg | rawMsg | base64 encoded raw data if rawMsg specified in startSession |
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. |
| Integer | seqNum | Identifier for event. Can be used as eventNumber with deleteEvent. |
Type: SendImSubCode
The subcode data returned with sendIM for mobile.
| Type | Field | Description |
| ICBM Errors | subError | suberror code |
| String | subReason | reason of the failure |
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: MediaContent
Media RSS content type
| Type | Field | Description |
| Integer | height | Image height |
| Integer | width | Image width |
| String | url | Image location |
Type: MediaThumbnail
Media RSS thumbnail type
| Type | Field | Description |
| Integer | height | Image height |
| Integer | width | Image width |
| String | url | Image location |
Type: MediaTitle
Media RSS title type
| Type | Field | Description |
| String | contentValue | Image title |
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 |
| Integer | timestamp | Epoch timestamp |
| String | author | Author |
| String | guid | guid |
| MediaContent | media-content | Media RSS content |
| MediaThumbnail | media-thumbnail | Media RSS thumbnail |
| MediaTitle | media-title | Media RSS title |
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: EventStatus
Event Status Information
| Type | Field | Description |
| Integer | event | Event Number |
| Integer | code | Event Response Code |
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: AvTrackImage
Image Reference
| Type | Field | Description |
| String | width | width |
| String | height | height |
| String | src | link of reference |
| Array of String | contentTags | content tag |
Type: AvTrackInfo
All info about an track
| Type | Field | Description |
| Integer | startDate | Unix EPOCH time when the track starts playing |
| Integer | Duration | Duration of the track |
| String | t | target name |
| AvTrackResultCodeValue | statusCode | result code |
| String | title | track name |
| String | uri | where to access the track directly |
| String | album | album name |
| String | albumLink | album link |
| String | artist | artist name |
| String | artistLink | artist link |
| Array of String | genres | genre |
| String | playlist | playlist name |
| String | playlistLink | playlist link |
| String | podcast | podcast name |
| String | podcastLink | podcast link |
| String | series | series name |
| String | seriesLink | series link |
| Array of AvTrackImage | images | image info |
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: PDNameResult
The target name and status code data.
| Type | Field | Description |
| String | aimid | aimid |
| PDResultCode | statusCode | status code returned for this aimid |
Type: PDResults
The result code returned for each object.
| Type | Field | Description |
| Integer | pdModeResult | Result of setting pdMode |
| Array of PDNameResult | allowResults | Status code of each target in pdAllow |
| Array of PDNameResult | blockResults | Status code of each target in pdBlock |
| Array of PDNameResult | IgnoreResults | Status code of each target in pdIgnore |
| Array of PDNameResult | allowRemoveResults | Status code of each target in pdAllowRemove |
| Array of PDNameResult | blockRemoveResults | Status code of each target in pdBlockRemove |
| Array of PDNameResult | 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":{
...
}
}
}
< /pre>
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>
< /pre>
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"
}
}
});
< /pre>
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
POST with Content type of application/x-www-form-urlencoded also supported
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 |
| Boolean | invisible | Start an invisible session |
| Boolean | rawMsg | Setting this will result in receiving raw data from fetchEvent API. This data can be used by legacy clients |
| 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 |
| Integer | buildNumber | Build Number |
| Integer | majorVersion | Major Version, i.e for 1.2.3, major version = 1 |
| Integer | minorVersion | Minor Version, i.e for 1.2.3, minor version = 2 |
| Integer | pointVersion | Point Version, i.e for 1.2.3, point version = 3 |
| Integer | pollTimeout | Default value requested for fetchEvents, so client does not need to supply in each request |
| String | includePresenceFields | Comma separated list of fields to include in a presence object. This can be used to minimize data that the client does not use. You can also include "=" for any of the fields, so that the field will only be present if the value does not match the specified default value. Example: includePresenceFields=aimId,userType=icq,friendly |
| String | excludePresenceFields | Comma separated list of fields to exclude in a presence object. This can be used to minimize data that the client does not use. You can also include "=" for any of the fields, so that the field will only be present if the value does not match the specified default value. Example: excludePresenceFields=userType=icq,buddyIcon |
Output Fields
| Type | Field | Description |
| String | fetchBaseURL | Base URL to do fetches with, see fetchEvents method below |
| Array of Integer | ts | Epoch timestamp - clientLogin required parameter |
| 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 |
| 401 | Authorization required |
| 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",
"ts":[
],
"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",
"updatedBuddyInfo":
},
"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>
<ts>
<0></0>
</ts>
<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>
<updatedBuddyInfo></updatedBuddyInfo>
</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 | [Default 1 hour] 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. For a web application this must be set. |
| 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 | Success |
| 401 | Authorization required |
| 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":"",
"seqNum":
}
]
}
}
}
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>
<seqNum></seqNum>
</event>
</events>
</data>
</response>
Method: deleteEvents
To delete multiple events
URL: GET http://api.oscar.aol.com/aim/deleteEvents
POST with Content type of application/x-www-form-urlencoded also supported
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 numbers to delete. Multiple allowed. |
Output Fields
| Type | Field | Description |
| Array of EventStatus | results | Events response status |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 462 | Parameter error |
Example: http://api.oscar.aol.com/aim/deleteEvents?f=json&aimsid=AIMSID&eventNumber=1&eventNumber=2
Sample JSON Output
{
"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
"results":[
{
"event":7,
"code":0
}
]
}
}
}
Sample XML Output
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
<results>
<eventStatus>
<event>7</event>
<code>0</code>
</eventStatus>
</results>
</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
POST with Content type of application/x-www-form-urlencoded also supported
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 |
| Boolean | invalidateToken | [Default 1] - Sending request to SAAB to logout |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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: setSessionParam
To set session parameters
URL: GET http://api.oscar.aol.com/aim/setSessionParam
POST with Content type of application/x-www-form-urlencoded also supported
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 |
| Integer | sessionTimeout | Time in seconds before terminating idle web session. |
| Event Type | tempEvents | Comma separated list of events to temporarily subscribe to, fetchEvents will only return these events. This can be used if the client is entering some mode where it only wants to receive a subset of the events subscribed to in the startSession |
| Integer | pollTimeout | Default value requested for fetchEvents, so client does not need to supply in each request |
| String | includePresenceFields | Comma separated list of fields to include in a presence object. This can be used to minimize data that the client does not use. You can also include "=" for any of the fields, so that the field will only be present if the value does not match the specified default value. Example: includePresenceFields=aimId,userType=icq,friendly |
| String | excludePresenceFields | Comma separated list of fields to exclude in a presence object. This can be used to minimize data that the client does not use. You can also include "=" for any of the fields, so that the field will only be present if the value does not match the specified default value. Example: excludePresenceFields=userType=icq,buddyIcon |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 462 | Parameter error |
Example: http://api.oscar.aol.com/aim/setSessionParam?f=json&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: aimStartPage
This method will redirect the caller to the correct AIM Start Page for given language. If WIM is being used from a web page then calling this api directly is enough. If WIM is being used from a clientLogin session or from the OSCAR protocol then a wrapping Single Signon call must be used. See here for an example of using Single Signon.
URL: GET http://api.oscar.aol.com/aim/getStartPage
POST with Content type of application/x-www-form-urlencoded also supported
Input Parameters
| Type | Field | Description |
| Format | f | [Required] The format of the data returned |
| String | c | JSONP callback |
| String | r | Request id |
| 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". |
| String | k | [Required] the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 460 | Missing required parameter |
| 462 | Parameter error |
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: aimExpressionsPage
This method will redirect the caller to the correct AIM Expressions page for given language. If WIM is being used from a web page then calling this api directly is enough. If WIM is being used from a clientLogin session or from the OSCAR protocol then a wrapping Single Signon call must be used. See here for an example of using Single Signon.
URL: GET http://api.oscar.aol.com/aim/getExpressionsPage
POST with Content type of application/x-www-form-urlencoded also supported
Input Parameters
| Type | Field | Description |
| Format | f | [Required] The format of the data returned |
| String | c | JSONP callback |
| String | r | Request id |
| 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". |
| String | k | [Required] the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 460 | Missing required parameter |
| 462 | Parameter error |
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: getHostBuddyInfo
Get host buddy info. Only valid format supported is html.
URL: GET http://api.oscar.aol.com/aim/getHostBuddyInfo
POST with Content type of application/x-www-form-urlencoded also supported
Input Parameters
| Type | Field | Description |
| String | f | [Required] Only f=html is supported |
| 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 | The current timestamp - clientLogin required parameter |
| String | sig_sha256 | Signature - clientLogin required parameter. |
| String | t | Target to query buddy info for |
| Boolean | headerOn | [Default 0] - Set to 1 if needed header data returned in response. |
| String | language | the language and locale 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). |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
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: startOSCARSession
Start a OSCAR AIM session. This API requires that the token came from a previous clientLogin call and that the URL is signed. For a complete example on using startOSCARSession see the OSCAR Protocol Signon 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/startOSCARSession
POST with Content type of application/x-www-form-urlencoded also supported
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 |
| Boolean | useTLS | Request the connection to BOSS use TLS |
| Integer | buildNumber | Build Number |
| Integer | majorVersion | Major Version, i.e for 1.2.3, major version = 1 |
| Integer | minorVersion | Minor Version, i.e for 1.2.3, minor version = 2 |
| Integer | pointVersion | Point Version, i.e for 1.2.3, point version = 3 |
| String | clientName | Client name - clientLogin parameter |
| Integer | clientVersion | Client version - clientLogin parameter |
| 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". |
| Integer | ts | [Required] Epoch timestamp - clientLogin required parameter |
| String | sig_sha256 | [Required] Signature - clientLogin required parameter. |
Output Fields
| Type | Field | Description |
| String | host | Host to connect to |
| String | port | Port to connect to |
| Array of Integer | ts | [Required] Epoch timestamp - clientLogin required parameter |
| String | cookie | Binary cookie to present to BOSS |
| String | tlsCertName | If TLS is being used then this is the cert name to verify for the boss connection |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 408 | Timeout of the backend servers |
| 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 |
Sample JSON Output
{
"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
"host":"10.1.2.3",
"port":"5190",
"ts":[
],
"cookie":"base64ed data",
"tlsCertName":"bos.oscar.aol.com"
}
}
}
Sample XML Output
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
<host>10.1.2.3</host>
<port>5190</port>
<ts>
<0></0>
</ts>
<cookie>base64ed data</cookie>
<tlsCertName>bos.oscar.aol.com</tlsCertName>
</data>
</response>
Method: addBuddy
Add a buddy to the buddylist.
URL: GET http://api.oscar.aol.com/buddylist/addBuddy
POST with Content type of application/x-www-form-urlencoded also supported
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. Multiple buddy= parameters are allowed. |
| String | group | [Required] group name to add buddy to |
Output Fields
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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/addBuddy?f=json&c=callback&aimsid=AIMSID&buddy=buddy1&group=groupABC
Sample JSON Output
{
"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
"results":[
{
"buddy":"foo",
"resultCode":"0 for success, non-0 for failure"
}
]
}
}
}
Sample XML Output
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
<results>
<result>
<buddy>foo</buddy>
<resultCode>0 for success, non-0 for failure</resultCode>
</result>
</results>
</data>
</response>
Method: removeBuddy
Remove a buddy from the buddylist.
URL: GET http://api.oscar.aol.com/buddylist/removeBuddy
POST with Content type of application/x-www-form-urlencoded also supported
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 | The current 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 |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
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: moveBuddy
Move a buddy inside a group or to a new group
URL: GET http://api.oscar.aol.com/buddylist/moveBuddy
POST with Content type of application/x-www-form-urlencoded also supported
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 | The current 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 |
| String | newGroup | Move the buddy to the end of this new group |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
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
POST with Content type of application/x-www-form-urlencoded also supported
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 | The current timestamp - clientLogin required parameter |
| String | sig_sha256 | Signature - clientLogin required parameter. |
| String | buddy | buddy name. Should only enter either buddy= or t= |
| String | t | buddy name. Should only enter either buddy= or t= |
| String | friendly | Friendly name |
| String | smsNumber | SMS number for buddy |
| String | workNumber | Work number for buddy |
| String | otherNumber | Other number for buddy |
| String | phoneNumber | Home number for buddy |
| String | note | note, max 80 bytes |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
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: getBuddyAttribute
Get some buddy's attributes
URL: GET http://api.oscar.aol.com/buddylist/getBuddyAttribute
POST with Content type of application/x-www-form-urlencoded also supported
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 | The current timestamp - clientLogin required parameter |
| String | sig_sha256 | Signature - clientLogin required parameter. |
| String | buddy | buddy name. Should only enter either buddy= or t= |
| String | t | buddy name. Should only enter either buddy= or t= |
Output Fields
| Type | Field | Description |
| String | friendly | Friendly name |
| String | smsNumber | SMS number for buddy |
| String | workNumber | Work number for buddy |
| String | otherNumber | Other number for buddy |
| String | homeNumber | Home number for buddy |
| String | note | note |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
Example: http://api.oscar.aol.com/buddylist/getBuddyAttribute?f=json&c=callback&aimsid=AIMSID&buddy=buddy1
Sample JSON Output
{
"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
"friendly":"",
"smsNumber":"",
"workNumber":"",
"otherNumber":"",
"homeNumber":"",
"note":""
}
}
}
Sample XML Output
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
<friendly></friendly>
<smsNumber></smsNumber>
<workNumber></workNumber>
<otherNumber></otherNumber>
<homeNumber></homeNumber>
<note></note>
</data>
</response>
Method: addGroup
Add an empty group to the buddylist.
URL: GET http://api.oscar.aol.com/buddylist/addGroup
POST with Content type of application/x-www-form-urlencoded also supported
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 |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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: 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
POST with Content type of application/x-www-form-urlencoded also supported
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 | The current 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 |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
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
POST with Content type of application/x-www-form-urlencoded also supported
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 | The current 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 |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
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: moveGroup
Move a group
URL: GET http://api.oscar.aol.com/buddylist/moveGroup
POST with Content type of application/x-www-form-urlencoded also supported
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 | The current 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 |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
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
POST with Content type of application/x-www-form-urlencoded also supported
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 | The current 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 |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
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: 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 web auth tokens must be provided.
URL: GET http://api.oscar.aol.com/buddylist/copy
POST with Content type of application/x-www-form-urlencoded also supported
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 | 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 |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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: addTempBuddy
Add a temporary buddy for presence updates
URL: GET http://api.oscar.aol.com/aim/addTempBuddy
POST with Content type of application/x-www-form-urlencoded also supported
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] buddy name, multiple t= parameters are allowed |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 462 | Parameter error |
Example: http://api.oscar.aol.com/aim/addTempBuddy?f=json&c=callback&aimsid=AIMSID&t=msft@relegence.com
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: removeTempBuddy
Remove a temporary buddy for presence updates
URL: GET http://api.oscar.aol.com/aim/removeTempBuddy
POST with Content type of application/x-www-form-urlencoded also supported
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] Buddy name, multiple t= parameters are allowed |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 462 | Parameter error |
Example: http://api.oscar.aol.com/aim/removeTempBuddy?f=json&c=callback&aimsid=AIMSID&t=msft@relegence.com
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
POST with Content type of application/x-www-form-urlencoded also supported
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 | The current 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 |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
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":,
"smart":,
"imserv":"",
"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",
"updatedBuddyInfo":
}
]
}
],
"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",
"updatedBuddyInfo":
}
]
}
}
}
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>
<smart></smart>
<imserv></imserv>
<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>
<updatedBuddyInfo></updatedBuddyInfo>
</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>
<updatedBuddyInfo></updatedBuddyInfo>
</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
POST with Content type of application/x-www-form-urlencoded also supported
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 | The current 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 |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
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":,
"smart":,
"imserv":"",
"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",
"updatedBuddyInfo":
}
]
}
],
"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",
"updatedBuddyInfo":
}
]
}
}
}
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>
<smart></smart>
<imserv></imserv>
<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>
<updatedBuddyInfo></updatedBuddyInfo>
</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>
<updatedBuddyInfo></updatedBuddyInfo>
</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
POST with Content type of application/x-www-form-urlencoded also supported
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 |
| 460 | Missing required parameter |
| 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
POST with Content type of application/x-www-form-urlencoded also supported
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 |
| Boolean | invisible | Invisible |
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 |
| 401 | Authorization required |
| 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",
"updatedBuddyInfo":
}
}
}
}
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></initial>
<trailing></trailing>
</smsSegment>
<userType>aim</userType>
<updatedBuddyInfo></updatedBuddyInfo>
</myInfo>
</data>
</response>
Method: setStatus
Sets the user's status message.
URL: GET http://api.oscar.aol.com/presence/setStatus
POST with Content type of application/x-www-form-urlencoded also supported
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 | The current timestamp - clientLogin required parameter |
| String | sig_sha256 | Signature - clientLogin required parameter. |
| String | statusMsg | [Required] status message display to other users |
| Boolean | beboFlag | This request is initiated by a Bebo client |
| String | mediaId | Identifier for photo/media associated with status. Can be multiple. |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
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
POST with Content type of application/x-www-form-urlencoded also supported
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 | The current timestamp - clientLogin required parameter |
| String | sig_sha256 | Signature - clientLogin required parameter. |
| String | profile | [Required] The new AIM Profile, or blank to clear the current AIM Profile |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
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
POST with Content type of application/x-www-form-urlencoded also supported
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 | The current timestamp - clientLogin required parameter |
| String | sig_sha256 | Signature - clientLogin required parameter. |
Output Fields
| Type | Field | Description |
| String | profileMsg | AIM Profile Message |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
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
POST with Content type of application/x-www-form-urlencoded also supported
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 |
| Integer | ts | The current timestamp - clientLogin required parameter |
| String | sig_sha256 | Signature - clientLogin required parameter. |
| 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 | displaySMSSegmentData | [Default false] - Set true to display SMS segment data |
| Boolean | offlineIM | Deliver as an offline IM when possible if the user isn't online, autoResponse flag can no bet set |
Output Fields
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 400 | Session does not exist |
| 401 | Authorization required |
| 430 | Sending IMs too fast |
| 450 | Consent required, use the redirectURL and append a k=KEY to it |
| 460 | Missing required parameter |
| 462 | Parameter error |
| 602 | Target user is not available |
| 603 | Target user is blocked |
| 606 | Message is too large |
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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
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":{
"subCode":{
"subError":"",
"subReason":""
}
}
}
}
Sample XML Output
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
<subCode>
<subError></subError>
<subReason></subReason>
</subCode>
</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
POST with Content type of application/x-www-form-urlencoded also supported
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 |
| Integer | ts | The current timestamp - clientLogin required parameter |
| String | sig_sha256 | Signature - clientLogin required parameter. |
| 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 |
| String | cookie | Base64 encoded cookie for this conversation |
| String | ip | IPv4 address recipient can connect to for peer-to-peer conversation |
| Integer | port | Port used in conjunction with ipAddr for connection |
| String | proposerIp | Internal IP address of client |
| Boolean | hostCheck | Host will check remote user to verify they have requested capability [Default 1] |
| Boolean | useRS | Use Relay server. ip will be from RS and not a peer [Default 0] |
| Integer | sequenceNum | Sequence number for proposal. Must increment by 1 |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 430 | Sending IMs too fast |
| 450 | Consent required, use the redirectURL and append a k=KEY to it |
| 460 | Missing required parameter |
| 462 | Parameter error |
| 602 | Target user is not available |
| 605 | Target user doesn't support the capability |
| 606 | Message is too large |
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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
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: rejectDataIM
Reject a Data IM from a user. Requires a valid aimsid from the startSession call or an AOL Authentication Token.
URL: GET http://api.oscar.aol.com/im/rejectDataIM
POST with Content type of application/x-www-form-urlencoded also supported
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 |
| Integer | ts | The current timestamp - clientLogin required parameter |
| String | sig_sha256 | Signature - clientLogin required parameter. |
| String | t | [Required] Destination aimId |
| String | cookie | [Required] base64 encoded converstation cookie |
| Reject Reason | reason | [Required] Reason for reject |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 430 | Sending IMs too fast |
| 450 | Consent required, use the redirectURL and append a k=KEY to it |
| 460 | Missing required parameter |
| 462 | Parameter error |
| 602 | Target user is not available |
| 605 | Target user doesn't support the capability |
| 606 | Message is too large |
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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
Example: http://api.oscar.aol.com/im/rejectDataIM?f=json&k=MYKEY&c=callback&aimsid=AIMSID&reason=denied&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
POST with Content type of application/x-www-form-urlencoded also supported
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 |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 462 | Parameter error |
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
POST with Content type of application/x-www-form-urlencoded also supported
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 |
| String | text | emoticon text, i.e :-) |
| 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 |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 460 | Missing required parameter |
| 462 | Parameter error |
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: getPersonalities
Returns the personalities information - a container for the personalized icons, sounds, and background images - for an AIM user.
URL: GET http://api.oscar.aol.com/expressions/getPersonalities
POST with Content type of application/x-www-form-urlencoded also supported
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 |
| Boolean | withExpressions | [Default 0] - if true all the expressions are returned for each personality |
Output Fields
| Type | Field | Description |
| Array of Personality | personalities | In JSON or Simple XML mode description of the personalities |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 460 | Missing required parameter |
| 462 | Parameter error |
Sample JSON Output
{
"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
"personalities":[
{
"name":"myPersonality",
"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>
<personalities>
<personality>
<name>myPersonality</name>
<expressions>
<expression>
<type>buddyIcon</type>
<id>050201020304</id>
<url>http://api.oscar.aol.com/get</url>
</expression>
</expressions>
</personality>
</personalities>
</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
POST with Content type of application/x-www-form-urlencoded also supported
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 | text | emoticon text, i.e :-) |
| String | defaultId | If expression doesn't exist, use this one instead |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 460 | Missing required parameter |
| 462 | Parameter error |
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
POST with Content type of application/x-www-form-urlencoded also supported
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 | The current timestamp - clientLogin required parameter |
| String | sig_sha256 | Signature - clientLogin required parameter. |
| Expression Type | type | [Required] The type of expression to set |
| String | id | [Required] The id of expression to set |
| String | typeAndId | [Required] The type and ID in the form of type:id. Multiple may be present. Ex: typeAndId=buddyIcon:0050201020304 |
| String | personality | The name of the specific personality set |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 462 | Parameter error, such as bad type or id |
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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
Example: http://api.oscar.aol.com/expressions/set?f=json&k=MYKEY&c=callback&aimsid=AIMSID&type=buddyIcon&id=00050201020304
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 |
| Integer | ts | The current timestamp - clientLogin required parameter |
| String | sig_sha256 | Signature - clientLogin required parameter. |
| 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 after stripping the leading 4 hex digits. |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 462 | Parameter error, such as bad type or id |
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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
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
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 460 | Missing required parameter |
| 462 | Parameter error |
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
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 460 | Missing required parameter |
| 462 | Parameter error |
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
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 460 | Missing required parameter |
| 462 | Parameter error |
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
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 460 | Missing required parameter |
| 462 | Parameter error |
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
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 460 | Missing required parameter |
| 462 | Parameter error |
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
POST with Content type of application/x-www-form-urlencoded also supported
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 | The current timestamp - clientLogin required parameter |
| String | sig_sha256 | Signature - clientLogin required parameter. |
| Boolean | Preferences | [Required] The preference to set, the field name isn't Preferences, instead it is a value from the enumeration |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
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
POST with Content type of application/x-www-form-urlencoded also supported
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 | The current timestamp - clientLogin required parameter |
| String | sig_sha256 | Signature - clientLogin required parameter. |
| Boolean | Preferences | Optional selector of which preferences to return, otherwise all are returned |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
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",
"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: getVanityInfo
Retrieve the vanity information for a user.
URL: GET http://api.oscar.aol.com/aim/getVanityInfo
POST with Content type of application/x-www-form-urlencoded also supported
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 | The current timestamp - clientLogin required parameter |
| String | sig_sha256 | Signature - clientLogin required parameter. |
| Boolean | includeBuddyCount | Request for number of unique real buddies on the buddy list |
| Boolean | includeWatcherCount | Request for number of reverse buddies - buddies that are watching you |
Output Fields
| Type | Field | Description |
| Integer | imsSent | Number of IMs the user has sent during the collection interval |
| Integer | imsReceived | Number of IMs the user has received during the collection interval |
| Integer | awayMsgs | Number of away messages set during the collection interval |
| Integer | onlineTime | Minutes online |
| Integer | collectionInterval | Minutes since the first time data was collected |
| Integer | uniqueBuddyCount | Number of unique real buddies |
| Integer | watcherCount | Number of watchers |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
Sample JSON Output
{
"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
"imsSent":10,
"imsReceived":20,
"awayMsgs":30,
"onlineTime":30,
"collectionInterval":300,
"uniqueBuddyCount":,
"watcherCount":
}
}
}
Sample XML Output
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
<imsSent>10</imsSent>
<imsReceived>20</imsReceived>
<awayMsgs>30</awayMsgs>
<onlineTime>30</onlineTime>
<collectionInterval>300</collectionInterval>
<uniqueBuddyCount></uniqueBuddyCount>
<watcherCount></watcherCount>
</data>
</response>
Method: setAvTrack
Set avTrack
URL: GET http://api.oscar.aol.com/aim/setAvTrack
POST with Content type of application/x-www-form-urlencoded also supported
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 | The current timestamp - clientLogin required parameter |
| String | sig_sha256 | Signature - clientLogin required parameter. |
| String | title | track name |
| String | uri | where to access track directly |
| String | image | image reference of a track, multiple can be handled. An example to set image : image=width=64,height=64,src=http://image.allmusic.com//00/amg/cov200/drf500/f555/f55590zg6bm.jpg,contentTag=album cover,contentTag=artist logo. Note that in addition to any URL encoding needed to get special characters into a field(i.e contentTag) value, the resulting value of image must be URL encoded for sending. |
| Integer | startDate | Unix EPOCH time when the track starts playing |
| String | album | album name |
| String | albumLink | album link |
| String | artist | artist name |
| String | artistLink | artist link |
| String | genre | multiple entries are allowed |
| String | playlist | playlist name |
| String | playlistLink | playlist link |
| String | podcast | podcast name |
| String | podcastLink | podcast link |
| String | series | series name |
| String | seriesLink | series link |
Output Fields
| Type | Field | Description |
| String | id | The id of the avtrack uploaded in hex |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
Example: http://api.oscar.aol.com/aim/setAvTrack?f=json&k=KEY&c=callback&a=mytoken&album=myalbum
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: getAvTrack
Get avTrack.
URL: GET http://api.oscar.aol.com/aim/getAvTrack
POST with Content type of application/x-www-form-urlencoded also supported
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 | t | target name to get avtrack for. Multiple t= parameters are allowed. |
| Boolean | bl | Return avtrack for buddies on the buddy list. |
Output Fields
| Type | Field | Description |
| Array of AvTrackInfo | tracks | Track info if exists, can be empty on timeout |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 460 | Missing required parameter |
| 462 | Parameter error |
Example: http://api.oscar.aol.com/aim/getAvTrack?f=json&k=MYKEY&c=callback
Sample JSON Output
{
"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
"tracks":[
{
"startDate":,
"Duration":,
"t":"",
"statusCode":"",
"title":"",
"uri":"",
"album":"",
"albumLink":"",
"artist":"",
"artistLink":"",
"genres":[
""
],
"playlist":"",
"playlistLink":"",
"podcast":"",
"podcastLink":"",
"series":"",
"seriesLink":"",
"images":[
{
"width":"",
"height":"",
"src":"",
"contentTags":[
""
]
}
]
}
]
}
}
}
Sample XML Output
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
<tracks>
<track>
<startDate></startDate>
<Duration></Duration>
<t></t>
<statusCode></statusCode>
<title></title>
<uri></uri>
<album></album>
<albumLink></albumLink>
<artist></artist>
<artistLink></artistLink>
<genres>
<genre></genre>
</genres>
<playlist></playlist>
<playlistLink></playlistLink>
<podcast></podcast>
<podcastLink></podcastLink>
<series></series>
<seriesLink></seriesLink>
<images>
<image>
<width></width>
<height></height>
<src></src>
<contentTags>
<contentTag></contentTag>
</contentTags>
</image>
</images>
</track>
</tracks>
</data>
</response>
Method: getAIMFight
Get the AIM Fight score and rank for multiple aimIds
URL: GET http://api.oscar.aol.com/aim/getAIMFight
POST with Content type of application/x-www-form-urlencoded also supported
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 | t | Target aimIds, multiple t parameters are allowed |
Output Fields
| Type | Field | Description |
| Array of AIMFightUser | users | AIM Fight User information |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 460 | Missing required parameter |
| 462 | Parameter error |
Sample JSON Output
{
"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
"users":[
{
"aimId":"chattingchuck",
"score":10000000,
"rank":1
}
]
}
}
}
Sample XML Output
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
<users>
<user>
<aimId>chattingchuck</aimId>
<score>10000000</score>
<rank>1</rank>
</user>
</users>
</data>
</response>
Method: setPermitDeny
Change the permit/deny settings. The backend system enforces the permit/deny settings, this API is used to update those settings.
URL: GET https://api.oscar.aol.com/preference/setPermitDeny
POST with Content type of application/x-www-form-urlencoded also supported
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 | The current timestamp - clientLogin required parameter |
| String | sig_sha256 | Signature - clientLogin required parameter. |
| String | pdAllow | Allow specified aimId |
| String | pdBlock | Block specified aimId |
| String | pdIgnore | Ignore IMs from specified aimId |
| String | pdAllowRemove | Remove specified aimId from allow list |
| String | pdBlockRemove | Remove specified aimId from block list |
| String | pdIgnoreRemove | Remove specified aimId from ignore list |
| PdMode | pdMode | Set the overall permit/deny mode |
Output Fields
| Type | Field | Description |
| PDResults | results | Results array for all items |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
Example: https://api.oscar.aol.com/preference/setPermitDeny?k=MYKEY&f=xml&pdAllow=ChattingChuck&pdDeny=fred
Sample JSON Output
{
"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
"results":{
"pdModeResult":0-Success,
"allowResults":[
{
"aimid":"foo",
"statusCode":"0"
}
],
"blockResults":[
{
"aimid":"foo",
"statusCode":"0"
}
],
"IgnoreResults":[
{
"aimid":"foo",
"statusCode":"0"
}
],
"allowRemoveResults":[
{
"aimid":"foo",
"statusCode":"0"
}
],
"blockRemoveResults":[
{
"aimid":"foo",
"statusCode":"0"
}
],
"IgnoreRemoveResults":[
{
"aimid":"foo",
"statusCode":"0"
}
]
}
}
}
}
Sample XML Output
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
<results>
<pdModeResult>0-Success</pdModeResult>
<allowResults>
<allowResult>
<aimid>foo</aimid>
<statusCode>0</statusCode>
</allowResult>
</allowResults>
<blockResults>
<blockResult>
<aimid>foo</aimid>
<statusCode>0</statusCode>
</blockResult>
</blockResults>
<IgnoreResults>
<IgnoreResult>
<aimid>foo</aimid>
<statusCode>0</statusCode>
</IgnoreResult>
</IgnoreResults>
<allowRemoveResults>
<allowRemoveResults>
<aimid>foo</aimid>
<statusCode>0</statusCode>
</allowRemoveResults>
</allowRemoveResults>
<blockRemoveResults>
<blockRemoveResults>
<aimid>foo</aimid>
<statusCode>0</statusCode>
</blockRemoveResults>
</blockRemoveResults>
<IgnoreRemoveResults>
<ignoreRemoveResult>
<aimid>foo</aimid>
<statusCode>0</statusCode>
</ignoreRemoveResult>
</IgnoreRemoveResults>
</results>
</data>
</response>
Method: getPermitDeny
Get the current permit/deny settings. The backend system enforces the permit/deny settings so this API really is only useful for building UIs that allow the user to change the settings.
URL: GET https://api.oscar.aol.com/preference/getPermitDeny
POST with Content type of application/x-www-form-urlencoded also supported
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 | The current timestamp - clientLogin required parameter |
| String | sig_sha256 | Signature - clientLogin required parameter. |
Output Fields
| Type | Field | Description |
| PdMode | pdMode | Permit/Deny mode |
| Array of String | allows | aimIds allowed |
| Array of String | blocks | aimIds blocked |
| Array of String | ignores | aimIds ignored |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
Sample JSON Output
{
"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
"pdMode":"permitOnList",
"allows":[
"ChattingChuck"
],
"blocks":[
"fred"
],
"ignores":[
"john"
]
}
}
}
Sample XML Output
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
<pdMode>permitOnList</pdMode>
<allows>
<allow>ChattingChuck</allow>
</allows>
<blocks>
<block>fred</block>
</blocks>
<ignores>
<ignore>john</ignore>
</ignores>
</data>
</response>
Method: getUserFeed
Get the buddyfeed for a user. An extra format type of rss is supported.
Trusted, Token and Aimsid validation methods are currently not enforced.
URL: GET http://api.oscar.aol.com/buddyfeed/getUser
POST with Content type of application/x-www-form-urlencoded also supported
Input Parameters
| Type | Field | Description |
| Format | f | [Required] The format of the data returned |
| String | c | JSONP callback |
| String | r | Request id |
| String | a | Use an AOL Authentication Token for authentication, from the getToken call |
| Integer | ts | The current timestamp - clientLogin required parameter |
| String | sig_sha256 | Signature - clientLogin required parameter. |
| String | t | Target aimId |
| String | feedCategory | Filter feeds by this feed category. Can be multiple instances up to filters |
| Boolean | fullContent | Return the full html content for published items |
| Integer | maxItems | Max total number of items |
| Boolean | bfUI | if provided and set to 1, Profile, away and status msgs are NOT retrieved |
| Boolean | statusMsgs | This is used in conjunction with the bfUI parameter to include status msgs, but exclude profile and away msgs. eg: bfUI=1&statusMsgs=1 will pull cache items and status msgs |
| String | lastGuid | Retrieve only items newer than the item with this GUID |
| String | awayMsgs | Should away msgs be retrieved (Y or N). Default is Y. eg. awayMsgs=N |
| String | loc | 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 |
| Array of BuddyFeedItem | items | Target aimId, multiple t parameters are allowed |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
Sample JSON Output
{
"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
"items":[
{
"aimId":"chattingchuck",
"title":"Blog update",
"link":"http://journals.aol.com/chattingchuck/entry",
"domain":"journals.aol.com",
"description":"What I ate today",
"category":"Journal",
"pubDate":"Mon, 02 Apr 2007 14:02:12 GMT",
"timestamp":1232986257,
"author":"chattingchuck@aol.com",
"guid":"Blah",
"media-content":{
"height":640,
"width":480,
"url":"http://images/test.jgp"
},
"media-thumbnail":{
"height":60,
"width":90,
"url":"http://images/test-thumbnail.jgp"
},
"media-title":{
"contentValue":"Self potrait"
}
}
]
}
}
}
Sample XML Output
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
<items>
<item>
<aimId>chattingchuck</aimId>
<title>Blog update</title>
<link>http://journals.aol.com/chattingchuck/entry</link>
<domain>journals.aol.com</domain>
<description>What I ate today</description>
<category>Journal</category>
<pubDate>Mon, 02 Apr 2007 14:02:12 GMT</pubDate>
<timestamp>1232986257</timestamp>
<author>chattingchuck@aol.com</author>
<guid>Blah</guid>
<media-content>
<height>640</height>
<width>480</width>
<url>http://images/test.jgp</url>
</media-content>
<media-thumbnail>
<height>60</height>
<width>90</width>
<url>http://images/test-thumbnail.jgp</url>
</media-thumbnail>
<media-title>
<contentValue>Self potrait</contentValue>
</media-title>
</item>
</items>
</data>
</response>
Method: getBuddylistFeed
Get the buddyfeed for a user's entire buddylist. An extra format type of f=native for RSS is supported.
URL: GET http://api.oscar.aol.com/buddyfeed/getBuddylist
POST with Content type of application/x-www-form-urlencoded also supported
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 |
| Integer | ts | The current timestamp - clientLogin required parameter |
| String | sig_sha256 | Signature - clientLogin required parameter. |
| String | groupBy | (T or F) F = Sort results in revchron order (default), T = Sort results by buddy/subsort in revchron order |
| Integer | maxItems | Max total number of items |
| Integer | maxItemsPerMember | Max items per member |
| Integer | maxMembers | Max number of unique buddies to report on |
| String | feedCategory | Filter feeds by this feed category. Can be multiple instances up to filters |
| Boolean | bfUI | if true, Profile, away and status msgs are NOT retrieved |
| Boolean | statusMsgs | This is used in conjunction with the bfUI parameter to include status msgs, but exclude profile and away msgs. eg: bfUI=1&statusMsgs=1 will pull cache items and status msgs |
| String | awayMsgs | Should away msgs be retrieved (Y or N). Default is Y. eg. awayMsgs=N |
| Boolean | includeSelf | if true, the buddylist owners feeds are returned as well |
| String | loc | 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 |
| Array of BuddyFeedItem | items | Items for all the users in the buddylist |
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 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 |
| 1015 | The ts parameter for clientLogin is too far in the past or future |
Sample JSON Output
{
"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
"items":[
{
"aimId":"chattingchuck",
"title":"Blog update",
"link":"http://journals.aol.com/chattingchuck/entry",
"domain":"journals.aol.com",
"description":"What I ate today",
"category":"Journal",
"pubDate":"Mon, 02 Apr 2007 14:02:12 GMT",
"timestamp":1232986257,
"author":"chattingchuck@aol.com",
"guid":"Blah",
"media-content":{
"height":640,
"width":480,
"url":"http://images/test.jgp"
},
"media-thumbnail":{
"height":60,
"width":90,
"url":"http://images/test-thumbnail.jgp"
},
"media-title":{
"contentValue":"Self potrait"
}
}
]
}
}
}
Sample XML Output
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
<items>
<item>
<aimId>chattingchuck</aimId>
<title>Blog update</title>
<link>http://journals.aol.com/chattingchuck/entry</link>
<domain>journals.aol.com</domain>
<description>What I ate today</description>
<category>Journal</category>
<pubDate>Mon, 02 Apr 2007 14:02:12 GMT</pubDate>
<timestamp>1232986257</timestamp>
<author>chattingchuck@aol.com</author>
<guid>Blah</guid>
<media-content>
<height>640</height>
<width>480</width>
<url>http://images/test.jgp</url>
</media-content>
<media-thumbnail>
<height>60</height>
<width>90</width>
<url>http://images/test-thumbnail.jgp</url>
</media-thumbnail>
<media-title>
<contentValue>Self potrait</contentValue>
</media-title>
</item>
</items>
</data>
</response>
Method: pushFeed
Push a simple Buddy Feed Item
URL: GET http://api.oscar.aol.com/buddyfeed/pushFeed
POST with Content type of application/x-www-form-urlencoded also supported
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 | feedTitle | [Required] Channel/Feed title |
| String | feedLink | [Required] URL to main feed page |
| String | feedDesc | [Required] Channel/Feed description |
| String | feedPublisher | Name of application publishing data |
| String | itemTitle | [Required] Title of item |
| String | itemLink | [Required] URL to item location |
| String | itemPubDate | Item published date in UNIX time in secs since EPOCH. If not provided, server will use system time |
| String | itemGuid | [Required] Unique per item ID |
| String | itemDesc | Item description |
| String | itemCategory | Item Category |
| String | media-thumbnail | Enclosed parameter list in the form of {field=value,field=value}. field/values are
Example : media-thumbnail={height=40,width=60,url=http://www.images.com/somethumbnail.jpg}
Note: Multiple instances of media-thumbnail are permitted.
| Field |
Value |
Example |
|
| height |
40 |
height=40 |
|
| width |
60 |
width=60 |
|
| url Required |
http://www.images.com/somethumbnail.jpg |
url=http://www.images.com/somethumbnail.jpg |
|
Note that in addition to any URL encoding needed to get special characters into a field/member value, the resulting value must be URL encoded for
sending. The actual value used for the value in the example above would need to be:
media-thumbnail=%7Bheight%3D40%2Cwidth%3D60%2Curl=http%3A//www.images.com/somethumbnail.jpg%7D
|
| String | media-content | Enclosed parameter list in the form of {field=value,field=value} field/values are
Example : media-content={height=40,width=60,url=http://www.images.com/someimage.jpg}
| Field |
Value |
Example |
|
| height |
40 |
height=40 |
|
| width |
60 |
width=60 |
|
| url Required |
http://www.images.com/someimage.jpg |
url=http://www.images.com/someimage.jpg |
|
Note that in addition to any URL encoding needed to get special characters into a field/member value, the resulting value must be URL encoded for
sending. The actual value used for the value in the example above would need to be:
media-content=%7Bheight%3D40%2Cwidth%3D60%2Curl=http%3A//www.images.com/someimage.jpg%7D
|
| String | media-title | Enclosed parameter list in the form of {field=value,field=value} field/values are
Example : media-title={type=plain,value=Family Picture}
| Field |
Value |
Example |
|
| type |
plain or html |
type=plain |
|
| value |
String |
value=Photos |
|
Note that in addition to any URL encoding needed to get special characters into a field/member value, the resulting value must be URL encoded for
sending. The actual value used for the value in the example above would need to be:
media-title=%7Btype%3Dplain%2Cvalue%3DFamily%20Picture%7D
|
Common Status Codes
| Status Code | Description |
| 200 | Success |
| 401 | Authorization required |
| 460 | Missing required parameter |
| 462 | Parameter error |
Common Status Detail Codes
| Status Detail Code | Description |
| 1004 | Referer used to create token doesn't match referer of call |
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>