1. Service Cloud Chat REST APIREST API for Chat in B2C Service
  2. Reference
  3. About Establish Sessions

About Establish Sessions

A typical chat app in Oracle B2C Service leverages the functionality of the various REST API operations documented in this guide. The chat app uses establishSessions, a REST endpoint in Oracle B2C Service to initiate a session and fetch the JSON Web Token (JWT) that is needed for authentication. Let's walk through the establish session flow:

  1. The chat app makes a POST REST request to the Oracle B2C Service establishSessions endpoint using Basic authentication.
  2. EstablishSessions generates the JWT and sends it to the chat session server for authentication.
  3. The chat session server validates and stores the JWT. It then returns the JWT and the session information to establishSessions.
  4. This JWT and session information is sent back to the chat app in the REST response of the establishSessions call.

Here's the URI for the establishSessions endpoint in Oracle B2C Service: 

/services/rest/crossChannelServices/latest/establishSessions

Supported Attributes

This table describes the attributes that can be specified in the establishSessions request body. You need to define these attributes inside the sessionInformation attribute in the request body.

Request Attributes Data Type Description Required/Optional
firstName String The first name of the customer. Optional
lastName String The last name of the customer. Optional
emailAddress String The email address of the customer. Optional
queueId Long The ID of the queue to which the customer is assigned. Optional
contactId Long The contact ID of the customer. Optional
organizationId Long The organization ID of the customer. Optional
productId Long The product ID associated with the customer's question. Optional
categoryId Long The category associated with the customer's question. Optional
incidentId Long The unique identifier for an existing incident. Optional
question String The question asked by the customer. Optional
auxillaryData Map A map of key-value pairs containing the browser, operating system, and user agent information of the end user. The following are the permitted keys:
  • BROWSER - The corresponding value indicates the browser used by the end user.
  • OPERATING_SYSTEM - The corresponding value indicates the operating system used by the end user.
  • USER_AGENT - The corresponding value indicates the user agent of the browser used to make the HTTP request.
  • ASYNC_REQUEST_ID - The identifier returned in the agent renewEngagement response so that this engagement gets assigned to a specific agent.

For example:

"auxiliaryData" : {
	"BROWSER" : "Mobile Safari 11.0",
	"OPERATING_SYSTEM" : "iPhone OS",
	"USER_AGENT" : "Mozilla/5.0 (iPhone; CPU iPhone OS 11_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/11.0 Mobile/15E148 Safari/604.1",
	"ASYNC_REQUEST_ID" : "1540987BYEF"
}
Optional
customFields String Array An array of custom fields that is passed by the customer. For example:
"customFields": [
     {"name":"inventoryItemId","id":999994000663239},
     {"name":"inventoryOrgId","id":204},
     {"name":"prodGroupId","id":109876540066008},
     {"name": "incidentName","type": "STRING","value": "SR0000256971"},
     {"name": "incidentType","type": "STRING","value": "SVC_SERVICE_REQUESTS"}
     ]
 Optional

Supported Request Headers

The required request headers for the establishSessions call are:

  • Authorization - This HTTP header is used to specify the Basic authentication credentials for the request.
  • OSvC-CREST-Application-Context - This HTTP header is used to add comments to REST API requests in Oracle B2C Service. The Application Context information can be viewed from the PAPI Meters Debug Log report. This report is available in the Reports Explorer at \Public Reports\Common\Site Administration\Public API. The maximum text length is 40 characters. If you provide more than 40 characters, then a Bad-Request error occurs.

Sample Payloads

Here's an example of the REST request body for the establishSessions call: 

{
 "sessionInformation": "{
 \"emailAddress\" : \"john.smith@vision.com\", 
 \"firstName\" : \"John\",
 \"lastName\": \"Smith\", 
 \"question\" : \"Refunds Issues\",
 \"customFields\" : [{\"name\" : \"location\", \"type\" : \"string\", \"value\" : \"401 Island Parkway Redwood Shores CA 94065 USA\"}], 
 \"auxiliaryData\" : {
	 \"BROWSER\" : \"Mobile Safari 11.0\", 
	 \"OPERATING_SYSTEM\" : \"iPhone OS\", 
	 \"USER_AGENT\" : \"Mozilla/5.0 (iPhone; CPU iPhone OS 11_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/11.0 Mobile/15E148 Safari/604.1\"
	} 
  }"
 }

The following is an example of the REST response body for the establishSessions call: 

{
"channelToken": "eyJhbGciOiJSU...Wst7gbQ6Nqs",
    "sessionServerResponse": "{\"domain\":\"chat_rest_server_domain.com\" ,\"pool\":\"297:1\"}",
    "siteName": "day119_181100_sql_238h",
    "links": [
        {
            "rel": "describedby",
            "href": "https://service_cloud_server.com/services/rest/crossChannelServices/latest/metadata-catalog/establishSessions",
            "mediaType": "application/schema+json"
        }
    ]
}