Protocols/WebAPI/Reference/Methods/BuddyList

WebAPI Protocol

Basic

Introduction

Clients

Whimsicals

Host Interaction

Flow

Authentication

• Client

• WebApp

Other Services

•

Foodgroups

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

addBuddy

Add a buddy to the Buddy List.

URL: GET http://api.oscar.nina.bz/buddylist/addBuddy

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
String	buddy	[Required] buddy name. Can be multipled.
String	group	[Required] group name to add buddy to

Common Status Codes

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

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

addGroup

Add an empty group to the buddylist.

URL: GET http://api.oscar.nina.bz/buddylist/addGroup

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

removeBuddy

Remove a buddy from the buddylist.

URL: GET http://api.oscar.nina.bz/buddylist/removeBuddy

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	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

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

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

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	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

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

renameGroup

Rename a group in the buddylist.

URL: GET http://api.oscar.nina.bz/buddylist/renameGroup

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	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

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

setBuddyAttribute

Set an attribute for a buddy

URL: GET http://api.oscar.nina.bz/buddylist/setBuddyAttribute

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	buddy	[Required] buddy name
String	friendly	Friendly name

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/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>

getBuddyAttribute

Get some buddy's attributes

URL: GET http://api.oscar.nina.bz/buddylist/getBuddyAttribute

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	buddy	[Required] buddy name

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

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/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":""
    }
  }
}

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

setGroupAttribute

Set an attribute for a group

URL: GET http://api.oscar.nina.bz/buddylist/setGroupAttribute

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	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

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

moveGroup

Move a group

URL: GET http://api.oscar.nina.bz/buddylist/moveGroup

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	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

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>

moveBuddy

Move a buddy inside a group

URL: GET http://api.oscar.nina.bz/buddylist/moveBuddy

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	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

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

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>

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 tokens must be provided

URL: GET http://api.oscar.nina.bz/buddylist/copy

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	s	Use trusted authentication, the source user
String	a	Use an NINA 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.nina.bz/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>

deleteUser

Delete user's entire Buddy List with option to bump user offline if the user is online.

URL: GET http://api.oscar.nina.bz/buddylist/deleteUser

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.
Boolean	noBumpUser	Is the user going to be bumped offline or not. By default, the user will be bumped off

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

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>