4.1.12 Presence

Presence

URL: /presence

This method allows you to: set the date of last activity, set your own status description, check the date of last activity for a given login and download statuses for all contacts.

Authorization

The method requires authorization using basic authentication. Please use the login and password.

Opis metod:

Setting the date of last activity

To set the date of last activity, call the  /presence method with parameters:

{"u":false}
{"u":true}

Return value

• If successful, we will receive code 200.

• If an error occurs on the server or any of the parameters contain an incorrect value, the method will return the appropriate 3-digit error code shown below:

  Code	Description
  400	Incorrect parameters - one of the parameters was not provided

Set status

To set the status, call the  /presence method with parameters:

{ "s": "online" }

Return value

• If successful, we will receive code 200.

• If an error occurs on the server or any of the parameters contain an incorrect value, the method will return the appropriate 3-digit error code shown below:

Retrieve status

To retrieve the status, call the  /presence method with the following parameters:

Return value

• If successful, we will receive a JSON object:

  {
   "s": string
  }

  where:

  • s - status, possible values: online, away, busy, snoozing
  • If an error occurs on the server or any of the parameters contain an incorrect value, the method will return the appropriate 3-digit error code shown below:

Set text status

To set the text status, call the /presence method with the following parameters: 

{ "ts": "Text status" }

Return value

• If successful, we will receive code 200.

• If an error occurs on the server or any of the parameters contain an incorrect value, the method will return the appropriate 3-digit error code shown below:

Retrieve text status

To retrieve the status text, call the /presence method with the following parameters:

Return value

• If successful, we will receive a JSON object:

  {
   "ts": string
  }

  where:

  • ts - text status
  • If an error occurs on the server or any of the parameters contain an incorrect value, the method will return the appropriate 3-digit error code shown below:

Checking the date of last activity for the specific login(account)

To check the date of last activity for the selected SIP login, call the  /presence method with the following parameters:

{ "l": "sip login" }

Return value

• If successful, we will receive a JSON object containing the current status of s (may contain the values: online, offline or unknown) and the date and time (UTC) of the last ls activity in the format yyyy-MM-ddTHH:mm:ss. In case of online or unknown status, the ls value is empty. Example:

  {
    "s": "offline",
    "ls": "2015-01-14T10:44:00"
  }

  To calculate the time difference between the ls date and the current server date, you should take into consideration the Date response header in which the current server date is given. Additionally, the dialer should include the Expires response header, which informs the dialer how long this response is valid.

• If an error occurs on the server or any of the parameters contain an incorrect value, the method will return the appropriate 3-digit error code shown below:

  Kod	Description
  400	Incorrect parameters - one of the parameters was not provided

Retrieve text status and avatar information for all contacts

To download the "text status" and information about your contacts' avatars, call the /presence method with the following parameters:

Additionally, this method supports the If-Modified-Since header. When sending If-Modified-Since, we tell the server to send the document only if it has been modified since a given date. If the document has not changed, the server should send the browser the response code 304 - HTTP STATUS: 304 Not Modified. We receive the modification date with each response (HTTP STATUS: 200 OK) in the Last-modified header. Before sending another query, the dialer should include the Expires response header, which informs the dialer how long this response is valid.

Return value

• If successful (HTTP STATUS: 200 OK), we will receive an array of JSON objects in the body containing:

• • id - contact id from local(device) address book

  • l - SIP login
  • s - status

  • av - information about the existence of the avatar: 0 - the file does not exist, 1 file exists,

  • avdt - the date and time when the avatar was changed in the format yyyy-MM-ddTHH:mm:ss
  • pv - information about the existence of a video profile: 0 - the file does not exist, 1 file exists,
  • pvdt -the date and time when the video avatar was changed in the format yyyy-MM-ddTHH:mm:ss
  • ts - text status
  • tsdt - the date and time when the status was changed in the formacie yyyy-MM-ddTHH:mm:ss

Example:

[
  { 
    "id"  : ulong, 
    "l"   : string,
    "s"   : string,
    "av"  : string, 
    "avdt": string,
    "pv"  : string,
    "pvdt": string, 
    "ts"  : string, 
    "tsdt": string
  }
]

• If an error occurs on the server or any of the parameters contain an incorrect value, the method will return the appropriate 3-digit error code shown below:

  Code	Description
  400	Incorrect parameters - one of the parameters was not provided

Saving settings

To save the settings, call the /presence method with parameters:

{
 "ss" : string,
 "sts": string,
 "sls": string,
 "sav": string,
 "sai": string
}

Return value

• If successful, we will receive code 200.

• If an error occurs on the server or any of the parameters contain an incorrect value, the method will return the appropriate 3-digit error code shown below:

Retrieve settings

To read the settings, call the /presence method with parameters:

Return value

Return value

If successful (HTTP STATUS: 200 OK), we will receive an array of JSON objects in the body containing:

• ss - show status -  possible values: everyone, contacts, nobody
• sts - show text status -  possible values: everyone, contacts, nobody
• sls - show last seen -  possible values: everyone, contacts, nobody
• sav - show avatar video -  possible values: everyone, contacts, nobody
• sai - show avatar image -  possible values: everyone, contacts, nobody