Customer Service API Usage

This is for:

Developer

This topic explains how to request case classifications and document suggestions, for the field filling and document suggestion stages of the Case Assist workflow, respectively.

Case Assist event flow

Case Classification

The Customer Service API case classification route allows you to request field value suggestions to help your end users and support agents as they create support cases.

Example

A client is creating a support case with the title GC110 malfunction and the description My GC110 electrical panel is cutting off intermittently. You have previously created a case classification configuration to request suggestions for the type of issues that your end users create.

You make the following request to the Customer Service API:

POST https://platform.cloud.coveo.com/rest/organizations/myorganizationid9sd8df7s/caseassists/myc45ea55-isti-d9d5-8f1d-81be8e739b70/classify HTTP/1.1
Authorization: Bearer ********-****-****-************

Payload:

{
  "visitorId": "04850f2-ee0d-47a9-aff5-39ee47f294f9",
  "fields": {
    "subject": { "value": "GC110 malfunction" },
    "description": { "value": "My GC110 electrical panel is cutting off intermittently" }
  }
}

The API returns the following payload:

{
  "fields": {
    "sftype": {
      "predictions": [
        {
          "value": "Electrical",
          "confidence": 0.9180843234062195,
          "id": "8c02099b-a227-46c4-aad1-46468e59e6c7"
        }
      ]
    }
  },
  "responseId": "123e4567-e89b-12d3-a456-426614174000"
}

You then suggest the field value Electrical issue to your client in your custom UI widget. This narrows down the options that they have to choose from and simplifies their case creation experience.

Retrieving Case Classifications

To retrieve meaningful suggestions from the Customer Service API, you need to provide meaningful field values in your requests. Typically, you’ll want to retrieve the subject and description of the case being created, and provide them as objects in the fields parameter of your request payload (for example, {"subject": { "value": "GC3000 won’t start" }, "description": { "value" : "My GC3000 series propane generator won’t start"} }).

You must also pass the user’s visitor ID[1] in the visitorId parameter (for example, c1i3n4v1-s1t0-rid9-8f1d-81be8e739b70).

Furthermore, we recommend that you pass the interface’s language tag in the locale parameter (for example, en-US).

Although the API doesn’t currently leverage the visitorId and locale parameters, it will soon use them to log {usage analytics events} and personalize suggestions.

For debugging purposes, you can set the debug query parameter to true to retrieve a detailed execution report. Avoid setting this parameter to true in production, as it has a negative impact on performance.

Use the PUT /rest/organizations/{organizationId}/caseassists/{caseAssistId}/classify endpoint and authenticate your request using an access token that grants the Customer Service - Use case assist - Allowed privilege.

You can retrieve the target caseAssistId from the Coveo Administration Console.

For each field targeted in your configuration, the API response includes a list of predictions, sorted by confidence value.

Example

A customer is creating a case with the title GC3000 won’t start and the description My GC3000 series propane generator won’t start. You retrieve the customer’s visitor ID from the visitor cookie.

You request case classifications by making the following request to the Customer Service API:

POST https://platform.cloud.coveo.com/rest/organizations/myorganizationid9sd8df7s/caseassists/myc45ea55-isti-d9d5-8f1d-81be8e739b70/classify HTTP/1.1
Authorization: Bearer ********-****-****-************

Payload:

{
  "visitorId": "c1i3n4v1-s1t0-rid9-8f1d-81be8e739b70",
  "fields": {
    "subject": { "value": "GC3000 won't start" },
    "description": { "value": "My GC3000 series propane generator won't start" }
  },
  "locale": "en-US"
}

The API returns the following response:

{
  "fields": {
    "opportunitytype": {
      "predictions": [
        {
          "value": "Propane",
          "confidence": 0.9178082346916199,
          "id": "aa24b08a-0ae5-5624-966b-d687cb37f045"
        }
      ]
    },
    "issuetype": {
      "predictions": [
        {
          "value": "Ignition",
          "confidence": 0.8325673948382833,
          "id": "7d25db2a-5a9f-5bb7-bfc9-5e9e59063077"
        },
        {
          "value": "Controller",
          "confidence": 0.5364940382730438,
          "id": "72a7b604-804b-5b29-a0da-ca0672741e3b"
        }
      ]
    }
  },
  "responseId": "123e4567-e89b-12d3-a456-426614174000"
}

Since the confidence scores for the Propane and Ignition predictions are fairly high, you suggest them to your customer in the Product and Issue type fields of your case creation interface.

Document Suggestions

The Customer Service API document suggestions feature lets you suggest documents to end users and support agents as they create support cases.

Example

A client is creating a support case with the title GC110 malfunction and the description My GC110 electrical panel is cutting off intermittently. You have previously created a document suggestions configuration to request suggestions for the type of issues that your end users create.

You make the following request to the Customer Service API:

POST https://platform.cloud.coveo.com/rest/organizations/myorganizationid9sd8df7s/caseassists/myc45ea55-isti-d9d5-8f1d-81be8e739b70/documents/suggest HTTP/1.1
Authorization: Bearer ********-****-****-************

Payload:

{
  "visitorId": "04850f2-ee0d-47a9-aff5-39ee47f294f9",
  "fields": {
    "subject": { "value": "GC110 malfunction" },
    "description": { "value": "My GC110 electrical panel is cutting off intermittently" }
  }
}

The API returns the following payload:

