FINOS Presence API
The Presence API from FINOS — 8 operation(s) for presence.
OpenAPI Specification
openapi: 3.0.1
info:
title: Agent Admin Presence API
description: 'This document refers to Symphony API calls to send and receive messages
and content. They need the on-premise Agent installed to perform
decryption/encryption of content.
- sessionToken and keyManagerToken can be obtained by calling the
authenticationAPI on the symphony back end and the key manager
respectively. Refer to the methods described in authenticatorAPI.yaml.
- Actions are defined to be atomic, ie will succeed in their entirety
or fail and have changed nothing.
- If it returns a 40X status then it will have sent no message to any
stream even if a request to some subset of the requested streams
would have succeeded.
- If this contract cannot be met for any reason then this is an error
and the response code will be 50X.
- MessageML is a markup language for messages. See reference here:
https://rest-api.symphony.com/docs/messagemlv2
- **Real Time Events**: The following events are returned when reading
from a real time messages and events stream ("datafeed"). These
events will be returned for datafeeds created with the v5 endpoints.
To know more about the endpoints, refer to Create Messages/Events
Stream and Read Messages/Events Stream. Unless otherwise specified,
all events were added in 1.46.
'
version: 25.8.1
servers:
- url: youragentURL.symphony.com/agent
tags:
- name: Presence
paths:
/v1/presence/feed/create:
post:
summary: Create Presence status feed.
description: 'Create a new stream capturing presence status changes ("presence feed").
When read from, the feed will return the current presence status of company (pod) users
if it has changed since the last read.
Returns the ID of the presence feed to be used in subsequent read operations.
'
consumes:
- application/json
produces:
- application/json
parameters:
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
tags:
- Presence
responses:
'200':
description: OK
schema:
$ref: '#/definitions/StringId'
examples:
application/json:
id: c4dca251-8639-48db-a9d4-f387089e17cf
'400':
description: Client error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
/v1/presence/feed/{feedId}/read:
get:
summary: Read a presence status feed.
description: 'Returns the current presence status of company (pod) users
if it has changed since the last read. Returns up to 500 records at a time.
'
produces:
- application/json
parameters:
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
- name: feedId
description: Presence feed ID.
in: path
required: true
type: string
tags:
- Presence
responses:
'200':
description: OK
schema:
$ref: '#/definitions/V2PresenceList'
examples:
application/json:
- category: AVAILABLE
userId: 14568529068038
timestamp: 1533928483800
- category: ON_THE_PHONE
userId: 974217539631
timestamp: 1503286226030
'400':
description: Client error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
/v1/presence/feed/{feedId}/delete:
post:
summary: Delete a presence status feed.
description: 'Returns the ID of the deleted feed.
'
consumes:
- application/json
produces:
- application/json
parameters:
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
- name: feedId
description: Presence feed ID.
in: path
required: true
type: string
tags:
- Presence
responses:
'200':
description: OK
schema:
$ref: '#/definitions/StringId'
examples:
application/json:
id: c4dca251-8639-48db-a9d4-f387089e17cf
'400':
description: Client error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
/v1/user/presence/register:
post:
summary: Register interest in a user's presence status
consumes:
- application/json
produces:
- application/json
parameters:
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
- name: uidList
description: List of (integer) User IDs of users whose presence to query
in: body
required: true
schema:
$ref: '#/definitions/UserIdList'
tags:
- Presence
responses:
'200':
description: OK
schema:
$ref: '#/definitions/SuccessResponse'
examples:
application/json:
format: TEXT
message: OK
'400':
description: Client error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'404':
description: 'Not Found: user id cannot be located.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: // Not Found. User id cannot be located. See response body for fruther details.
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
/v2/user/presence:
get:
summary: Get presence information about the requesting user.
produces:
- application/json
parameters:
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
tags:
- Presence
responses:
'200':
description: OK
schema:
$ref: '#/definitions/V2Presence'
examples:
application/json:
category: AVAILABLE
userId: 14568529068038
timestamp: 1533928483800
'400':
description: Client error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
post:
summary: Set the presence of the requesting user.
consumes:
- application/json
produces:
- application/json
parameters:
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
- name: soft
description: 'If true, the user''s current status is taken into consideration. If the user is currently OFFLINE,
the user''s presence will still be OFFLINE, but the new presence will take effect when the
user comes online. If the user is currently online, the user''s activity state will be
applied to the presence if applicable. (e.g. if you are setting their presence to AVAILABLE,
but the user is currently idle, their status will be represented as AWAY)
'
in: query
required: false
type: boolean
- name: presence
in: body
required: true
schema:
$ref: '#/definitions/V2PresenceStatus'
tags:
- Presence
responses:
'200':
description: OK
schema:
$ref: '#/definitions/V2Presence'
examples:
application/json:
category: AWAY
userId: 14568529068038
timestamp: 1533928483800
'400':
description: Client error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
/v3/user/{uid}/presence:
get:
summary: Get presence information about a particular user.
produces:
- application/json
parameters:
- name: uid
description: 'User ID as a decimal integer
'
in: path
required: true
type: integer
format: int64
- name: local
description: 'If true, a local query will be performed and the presence will be
set to OFFLINE for users who are not local to the calling user''s
pod. If false or absent, then the presence of all local users and
the presence of all external users to whom the calling user is
connected will be queried.
For external users, a "presence interest" should be registered through
/v1/user/presence/register before querying for presence.
'
in: query
type: boolean
required: false
default: false
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
tags:
- Presence
responses:
'200':
description: OK
schema:
$ref: '#/definitions/V2Presence'
examples:
application/json:
category: AVAILABLE
userId: 14568529068038
timestamp: 1533928483800
'400':
description: Client error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'404':
description: 'Not Found: user id cannot be located.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: // Not Found. User id cannot be located. See response body for fruther details.
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
/v2/users/presence:
get:
summary: Get presence information about all company (pod) users.
description: 'The returned data is taken from the in-memory cache for performance
reasons which means inactive users may be omitted from the response.
All non-inactive users WILL be returned and some inactive users MAY
be included. Any omitted user IS inactive.
Returned records are sorted by user ID, ascending.
This method is expensive. It pulls ALL records from the cache, sorts them and then only uses a subset.
For large numbers of users, this can be very inefficient both due to sorting
and due to the cache being distributed across many nodes.
Addiionally, there is the potential to miss users if they become active
after the page in which their user ID falls has already been read by the client.
To avoid this situation, a presence feed should be created (and optionally read from)
first to capture presence changes of users who get reactivated during a paged call to this endpoint.
'
produces:
- application/json
parameters:
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
- name: lastUserId
description: Last user ID retrieved. Used for paging; if provided, results will skip users with IDs less than this parameter.
in: query
required: false
type: integer
format: int64
- name: limit
description: Max number of records to return. If no value is provided, 1000 is the default. The maximum supported value is 5000.
in: query
type: integer
required: false
tags:
- Presence
responses:
'200':
description: OK
schema:
$ref: '#/definitions/V2PresenceList'
examples:
application/json:
- category: AVAILABLE
userId: 14568529068038
timestamp: 1533928483800
- category: OFFLINE
userId: 974217539631
timestamp: 1503286226030
'400':
description: Client error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
/v3/user/presence:
post:
summary: Set presence information for a particular user.
produces:
- application/json
parameters:
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
- name: soft
description: 'If true, the user''s current status is taken into consideration. If the user is currently OFFLINE,
the user''s presence will still be OFFLINE, but the new presence will take effect when the
user comes online. If the user is currently online, the user''s activity state will be
applied to the presence if applicable. (e.g. if you are setting their presence to AVAILABLE,
but the user is currently idle, their status will be represented as AWAY)
'
in: query
required: false
type: boolean
- name: presence
in: body
required: true
schema:
$ref: '#/definitions/V2UserPresence'
tags:
- Presence
responses:
'200':
description: OK
schema:
$ref: '#/definitions/V2Presence'
examples:
application/json:
category: AVAILABLE
userId: 14568529068038
timestamp: 1533928483800
'400':
description: Client error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'404':
description: 'Not Found: user id cannot be located.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: // Not Found. User id cannot be located. See response body for fruther details.
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
definitions:
UserIdList:
type: array
items:
type: integer
format: int64
example:
- 7215545058313
- 7215545078461
V2PresenceStatus:
type: object
properties:
category:
type: string
description: "Presence status. Possible values are:\n - UNDEFINED\n - AVAILABLE\n - BUSY\n - DO_NOT_DISTURB\n - ON_THE_PHONE\n - BE_RIGHT_BACK\n - IN_A_MEETING\n - AWAY\n - OUT_OF_OFFICE\n - OFF_WORK\n - OFFLINE\n"
example: AWAY
required:
- category
V2UserPresence:
allOf:
- $ref: '#/definitions/V2PresenceStatus'
- type: object
properties:
userId:
type: integer
format: int64
description: The ID of the user to whom the presence state relates.
example: 14568529068038
SuccessResponse:
type: object
properties:
format:
type: string
enum:
- TEXT
- XML
example: TEXT
message:
type: string
example: Success
V2Presence:
allOf:
- $ref: '#/definitions/V2UserPresence'
- type: object
properties:
timestamp:
type: integer
format: int64
description: The time, in milliseconds since Jan 1 1970, when the presence state was set.
example: 1533928483800
StringId:
type: object
properties:
id:
type: string
example: xhGxbTcvTDK6EIMMrwdOrX___quztr2HdA
V2PresenceList:
type: array
items:
$ref: '#/definitions/V2Presence'
example:
- category: AVAILABLE
userId: 14568529068038
timestamp: 1533928483800
- category: OFFLINE
userId: 974217539631
timestamp: 1503286226030
Error:
type: object
properties:
code:
type: integer
format: int32
example: 401
message:
type: string
example: Invalid session