Protocols/WebAPI/Reference/Methods/Session

WebAPI Protocol

Basic

Introduction

Clients

Whimsicals

Host Interaction

Flow

Authentication

• Client

• WebApp

Other Services

•

Foodgroups

This page is about WebAPI session methods, in a series for the WebAPI reference manual.

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 NINA Authentication Token for most of the APIs. An NINA 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.nina.bz/aim/startSession

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	[Required] the AIM Web Key from http://dev.nina.bz/aim - use the same key for all calls
String	a	[Required] Use an NINA 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
String	friendly	For anonymous sessions, this is an optional friendly name to display
String	language	The language and locale to use in "<lang>-<locale>" format. The lang is the 2 letter language code for I18N (default: en) and the locale is the 2 letter Locale code for I18N (default: us). If not passed in, the language will default to "en-us".
String	clientName	Client name - clientLogin parameter
Integer	clientVersion	Client version - clientLogin parameter
Integer	ts	Epoch timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
Boolean	mobile	Whether this is a mobile session.
Integer	sessionTimeout	Time in seconds before terminating idle web session.
Presence State	view	How we should appear to other users, offline and mobile are not valid in this case

Output Fields

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

Common Status Codes

Status Code	Description
200	Success
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.nina.bz/aim/startSession?f=json&k=KEY&c=callback&a=AOLAUTHTOKEN

Sample JSON Output

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

Sample XML Output

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

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>

deleteEvents

To delete multiple events

URL: GET http://api.oscar.nina.bz/aim/deleteEvents

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.nina.bz/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>

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.nina.bz/aim/endSession

Input Parameters

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

Common Status Codes

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

Example: http://api.oscar.nina.bz/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>

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.nina.bz/aim/startOSCARSession

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.nina.bz/aim - use the same key for all calls
String	a	[Required] Use an NINA Authentication Token for authentication, from the getToken call
Boolean	useTLS	Request the connection to BOSS use TLS
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
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",
      "cookie":"base64ed data",
      "tlsCertName":"bos.oscar.nina.bz"
    }
  }
}

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>
    <cookie>base64ed data</cookie>
    <tlsCertName>bos.oscar.nina.bz</tlsCertName>
  </data>
</response>