Help Center

FAQ about our API

Last Updated: Jun 23, 2017 09:40AM EDT

General

How do I start?
Which type of account do I need to be able to use the API?
Do you have a client library in programming language x?
Can I quickly test the API?
Can you increase the rate limits?

 

Authentication

How are API calls authenticated?
Do I really need to implement oAuth for my application?
How long are access tokens valid?
What accounts/data can I access with a token?

 

Working with mentions

I want to get the mentions from my CX Social inbox into my own application
Tweets returned by the API are missing details?
Why are some Facebook posts anonymous?
Can I add my own messages to CX Social?
Can I import messages to CX Social's outbox? 
Can I add tags to mentions, edit the status or assign mentions?

 

Publishing

Can I use the CX Social API to publish to a social channel?


Working with Social Profiles

Can I retrieve information about the social profiles in my topics? Including custom attributes, etc.

 

Working with Insights

Can I get statistics from CX Social?

 

Problems

Where can I find my account id?
Where can I find my topic id? 
Where can I find my user id?



General

 
How do I start?
Our step by step guide details all relevant steps for building a great CX Social API application: http://developers.engagor.com/documentation/steps/
 
 
Which type of account do I need to be able to use the API?
Access to the API isn't included in all pricing plans. During your trial period you're free to experiment with the API, but after that it depends on your subscription. Please talk to your Sales or Customer Success Manager for details.
 
 
Do you have a client library in programming language x?
CX Social doesn't offer client libraries, but libraries for the oAuth protocol exist in almost every language, see http://oauth.net/code/.
 
 
Can I quickly test the API?
Via the API Console http://developers.engagor.com/tools/console you can pick an endpoint fill in some parameters and do a request to the API and immediately inspect the results.
 
 
Can you increase the rate limits?
How we handle rate limits is documented on http://developers.engagor.com/documentation/ratelimiting. Our current rate limits are more than enough for normal use cases. If however, you would need extra rate limits, please get in touch with support@engagor.com and describe the use case of your application and the requested rate limits.
 
 

Authentication

 
How are API calls authenticated?
We use the standard oAuth 2.0 protocol. This standard is used by many websites, including Facebook, Twitter, Instagram and most other social API's. For more information on authentication and a full example, see http://developers.engagor.com/documentation/auth/.
 
 
Do I really need to implement oAuth for my application?
If you don't need the users of your application to authenticate their CX Social account, when you e.g. have a single user application (for syncing your own backend with the CX Social database), you can skip implementing the oAuth-dance, and generate an oAuth token for your own CX Social user. Go to the application overview (http://developers.engagor.com/applications), click edit next to your registered application, go to the "Access Tokens" tab. If you click "Authorise Myself", an access token for your current logged-in user (with its permissions) will be generated. You can use this access token to sign API requests. 
 
 
How long are access tokens valid?
The expiry time of access tokens is part of the result of the Access Token Endpoint result, see http://developers.engagor.com/documentation/auth/#accesstokenendpoint.
 
What accounts/data can I access with a token?
An oAuth access token is generated for a specific CX Social User. This user has access to one or more Accounts. (See which ones via the `/me/accounts` endpoint.) What data you can access of what accounts depends on what accounts the user itself has access too, and what his/her user role in that account is.
 

Working with mentions

 
I want to get the mentions from my CX Social inbox into my own application
With the `/{account_id}/inbox/mentions` endpoint you can retrieve all the mentions in any of your topics. 

Which data is available per mention is described here: http://developers.engagor.com/documentation/responses#responsemention
You can use the same filters in the API that you can use in the CX Social web application, and you can choose how you want your messages sorted. Details about the filters you can use can be found on http://developers.engagor.com/tools/filterbuilder
A few of the possible use cases are:
  • Returning all mentions with a certain tag from one or more topics.
  • Returns all unresolved mentions older than a certain date.
  • Perform backups of mentions tracked by CX Social.
  • Syncing certain mentions with your own CRM system.

Note that you could also design a workflow to call up web hooks in your application using CX Social's automation recipe feature (http://help.engagor.com/customer/portal/articles/2777952-account-setup-using-automation-recipes-and-webhooks-to-automate-your-workflow#Webhooks)
 
