Purpose

You may have seen that Khoros Marketing has an integration with Salesforce. This integration is productized, available to all Care Module customers with a simple OAuth of your sandbox or production Salesforce accounts. In addition, to support for Salesforce, Khoros is thrilled to provide first-class support for CRM and Customer Engagement software not currently productized by Khoros.

Your company’s customers contact you via phone and email in addition to reaching out to you on social media, and the Khoros Marketing Custom CRM API Spec allows you to connect the social conversation together with that same customer’s conversation happening on non-social channels.

Read on – whether you are looking to implement a custom solution to enforce unique business requirements for your company or looking to connect to a CRM not yet supported by Khoros Marketing.

The Khoros Marketing Care Module offers an out-of-the-box integration with Salesforce that supports connecting customer records and sending social media interactions as a part of a Salesforce case. This API Spec allows for this same user experience to be replicated with other software beyond Salesforce.

If you have not yet seen a walkthrough of the productized workflow with Salesforce, we recommend it. The existing Salesforce integration could be illustrative for your development efforts, so please reach out to your Khoros account team to learn more.

CRM API Spec Overview

Khoros Marketing breaks down the customer experience into three primary objects: Customers, Interactions, and Cases.

• Customer (Jane Doe) object is an individual customer record in your system. The Customer object is manually linked to one or more social handles by a user in Khoros Marketing.
• The Interaction is any piece of content in a Khoros Marketing stream (be it a Tweet, a Facebook comment, an Instagram post, a review, or other communication), whether it is the customer’s own communication or the brand’s response on social media published from Khoros. This is the conversation between the customer and the user in Khoros Marketing (often a Customer Care Agent).
• The Case is the collection of interactions associated with one customer which represents a specific issue.

This post details the API Spec used to enable a custom integration. The goal of a custom integration to map these Khoros Marketing concepts into your own models and create the middleware necessary to connect to Khoros. To achieve this, a server must be stood up meeting the criteria described in the specification, and registered with Khoros. Once registered, the CRM can be used in the same way as any other CRM, configured to one or more Khoros initiatives. As a first-class citizen to Khoros, it will be completely transparent to Khoros Agents.

We invite you to:

• Review the CRM API Spec.
• Review this example implementation to Zendesk provided as an attachment below.

The rest of this blog post provides context with regards to each endpoint. We detail the use case for each endpoint, when each endpoint is used in workflow, and how frequently each endpoint would be called to give you more color for implementation.

Method

In general, each concept outlined above is mapped to the Create, Read, and Update methods of standard CRUD operations. The specification also defines a set of configuration endpoints to expose your data model, that is the fields and their data types for customers and cases. Additionally, there is a single public Khoros Marketing API endpoint to register a ready implementation which can be called manually via the Khoros Marketing API Explorer.

CONFIGURATION

Data Model - GET /api/v1/meta/object/<type> Khoros synchronizes the data model each time the Administration attempts to edit a given configuration. The expected types to synchronize are customer and case. For each type, the data returned should represent the fields and their datatypes available for the given object.

For the customer, the following fields are required:

• id - String - The unique identifier for the customer in your system. Khoros will use this to link to Social Identities and assign these Ids as the customerId in cases.

• uri - String - The URI to direct Khoros Marketing Agents to when clicking on a customer for more details in your system.
  For case, the following fields are required:

• id - String - the unique identifier of the case in your system. Khoros uses this internally to link individual interactions which an agent has added to a case, and when looking up details for a specific case.

• linkUrl - String - the URI to direct Khoros Marketing Agents to when clicking on a case for more details.

• created - String in ISO-8601 format - The date and time the case was created. Example: “2017-08-07T14:09:00Z”

These required fields plus any additional fields will be provided to the Khoros Marketing Admin to configure. The configuration consists of choosing which fields to display when giving summaries of a customer, and more importantly, which fields a Khoros Marketing Agent is expected to populate when creating new customers and cases.

The following field types are supported by Khoros:

• Text - a string field. Presented as a single-line text box on customer/case creation forms.
• Textarea - a string field. Presented as a multi-line text box on customer/case creation forms.
• Single_sel_list - a predetermined list of values, of which only one can be chosen. Presented as a dropdown on customer/case creation forms.
• Checkbox - a true/false value. Presented as a checkbox in customer/case creation forms.

In addition to the type, each field should be given a name which Khoros Marketing will use in JSON payloads to identify the field. The searchable boolean value indicates that the field can be populated when creating a customer or case, but when false, will be not be presented in customer search forms. The provided label is displayed to the Khoros Marketing Agent on all forms in place of the field’s name.

CUSTOMER

Customer Search - POST /api/v1/customers
Probably the most frequently hit endpoint is Customer search. Khoros will include in the post body every populated field formed by our best match algorithm or requested directly by the user via advanced search.

Customer Search (best match) - POST /api/v1/customer/bestmatch
When a Khoros Marketing Agent works in the context of a new customer, this endpoint will be called first in an attempt to find a matching customer given only the social context known by Khoros. Specifically this context includes the user’s handle, display name, and possibly the profiles URL, email, addresses, phone numbers and other information added by Spedfast Agents in the past.

Customer Lookup - GET /api/v1/customer/<id>
Khoros calls this endpoint when a Khoros Marketing Agent pulls up a social identity which has previously been linked to the given customer. The results should include every populated field based on the provided model.

Fetch customer cases - GET /api/v1/customer/<id>/cases
To separate concerns and make implementation easier, the fetch cases for a customer was given its own endpoint. This is also used by Khoros when details of the customer are already known by the UI state, but cases need to be updated.

Create customer - POST /api/v1/customer
Customer creation happens when a Khoros Agent cannot find an existing customer who matches the current social identity. As with Customer Search, the body contains only non-empty fields provided by the Spedfast Agent and enabled by the Khoros Admin.

Edit customer - PATCH /api/v1/customer/<id>
This endpoint is used when a Khoros Agent wants to update the information of an existing linked customer. The results should include every populated field based on the provided model.

CASE

Create Case - POST /api/v1/case
When a Khoros Marketing Agent creates a new case, this endpoint will be called. Same POST body criteria exist here as with Create Customer. Additionally, a list of interactions will be passed.

Lookup Case - GET /api/v1/case/<id>
Khoros will request the details of an individual case when a Khoros Marketing Agent starts an edit process on a Case.

Update a Case - PATCH /api/v1/case/<id>
When a Khoros Marketing Agent updates a case, this endpoint will be called. All valid fields for Create Case are also possible to update targets.

RETURN CODES AND ERROR HANDLING

The list below is a high-level overview of the complete set of return codes and payloads expected from the service. Not all codes are valid for every endpoint, please refer to the spec for details.

• 200 - Requested data is found and returned in the body
• 201 - Case or contact created successfully
• 400 - Invalid field in payload
• 401 - API key is invalid or has become de-authenticated
• 404 - contact or case not found
• 422 - Field validation error when creating a customer or case, or updating a case.
• Body should contain information on which fields are invalid and optionally a reason to display to the Khoros Agent
• 500 - unexpected error

The body should contain information relevant to debugging the service.

All errors passed back to Khoros should be in the following form:

If the error is related to a specific field, a 422 error code should be returned with the following payload:

fields Object

Appendix

CAVEATS

• Each /meta endpoint is allowed up to 20 seconds to resolve. If Khoros fails to receive a response within this time, an error is presented to the Spedfast Admin and the Admin will have to refresh the page to try again before being allowed to view or modify the configuration.
• All other endpoints must resolve within 8 seconds or an error will be thrown to the Khoros Marketing Agent. If Spedfast fails to receive a response, the Khoros Marketing Agents will receive an error. The specific error depends on the endpoint being called:
  • Create customer/case - a generic error is presented to the Agent requesting they try again.
  • Bestmatch search customer - The agent will be presented with a message saying there is a temporary error and to try again.
  • Search customer - The agent will be presented with a message saying there is a temporary error and to retry the search.