Customer Service API usage

This is for:

Developer

In this article

Case Classification
Document Suggestion
Error handling
What’s next?

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.

Note

All REST API string fields are case-sensitive unless otherwise specified. For example, search queries aren’t case-sensitive.

To keep behavior consistent across the Coveo Platform, the same value passed to different REST APIs must always be passed using the same case. For example, if the unique product identifier, such as ec_product_id, is passed to the Commerce API in lowercase, then it should also be passed to the Usage Analytics Write API in lowercase.

Case Classification

The Customer Service API Case Classification feature lets you 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 Suggestion

The Customer Service API Document Suggestion 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

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).

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

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

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	Perform the operation again using an exponential backoff. Monitor the status of Coveo from the Coveo Service Status page. Write down the `X-Request-ID`. If the situation persists, contact Coveo Support.
`503`	`SERVER UNAVAILABLE`	Internal error	Perform the operation again using an exponential backoff. Monitor the status of Coveo from the Coveo Service Status page. If the situation persists, contact Coveo Support.

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

Perform the operation again using an exponential backoff.
Monitor the status of Coveo from the Coveo Service Status page.
Write down the X-Request-ID.
If the situation persists, contact Coveo Support.

503

SERVER UNAVAILABLE

Internal error

Perform the operation again using an exponential backoff.
Monitor the status of Coveo from the Coveo Service Status page.
If the situation persists, contact Coveo Support.

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.