service_details field was added with following (optional) fields:location_id
location_name
location_url
location_address
app_id
app_name
product_id
product_name
shop_id
shop_name
location.continent
location.country
location.city
location.region
location.longitude
location.latitude
20221028.
stripped_content has been added to the Mention object./{account_id}/inbox/mention/{topic_id}/{id} an error of type invalid_parameter will be returned if you update the status of the mention to the same status.
This change goes into effect if you are not specifying the version or any version above 20220930.
metadata fields for mention_actionprevious_priority was added next to priority with the same possible values: 'low', 'medium', 'high', 'critical'
display_name was added to mention_assignee
timestamps on the Mention Object has been updated. This array can contain the following new properties:
unresolved_time: The total time a case has been in unresolved status, in seconds.unresolved_time_during_bh: The total time (during business hours) a case has been in unresolved status, in seconds.pending_time: The total time a case has been in pending status, in seconds.mention will now have two optional additional fields: buttons (the list of buttons/quick replies that were send) and clicked_buttons (a list with the buttons the user selected from the sent multiple choice question).
metadata field for mention_actionstatus with possible values: 'new', 'done'
priority with possible values: 'low', 'medium', 'high', 'critical'
assignees which returns an array of mention_assignee
mention.todos field for mention updatemention will now have the field todos.
It contains a list of to-do's that were added in notes attached
to a mention.
/{account_id}/inbox/case/{topic_id}/{id} endpoint
that returns a single case together with it's linked mentions, in the same case_conversation format as the /{account_id}/inbox/cases endpoint.
You can use this endpoint if you need the details of a single case only, but together with all of its linked mentions.
/{account_id}/inbox/contact/{contact_id} endpoint we will now only update the tags of a contact if you specify the property 'tags' in the updates parameter. To clear the contact tags of a contact you should thus now specify the updates param as {"tags":[]} instead of `{}`. We have made this change so you don't accidentally clear contact tags when updating other properties of a contact. If you would like to keep using the previous behavior of this endpoint, please provide a version parameter lower than "20210601".,
mention.source.thread_id field for mention updatemention will now (optionally) have a field mention.source.thread_id.
This field is to indicate to which "thread" a comment/reply belongs.
If you have e.g. a Facebook Post A, a comment to it B, and a reply C to that comment. The thread_id of both the comment and reply to that comment will point to post "A".
This new field allows you to re-build threads that are more than 1 level deep. This data isn't available for all sources.
/{account_id}/settings/topics
endpoint. The API response will now also include all monitored profiles of each topic.
/{account_id}/inbox/contact/{service}/{service_id} endpoint now includes phone number for WhatsApp contacts new/{account_id}/inbox/contact/{service}/{service_id} endpoint to request
details about a WhatsApp contact, the result will now always include the telephone number of the WhatsApp contact even if the information wasn't previously
saved or confirmed by an agent via the tool. Since we have to do an API call to fetch this information ourselves, we're only including this information in the endpoint
that returns a single contact, and not endpoints that list several contacts, unless it was previously saved via the interface.
/{account_id}/publisher/add,
as you would reply on a private message.action_link
with key "privatemessage" is available, it can be replied to with a private message./{account_id}/settings/tags endpoint now has two
additional parameters to control which tags are returned. You can choose to only return smart tags, and also whether or not any tags that are
related to XM Discover enrichment categorization models should be included.
message.entities in the mention object will be empty by default info20201001.
message.entities represents entities extracted from the content and will now only be available upon request.
/{account_id}/inbox/cases endpoint now also returns a
`contact` object for cases that were auto-created for a certain author.
The contact object will contain any custom attributes and data saved in the Engage CRM.
business_hours_schedule objects, will now
include an object users that contains the number of users that have the business hours configured, and how much of them are available, busy or unavailable.
mention that represent YouTube videos or comments, will no longer contain all properties (like the comment text, or author's name).
Instead, only Qualtrics Social Connect specific data will be returned, as well as the identifiers of the video/comment. These identifiers can then be used
to retrieve the data from the Youtube Data API. We're making this change to ensure that
any usage of YouTube data obtained via our platform is used in accordance to their Terms of Service and other policies.
mention Object.
part_of_cases.mention_identifiers was added to the mention object,
indicating whether this mention is part of one or more cases.
/{accountid}/inbox/mentions endpoint/{accountid}/inbox/mentions
API endpoint. From today on the returned page_token will have been made using a different algorithm. When requesting data from the endpoint with a page_token, page_tokens
generated before today will continue to work until 2020-06-08. After that date, only page_tokens generated after today will be valid. If your application
requests data from this endpoint (and uses the returned page_token) at least once in the coming 2 weeks, there's no action you need to take.
assigment.team_ids and assigment.user_ids will no longer be able when stating a version bigger or equal to 20200427.
assignees was added to the mention object. It contains a set of mention_assignee objects giving more details about the users and teams this mention is assigned to.
`gender` property removed from `contact` object
breaking change`contact` objects
are returned, the response will no longer contain a `gender` property. The Gender feature in our CRM
has been removed because it was a binary option. We encourage accounts that want to identify genders via the CRM to
set-up a custom contact field with non-binary options too. Our API returns all custom contact fields on a contact.
mention Object.
See updated definition of the mention_attachment object.
userrole object. newuserrole objects, will now
include a property topics that is a list of all topics this user role has access too.
`oauth_token`'s
(e.g. with different scopes). For this we are also changing the way rate limiting is measured; going forward it will be measured
by the User ID associated with the `access_token` used. This means that `access_token`'s associated with the
same user will share rate limit allocations. `access_token`'s for different users will of course not impact each other.
Our documentation on rate limiting has been updated.
GET header in /{account_id}/settings/businesshoursschedule/{id} endpoint.
It returns business_hours_schedule object of the specified id.
See the Response documentation for more details and example.
business_hours_schedule objects, will now
include a property is_active that is true if within the business hours otherwise it will be false.
user objects, will now
include a property businesshours_is_active that is true if within the business hours otherwise it will be false.
`company` property removed from `user` object breaking change`user` objects are returned, the response will no longer contain a `company` property. The ability for Engage users to fill in their company in their personal settings was since long removed, so it didn't make sense to continue to expose this in the API. (Note: the `company` property on a `contact` object is not affected.)
`user` objects are returned, the response will now also contain the user's status (Available, Unavailable, Busy).
mention.author.managed to indicate if the author of the mention a connected stream in Engage.
mention.source.sender to indicate who or what sent the mention.
userrole object. newuserrole objects, will now
include a property permissions that is a list of all permissions this role has.
See the Response documentation for a list of all possible permissions.
source.url for Tweets when returning mention response objects. Use this endpoint to look up multiple tweets
at once. Read
more
paging.next_url.contact details.
topic objects for your account.
access_token's from the applications a user authorized, when a user changes their password. This will result in a standard OAuth error. You will be able to resolve by just re-authenticating the user. Read more about authenticating with our API.
mention response object new version 20180406unique_id is now filled in as a Qualtrics Social Connect specific identifier for the mention.
publishing_guideline objects for your account.
$businessHoursSchedule into $business_hours_schedule to add a new business hours schedule: /{account_id}/settings/businesshoursschedules.profile_group objects and which profiles are in which group via /{account_id}/settings/profilegroups.attachment response object new version 20180213question to the attachment response object.
service response object new version 20180208status to the service response object.
mention response object new version 20180125source.profile is now filled in for Twitter private message mentions. You
now have all the id's required to rehydrate them. Read
more about why not all data is returned for Twitter, and how to solve this.
tag response object new version 20180115status to the tag response object.
publisher_mention response object newin_reply_to of the type mention.
This is an optional property that will only be returned on the endpoint /{account_id}/publisher/mention/{id} and only if the post is a reply to a mention.
Data security and integrity are top priorities for Qualtrics. As part of our ongoing commitment to ensuring all Qualtrics products are secure, we have taken a similar decision to many other SaaS companies in disabling the use of TLS 1.0.
Qualtrics plans to disable TLS 1.0 encryption as an industry best practice. If you are using a browser that does not support modern encryption protocols, or if you are using a browser other than the supported browsers, you will experience issues accessing Qualtrics Social Connect and other Qualtrics Hosted Services.
This is remedied upgrading your browser or http clients to a modern version.
[profile.name] or [profile.url] you need to pass reply_type, service_type and service_id to /{account_id}/settings/canned_responses.
We've also added a new order parameter to sort the canned responses.
user response object newavatar is added to the user response object.
contact response object bug fixcontact.date.added and contact.date.updated would sometimes be returned as a string representation of the date instead of a UNIX timestamp that was described in the documentation.
/{account_id}/inbox/context endpoint to get more context about a mention (the previous conversations with the customer, notes added by users, etc.).
contact.permalink property to contact response object newcontact.permalink to the contact object. This object contains a link straight to the contact's details in the Qualtrics Social Connect tool, and can be used to link to in your apps.contact object's properties.
contact object fields changecontact.url, contact.address.street, contact.address.number, contact.address.zip from the contact object since they are unavailable to fill in in the interface and are thus obsolete.
extra_fields to every returned mention object.
/{account_id}/inbox/contact/{service}/{service_id} endpoint, you can now supply both address.country.name and/or address.country.code as updates. When `code` is set, that one will get precedence, or when `name` is set for the country, we'll look up the provided name in our English list of countries to find the corresponding code. If you provide a country name we don't recognize, an error of type invalid_parameter will be returned. We use ISO 3166-1 alpha-2 for country codes.
customattributes_edit_mode:overwrite option parameter for the /{account_id}/inbox/contact/{service}/{service_id} endpoint. This edit mode will remove all existing attributes, and set the new provided ones. (Similar to the tags_edit_mode option.)
/{account_id}/inbox/contacts endpoint so only contacts with a certain tag are returned by supplying a filter argument, and filter on a contact tag, with e.g. contacttag:yourtagname.
/{account_id}/inbox/contacts endpoint so only contacts updated after a certain date are returned.
/{account_id}/inbox/contacts endpoint to be sorted, by creation date or by last update.date.added and date.updated to every returned contact object.
/{account_id}/publisher/add endpoint.
/{account_id}/settings/canned_responses_folders endpoint.
/{account_id}/settings/responses endpoint.
/{account_id}/crisis/todo endpoint.
/{account_id}/crisis/event endpoint.
visible field and category_model_tag field, have been added.
contact.id, not only via a combination of the social service and service id. The new endpoint /{account_id}/inbox/contact/{contact_id} works in exactly the same was as the existing /{account_id}/inbox/contact/{service}/{service_id} endpoint.
/{account_id}/inbox/contact/{service}/{service_id} has been updated to support updating the contact tags and updating multiple custom attributes at once. For this we had to make a few breaking changes in how you update address data, and custom attributes. We've updated the examples.
/{account_id}/inbox/contacts endpoint.
/{account_id}/settings/customattributes endpoint.
/{account_id}/crisis/plans endpoint.
/{account_id}/dashboards/component/{dashboard_id}/{component_id} endpoint.
/{account_id}/publisher/mentions bug fixdate_from and date_to of the /{account_id}/publisher/mentions only had effect when you filtered on mentions with status "posted" (i.e. your publisher history). We have fixed that the parameters now always have effect.
/{account_id}/dashboards/export/{dashboard_id} endpoint the data returned is now structured in the same format as all other widgets for consistency.
https://api.engagor.com/{account_id}/publisher/mention/{id} endpoint you can add/edit or delete tags. For examples you can refer to the examples on Inbox Mentions.
https://api.engagor.com/{account_id}/publisher/mentions endpoint. You can now use next_url and previous_url.
POST https://api.engagor.com/{account_id}/publisher/mention/{id} endpoint. Check the endpoint documentation for an example and more details on how.post_params has been added. This optional field will be filled when a POST action link requires specific arguments.
/{account_id}/inbox/mention/{topic_id}/{id} endpoint to update a mention.
DELETE http request to /{account_id}/inbox/mention/{topic_id}/{id} to remove the mention from Qualtrics Social Connect. Optionally you can also request to have the mention deleted from Facebook/Twitter, etc.key: delete.
http_method has been added. This field describes which http method you should use when making the request to the link. This has been added to distinguish between GET, POST and DELETE requests.
POST request to /{account_id}/inbox/mention/{topic_id}/{id} with e.g. updates={"message":{"sentiment":"positive"}}.
More details in this example.
notes of the Contact Object has been removed, in favour of using notes on Mention Objectscomments field of the Contact Object.
entities, has been documented. This array can contain the following objects;
POST request to /{account_id}/publisher/mention/{id} with updates={"actions":[{"type":"note","extra":"Text of the note to be added goes here."}]}. More details in this example.
actions has been added to the Publisher Mention Object. This array contains Mention Action Objects similar to Action objects of Mention Objects.
/{account_id}/security/audit endpoint you can fetch all security audit logs for a certain account. Full documentation can be found on the Endpoint documentation page.
timestamps has been added to the Mention Object. This array can contain the following properties:
response_time: The time between date.published and the first reply (if any), in seconds.response_time_during_bh: The time (during business hours) between date.published and the first reply (if any), in seconds.resolve_time: The time between date.published and the first resolve date (if any), in seconds.resolve_time_during_bh: The time (during business hours) between date.published and the first resolve date (if any), in seconds.handle_time: The total time spent handling this message, in seconds./{account_id}/inbox/contact/{service}/{service_id} endpoint. Full documentation and a few examples can be found on the Endpoint documentation page.
/{account_id}/inbox/mailboxes endpoint you can get the configuration details of all mailboxes configured for an account. The configuration of eg. a certain mailbox folder can then be used to decide on which parameters to send to the /{account_id}/inbox/mentions API endpoint to fetch mentions for a certain smart folder.
/{account_id}/settings/history endpoint you can fetch the audit log of all configuration changes to an account. You can filter on type, topic and/or user.
dashboard_widget response object now also includes details about the width, height and positioning of each widget on the dashboard. So if you're using the /{account_id}/dashboards/export/{dashboard_id} endpoint you will now also receive these extra details./{account_id}/inbox/mentions endpoint now has an extra (optional) sort parameter to retrieve mentions in the order you like; from new to old, from old to new, by latest edit date, etc.
/tools/sentiment endpoint has been updated to use our improvement sentiment detection algorithm, and also accepts an optional language parameter if you want to bypass our automatic language detection.
source.service, showing if a mention is from "twitter", "facebook", or other known service has been added to the Mention Object. This is now recommended over the source.type field which contains more internal names for our services (eg. SearchProviderTwitter for Twitter).
assignment of the Mention Object
has been split into assignment.user_ids and assignment.comment.
?fields=name,plan,projects.limit(1).fields(name,topics) to the /me/accounts endpoint.meta.etag with the etag for that response.meta.error, meta.error_description and meta.error_details of the Response Envelope have been removed. Non-fatal errors (and warnings) will now be of type message in the meta.messages field.
?format=xml if you want the response to be in the XML format, instead of the default JSON. Click "Advanced" in the API Test Console to try it out.