API menu

Social Media, Chat and Messaging Documentation


Engage with your customers using the Parley Webcare API. This API lets you track and respond to messages directed to you on social media such as Twitter, Facebook, Instagram, WhatsApp, Forums or many more.

API specification

Test the API on SwaggerHub

Base URL


Conceptual model

Documentation page Tracebuzz SocialMediaWebcare conceptual model



The highest entity in our system. Anything in Parley always belongs to an account. A business has one account, even with multiple brands you will usually only have 1 account.


A case is a (part of) a conversation with a person on one or multiple sources. This will contain multiple results indicating a back and forth conversation between the person and the account.


A handler is an agent/centralist who is in charge of the conversation on a case.


Someone who contacts your business through one or multiple of the sources we support. We can group your profile on Twitter, Facebook and more under one person.


The profile of a person as created on a specific source.


A single message, comment, post, for example on the source.


Social media posts and private messages (results) are saved in a search profile. When querying results in a search profile, filters can be applied.


This refers to Facebook, Twitter, WhatsApp, Parley, etc. and is where we get the data in our application from. Any results, profiles, etc. will come from a source.


A (usually human) user of the Tracebuzz application or API.

API workflow

Documentation page Tracebuzz Webcare workflow


  • This API is useable for KPN employees and partners only.
  • A Tracebuzz instance has to be available to you, in order to make use of this API.

Features and constraints


  • Receive all messages in a search profile, with the option to filter.
  • Respond to incoming messages or messages in which you are mentioned.
  • Sentiment analysis.
  • Send events to the platform.


  • Cases are bound by source type. For example, messages on WhatsApp or Facebook coming from the same person, will be handled as 2 separate cases.

Getting started

Make sure you've read What's in it for you for more info on how to register and start testing APIs.


The API follows the KPN Store API Authentication Standard to secure the API. It includes the use of OAuth 2.0 client_id and client_secret to receive an access token.

Go to the Authentication tab on top of this page to find out how to:

  • Authenticate to an API using cURL.
  • Authenticate to an API on Swaggerhub.
  • Import Open API Specifications (OAS), also called Swagger files into Postman.

Result management

You may reply on results that have the parameter replyAvailable set to true. When supported by the platform, events such as startTyping and stopTyping can be used to indicate to the end user that the agent is working on a reply. A key component of result management is filtering the result set. Many filters can be applied to the result set. Possible filters are:

Filter option   Format  
Search profile   /search+profile+name/  
Source   /source:twitter,facebook,instagram,linkedin,whatsapp,blogs,forums,news,web,print,rtv,irischat/  
Sentiment   /very+negative,negative,neutral,positive,very+positive/  
Period   /2016-06-15T23:31:27,2016-06-22T23:59:59/ (UTC/GMT) (can also be /day/, /week/, /month/ or /year/)  
Category   /category:category+name/  
Label   /label:label+name/  
Hashtag   /hashtag:hashtag/  
Website   /website:website+URL/  
Word   /word:word/  
Profile   /profile:profile+name/  
Country   /country:country+name/  
City   /city:city+name/  
Municipality   /municipality:municipality+name/  
Province   /province:province+name/  
Result   /result:resultId/ (or comma separated resultIds)  
Assigned   /assigned:userId/  
Order   /most+recent/ or /least+recent/  
Since id   /sinceId:resultId  
New results   /new+results:true/ or /new+results:reset/  
Limit   /limit:25/  
Offset   /offset:100/  
Checked results   /checked/ or /notChecked/  

Case management

Cases can be accessed by means of searches. The searchId's that you will have to provide can be found in the configuration. With a case (caseId) you can:

  • Close the case.
  • Release the case to a handler.
  • Release a handler from the case.

How to...

Retrieve the access token

The single sign-on accessToken will be regenerated for the given user each time that this call is executed. An expiry date/time is given as a response.


GET /ssoAccessToken/{email}

Get Configuration

The configuration request retrieves information about the current account. It returns a lot of information including:

  • Social platforms configured.
  • Status messages definition.
  • Account settings.
    • Search profiles setup.
  • (Sub)Tabs configuration.

The request also returns some default parameters that help you understand the integers we return.


GET /configuration

Retrieve information for 1 specific result ID

Retrieves information for 1 specific result ID. By default it returns a limit of 10 and excludes deleted messages.


GET /results/{resultId}

Path parameter Type Description
resultId* integer The unique result ID.

Retrieve information for 1 specific result ID without context

Retrieves information for 1 specific result ID.


Get /results/{resultId}/noContext)

Path parameter Type Description
resultId* integer The unique result ID.

Post reply

Replies to a message.


POST /results/{resultId}/replies

Path parameter Type Description
resultId* integer The unique result ID.
Body parameter Type Description
message string The content of the message.
connectionId* integer The connection ID.
public* boolean Set public=false if you want to reply private on a public message.

Post event

Starts or stops typing on a message. Opens or closes a message.


POST /results/{resultId}/event/{event}

Path parameter Type Description
event* string Possible events: starttyping, stoptyping, closed, opened`.
resultId* integer The unique result ID.
{ "data": {}, "messages": [], "status": "SUCCES", "metadata": { "values": { "url": "results/233/event/opened" }, "method": "post", "duration": 0.011 } }

Close case

Handler releases case to handler

Handler releases from case