1. Engagement Cloud Chat REST APIREST API for Chat in Oracle Fusion Service
  2. Quick Start

Quick Start

You can make many types of HTTP requests using Fusion Applications APIs. You can easily make requests to view, create, update, or delete information. So, let's first send a REST HTTP request to create a chat engagement.

Step 1: Consider Before You Start

Review the basics. If you're new to REST APIs, make sure you understand the basics of REST and JSON, and scan our list of important terms.

Review roles and privileges: You must have the necessary security roles and privileges to use the GET, POST, PATCH, and DELETE methods on your parent and child resources.

Review opt-in requirements. Some resources of their attributes may be associated with features that require opt-in before you can use them. You must make sure that you enable opt-in features before you start.

Choose a REST client. REST APIs connect software programs over the HTTP protocol. You need a software client to send the HTTP requests. In our examples, we use cURL. But, cURL isn't the only tool you can use. To help you choose one, see Work with your REST Client.

Step 2: Get Your Fusion Applications Account Info

To make a REST HTTP request, you need to gather a few bits of information:

  • REST Server URL. The server on which the chatAuthenticate endpoint is hosted. For example: 
    https://servername.fa.us2.oraclecloud.com
  • User name and password. An Oracle Cloud service user with permissions to access the chatAuthenticate endpoint.

You can find the REST Server URL, user name, and password in the welcome email sent to your Oracle Cloud service administrator.

Step 3: Authenticate

For creating a chat engagement, you need a JSON Web Token (JWT) for authentication. You need to specify this JWT as a Bearer Authorization header in your request to create a chat engagement.

You can determine this JWT by invoking the chatAuthenticate endpoint in Engagement Cloud using the Basic Authorization header to specify the credentials (from Step 2). The JWT is returned in the response of the chatAuthenticate call. To know more about the chatAuthenticate endpoint, see About Chat Authenticate.

The chatAuthenticate response also returns the following values that are required in the request for creating a chat engagement:

  • Domain. The domain URL of your Oracle Fusion Service Chat service. For example, https://chat_rest_server_domain.com.
  • Site Name. The fully qualified name of the site returned in the response of the chatAuthenticate call.
  • Port. The port value is returned only if the port is not a default port, such as 80 or 443.
  • Pool ID. The pool ID that is configured for the site. The pool ID indicates the ID of the cluster where the chat service is running. Oracle may alter the pool ID during scheduled/un-scheduled maintenance.

The cURL command to call chatAuthenticate and retrieve the JWT is as follows: 

curl -X POST "https://servername.fa.us2.oraclecloud.com/serviceApi/resources/11.13.0.0/chatAuthenticate" -H "Accept: application/json" -H "Accept-Language: en_US" -H "Authorization: Basic ZGNzYWRtaW4xOldlbGNvbWUx" -H "Content-Type: application/vnd.oracle.adf.resourceitem+json" -d "{\"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}"

Note:

  • The user name and password are encoded in Base64 format and specified using the Basic Authorization header in the cURL command as seen in the preceding example. Alternatively, you can use the -u cURL option to pass the user name and password. The syntax is -u username:password.
  • The user metadata is specified using -d option in the cURL command.

In a REST API client such as Postman, you enter the user name and password in the Authorization tab. This screenshot shows how to specify this information in Postman:

Postman example with basic authentication, user name, and password.

If the authentication is successful, the JWT, domain, site name, port, and pool ID are returned, as applicable, in the response as follows:

{
    "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": "eyJhbGciOiJSUz...tr0Cw5qyvZMd64fyCA",
    "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,
    "mediaList": 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"
        }
    ]
}

Step 4: Configure Your Client

With the information gathered so far, you're ready to configure your client to send a REST HTTP request.

  1. Construct the request URL. The URL consists of the domain name and the endpoint path: 
    https://<domain>/<endpoint-path>

    The <domain> is the REST server domain from Step 3, as in: 

    https://chat_rest_server_domain.com

    The <endpoint-path> is the relative path to the REST endpoint you're working with. You can pick any endpoint in All REST Endpoints. For example, we're interested in the requestEngagement endpoint: 

    /engagement/api/consumer/{fqSiteName}/v1/requestEngagement

    Where fqSiteName value is 'sdi_11_20_18_2022_21-3586727808788512-Fusion' as determined in Step 3.

    Combine the domain name and, in this example, the requestEngagement REST endpoint path and your request URL is complete. For more information, see URL Path. 

    https://chat_rest_server_domain.com/engagement/api/consumer/sdi_11_20_18_2022_21-3586727808788512-Fusion/v1/requestEngagement
  2. Determine the HTTP verb. The HTTP verb depends on the type of CRUD operation you are going to perform. In this case, the HTTP verb will be POST as we are going to create a chat engagement.
  3. Set the media type. Media type defines the structure of the HTTP payloads exchanged between the server and the client. If you're using cURL, you can specify a media type using the header -H option. In this case, as it is a POST request, the media type will be application/json. For more on media types, see Supported Media Types.
  4. Specify the request body. Use the -d option to specify the request body as follows: 
    -d "{\"clientRequestTime\" : \"2019-01-14T14:35:14.226Z\",\"clientTransactionId\" : 1}"
  5. Provide the pool ID. Include the pool ID value (from Step 3) as follows: 
    https://chat_rest_server_domain.com/engagement/api/consumer/sdi_11_20_18_2022_21-3586727808788512-Fusion/v1/requestEngagement?pool=353:2

