Protocols/WebAPI/Reference/Methods/IM

WebAPI Protocol

Basic

Introduction

Clients

Whimsicals

Host Interaction

Flow

Authentication

• Client

• WebApp

Other Services

•

Foodgroups

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

sendIM

Send an IM to an AIM user. Requires a valid aimsid from the startSession call or an NINA Authentication Token.

URL: GET http://api.oscar.nina.bz/im/sendIM

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	a	Use an NINA Authentication Token for authentication, from the getToken call
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
Integer	ts	Epoch timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	t	[Required] Destination aimId
String	message	[Required] utf8 encoded message, limited to 1024 bytes
Boolean	autoResponse	Set the auto response flag be set, can not be set with offlineIM
Boolean	displaySMSSegmentData	[Default false] - Set true to display SMS segment data
Boolean	offlineIM	Deliver as an offline IM when possible if the user isn't online, autoResponse flag can no bet set

Output Fields

Type	Field	Description
SendImSubCode	subCode	subcode

Common Status Codes

Status Code	Description
200	Success
400	Session does not exist
401	Authorization required
430	Sending IMs too fast
450	Consent required, use the redirectURL and append a k=KEY to it
460	Missing required parameter
462	Parameter error
602	Target user is not available
603	Target user is blocked
606	Message is too large

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/im/sendIM?f=json&k=MYKEY&c=callback&aimsid=AIMSID&msg=Hi&t=ChattingChuck

Sample JSON Output

{"response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "subCode":{
        "subError":,
        "subReason":""
      }
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <subCode>
      <subError></subError>
      <subReason></subReason>
    </subCode>
  </data>
</response>

sendDataIM

Send a Data IM to an AIM user. Requires a valid aimsid from the startSession call or an NINA Authentication Token.

URL: GET http://api.oscar.nina.bz/im/sendDataIM

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	a	Use an NINA Authentication Token for authentication, from the getToken call
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
Integer	ts	Epoch timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	t	[Required] Destination aimId
Capability	cap	[Required] AIM Capability
Data IM Type	type	[Required] Type of Message
String	data	[Required] Data to send remote AIM user.
Boolean	dataIsBase64	If present, then the data parameter is base64 encoded
Boolean	autoResponse	Should the auto response flag be set
String	inviteMsg	For the invite message type, and optional invite message can be included
String	cookie	Base64 encoded cookie for this conversation
String	ip	IPv4 address recipient can connect to for peer-to-peer conversation
Integer	port	Port used in conjunction with ipAddr for connection
String	proposerIp	Internal IP address of client
Boolean	hostCheck	Host will check remote user to verify they have requested capability [Default 1]
Boolean	useRS	Use Relay server. ip will be from RS and not a peer [Default 0]
Integer	sequenceNum	Sequence number for proposal. Must increment by 1

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
430	Sending IMs too fast
450	Consent required, use the redirectURL and append a k=KEY to it
460	Missing required parameter
462	Parameter error
602	Target user is not available
605	Target user doesn't support the capability
606	Message is too large

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/im/sendDataIM?f=json&k=MYKEY&c=callback&aimsid=AIMSID&data=DATAHERE&t=ChattingChuck& cookie=MTIzNDU2NzgK

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>

rejectDataIM

Reject a Data IM from a user. Requires a valid aimsid from the startSession call or an NINA Authentication Token.

URL: GET http://api.oscar.nina.bz/im/rejectDataIM

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	a	Use an NINA Authentication Token for authentication, from the getToken call
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
Integer	ts	Epoch timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	t	[Required] Destination aimId
String	cookie	[Required] base64 encoded converstation cookie
Reject Reason	reason	[Required] Reason for reject

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
430	Sending IMs too fast
450	Consent required, use the redirectURL and append a k=KEY to it
460	Missing required parameter
462	Parameter error
602	Target user is not available
605	Target user doesn't support the capability
606	Message is too large

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/im/rejectDataIM?f=json&k=MYKEY&c=callback&aimsid=AIMSID&reason=denied&t=ChattingChuck&cookie=MTIzNDU2NzgK

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>

setTyping

Set the current typing status. Only send a typing status on event change - there is no need to send a typing for every key press. Requires a valid aimsid from the startSession call.

URL: GET http://api.oscar.nina.bz/im/setTyping

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
String	t	[Required] Destination aimId
Typing Status	typingStatus	[Required] The new typing 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/im/send?f=json&k=MYKEY&c=callback&aimsid=AIMSID&typingStatus=typing&t=ChattingChuck

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>