Customer Service API Usage

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
        }
      ]
    }
  }
}

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.

Configuring Case Classifications

To use the case classification route of the Customer Service API, you first need to create an appropriate configuration. This configuration holds:

  • The list of fields for which to provide suggestions (fieldsToPredict).

  • A filter query expression that restricts the items on which to base the field value suggestions. For example, a filter value of @objecttype==case will ensure that the user only receives field value suggestions from indexed items with an objecttype field value of case.

  • The classification strategy. The only strategy currently available is Some, which leverages the $some query extension to retrieve relevant field value suggestions.

Use the POST /rest/organizations/{organizationId}/caseassists endpoint to create your configuration. You can also modify an existing configuration using the PUT /rest/organizations/{organizationId}/caseassists/{caseAssistId} endpoint.

Authenticate your request using an access token that grants the Customer Service - Case Assist Configuration - Edit privilege.

EXAMPLE

You create a case classification configuration by making the following request to the Customer Service API:

POST https://platform.cloud.coveo.com/rest/organizations/myorganizationid9sd8df7s/caseassists HTTP/1.1
Authorization: Bearer ********-****-****-************

Payload:

{
  "name": "My case classification configurations",
  "classificationConfigurations": [
    {
      "strategy": "Some",
      "fieldsToPredict": [{"name": "opportunitytype"}, {"name": "issuetype"}],
      "filter": "@objecttype==case AND @sfstatus==completed"
    }
  ]
}

To use a case classification configuration, you must retrieve its ID. Use the GET /rest/organizations/{organizationId}/caseassists endpoint to do so.

Authenticate your request using an access token with the Customer Service - Case Assist Configuration - View privilege.

EXAMPLE
GET https://platform.cloud.coveo.com/rest/organizations/myorganizationid9sd8df7s/caseassists HTTP/1.1
Authorization: Bearer ********-****-****-************

The API returns the following payload:

{
  "configurations": [
    {
      "id": "myc45ea55-isti-d9d5-8f1d-81be8e739b70",
      "name": "My case classification configuration",
      "classificationConfigurations": [
        {
          "filter": "@objecttype==case AND @sfstatus==completed",
          "fieldsToPredict": [
            {
              "name": "opportunitytype",
              "name": "issuetype"
            }
          ],
          "strategy": "Some"
         }
      ]
    }
  ],
  "totalEntries": 1,
  "totalPages": 1
}

You locate the target configuration in the response and store its id value (myc45ea55-isti-d9d5-8f1d-81be8e739b70) for use in future requests.

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 (e.g., {"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 (e.g., c1i3n4v1-s1t0-rid9-8f1d-81be8e739b70).

Furthermore, we recommend that you pass the interface’s language tag in the locale parameter (e.g., 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.

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.

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
        }
      ]
    },
    "issuetype": {
      "predictions": [
        {
          "value": "Ignition",
          "confidence": 0.8325673948382833
        },
        {
          "value": "Controller",
          "confidence": 0.5364940382730438
        }
      ]
    }
  }
}

Since the confidence scores for the Propane and Controller 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",
      "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,
        ...
      }
    }
  ],
  "totalCount": 1
}

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

Configuring Document Suggestions

To use the document suggestions feature of the Customer Service API, you must first create an appropriate configuration. This configuration holds:

  • The suggestion strategy. The only strategy currently available is ITD, which leverages Intelligent Term Detection to retrieve document suggestions.

  • The name of a query pipeline to use to retrieve document suggestions. The query pipeline must support the strategy defined in the strategy parameter. For example, if you selected ITD as the strategy, you must provide the name of a pipeline that has an ITD-enabled Coveo ML ART model association.

  • A filter query expression that restricts the items from which to base document suggestions. For example, a filter value of @objecttype==Troubleshooting will ensure that the user only receives suggestions from indexed items with an objecttype field value of Troubleshooting.

Use the POST /rest/organizations/{organizationId}/caseassists endpoint to create your configuration. You can also modify an existing configuration using the PUT /rest/organizations/{organizationId}/caseassists/{caseAssistId} endpoint.

Authenticate your request using an access token that grants the Customer Service - Case Assist Configuration - Edit privilege.

EXAMPLE

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

POST https://platform.cloud.coveo.com/rest/organizations/myorganizationid9sd8df7s/caseassists HTTP/1.1
Authorization: Bearer ********-****-****-************

Payload:

{
  "name": "My document suggestions configuration",
  "documentSuggestionConfiguration": [
    {
      "strategy": "ITD",
      "pipeline": "myPipeline",
      "filter": "@objecttype==Troubleshooting"
    }
  ]
}

To use a document suggestions configuration, you must retrieve its ID. Use the GET /rest/organizations/{organizationId}/caseassists endpoint to do so.

Authenticate your request using an access token that grants the Customer Service - Case Assist Configuration - View privilege.

EXAMPLE

You retrieve your configurations by making the following request to the Customer Service API:

GET https://platform.cloud.coveo.com/rest/organizations/myorganizationid9sd8df7s/caseassists HTTP/1.1
Authorization: Bearer ********-****-****-************

The API returns the following payload:

{
  "configurations": [
    {
      "id": "812efd5e-a7e3-49d5-8f1d-81be8e739b70",
      "name": "My document suggestions configuration",
      "documentSuggestionConfiguration": [
        {
          "strategy": "ITD",
          "filter": "@objecttype==Troubleshooting",
          "pipeline": "myPipeline"
        }
      ]
    }
  ],
  "totalEntries": 1,
  "totalPages": 1
}

You locate the target configuration in the response and store its id value (812efd5e-a7e3-49d5-8f1d-81be8e739b70) for use in future requests.

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 (e.g., {"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 (e.g., c1i3n4v1-s1t0-rid9-8f1d-81be8e739b70).

Furthermore, we recommend that you pass the interface’s language tag in the locale parameter (e.g., 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.

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.

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" }
  },
  "locale": "en-US"
}

The API returns the following payload:

{
  "documents": [
    {
      "title": "GC3000 Series Propane Generator Ignition",
      "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",
      "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,
        ...
      }
    }
  ],
  "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

  • Perform the operation again using an exponential backoff.

  • Monitor the status of the Coveo Platform from https://status.cloud.coveo.com.

  • Write down the X-Request-ID.

  • If the situation persists, Contact us.

503

SERVER UNAVAILABLE

Internal error


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