When you're done, the complete cURL command should look like this:

curl -X POST "https://chat_rest_server_domain.com/engagement/api/consumer/sdi_11_20_18_2022_21-3586727808788512-Fusion/v1/requestEngagement?pool=353:2" -H "Accept: application/json;charset=utf-8" -H "Content-Type: application/json;charset=utf-8" -d "{\"clientRequestTime\" : \"2019-01-14T14:35:14.226Z\",\"clientTransactionId\" : 1}"

If you're not familiar with any of the syntax used in the example, check out Work with your REST Client.

If you're an advanced REST user, but are reading our Quick Start anyway, you might want to Configure Cross-Origin Resource Sharing now. Otherwise, you're ready to move on to Step 5.

Step 5: Authorize

Now that you've configured the client with a complete request URL and fetched the authentication JWT, you can proceed to authorization. While authentication proves that your credentials are genuine, authorization allows you to apply your access privileges.

To get authorized access to create a chat engagement, you need to include the JWT from Step 3 in your request using the Bearer Authorization header, as follows: 

curl -X POST "https://chat_rest_server_domain.com/engagement/api/consumer/sdi_11_20_18_2022_21-3586727808788512-Fusion/v1/requestEngagement?pool=353:2" -H "Accept: application/json;charset=utf-8" -H "Authorization: Bearer eyJhbGciOiJSUz...tr0Cw5qyvZMd64fyCA" -H "Content-Type: application/json;charset=utf-8" -d "{\"clientRequestTime\" : \"2019-01-14T14:35:14.226Z\",\"clientTransactionId\" : 1}"

In a client such as Postman, you specify the JWT as a Bearer Authorization Header. This screenshot shows how to specify this information in Postman:

Passing of the authorization and authentication information in Postman.

Step 6: Send an HTTP Request

You're almost done. Now that your authentication and authorization are set, you're ready to send a test HTTP request. Continuing with our example, we want to create a chat engagement. You can do this using the following command in cURL:

curl -X POST "https://chat_rest_server_domain.com/engagement/api/consumer/sdi_11_20_18_2022_21-3586727808788512-Fusion/v1/requestEngagement?pool=353:2" -H "Accept: application/json;charset=utf-8" -H "Authorization: Bearer eyJhbGciOiJSUz...tr0Cw5qyvZMd64fyCA" -H "Content-Type: application/json;charset=utf-8" -d "{\"clientRequestTime\" : \"2019-01-14T14:35:14.226Z\",\"clientTransactionId\" : 1}"

This is how the request looks in Postman:

Example of a request in Postman

If your request to create a chat engagement is successful, you receive a response with a body similar to the following example. If your request fails, and you're using cURL, review the response comments, adjust your request, and then try again. If you're using other clients, review the failure Status Codes, and then try again. 

{
    "engagementId": 226,
    "engagementIdString": "226",
    "cancelledSurveyId": 0,
    "cancelledSurveyIdString": "0",
    "completedSurveyId": 0,
    "completedSurveyIdString": "0",
    "cancelledSurveyAuth": "",
    "completedSurveyAuth": "",
    "resultType": "SUCCESS",
    "sessionId": "170c233dfi4gy1vkwyw6yxdq1a",
    "sneakPreviewState": "DISABLED",
    "sneakPreviewInterval": 3000,
    "clientRequestTime": "2019-01-14T14:35:14.226Z",
    "clientTransactionId": 1,
    "clientTransactionIdString": "1",
    "serviceStartTime": "2019-01-11T10:12:13.175Z",
    "serviceFinishTime": "2019-01-11T10:12:13.298Z",
    "clientId": 246,
    "clientIdString": "246"
}

In a client such as Postman, the results are formatted and displayed in the Response section. For example, Postman lets you view the output in multiple formats. This screenshot shows the response in JSON.

Example of a response in Postman

Congratulations! Now you're ready to do more with your REST APIs.