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