Khoros Care brings an engagement-centric mindset – for marketing surprise-and-delight and digital care – to your digital operations. While providing an out-of-the-box experience that allows your moderators, specialists, and agents to be efficient and effective in delivering amazing digital customer experience, Khoros Care also delivers APIs for incorporating this digital engagement into your broader ecosystem.

About Khoros Care

Khoros Care connects digital engagement professionals to relevant conversations occurring on the social web and messaging channels including owned messaging (Modern Chat) in your mobile apps and on your website. Khoros Care enables companies to manage all these asynchronous conversations at scale without sacrificing quality. Through its scalable, intuitive workflow, Khoros Care helps build strong brand advocates through digital engagement.

At the highest level, the Khoros Care workflow looks something like this:

An author (a company’s customer) creates a post on a messaging channel or the social web, which is picked up and passed to Khoros Care.
Khoros Care filters and prioritizes these posts, and then routes the posts to Work Queues that customer care agents can access via a Queue or Push workflow.
An agent works the post, using author information presented within Khoros Care.
The agent creates a response and sends it to the Author resulting in the conversation moving to a pending state until the customer responds or other workflow action occurs.

API overview

This diagram illustrates the Care APIs used to integrate Khoros Care into your enterprise environment. The main areas are discussed in the following sections.

Automation Framework

The Automation Framework provides an event-based platform for listening to back-end Khoros Care events and taking whatever action is appropriate. In particular, this framework allows integrating a chatbot into every channel supported by Khoros Care, but more powerfully, it allows your systems to implement priority, routing, and tagging rules, provide Suggested Answers to agents, and many other use-cases including mirroring posts and conversations in external case-management / crm platforms. Below is a brief introduction to how you use this event-based infrastructure.

Acknowledgment Event - of the event is used to monitor the health of your endpoint. Built-in workflow ensures conversations do not get “stuck”. Notifications alert you to degraded and unavailable endpoints.
Process Event - You can perform different actions depending on the purpose of your automation including responding, prioritizing, tagging, routing, etc.
Monitor Request Status (optional) - You can optionally monitor for the status of requests you’ve made either by querying for the status of a specific request, or more commonly by asking for all recent requests in an error state.

UI Extensions (At-the-Glass Integration)

Khoros Care provides “at-the-glass” integration – the ability to trigger events from the UI and display data that is not stored or even passed through Khoros. These integrations use encrypted payloads and SSO tokens (if available) to enforce security.

The two main integration patterns available for At-the-Glass integration are:

Khoros Added Content – Khoros can add custom content to the profile including buttons that trigger server or client-side calls to your APIs (the API can return content displayed in the UI) or launch another form (for example, to create a contact). Contact our Professional Services team to discuss your use case.
IFrame you render – the Khoros Care UI has real estate that you can completely control via an iFrame. Khoros places an encrypted payload in the url request and decoding the payload validates the request and provides the content of the conversation – including the logged-in user allowing you to personalize what you chose to show. Additionally, for customers who have SSO for users logging into Khoros Care, the iFrame can be further secured.

Networks Attributes are provided by the specific channel and discussed in the next section.

IFrame that you render

This option has a straight-forward architecture. The Khoros Care UI has two locations (one in the Author profile (see screenshot above) and one at the bottom of the wide middle panel) that we can plug in a webpage that you create.

To display this webpage, you must create an https endpoint of the form https://<endpoint>?payload=<encryptedPayload> returns/redirects-to the webpage you want to display. The common steps your endpoint could do are:

Evaluate the origin of the request to see if it is an allowed domain. Alternatively, you can make the endpoint available only on your corporate network.
If you have SSO configured with Khoros Care, you can evaluate the SSO token and return an error if not valid.
Decrypt the payload with a shared secret we provide - if you can decrypt the payload, the request was generated by Khoros Care. Examples are provided in our iFrame guide.
Evaluate the timestamp in the encrypted payload - if the timestamp is more than X minutes old, consider the request invalid and return an error page. The payload is re-created when the iFrame renders, so X=3-5 minutes might be appropriate.
Based on the content in the encrypted payload, gather the information you need. This might include calling back into Khoros Care to get additional meta-data (in particular, calling the Author API).
Determine what you want to display and return it.

Encrypted Payload

The encrypted payload includes the context the iFrame is being rendered in for you to evaluate and decide what to render. This includes the viewing agent, author, channel, conversationId, and a timestamp.

iFrame Documentation

CRM Gateway API

In addition to offering the at-the-glass integration, Khoros Care also offers a use-case API to integrate into any external system that represents contact and cases/tickets - most often this is a CRM. The purpose of this architecture is to allow a customer’s IT team or Khoros Technical Services to implement an API interface to that system that powers the agent workflow and UI in Khoros. The IT work needed is just the integration and the rest just works.

As seen in the diagram below, Khoros has implemented the interface for Salesforce and SAP, and we have templates for Msft Dynamics, Zendesk, and Oracle Service Cloud. There may be even more by the time you read this.

This integration breaks down the integration into three primary objects: Customers, Conversations, and Interactions.

