An Overview

The Khoros Marketing Notifications API service allows you to subscribe to interesting events in Conversations and be alerted when they happen. We’ve released this API in response to our Khoros enterprise customers looking for this level of visibility across their organizations in both the use cases of Khoros for Outbound Marketing and Khoros for Social Customer Care.

For those using Khoros for Outbound Marketing, where collaboration across a large team is necessary, we heard requests to:

Apply a label from the Khoros Conversations Inbox and automatically route that post to Khoros Experiences to be highlighted in an employee or customer love Experiences Visualization displaying social posts on a large screen be it at a conference or in an office lobby
Notify a Slack channel or a specific individual via Slack when a scheduled post is published from Khoros for coordination across other channels around real-time marketing events
Notify colleagues working in an adtech platform about a natively scheduled Facebook post that is a candidate for boosting

For those working from Khoros to solve Social Customer Care issues, we heard requests to:

Escalate issues from Khoros to colleagues working in Zendesk by applying a label to an item in the Conversations Inbox and automatically having a Zendesk ticket created
Notify colleagues via Slack when keywords are mentioned on social (taking rules configured in the Conversations Inbox to identify sensitive social posts)
Route a social post from the Khoros Conversations Inbox to Khoros Experiences for visibility in a Command Center or Crisis War Room

To accomplish these requests, Khoros released three supported trigger events for the launch of our Notifications API:

Applying a label to an item in the Conversations Inbox (Found in the API as “stream-item-label-applied”)
The act of a message being published from Conversations (Found in the API as “message-published”)
The conditions matching for a previously configured automatic rule in the Conversations Inbox (Found in the API as “rule-applied”)

An Example With Zendesk

We chose an illustrative integration to demonstrate the necessary steps for enabling your Khoros instance with a subscription of events through the Notifications API. We are leveraging the event of applying a label to an item in the Conversations Inbox. Specifically, we are triggering off the application of a label called “CreateCase” to a social post in the Inbox. We have two choices on how we will know when this happens. We can poll the Notifications API every so often to see if there are any new events, or we can have the Notifications API call us when it happens. We’ll choose the latter as it will be more “real-time”.This application note describes how you can use the Khoros Notifications API to drive workflow automation within your organization. In this example, we will integrate Khoros Conversations to Zendesk. Whenever an agent applies a “CreateCase” label inside of Khoros Conversations, a new ticket will be automatically created in Zendesk. Building these integrations is straightforward but it does require a small bit of glue code. Fortunately, with today’s “serverless” platforms such as Heroku and AWS Lambda, it's never been more simple to automate your business. With a little effort, you can automate your business processes and have full control over how that process works. In this example, you will:

Register for and configure a Zendesk account
Register for a new Khoros API application and obtain access credentials
Deploy and configure a small application to connect Khoros to Zendesk

STEP 1 - REGISTER FOR AND CONFIGURE A ZENDESK ACCOUNT

Get a Zendesk Account

Zendesk makes it very easy to sign up for a test account. Visit https://zendesk.com and register.

Enable Zendesk API Access

Zendesk supports multiple authentication mechanisms. We’ll use their token-based method since we’re building a server application that needs a long-lived access token.

Copy your access token to a safe place. You’ll need it later.

STEP 2 - REGISTER FOR A NEW KHOROS MARKETING API APPLICATION AND OBTAIN ACCESS CREDENTIALS

The Khoros Marketing platform uses OAuth as its authentication mechanism. As part of this exercise, we recommend you contact Khoros support for a new API client id and secret. You may also optionally configure a new service user who is restricted to just a test initiative in your account and the writer role. This creates a least-privilege account that is sufficient for this exercise but which does not have enough privilege to publish to or access your production social accounts. We recommend you follow this approach for API integrations as a best practice unless your application needs publishing permissions.

Have your company administrator contact Khoros support and request a new client id and secret
Create a new service account user with the writer role and restrict that account to just test initiatives

Once you have your client id and secret, and your test user provisioned, generate an access token:

Log in to Khoros Marketing as your service user.
Follow this guide to generate a new API Access Token.
Copy this token into a safe place. You’ll need it later.
Also make note of your Company ID.

Great, now you have both Zendesk and Conversations ready to go. We just need a way to connect them.

STEP 3: DEPLOY AND CONFIGURE A SMALL APPLICATION TO CONNECT KHOROS TO ZENDESK

Khoros Marketing Notifications is an API service documented here. Per the above, in this example, we will subscribe for the condition of a label called “CreateCase” being applied to a stream item. We have two choices on how we will know when this happens. We can poll the Notifications API every so often to see if there are any new events, or we can have the Notifications API call us when it happens. We’ll choose the latter as it will be more “real-time”.

The “Deploy to Heroku” button allows you to directly deploy this application to Heroku. If you would like, press it now to jump ahead to “Deploy the Application” below. Otherwise, let’s look at the code.

The integration application for this example is a small node.js application. You could code in any language you like as long as you have an execution environment you can run it in.

This application does two things. First, it makes an API call to Khoros Marketing to subscribe to label events from the social inbox. Then it listens on a network port for those notifications. Each time it receives a notification, it uses the items from Conversations to create tickets within Zendesk. Example code below is selected from Github. Please see the full listing at Github.

Let’s review the subscription request that is sent to Conversations:

Name	Type	Required?	Description
companyId	Number	Yes	This is your company id.
externalId	String	Yes	This is a string you specify for the subscription. This makes initialization very simple as you can just resubscribe each time your application starts and it will create or update an existing subscription with that name.
eventName	String	Yes	This is the Conversations event you want to know about.
notificationUri	String	Yes	This is the URL Conversations will call when an event occurs. This must be reachable on the public internet.
query	String	Yes	This optional parameter can be used to filter events. Here we’re using it to specify a label name. Regular expressions are allowed here as well.
bearerToken	String	Yes	For security, you can specify a token that will be provided in each API call Conversations makes to your service. This token will be in the HTTP “Authorization” header using the RFC6750 bearer token scheme.

Deploying the Application

You could run the application anywhere it is reachable via the public internet. For this example, we’ll deploy it using Heroku. The demo application comes with a Heroku deployment description and can be deployed directly from GitHub.

Sign up for a free Heroku account at https://heroku.com. Once you have one, you’re ready to deploy the integration application. Click on the “Deploy to Heroku” in Github. This should redirect you to Heroku where you will be prompted for the information you collected above.

You’ll need to fill in all of the following information:

Name	Type	Required?	Description
App Name	String	No	You must choose a name for your application because it must be also provided as an environment variable called HEROKU_APP_NAME.
Runtime Selection	String	Yes	Leave as its default.
HEROKU_APP_NAME	String	Yes	Copy your application name from the first field here.
SPREDFAST_API_TOKEN	String	Yes	This is your Spredfast secret Access Token you saved from Khoros.
SPREDFAST_COMPANY_ID	String	Yes	This is your company id.
SPREDFAST_LABEL_NAME	String	Yes	This is the label that will cause a case to be created. In our example it is “CreateCase”.
ZENDESK_API_URL	String	Yes	This is the URL to your Zendesk instance. It is the first part of the URL when you are logged into Zendesk.
ZENDESK_USER_EMAIL	String	Yes	This is the email address of your Zendesk user.
ZENDESK_API_TOKEN	String	Yes	This is your Zendesk API token that you created when you enabled API access.
NOTIFICATION_BEARER_TOKEN	String	Yes	This token is generated by Heroku and used in the Spredfast events. This allows the example application to verify the request came from Khoros.

Testing the Application

Assuming your application deployed successfully you’re ready to try it out.

Ensure you have defined a “CreateCase” label at your company settings if you have restricted label creation.

Log into Conversations as any user and apply a “CreateCase” label to an item in the inbox. A ticket should be created in Zendesk. Watch the application logs on Heroku for progress or errors.