Tweets returned by the API are missing details?
For Tweets we're only allowed to return the CX Social specific data and the Twitter Tweet ID. This is a restriction from the Twitter API Terms (https://dev.twitter.com/overview/terms/agreement-and-policy) that we cannot do anything about. Luckily you have the Tweet ID, so if you need all details you can access the Twitter API and use the "/statuses/lookup" endpoint (https://dev.twitter.com/rest/reference/get/statuses/lookup) for fetching all details.
Twitter requires this, because they want to keep control over who is using their data.

(The relevant section in Twitter's Terms is 
"If you provide Content to third parties, including downloadable datasets of Content or an API that returns Content, you will only distribute or allow download of Tweet IDs and/or User IDs.".)

 
 
Why are some Facebook posts anonymous?
Public Facebook posts (picked up by CX Social through your keyword search, not messages on your Facebook pages) are anonymised. This is a limitation from the Facebook API and beyond our control. 
 
 
Can I add my own messages to CX Social?
If you have a contact form, or internal forum that you'd like to see monitored by CX Social, you can call the "/{account_id}/inbox/add" (http://developers.engagor.com/documentation/endpoints/?url=%2F%7Baccount_id%7D%2Finbox%2Fadd) endpoint to add your custom messages to CX Social. These messages will then be accessible in your CX Social inbox and insights.
Messages added to CX Social via the API cannot be replied from within CX Social. If you want to have this tighter integration with your custom system, please get in touch via support@engagor.com. 
 
 
Can I import messages to CX Social's outbox? 
In some cases, it's common practice to broadcast company publications (on the Wordpress blog e.g.) via the social media channels through CX Social. You can create drafts of new posts for community managers to verify/edit/publish through the endpoint "/{account_id}/publisher/add" (http://developers.engagor.com/documentation/endpoints/?url=%2F%7Baccount_id%7D%2Fpublisher%2Fadd)
 
 
Can I add tags to mentions, edit the status or assign mentions?
You can edit existing CX Social mentions by using the "/{account_id}/inbox/mention/{topic_id}/{id}" endpoint (see http://developers.engagor.com/documentation/endpoints/?url=%2F%7Baccount_id%7D%2Finbox%2Fmention%2F%7Btopic_id%7D%2F%7Bid%7D). The documentation for this endpoint has examples for updating a mention's tags, adding a note, etc.
 

Publishing

 ‚Äč

Our API doesn't allow directly publishing to 3rd party platforms. This means you cannot use the CX Social API to eg. publish a tweet or a Facebook comment. While this would be technically possible, most social websites explicitly disallow this types of use cases, because this way they don't have control over the interface used to publish. (Twitter periodically checks CX Social to see if we adhere to their guidelines and policies.)

You can however use the CX Social API to create drafts or queue messages for approval. These will then be published when approved or published through the CX Social interface. The endpoint to do this is /{account_id}/publisher/add
 

Working with Social Profiles

 
Can I retrieve information about the social profiles in my topics? Including custom attributes, etc.
Via the "/{account_id}/inbox/contact/{service}/{service_id}" endpoint (documented at http://developers.engagor.com/documentation/endpoints/?url=%2F%7Baccount_id%7D%2Finbox%2Fcontact%2F%7Bservice%7D%2F%7Bservice_id%7D) you can fetch information about a certain social profile. This will include any details you've filled in for that person within the CX Social CRM, like gender, email, or custom attributes you've added for this user.


 

Working with Insights

 
Can I get statistics from CX Social?

If you want to use insights from CX Social you can do so in 2 ways;

Problems

 
Where can I find my account id?
Once you've authenticated, you can get a list of all accounts (and their ids) a user has access to via the "/me/accounts" endpoint, see http://developers.engagor.com/documentation/endpoints/?url=%2Fme%2Faccounts.
 
 
Where can I find my topic id?
Once you've authenticated, you can get a list of all the topics (and their ids) a user has access to via the "/me/accounts" endpoint, see http://developers.engagor.com/documentation/endpoints/?url=%2Fme%2Faccounts.
 
 
Where can I find my user id?
Once you've authenticated, you can get details about the authenticating user (including his/her id) via the "/me" endpoint, see http://developers.engagor.com/documentation/endpoints/?url=%2Fme.
 
 

Contact Us

support@engagor.com
http://assets0.desk.com/
false
engagor
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete