Protocols/WebAPI/Reference/Methods/IM

From NINA Wiki
Revision as of 07:25, 26 March 2020 by AD (talk | contribs) (Created page with "{{Protocols/WebAPI}} This page is about WebAPI IM methods, in a series for the WebAPI reference manual....")
(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 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={data}&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>
Retrieved from "https://wiki.nina.chat/index.php?title=Protocols/WebAPI/Reference/Methods/IM&oldid=1970"