{
  "documents": [
    {
      "title": "GC110 Series Electrical Panel Troubleshooting",
      "uniqueId": "84.72597$https://na174.salesforce.com/5017g000000vLFgBCM:2",
      "hasHtmlVersion": true,
      "clickUri": "https://na174.salesforce.com/5017g000000vLFgBCM",
      "excerpt": "The GC110 series electrical panel needs to be reset using the following process if it begins to turn on and off without warnin...",
      "fields": {
        "syssfcreatedbyid": "0056g001172vCuBMAU",
        "sfsystemmodstamp": 1578952955001,
        ...
      }
    }
  ],
  "responseId": "2394cnd8-8dnc-3nc9-k432-9dn2nd8f93nd",
  "totalCount": 1
}

You then suggest that solution item to the client before they even finish creating their case, resulting in case deflection!

Retrieving Document Suggestions

To retrieve meaningful suggestions from the Customer Service API, you need to provide meaningful field values in your requests. Typically, you’ll want to retrieve the subject and description of the case being created, and provide them as objects in the fields parameter of your request payload (for example, {"subject": { "value": "GC3000 won’t start" }, "description": { "value" : "My GC3000 series propane generator won’t start"} }).

You must also pass the user’s visitor ID[2] in the visitorId parameter (for example, c1i3n4v1-s1t0-rid9-8f1d-81be8e739b70).

Furthermore, we recommend that you pass the interface’s language tag in the locale parameter (for example, en-US).

Although the API doesn’t currently leverage the visitorId and locale parameters, it will soon use them to log {usage analytics events} and personalize suggestions.

Optionally, you can pass context information in the context parameter of your request payload (for example, { "product": "Propane Generator", "subproduct": "GC3000 Series" }). Doing so would allow you to leverage this context information in your query pipeline (see Manage ranking expression rules and Manage query pipeline conditions).

For debugging purposes, you can set the debug query parameter to true to retrieve a detailed execution report. Avoid setting this parameter to true in production, as it has a negative impact on performance.

Use the PUT /rest/organizations/{organizationId}/caseassists/{caseAssistId}/documents/suggest endpoint and authenticate your request using an access token that grants the Customer Service - Use case assist - Allowed privilege.

You can retrieve the target caseAssistId from the Coveo Administration Console.

The API response includes a list of documents, which each includes the document title, clickuri, excerpt, and raw fields.

Example

A customer is creating a case with the title GC3000 won’t start and the description My GC3000 series propane generator won’t start. You retrieve the customer’s visitor ID from the visitor cookie.

You request document suggestions by making the following request to the Customer Service API:

POST https://platform.cloud.coveo.com/rest/organizations/myorganizationid9sd8df7s/caseassists/myc45ea55-isti-d9d5-8f1d-81be8e739b70/documents/suggest HTTP/1.1
Authorization: Bearer ********-****-****-************

Payload:

{
  "visitorId": "c1i3n4v1-s1t0-rid9-8f1d-81be8e739b70",
  "fields": {
    "subject": { "value": "GC3000 won't start" },
    "description": { "value": "My GC3000 series propane generator won't start" }
  },
  "context": { "product": "Propane Generator", "subproduct": "GC3000 Series" },
  "locale": "en-US"
}

The API returns the following payload:

{
  "documents": [
    {
      "title": "GC3000 Series Propane Generator Ignition",
      "uniqueId": "84.72597$https://na174.salesforce.com/5016g000000vLFgAAM:2",
      "hasHtmlVersion": true,
      "clickUri": "https://na174.salesforce.com/5016g000000vLFgAAM",
      "excerpt": "The GC3000 series propane generators need to be started up using the following process if the ignition fails on the first try: 1) Disengage the fuel source. ... 2) Use the vacuum pump provided to s...",
      "fields": {
        "syssfcreatedbyid": "0056g000002vBuCAAU",
        "sfsystemmodstamp": 1578952955000,
        ...
      }
    },
    {
      "title": "Selecting the Right Generator for Your Needs",
      "uniqueId": "84.392832$https://na174.salesforce.com/5016g000000vLFfAAM:1",
      "hasHtmlVersion": true,
      "clickUri": "https://na174.salesforce.com/5016g000000vLFfAAM",
      "excerpt": "GenWatt offers a wide range of electric generators for every need -- from high-powered industrial-strength generators, to medium-capacity standby generators, to emergency-use portable generators.",
      "fields": {
        "syssfcreatedbyid": "0056g000002vBuCAAU",
        "sfsystemmodstamp": 1578952955000,
        ...
      }
    }
  ],
  "responseId": "2394cnd8-8dnc-3nc9-k432-9dn2nd8f93nd",
  "totalCount": 2
}

You can then retrieve these document suggestions and display them in your user case creation interface to hopefully deflect the case creation.

Error Handling

You must handle Coveo errors properly if you experience network issues or unexpected downtime.

This table lists the most common errors.

HTTP Status Description Possible Causes Retry Strategy

400

BAD REQUEST

  • Request body doesn’t respect expected format

  • Missing parameter

Not applicable

401

UNAUTHORIZED

  • Authentication token is invalid

  • Missing authentication

Not applicable

403

FORBIDDEN

  • Missing privilege

  • Missing feature flag

Not applicable

404

NOT FOUND

The resource doesn’t exist.

Not applicable

429

TOO MANY REQUESTS

Too many requests were sent within a specified amount of time.

Invoke the request again using an exponential backoff.

Note: Check the value of the Retry-after header before invoking the request again.

500

INTERNAL SERVER ERROR

Internal error

503

SERVER UNAVAILABLE

Internal error

What’s Next

As your users interact with your Case Assist interface, you’ll want to log Case Assist events.

1. You can typically retrieve the visitor ID from the visitor cookie.
2. You can typically retrieve the visitor ID from the visitor cookie.