Social Media, Chat and Messaging Documentation

Introduction

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

https://api-prd.kpn.com/communication/tracebuzz/social-media-webcare

Conceptual model

Definitions

Account

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.

Case

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.

Handler

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

Person

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.

Profile

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

Result

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

Search

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

Source

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.

User

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

API workflow

Requirements

• 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

Features

• 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.

Constraints

• 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.

Authentication

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:

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.

Request

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.

Request

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.

Request

GET /results/{resultId}

Retrieve information for 1 specific result ID without context

Retrieves information for 1 specific result ID.

Request

Get /results/{resultId}/noContext)

Post reply

Replies to a message.

Request

POST /results/{resultId}/replies

Post event

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

Request

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

      Response
      
        Code copied
        
            
      

{
    "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