Introduction to Messenger APIs

Prerequisites
HTTP
URIs, URI parameters, and URL encoding
Request / Response Headers
HTTP content
RESTful
APIs use HTTP GET, POST, and the less common PUT, DELETE
Override using HTTP POST and URI parameter “_method=[put,delete]”
JSON
No XML support
Content-Type: application/json;charset=utf-8

Authentication
Standard Oauth
Direct Oauth
Consumer key must have read/write access for Y! Messenger
Programmatic authentication
No browser
Other mobile integration friendly optimizations
Accuracy of timestamp restriction is relaxed if you use PLAINTEXT oauth signature
Pitfall – consumer key / consumer secret sent in the clear

Introduction to the Messenger APIs
Types of communication
Client to Server communication (typically user actions)
Send an instant message
Login into messenger
Server to Client communication (… but client initiated)
Someone send you an instant message
Someone tries to add you to their buddy list

Client to Server API’s
Session Management
Login (POST /session)
Dynamic capabilities (mailAlerts/fileXfer/buzz/smiley) per login session
Supply presence information at login
Get back the contact or group list in the response
Look for the URI parameter ‘fieldsBuddyList’ or ‘fieldsGroupList’
Logout (DELETE /session)
Keepalive (PUT /session/keepalive)
Client heartbeat
Presence Management
Update your presence information (PUT /presence)
State (available, busy, idle, invisible)
Custom message

Client to Server API’s
Message Management
Instant Message (POST /message/{network}/{id})
No Interop (msn/hotmail/etc)
Contact/Group Management
Fetch your contact or group list
Now supports fetching a subset of your AddressBook data
Add a contact (PUT /group/{groupname}/contact/…)
Delete a contact (DELETE /group/{grpname}/conta..)

Server to client api’s
What is a Notification?
An event targeted to a logged in session
Most common notification types
message
Typically an incoming instant message
buddyInfo
Information about a contact that just logged into messenger
Information about contacts online when you first login
buddyStatus
A buddy updated their presence information (state/custom message)
logoff
A buddy went offline
buddyAuthorize
Someone is trying to add you to their buddy list
The accept or denial response to an add request you previously sent

Server to client api’s
Notification Sequence Number
All notifications have a sequence number unique to the session
Incremental integer
Unlikely, but design for skips in the sequence counter
Design to be able to skip unknown notification types
Retrieving Notifications
Periodic Polling
Provide start sequence number and optional count
Limited to under once every 5-10 seconds
Does not support persistent connections
Comet Style Push (Long Poll)
Provide start sequence number and optional idleTimeout
Expected that client will always maintain an available long poll
Supports HTTP 1.1 and persistent connections

More than just basic IM FEATURES
File Transfer
Send and Receive files
Remember to indicate ‘fileXfer’ clientCapability at login
Display Images
Upload and update your custom display image
Retrieve the display images for your contacts

Getting started - Sample Session guidelines
Obtain your credentials
Login (POST /session)
Request for groups list in the response
Look at URI parameter ‘fieldsGroupList’
Information about your buddies
Don’t request for information using Group or Contact List Management APIs
Wait for buddyInfo notifications for all online buddies
Automatically also subscribed for delta notifications (buddyStatus/logoff/etc)
Triggers any offline messages received
Look for offlineMessage notification type
< Other API calls. Don’t forget /keepalive>
Logout (DELETE /session)

DIRECT OAUTH
Consumer key must have read/write access to Y! Messenger
Exchange UserId/Password for PART
PART = Pre-Approved Request Token
Programmatic solution
Exchange PART for Access Token / Handle
Date/Time issue on mobile devices
Accuracy requirement relaxed if you use PLAINTEXT oauth signature method
Access token expiration
Looking to extend this for Y! Messenger only consumer keys
Refresh access token as needed using Handle

Introduction to Messenger APIs

by vivekvik

Accessibility

Categories

Upload Details

Usage Rights

1 Embed 1

Statistics