The Customer object is an individual customer or contact record in your system. The Customer object is manually linked to one or more messaging or social identities by a user in Khoros Care.
The Conversation with the customer encompasses a set of Interactions - in this context, an interaction is either a post coming from the customer or a response from the brand (automated or manual).

The implementation of the interface maps these objects into your system’s models.

We invite you to

Review the CRM API specification
Review our example implementation to Zendesk

Embedding APIs and UI Widgets

Khoros provides a fully functional agent interface to manage all digital engagement. As outlined above, it provides an architecture to embed external widgets. This enables an experience allowing agents to be effective and efficient. However, we believe that in order for maximum effectiveness and efficiency, and agent’s experience must be inclusive of all elements related to the customer journey, and for some enterprises, this means Khoros Care will need to be embedded in a “Single Agent Desktop” solution if a brand chooses to invest in this.

Khoros has some capabilities today that enable this, and we are continuing to work in this direction.

Today we have an API allowing an Agent’s state to be managed externally. This allows a common agent workforce management console and was a use-case brought to us by a customer. Khoros Care also provides an embeddable read-only widget conversation display widget.

We currently have a prototype allowing Agent View to be embedded via an iframe. This capability removes the navigation bar and sets Content Security Policy headers to a configured domain.

Author and Conversation API

Khoros Care customers generally have multiple CRM systems that they want Khoros to interact with. These APIs let customers interrogate Khoros for more information about the people sending messages and the conversations they are having, and it also lets information be set in Khoros.

Information can be provided to agents via the at-the-glass integration or the CRM Gateway integration described earlier, but if this information needs to be used in automated business rules to route, prioritize, and tag conversations – and filtering Analytics (“Did we service our top-tier customers with the appropriate level of support?”) - it needs to be stored in Khoros Care. The type of integration most appropriate will be determined based on your specific use-case, input from your InfoSec team, and the availability of technical resources.

To access author and conversation information, Khoros Care provides Author and Conversation APIs.

In the Author Profile example screenshot in the UI Extension section above, data added into Khoros with the Author API is displayed as seen in the Author Attributes box.

The primary use-cases are to:

Synchronize Author attributes with attributes in other systems
Display Conversations from Khoros in-line with a contact’s record in CRM
Create (and synchronize) Case Details with Conversations in Response

Brand Messenger (Messaging APIs)

Khoros Care provides an owned messaging channel. This is a messaging channel that supports asynchronous messaging and you own the data. This channel can be deployed to support a transfer-from-social use-case as well as messaging embedded in your mobile apps and deployed on your website as the next version of webchat. The SDKs include:

Web Messenger SDK – for embedding messaging in your website for either anonymous or authenticated messaging. If the user is authenticated, the messaging is asynchronous allowing the user to return later to your website and continue the conversation.
Mobile SDKs (iOS and Android) – for embedding in your native mobile apps. Native iOS and Android SDKs are provided.

Documentation

Analytics API

Documentation

Analytics API Documentation

All of the raw data available in Analytics is also available via an API. The API mirrors the exports available from the Analytics user-interface includes Conversation, Author, Incoming Posts, Responses, Agent Performance, and Published Posts.

The primary use-cases these APIs are used for include:

Enterprise Data Warehouse data extraction
Corporate Data Reporting
Workforce Management
3rd-party Survey input files

Listening API (Legacy)

Although Khoros Care supports a wide range of social networks and messaging channels natively, you might have content sources from which you want to create conversations for agents to work. For example, you might have custom messaging platforms or 3rd-party sites you wish to integrate.

For these use-cases, Khoros Care provides an API that allows you to deliver messages to Khoros Care and receive a notification when an agent responds.

Bot API (Legacy)

Note: although this API is still available, it has been logically replaced by the Automation Framework outlined above. Legacy Bot API Documentation.

Social networks such as Twitter and Facebook support APIs and mechanisms that allow you to implement bots and other automation experiences, typically via private messages. Khoros Care’s legacy Bot API enables you to integrate your bot(s) into the seamless customer experience with your customer care specialists.

The three (3) main system interactions between your bot(s) and SMM Response are to:

Close a conversation when the bot fully serves the customer
Hand-off to an agent when the bot can’t answer or customer wants an agent
Receive notification that a handed-off conversation is closed by an agent so the bot knows to respond next time

API Technical Overview

The APIs are invoked via HTTP endpoints using GET, POST, PUT, and DELETE methods. Payloads and responses are in JSON format (the Analytics APIs also allow you to specify a csv format (not recommended)).

Authentication

There are two (2) types of authentication used by the API calls:

Bearer Token Authentication – the Automation Framework uses Bearer authentication with an access token. You create the token with a permissioned user using Basic Auth, this token is valid for 90 days, and you can refresh it. At any time you can invalidate the token.
All other API calls use HTTP Basic Authentication via an Authorization header. Khoros recommends creating a single, distinct user account for each project that uses the APIs – and special permission must then be granted for each different API.

Rate Limits

To maintain system performance, each API endpoint is rate limited. If you have a use-case requiring higher rate limits than initially configured, you can let us know and the rate limit can be increased (we do not charge for higher rate-limits).