Protocols/WebAPI/Reference/Methods/Presence

From NINA Wiki
Revision as of 07:13, 26 March 2020 by AD (talk | contribs) (Created page with "{{Protocols/WebAPI}} This page is about WebAPI presence methods, in a series for the WebAPI Protocols/WebAPI/Reference|reference manu...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
WebAPI Protocol
Basic
Introduction
Clients
Whimsicals
Host Interaction
Flow
Authentication
• Client
• WebApp
Other Services
•
Foodgroups

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

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

Input Parameters

Type Field Description
Format f [Required] The format of the data returned
String c JSONP callback
String r Request id
String k [Required] either an AIM Web Key or AIM Presence Key from http://dev.nina.bz/aim
String aimsid Use an AIM Session Id from the startSession call for authentication - k is not required
String a Use an NINA Authentication Token for authentication, from the getToken call
Integer ts Epoch 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

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

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>
      <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>
      </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>
    </user>
    </users>
  </data>
</response>

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

Input Parameters

Type Field Description
Format f [Required] The format of the data returned
String c JSONP callback
String r Request id
String k [Required] either an AIM Web Key or AIM Presence Key from http://dev.nina.bz/aim
String aimsid Use an AIM Session Id from the startSession call for authentication - k is not required
String a Use an NINA Authentication Token for authentication, from the getToken call
Integer ts Epoch 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

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

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>
      <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>
      </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>
    </user>
    </users>
  </data>
</response>

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

Input Parameters

Type Field Description
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 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.nina.bz/presence/icon?&k=MYKEY&t=ChattingChuck">

setState

Sets the user's Presence information. The setState method call requires an aimsid from a previous startSession call.

URL: GET http://api.oscar.nina.bz/presence/setState

Input Parameters

Type Field Description
Format f [Required] The format of the data returned
String c JSONP callback
String r Request id
String aimsid [Required] Use an AIM Session Id from the startSession call for authentication
Presence State view [Required] How we should appear to other users, offline and mobile are not valid in this case
String away If setting the state to away, this is the away message display to other users on mouse over
Boolean encodeData Base 64 encode the data in imdata events
Capability assertCaps Comma separated list of capabilities to assert to other users.
Capability interestCaps Comma separated list of capabilities to receive from other users. AssertCaps will also be received from other users.
String 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.nina.bz/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"
      }
    }
  }
}

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>
    </myInfo>
  </data>
</response>

setStatus

Sets the user's status message.

URL: GET http://api.oscar.nina.bz/presence/setStatus

Input Parameters

Type Field Description
Format f [Required] The format of the data returned
String c JSONP callback
String r Request id
String k the AIM Web Key from http://dev.nina.bz/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 NINA Authentication Token for authentication, from the getToken call
Integer ts Epoch timestamp - clientLogin required parameter
String sig_sha256 Signature - clientLogin required parameter.
String statusMsg [Required] status message display to other users

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

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

setProfile

Set the AIM buddy info for a user.

URL: GET http://api.oscar.nina.bz/presence/setProfile

Input Parameters

Type Field Description
Format f [Required] The format of the data returned
String c JSONP callback
String r Request id
String k the AIM Web Key from http://dev.nina.bz/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 NINA Authentication Token for authentication, from the getToken call
Integer ts Epoch 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

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

getProfile

Get the AIM Profile message for an aimId .

URL: GET http://api.oscar.nina.bz/presence/getProfile

Input Parameters

Type Field Description
Format f [Required] The format of the data returned
String c JSONP callback
String r Request id
String k the AIM Web Key from http://dev.nina.bz/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 NINA Authentication Token for authentication, from the getToken call
Integer ts Epoch 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

Example: http://api.oscar.nina.bz/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>
Retrieved from "https://wiki.nina.chat/index.php?title=Protocols/WebAPI/Reference/Methods/Presence&oldid=1969"