Who Is This For?

This document is intended for third party software integrators who'd like to see Clarabridge Engage's social messages available in other software packages, like CRM solutions or call center software; so that messages monitored by Clarabridge Engage can be escalated to other products.

If you are interested in integrating with Clarabridge Engage, please do get in touch with us first.

Introduction

If you want to integrate Clarabridge Engage into other software platforms, there are 4 main aspects to consider ...

API Basics

Clarabridge Engage's API is a REST API, returning JSON, and authenticating with the API is via the standard oAuth 2.0 protocol. The basic steps of using the Clarabridge Engage API are discussed here.

If you want to build a prototype or only need a single user login, you can go to your application's settings and just request a single oauth token for the logged-in user, without having to implement the oAuth dance.

Use the API console to play around with the various endpoints and see results.

We also have the ability to trigger webhooks from our automation engine. If you're building an integration, this feature is interesting to be notified of e.g. new data in Clarabridge Engage topics. Read more about webhooks.

Monitoring

  • If you want to have Clarabridge Engage data available into your own system, you can do this polling for (new) data periodically. If you want to automatically push new mentions to your system, we have support for webhooks in our automation feature that allow you to get updates about new data quickly. Read more here.
  • A message in Clarabridge Engage is called a "mention"; so that is the type of object you'll be working with. A mention returned by the Clarabridge Engage API looks like this. Please note the remark about Twitter data!
  • The API endpoint to fetch a list of mentions is /{account_id}/inbox/mentions. (In this url replace {account_id} with the id of the accounts you have access to, see /me/accounts-endpoint for those details.)
  • Via the params for that endpoint you can control which mentions (for which filter, for which date range) should be picked up by your tool. Full filter functionality, as can be found in the Clarabridge Engage Inbox, is exposed via the API too. If you want to know which filter & topics should be used to get data for a certain mailbox you can use the /{account_id}/inbox/mailboxes endpoint.
  • The topic.id in combination with id fields of a mention make a mention unique.
  • If you don't want to do uniqueness checks on your end; a good workflow for "fetching only new mentions" would be:
    1. Fetch all mentions with filter "without tag x" Eg. ?filter=-usertag:yourtool.
    2. For all mentions in the API call result, update the Clarabridge Engage mention with the tag. This endpoint's documentation page has an example of how to add tags to a mention via the API.
    3. Repeat; in a new call you will only receive mentions that are new to your tool.
    This will also give people who use Clarabridge Engage an idea of which messages have been picked up by the call center software.
    Bonus tip: You can also use tags to store custom data (eg. the id of the message in your own system), by adding tags in this format key:value, eg. callcentermessageid:123456.

Taking Actions

  • Each mention returned by our API contains an array of "action links". These define the possible actions on a mention and the urls where to do them (url in the web app, or url in the API, if available).
  • An actionlink looks like this. The documentation also has a list of possible action link types (the most important probably being "reply" and "comment" for eg. Twitter and Facebook mentions).
  • The Terms of Services of the Third Party services we use (Twitter, a.o.) don't allow us to expose publishing functionality in our API, so we cannot offer API endpoints to reply in Twitter or comment on a Facebook post via the Clarabridge Engage API.
    Our API does allow to create a draft or post awaiting approval, though.

If you want to keep your own tool in sync with the actions that have been done in Clarabridge Engage (eg. a reply, or adding a tag, or marking as resolved in Clarabridge Engage), you can call the /{account_id}/inbox/mentions-endpoint, sorted on "recently updated", to fetch recently updated mentions.

Push Updates to Clarabridge Engage

Accessing profile data
When you need more information about the authors of a message, you can access this information via the contact endpoint /{account_id}/inbox/contact/:service/:service_id. You can also use this endpoint to store extra data, like custom attributes, for that contact in Clarabridge Engage.
At the moment we don't have support for searching on contacts.
Fetching conversations
If you want to know which conversation a message belongs to, you can do a new search via the inbox/mentions endpoint for filter conversation_in_reply_to:(topic.id)_(id). This will return a list of all mentions related to the mention you're requesting it for, similar to the "related mentions" button in the Clarabridge Engage Inbox in the web app. Click "Filter On Thread" in a mentions dropdown, and copy the filter that's been set up after that for an example of this.
Updates
Definitely keep an eye on our changelog to keep up to date on API changes.

When you're interested in this kind of integration or other related API enquiries, please get in touch with support@engagor.com.

©2019 Clarabridge®. All rights reserved.
Stay Connected