Protocols/WebAPI/Reference

WebAPI Protocol

Basic

Introduction

Clients

Whimsicals

Host Interaction

Flow

Authentication

• Client

• WebApp

Other Services

•

Foodgroups

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

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

Typical Authenticated Application Flow

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

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

Typical Anonymous Application Flow

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

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

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

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