Detecting User Presence

Last updated: 2024-08-15Contributors
Edit this page

Understanding a user's availability is an essential component when considering who to forward calls to, who can attend an ad-hoc meeting, or even where people are (depending upon their status message). As an all-in-one communication platform, the Presence API gives apps visibility into a user's availability across the entire platform: are they on the phone? are they in a meeting? are they available, but their status is set to "Do Not Disturb" etc.

Apps can determine one's availability by looking at an aggregated status the platform computes automatically, or can look at each presence state independently and make other informed decisions.

Presence Response

Below is a sample response from the Presence API to illustrate the visibility it can provide. The aggregated/computed status is highlighted below.

{
  "uri": "https://platform.ringcentral.com/restapi/v1.0/account/248xxx004/extension/248xxx004/presence",
  "extension": {
    "uri": "https://platform.ringcentral.com/restapi/v1.0/account/248xxx004/extension/248xxx004",
    "id": 248111004,
    "extensionNumber": "101"
  },
  "presenceStatus": "Available",
  "telephonyStatus": "NoCall",
  "userStatus": "Available",
  "dndStatus": "TakeAllCalls",
  "allowSeeMyPresence": true,
  "ringOnMonitoredCall": false,
  "pickUpCallsOnHold": false
}

Sample Code to Get Started with Presence

/* You get the environment parameters from your
   application dashbord in your developer account
   https://developers.ringcentral.com */

const RC = require('@ringcentral/sdk').SDK
require('dotenv').config();

const RECIPIENT    = process.env.SMS_RECIPIENT

var rcsdk = new RC({
    'server':       process.env.RC_SERVER_URL,
    'clientId':     process.env.RC_APP_CLIENT_ID,
    'clientSecret': process.env.RC_APP_CLIENT_SECRET
});

var platform = rcsdk.platform();

platform.login({ 'jwt':  process.env.RC_USER_JWT })

platform.on(platform.events.loginSuccess, function(e){
    get_users_presence()
});

async function get_users_presence(){
    try {
        var resp = await platform.get('/restapi/v1.0/account/~/presence', {
            detailedTelephonyState: true
        })
        var jsonObj = await resp.json()
        for (var record of jsonObj.records){
            console.log(record.userStatus)
        }
    }catch(e){
        console.log(e.message)
    }
}
#!/usr/bin/python

# You get the environment parameters from your
# application dashbord in your developer account
# https://developers.ringcentral.com

import os
import sys

from dotenv import load_dotenv
from ringcentral import SDK
load_dotenv()

rcsdk = SDK( os.environ.get('RC_APP_CLIENT_ID'),
             os.environ.get('RC_APP_CLIENT_SECRET'),
             os.environ.get('RC_SERVER_URL') )
platform = rcsdk.platform()
try:
  platform.login( jwt=os.environ.get('RC_USER_JWT') )
except Exception as e:
  sys.exit("Unable to authenticate to platform: " + str(e))

endpoint = "/restapi/v1.0/account/~/presence"
payload = { 'detailedTelephonyState' : True }
resp = platform.get( endpoint, payload)
for record in resp.json().records:
    print(record.userStatus)
<?php
/* You get the environment parameters from your
   application dashbord in your developer account
   https://developers.ringcentral.com */

require('vendor/autoload.php');
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . '/../');
$dotenv->load();

$rcsdk = new RingCentral\SDK\SDK( $_ENV['RC_APP_CLIENT_ID'],
                                  $_ENV['RC_APP_CLIENT_SECRET'],
                                  $_ENV['RC_SERVER_URL'] );
$platform = $rcsdk->platform();
$platform->login( [ "jwt" => $_ENV['RC_USER_JWT'] ] );

$endpoint = "/account/~/presence";
$payload = array( 'detailedTelephonyState' => true );
$resp = $platform->get($endpoint, $payload);
foreach ($resp->json()->records as $record)
    print_r ($record->userStatus . "\n");

?>
using System;
using System.Threading.Tasks;
using RingCentral;

namespace Read_Presence
{
  class Program
  {
    static RestClient restClient;

    static async Task Main(string[] args)
    {
      restClient = new RestClient(
        Environment.GetEnvironmentVariable("RC_APP_CLIENT_ID"),
        Environment.GetEnvironmentVariable("RC_APP_CLIENT_SECRET"),
        Environment.GetEnvironmentVariable("RC_SERVER_URL"));
      await restClient.Authorize(Environment.GetEnvironmentVariable("RC_USER_JWT"));
      await read_users_presence();
    }

    static private async Task read_users_presence()
    {
      var parameters = new AccountPresenceParameters();
      parameters.detailedTelephonyState = true;

      var resp = await rc.Restapi().Account().Presence().Get(parameters);
      foreach (var record in resp.records)
      {
        Console.WriteLine(record.userStatus);
      }
    }
  }
}
import com.ringcentral.*;
import com.ringcentral.definitions.*;

public class Read_Presence {
  static RestClient restClient;
  public static void main(String[] args) {
    var obj = new Read_Presence();
    rc = new RestClient( System.getenv("RC_APP_CLIENT_ID"),
    System.getenv("RC_APP_CLIENT_SECRET"),
    System.getenv("RC_SERVER_URL") );
    try {
      rc.authorize(System.getenv("RC_USER_JWT"));
      obj.read_users_presence();
    } catch (RestException | IOException e) {
      e.printStackTrace();
    }
  }

  public static void read_users_presence() throws RestException, IOException{
    var parameters = new ReadAccountPresenceParameters();
    parameters.detailedTelephonyState = true;

    var response = rc.restapi().account().presence().get(parameters);
    for (var record : response.records)
    System.out.println(record.userStatus);
  }
}
#!usr/bin/ruby

# You get the environment parameters from your
# application dashbord in your developer account
# https://developers.ringcentral.com

require 'ringcentral'
require 'dotenv/load'

SENDER       = ENV['SMS_SENDER']
RECIPIENT    = ENV['SMS_RECIPIENT']

$rc = RingCentral.new( ENV['RC_APP_CLIENT_ID'],
                       ENV['RC_APP_CLIENT_SECRET'],
                       ENV['RC_SERVER_URL'] )

$rc.authorize( jwt: ENV['RC_USER_JWT'] )

def output_presence()
  endpoint = "/restapi/v1.0/account/~/presence"
  payload = { detailedTelephonyState: true }

  resp = $rc.get(endpoint, payload: payload )

  for record in resp.body['records'] do
    puts record.userStatus
  end
end

output_presence()

Required Permissions

Apps requesting to read presence information require the ReadPresence permission.

Presence APIs

The following APIs are often used in reading and updating user presence information: