1. Integrating and Extending Oracle Content and Experience
  2. Oracle Content and Experience REST APIs
  3. REST API for Conversations

REST API for Conversations

You can use the Oracle Cloud REST API for Conversations to create and manage conversations in your cloud resources that enable real-time collaboration between individuals and teams and connect your business processes, enterprise applications, and content.

The REST API for Conversations uses the JSON data format and relies on a REST-based architectural style that provides a convenient and consistent approach to requesting and modifying data. The client specifies an action using an HTTP verb such as POST, GET, PUT, or DELETE. It specifies a resource using a unique URL in this format: 

https://oracleContentInstance-identityName.network.dataCenter.oraclecloud.com/osn/social/api/v1/resource-path
In the URL:

  • oracleContentInstance is the name you chose for your Oracle Content and Experience Cloud instance when it was provisioned.

  • identityName is the identity name you chose when you signed up with Oracle Public Cloud.

  • network is the name of your network.

  • dataCenter is the data center that Oracle Content and Experience Cloud is set up to use.

  • resource-path is the relative path that defines the resource.

The following topics provide overview information about developing with the REST API for Conversations:

Oracle Content and Experience also provides the following REST APIs:

REST API Features for Conversations

Features of the REST API for Conversations help you develop custom integrations with conversation objects in Oracle Content and Experience.

API Security

All API invocations happen in the security context of the signed-in user.

Agent users can do actions on the system, either independently or on behalf of a particular user. In specific situations you might need to use one of the following properties. Among agent user techniques, as a best practice you should use Impersonate. Use On Behalf Of or Bypass only on the advice of Oracle support or the Oracle integration team.

  • Impersonate (in XV1ConnectionUpdateInfo)

    During the connection to the server, the impersonation sign in is recorded. The server also tracks when the impersonation ends. The audit log tracks the actions as being done by the user being impersonated; it does not track the impersonating agent for each action.

    The permissions for actions are based on the permission level of the user being impersonated.Impersonate is intended for use only in automated processes, such as for conversation object updates where you want to show that the update was made by a particular user. Keep in mind that using Impersonate can degrade analytics accuracy because it associates actions with the impersonated user.

  • On Behalf Of (in XV1ConnectionUpdateInfo) - Allows a user to do a limited number of end-user functions on behalf of another user, such as posting a message to a Conversation or uploading a document. When this privilege is used, the audit log indicates both the user who performed the action and the user on whose behalf it was performed; in clients, the action is labeled as having been performed by the user the action was performed for.

  • Bypass (in XV1SocialObjectRole, XV1ConversationRole, and XV1SocialObjectRole) - Allows the user to do any action without failing due to inadequate permissions (although a request might fail for another reason, such as not being a member of the Conversation being acted on). The Bypass privilege is intended for use only in certain automated processes in a highly secure environment.

API Versioning

The current version of the REST API for Conversations is v1. API versions are not tied to releases of Oracle Content and Experience.

The version number is placed in the URL directly following /social/api. For example:

https://<host>[:<port>]/osn/social/api/v1

A GET request to the API endpoint returns a list of the top-level URIs that the server supports. For example, this request:

https://<host>[:<port>]/osn/social/api/
Returns a list of supported versions, including the 
VCurrent
identifier, which identifies the most recent release of the server API. The current release is "V1". The result follows: 
{"V1" : "https://osn/api/v1",
}

Case Sensitivity

Case is important throughout the REST API because URLs, methods, names, and object IDs are all case sensitive.

Case is significant in the REST API URLs.

HTTP Methods

The REST API for Conversations supports standard HTTP methods (verbs).

Method Description

GET

Retrieve or query resources.

If you send a GET request for a specific field's value but that field does not exist, the API returns the field that you passed, with a null value and a status of 200.

POST

Create a new instance of a resource, such as a conversation.

In addition, you can use POST to create a relationship between two objects. For example, you can use POST to create a Like (Starred) relationship between a user and a conversation.

PUT

Update the state of an existing instance of a resource.

For example, you can use PUT to change the state of a conversation from Open to Closed. PUT requests use the XUpdater class.

DELETE

Delete an existing instance of a resource or delete a relationship between two objects.

Subset of HTTP Methods Supported by Client

If the client supports only a subset of these HTTP methods, you can tunnel the other methods using the POST method by specifying the desired method in the method query parameter. For example, the DELETE operation can be achieved by doing a POST on a resource with "method=delete" in the query string portion of the URL.

PUT Requests with XUpdater

When updating an object using a PUT request, such as with XConversationUpdater, you can use XUpdater to specify the value that you want to change. XUpdater is a class that represents the DTO for updating objects; the updater field actually represents a map of field values. For example, XUpdater can be reresented as follows: 

{
"updater": "XUpdater"
}

For example, you can use a PUT request to . . ./social/api/v1/conversations/ObjectID with the request payload {"updater":{"SHORT_NAME":"String for short name"}} to change the short name.

XUpdater is used with Collections, Conversations, Groups, People, and Collaboration objects.

Optional Fields and Default Values for JSON Data Representations

The API reference documentation uses the term optional in describing JSON data representation fields.

Optional has a slightly different meaning depending on the data type:

  • String: default is null if not specified.

  • int: default is zero (0) if not specified.

  • boolean: default is false if not specified.

Return Values

You can control the response payload's content type by specifying the JSON or HTML MIME type in the "Accept" HTTP header.

The content type defaults to 'application/json'. Examples are presented in JSON.

You can specify the value 'text/html' to get an HTML version of the JSON that is returned.

Name Patterns

All external class names begin with the letter X, followed by the version number, followed by a noun (for example, Conversation, Message, or People), followed by one or more modifiers, depending on the function of the class.

The following table describes the class name conventions and the associated functions, using the Conversation resource type as an example.

XV1Conversation. . . Action
Info Get information about a Conversation (GET).
CreateInfo Create a Conversation and set properties (POST).
FilterInfo Get Conversations that meet the filter criteria (GET).
MemberCreateInfo Add a member to a Conversation and set properties (POST).
MemberInfo Get information about a member of a Conversation (GET).
MessageCreateInfo Add a message in a Conversation (POST).
PropertyCreateInfo Set properties for a Conversation (POST).
PropertyInfo Get a property for an existing Conversation (GET).
PropertyUpdateInfo Set a property for a Conversation (PUT).
UpdateInfo Update attributes for a Conversation (PUT).
ListInfo Get a list of all Conversations (GET).
MemberListInfo Get a list of all direct members of the Conversation (GET).
PropertyListInfo Get a list of all properties for the Conversation (GET) .
StarListInfo Get a list of starred Conversations and their messages (GET) .

XObjectID

Each object in the REST API for Conversations has a unique ID. From that ID, you can load the object, if you have sufficient permissions. Many data transfer objects (DTOs) specify IDs of other objects related to the current object. Some examples include ParentID, ModifiedByUserID, CreatedByUserID, and ConversationID. These are all links or references to other objects in the system.

Note that the ID parameter represents a name for fields, an ObjectID or an External ID for Conversation objects, and an Object ID or sign in name for users.

URL Encoding

For readability, examples might be shown in literal text, but your requests should always be URL-encoded (percent-encoded).

For example:

/conversations?filter={"LimitToStarred":true,"ExcludeMuted":true}

This example should be URL-encoded as follows:

/conversations?filter=%7B%22LimitToStarred%22%3Atrue%2C%22ExcludeMuted%22%3Atrue%7D

Pagination

Pagination capabilities are supported by default on all GET operations that have a response payload of XV1*ListInfo (for example, XV1ConversationListInfo), unless otherwise specified.

You can use offset and count in the query argument, where the default values are 0 and 20 respectively. For example: 

https://<host:[<port>]/osn/social/api/conversations/<conversationID>/messages?offset=0&count=25

This request gets the first 25 messages, returning them with the newest message first. You can send additional requests to get incrementally older posts in the Conversation.

Filters

Filter capabilities are supported where specified.

To use a filter, specify the filter query argument in JSON format, using URL encoding as appropriate. For example, this request returns starred Conversations but no muted Conversations:

/conversations?filter={"LimitToStarred":true,"ExcludeMuted":true}

Sort Order

The currently assigned sort order determines the order in which results are returned.

You can change the sort order using the SortField field, which is available in XV1ConversationFilterInfo, XV1SocialObjectFilterInfo, and others. For example, this request returns results sorted by Conversation age, with the newest Conversation first:

/conversations?filter={"LimitToStarred":true,"ExcludeMuted":true,"SortField":CONVERSATION_IS_NEW}

Localization

This background information about localization might be useful as you are implementing or troubleshooting an Oracle Content and Experience integration.

Some of the concepts described in this section go beyond the REST API.

Localization is performed according to the following steps:

  1. Choose a language locale.

    1. If an HTTP request exists and has an X-Waggle-ForceLanguage header, then use the X-Waggle-ForceLanguage header value as the language locale and go to step 2.

    2. If a particular user is signed in or otherwise identified, check to see if the user has set a preferred language locale in their user profile. If set, use it and go to Step 2.

      A language locale from LDAP will be copied to the user profile in Oracle Content and Experience. If the LDAP realm has sync-on-authentication enabled, then for each sign in, the LDAP values will overwrite the user profile settings. However, if the user changes the value in their Oracle Content and Experience profile, it is not written back to LDAP; Oracle Content and Experience does not write any attributes to LDAP.

      If the LDAP Preferred Language is not supported in Oracle Content and Experience (for example, ar), English is displayed regardless of the application default language setting.

    3. If an HTTP request exists and has an Accept-Language header, use the Accept-Language header to select the language locale.

      Using the Accept-Language header, perform a lookup as described in RFC-4647 section 3.4. This will result in a language locale being chosen based on an exact or partial match of the header, the available translation bundles, and the bundle of last resort.

    4. If the server has a language locale set, use it.

    5. Select the host machine default language locale.

  2. Choose a translation bundle with the exact or longest possible partial match of the chosen language locale. If no exact or partial match exists, then choose the bundle for English.

Supported Locale Codes

The currently supported locale codes are:

  • cs (Czech)
  • da (Danish)
  • de (German)
  • en (English)
  • es (Spanish))
  • fi (Finnish)
  • fr (French)
  • fr-CA (French-Canadian)
  • hu (Hungarian)
  • it (Italian)
  • ja (Japanese)
  • ko (Korean)
  • nl (Dutch)
  • no (Norwegian)
  • pl (Polish)
  • pt-br or pt_BR (Portuguese-Brazilian)
  • ro (Romanian)
  • ru (Russian)
  • sv (Swedish)
  • tr (Turkish)
  • zh-CN or zh_CN (Chinese-Simplified)
  • zh-TW or zh_TW (Chinese-Traditional)

Name Field Length Limit

The Name field for objects, such as Conversation names or User names, has a length limit of 256 characters.

HTTP Status Codes and Error Handling

HTTP status codes for the Collaboration REST API follow.

Status Code Description
200 Request Successful.
4xx Bad requests. Invalid URI, invalid body format.
401 Unauthorized. Should sign in or get a security token.
403 Forbidden. Access denied.
5xx Internal server error.

For all responses, the status code is also available in the actual payload in the StatusCode field. For all non-HTTP Status 200 responses, a message explaining the cause of the error is available in the return value. For example: 

{
"StatusCode" : "401",
"StatusCode" : "Unauthorized",
"ResourceID" : "waggle.modules.realm.InvalidLogin",
"ResourceMessage" : "Login required."
}

Exception Response Fields

Field Description
statusCode The HTTP status code.
statusMessage The HTTP status message.
exceptionID The exception ID.
exceptionClass The exception class.
exceptionMessage The exception message.
exceptionDate The exception date.

Collaboration Resource

Use the Collaboration resource API endpoints to interact with your cloud resources that enable real-time collaboration between individuals and teams and connect your business processes, enterprise applications, and content.

With the Collaboration resource, you can manage these objects:

  • Conversations

  • Members of conversations (direct and indirect)

  • Documents associated with conversations

  • Messages and replies to messages in conversations

  • Followups on messages for users

  • Applinks and hybrid links for conversations

  • Inbound mail tokens

  • Properties and user properties of conversations

  • Likes for conversations and messages

  • Stars for conversations and messages

Also, you can list folder IDs that have associated conversations.

For endpoint descriptions and examples, see "Collaboration" in REST API for Conversations.

Configuration Resource for Conversations

Use the Configuration resource API endpoints to configure resources and services.

With the Configuration resource, you can manage these configuration properties:

  • hasMore

  • items

  • nextURL

  • previousURL

  • total (number of available items)

For endpoint descriptions and examples, see "Configuration" in REST API for Conversations.

Security Resource

Use the Security resource API endpoints to manage connections and access.

With the Security resource, you can manage connections for users and conversations.

For endpoint descriptions and examples, see "Security" in REST API for Conversations.

Social Resource

Use the API endpoints of the Social resource to help users mark favorite conversations and documents and collaborate with each other.

With the Social resource, you can manage followups and stars for users.

To manage collaboration for other users, you need to have a dedicated "Integration User" role. See Functionality Provided Through User Roles in Administering Oracle Content and Experience.

For endpoint descriptions and examples, see "Social" in REST API for Conversations.