1. Engagement Cloud Chat REST APIREST API for Chat in Oracle Fusion Service
  2. Reference
  3. About Chat Authenticate

About Chat Authenticate

The chatAuthenticate endpoint is invoked by the Digital Customer Service (DCS) when a logged-in DCS user initiates a new conversation with a Fusion agent. DCS is an offering within Chat for B2B Service that provides its customers the ability to provide customer service through digital channels - from websites, email messages, to online chat.

The chatAuthenticate endpoint authenticates an agent on the Oracle Service Cloud (OSvC) Chat Server and return a JSON response containing a JSON Web Token (JWT). This JWT is then used by DCS in the requestEngagement call to OSvC Chat Server. The chatAuthenticate endpoint is called using a POST HTTP request.

Here's the URI for the chatAuthenticate endpoint is as follows: 

/serviceApi/resources/11.13.0.0/chatAuthenticate

The chatAuthenticate endpoint is protected by the entitlement SVC_REQUEST_FOR_CHAT_PRIV and can be called only by DCS authenticated users assigned to the ORA_SVC_CUSTOMER_SELF_SERVICE_USER_ABSTRACT role.

Supported Attributes

The following table describes the attributes that can be specified in the chatAuthenticate request body.

Request Attribute Data Type Description Required/Optional
clientType String The type of REST API provided by the Chat Service. If null, it defaults to 'CONSUMER'. Optional
authUserName String The unique identifier of the logged-in DCS user. This field is passed to the Chat Service in the JWT payload and is used as a key by the Chat Service. Required
contactId Long The PARTY_ID of the logged-in DCS user in the FUSION.HZ_PARTIES table where PARTY_TYPE = 'PERSON'. Optional
emailAddress String The email address of the logged-in DCS user. Optional
firstName String The first name of the logged-in DCS user. Optional
lastName String The last name of the logged-in DCS user. Optional
organizationId Long The PARTY_ID of the logged-in DCS user in the FUSION.HZ_PARTIES table where PARTY_TYPE = 'ORGANIZATION'. Optional
question String The initial question asked by the logged-in DCS user. Optional
queueId Long The unique identifier of the queue. For versions R13.17.11 and lower, the value is always set to '1'. For versions higher than R13.17.11, the value is set by the Fusion code. When this value is set by the Fusion code depends on the SVC_CHAT_WAIT_TIME_ENABLED profile option. If the value of this profile option is 'No' then it is set during the 'chatAuthenticate' call. If the value of this profile option is 'Yes' it is set during the 'requestEngagement' call. Optional
interfaceId Long The unique identifier of the Chat service interface. For versions before R13.18.05 it is always '1'. From R13.18.05 onwards, any value is overwritten by the Fusion code. Required
resumeType String Indicates whether the chat session should be resumed or not. The only accepted value is 'RESUME'. Optional
categoryId Long The CATEGORY_ID in the FUSION.SVC_CATEGORIES table related to the question posted by the logged-in DCS user. Optional
incidentId Long The unique identifier of an entity related to the interaction, such as product, service request, sales opportunity, and so on. This attribute is not used. Optional
productId Long The unique identifier of the product. This attribute is not used. Optional
incidentName String The SR_ID in the FUSION.SVC_SERVICE_REQUESTS table. Optional
incidentType String The code for the incident type. The value is 'SVC_SERVICE_REQUESTS'. Optional
inventoryItemId String The unique identifier of the inventory item. It is used along with inventoryOrgId and prodGroupId to identify the product. This is the INVENTORY_ITEM_ID of the product in the EGP_ITEM_ORG_ASSOCIATIONS table. Optional
inventoryOrgId String The unique identifier of the inventory organization. It is used along with inventoryItemId and prodGroupId to identify the product. This is the INVENTORY_ORG_ID of the product in the EGP_ITEM_ORG_ASSOCIATIONS table. Optional
prodGroupId String The unique identifier of the product group. It is used along with inventoryOrgId and inventoryItemId to identify the product. This is the PROD_GROUP_ID in FUSION.QSC_PROD_GROUPS table. Optional
businessUnitOrgId String The organization ID of the business unit associated with the engagement. This attribute is available from 11.13.19.01.0. Optional
chatPriority String The priority of the engagement which is used by the routing mechanism to determine the order in which it assigns engagements to agents. This attribute is available from 11.13.19.07.0. Optional
stripeCode String The application to which the interaction belongs, such as CRM, HRHD, or ISR. Optional
incidentSeverityCode String The lookup code for the severity of the entity related to the interaction, such as service request, sales opportunity, and so on. Optional
customFields String A JSON string that contains Custom Fields key-value pairs to be used to assign this interaction. Optional
assigneeId String The unique identifier of the resource being proposed is assigned to this interaction. Optional
applicationClassification String The application classification such as Sales or Service. Optional
allowAgentAttachments String When set to true, it indicates that the agent is allowed to attach files to chat messages. Optional
escalationLevel String This is a level indicating if the interaction is escalated. By default, it is set to 0. If a chat is escalated from a digital assistant to a live agent, the escalation level will be set to 1. Optional
chatSource String Indicates where the chat was initiated, like WCFS, RW UI, or Facebook. Available from 11.13.24.10.0. Optional
chatDirection String Indicates who initiated the chat; this may be customer-initiated or agent-initiated chat. Available from 11.13.24.10.0. Optional

Supported Request Headers

The following are the required request headers for the chatAuthenticate call:

  • Authorization - This HTTP header is used to specify the Basic authentication credentials for the request. For example, Basic ZGNzYWRtaW4xOldlbGNvbWUx.
  • Content-Type - This HTTP header is used to indicate the media type of the resource. The value for this call is application/vnd.oracle.adf.resourceitem+json.
  • Accept-Language - This HTTP header advertises which languages the client is able to understand. For example, en-US.
  • Accept - This HTTP header advertises which content types, expressed as Multipurpose Internet Mail Extensions (MIME) types, the client is able to understand. The value for this call is application/json.

Sample Payloads

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

{
	\"clientType\" : \"CONSUMER\",
	\"authUserName\" : \"John Smith\",
	\"categoryId\" : null,
	\"contactId\" : null,
	\"emailAddress\" : \"john.smith@vision.com\",
	\"firstName\" : \"John\",
	\"lastName\" : \"Smith\",
	\"incidentId\" : null,
	\"organizationId\" : null,
	\"productId\" : null,
	\"question\" : \"Question\",
	\"queueId\" : \"2\",
	\"interfaceId\": \"1\",
	\"resumeType\": \"RESUME\",
	\"incidentName\": \"TestIncident\",
	\"incidentType\": \"SVC_SERVICE_REQUESTS\",
	\"inventoryItemId\": null,
	\"inventoryOrgId\": null,
	\"prodGroupId\": null,
	\"businessUnitOrgId\" : null
}

Here's an example of the REST response body for the chatAuthenticate call: 

{
    "authUserName": "John Smith",
    "categoryId": null,
    "chatSiteName": "sdi_11_20_18_2022_21-3586727808788512-Fusion",
    "clientType": "CONSUMER",
    "contactId": null,
    "domain": "chat_rest_server_domain.com",
    "emailAddress": "john.smith@vision.com",
    "firstName": "John",
    "incidentId": null,
    "interfaceId": "1",
    "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsIng1dCI6Ik9aOVBxbnotd0xraERLclQwSEhBVDFVWE1GQSIsImtpZCI6InRydXN0c2VydmljZSJ9.eyJleHAiOjE1NDc0NzY2MTgsInN1YiI6IkhhcmkgTSIsImF1ZCI6Imh0dHBzOi8vZGVuZHEtZnVzaW9uY2hhdC12aXAudXMub3JhY2xlLmNvbS9lbmdhZ2VtZW50L2FwaS9jb25zdW1lci9zZGlfMTFfMjBfMThfMjAyMl8yMS0zNTg2NzI3ODA4Nzg4NTEyLUZ1c2lvbiIsImlzcyI6IkZ1c2lvbiBBcHBzIiwicHJuIjoiSGFyaSBNIiwiaWF0IjoxNTQ3NDc2NDk4fQ.Qm2PTNP1ji0ay6MGLUTN-8_BCYH0bQ8MmxCOXSmQp8Hf6ljDJm0v5nNTr1ilk4geqe_kC8AmvQzVVXbQUE5dUgPYsiefs67XjDCdzTEfYIO3Wa7OQ0WHui-v7Mfa3xyIbkM9KsGhwVxyxDK-sPRRQLiXVpX_1L0yHn5ZfnioN_ISx_4xycusxHrftNSnzHBju4O09w72j0sP6M7IiwE-zEbKTPPDK-nS0RNSRuLD2Wo3n1KOifQpbB3YfE1i1bPMvsTkSHxkt5Je8Nmr1ReeH1wffuKAzNJJZku90rqe55GItwjWXDUpk96fVSQWEEXRk8DEtr0Cw5qyvZMd64fyCA",
    "lastName": "Smith",
    "organizationId": null,
    "poolId": "353:2",
    "productId": null,
    "question": "Question",
    "queueId": "2",
    "resumeType": "RESUME",
    "incidentName": "TestIncident",
    "incidentType": "SVC_SERVICE_REQUESTS",
    "inventoryItemId": null,
    "inventoryOrgId": null,
    "prodGroupId": null,
    "businessUnitOrgId": null
    "links": [
        {
            "rel": "self",
            "href": "https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.0.0/chatAuthenticate/John%20Smith",
            "name": "chatAuthenticate",
            "kind": "item"
        },
        {
            "rel": "canonical",
            "href": "https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.0.0/chatAuthenticate/John%20Smith",
            "name": "chatAuthenticate",
            "kind": "item"
        }
    ]
}