openapi: 3.0.0 info: contact: email: api_developer@kpn.com name: API Support url: https://developer.kpn.com/support description: | The SocialMediaWebcare API allows you to organise and manage your inbound and outbound social media channels traffic. ### Key highlights - **Security:** HTTPS, Oauth, Rate limit - **Versioning:** supports version-less API, version tight. If no version is provided (in header) it defaults to latest version. ## Getting Started ## [Source view](https://app.swaggerhub.com/apis/kpn/SocialMediaWebcare-Tracebuzz/)
[Documentation view](https://app.swaggerhub.com/apis-docs/kpn/SocialMediaWebcare-Tracebuzz/) --- ## [KPN Developer](https://developer.kpn.com/)
[Getting Started](https://developer.kpn.com/getting-started) --- termsOfService: https://developer.kpn.com/legal title: SocialMediaWebcare - Tracebuzz version: "1.0.0" tags: - name: OAuth 2.0 description: 'Authentication' - name: Results description: 'All about managing results' - name: Configuration description: 'All about configuring Tracebuzz' - name: Cases description: 'All about case handling' servers: - url: https://api-prd.kpn.com/communication/tracebuzz/social-media-webcare variables: {} externalDocs: description: HTTP response headers url: https://developer.kpn.com/documentation-response-headers paths: /configuration: get: deprecated: false description: The configuration contains a lot of information about the current account. Available searches, social media connections, users, etc., and some default parameters that help you understand some of the integers we return. operationId: Configuration security: - oauth2: [] parameters: [] responses: 200: $ref: '#/components/responses/config_result' 400: $ref: '#/components/responses/bad_request' 401: $ref: '#/components/responses/unauthorized' 403: $ref: '#/components/responses/forbidden' 404: $ref: '#/components/responses/not_found' 405: $ref: '#/components/responses/method_not_allowed' 412: $ref: '#/components/responses/precondition_failed' 429: $ref: '#/components/responses/too_many' 500: $ref: '#/components/responses/server_error' 502: $ref: '#/components/responses/bad_gateway' 503: $ref: '#/components/responses/service_unavailable' summary: Configuration tags: - Configuration /results/{profilename}/source:{media}: get: deprecated: false description: | Use filters to retrieve results. You need to add the `profilename` and the `media`. If you are in the Traceboard dashboard, you can find the string with filters in the URL. All filters can be used within the string. Example URL: `/test-profile/source:twitter/word:aloha/` **media** - twitter - facebook - instagram - google+plus - linkedin - whatsapp - blogs - forums - news - web - print - rtv - irischat operationId: Result security: - oauth2: [] parameters: - description: 'Enter the profile name, for example: `/demo1`.' explode: false in: path name: profilename required: true schema: type: string style: simple - description: 'Enter the media, for example`/source:twitter`' explode: false in: path name: media required: true schema: type: string style: simple responses: 200: $ref: '#/components/responses/fetch_result' 400: $ref: '#/components/responses/bad_request' 401: $ref: '#/components/responses/unauthorized' 403: $ref: '#/components/responses/forbidden' 404: $ref: '#/components/responses/not_found' 405: $ref: '#/components/responses/method_not_allowed' 412: $ref: '#/components/responses/precondition_failed' 429: $ref: '#/components/responses/too_many' 500: $ref: '#/components/responses/server_error' 502: $ref: '#/components/responses/bad_gateway' 503: $ref: '#/components/responses/service_unavailable' summary: Result tags: - Results /results/{resultId}/noContext: get: deprecated: false description: 'Retrieves information for 1 specific `resultId`. Retrieves all information for a result object.' operationId: ResultWithoutContext security: - oauth2: [] parameters: - description: '' explode: false in: path name: resultId required: true schema: type: string style: simple responses: 200: $ref: '#/components/responses/fetch_result' 400: $ref: '#/components/responses/bad_request' 401: $ref: '#/components/responses/unauthorized' 403: $ref: '#/components/responses/forbidden' 404: $ref: '#/components/responses/not_found' 405: $ref: '#/components/responses/method_not_allowed' 412: $ref: '#/components/responses/precondition_failed' 429: $ref: '#/components/responses/too_many' 500: $ref: '#/components/responses/server_error' 502: $ref: '#/components/responses/bad_gateway' 503: $ref: '#/components/responses/service_unavailable' summary: Retrieves results without context tags: - Results /results/{resultId}/replies: post: deprecated: false description: 'This endpoint allows you to reply to a message' operationId: Reply security: - oauth2: [] parameters: - description: 'Use `application/x-www-form-urlencoded`.' explode: false in: header name: Content-Type required: true schema: example: application/x-www-form-urlencoded type: string style: simple - description: 'Enter the unique `resultId`.' explode: false in: path name: resultId required: true schema: example: 233 format: int32 type: integer style: simple requestBody: content: application/x-www-form-urlencoded: schema: properties: connectionId: example: 1451 format: int32 type: integer description: ConnectionId message: example: '@pranavsnazzy ok' type: string description: Message content public: example: true type: boolean description: Set `public=false` if you want to reply private to a public message. required: - message - connectionId - public type: object required: false responses: 200: $ref: '#/components/responses/reply_result' 400: $ref: '#/components/responses/bad_request' 401: $ref: '#/components/responses/unauthorized' 403: $ref: '#/components/responses/forbidden' 404: $ref: '#/components/responses/not_found' 405: $ref: '#/components/responses/method_not_allowed' 412: $ref: '#/components/responses/precondition_failed' 429: $ref: '#/components/responses/too_many' 500: $ref: '#/components/responses/server_error' 502: $ref: '#/components/responses/bad_gateway' 503: $ref: '#/components/responses/service_unavailable' summary: Replies to a message tags: - Results /results/{resultId}/event/{event}: post: deprecated: false description: | Start or stop typing on a message. Open or close a message. operationId: Event security: - oauth2: [] parameters: - description: 'Enter the `resultId`.' explode: false in: path name: resultId required: true schema: type: string style: simple - description: 'Possible events: `starttyping`, `stoptyping`, `closed`, `opened`.' explode: false in: path name: event required: true schema: type: string style: simple responses: 200: $ref: '#/components/responses/result_event' 400: $ref: '#/components/responses/bad_request' 401: $ref: '#/components/responses/unauthorized' 403: $ref: '#/components/responses/forbidden' 404: $ref: '#/components/responses/not_found' 405: $ref: '#/components/responses/method_not_allowed' 412: $ref: '#/components/responses/precondition_failed' 429: $ref: '#/components/responses/too_many' 500: $ref: '#/components/responses/server_error' 502: $ref: '#/components/responses/bad_gateway' 503: $ref: '#/components/responses/service_unavailable' summary: Message events tags: - Results /searches/{searchId}/cases/{caseId}/close: post: deprecated: false description: This method let's you close the case. operationId: CloseCase security: - oauth2: [] parameters: - description: 'The search id for that search profile.' explode: false in: path name: searchId required: true schema: type: string style: simple - description: 'The case id for that case..' explode: false in: path name: caseId required: true schema: type: string style: simple responses: 200: $ref: '#/components/responses/case_result' 400: $ref: '#/components/responses/bad_request' 401: $ref: '#/components/responses/unauthorized' 403: $ref: '#/components/responses/forbidden' 404: $ref: '#/components/responses/not_found' 405: $ref: '#/components/responses/method_not_allowed' 412: $ref: '#/components/responses/precondition_failed' 429: $ref: '#/components/responses/too_many' 500: $ref: '#/components/responses/server_error' 502: $ref: '#/components/responses/bad_gateway' 503: $ref: '#/components/responses/service_unavailable' summary: Closes case tags: - Cases /searches/{searchId}/cases/{caseId}/close/handOverToHandler/{handlerId}: post: deprecated: false description: This method let's you assign your case to another handler. operationId: HandlerReleasesCaseToHandler security: - oauth2: [] parameters: - description: '' explode: false in: path name: searchId required: true schema: type: string style: simple - description: '' explode: false in: path name: caseId required: true schema: type: string style: simple - description: '' explode: false in: path name: handlerId required: true schema: type: string style: simple responses: 200: $ref: '#/components/responses/case_result' 400: $ref: '#/components/responses/bad_request' 401: $ref: '#/components/responses/unauthorized' 403: $ref: '#/components/responses/forbidden' 404: $ref: '#/components/responses/not_found' 405: $ref: '#/components/responses/method_not_allowed' 412: $ref: '#/components/responses/precondition_failed' 429: $ref: '#/components/responses/too_many' 500: $ref: '#/components/responses/server_error' 502: $ref: '#/components/responses/bad_gateway' 503: $ref: '#/components/responses/service_unavailable' summary: Releases case to another handler tags: - Cases /searches/{searchId}/cases/{caseId}/releaseHandler: post: deprecated: false description: This method let's you release the case. operationId: HandlerReleasesFromCase security: - oauth2: [] parameters: - description: '' explode: false in: path name: searchId required: true schema: type: string style: simple - description: '' explode: false in: path name: caseId required: true schema: type: string style: simple responses: 200: $ref: '#/components/responses/case_result' 400: $ref: '#/components/responses/bad_request' 401: $ref: '#/components/responses/unauthorized' 403: $ref: '#/components/responses/forbidden' 404: $ref: '#/components/responses/not_found' 405: $ref: '#/components/responses/method_not_allowed' 412: $ref: '#/components/responses/precondition_failed' 429: $ref: '#/components/responses/too_many' 500: $ref: '#/components/responses/server_error' 502: $ref: '#/components/responses/bad_gateway' 503: $ref: '#/components/responses/service_unavailable' summary: Releases handler from case tags: - Cases components: parameters: api_version: description: API Version. If no version is provided it defaults to latest version. in: header name: api-version required: false schema: type: string api_version_query: description: API Version. If no version is provided it defaults to latest version. in: query name: api-version required: false schema: type: string responses: get_configuration: description: OK content: application/json: schema: type: object properties: configuration: type: array items: $ref: '#/components/schemas/configuration' tabs: type: array items: $ref: '#/components/schemas/tab' subtabs: type: array items: $ref: '#/components/schemas/subtab' results_no_context: description: OK content: application/json: schema: type: object properties: activities: type: array description: This is an array with all the activities for this result. items: $ref: '#/components/schemas/activity' earlierContact: type: boolean description: If there is ealier contact with the author from the result. authorNotes: type: boolean description: Notes belonging to the author. For some accounts this value is set. notes: type: array description: Notes that belong to this result. items: type: string description: This is the text for the note relatedNotes: type: string description: Notes by other messages from this author conversationNotes: type: string description: Notes by comments from this message draft: type: string description: Drafts contain messages that needs to be send later. It will be saved if it is a private message, the user who did it, the connectionId and possibly an imageurl. availableConnections: type: array description: For each availableConnection an object with values for the connection items: {} defaultConnection: type: integer description: This is the same as the availableConnection that is used by default. replyPrefix: type: string description: The message at the beginning of a new reply. For Twitter this will be the persons that you would like to mention replySuffix: type: string description: This is the message after a new reply. For Twitter this will be the initials from the current user ^MK for example kanaActions: type: object description: All kana activities. The possible actions for this account. Example actions are reply and log. uniqueId: type: integer description: Unique id for the message searchId: type: integer description: Search id for the message link: type: string description: URL to the source profileId: type: string description: Contains the unique id of the social profile that authored/send this message. For Twitter this contains the username (@name) instead of an id. description: type: string description: content for the message private: type: boolean description: Private message or public message on platform replies: type: array description: Replies result array. The uniqueId is the key for the array. items: type: string description: Reply message twitterFavorite: type: boolean description: Is this post bookmarked image: type: string description: First found image in the resultId. Only images from the message not from profile information are in this URL. imageLink: type: string description: Location for the profile image (URL) time: type: string description: Time stamp placed time for the message on the platform status: type: integer description: Status for the message own: type: integer description: Own set to 1 for all the messages from your own company. 0 for message from customer source: type: integer description: Full list with sources is available in configuration -> global -> source type: type: integer description: Type message 1=page, 2=post, 3=comment, 4=private message, 5=ad bookmarked: type: integer description: Bookmarked is 1 if the result is in the bookmarked list tbrank: type: integer description: Rank that Tracebuzz added to this result as important checked: type: integer description: When is the message checked by a engagement user sentiment: type: integer description: -1 negative, 0 neutral, 1 positive title: type: string description: Title for the message subtitle: type: string description: Subtitle for the message tagsList: type: array description: All the labels added to the result items: $ref: '#/components/schemas/taglist' personId: type: string description: Id for the author of the message. If the message is from company it should state the personId from the person that you reply to caseId: type: string description: Id for the case of the message fetch_result: description: OK content: application/json: schema: $ref: '#/components/schemas/get_result' reply_result: description: OK content: application/json: schema: $ref: '#/components/schemas/post_result' case_result: description: OK content: application/json: schema: $ref: '#/components/schemas/case_result' config_result: description: OK content: application/json: schema: $ref: '#/components/schemas/config_result' result_event: description: OK content: application/json: schema: $ref: '#/components/schemas/post_result' bad_gateway: content: application/json: schema: $ref: '#/components/schemas/error' description: bad gateway bad_request: content: application/json: schema: $ref: '#/components/schemas/error' description: bad request forbidden: content: application/json: schema: $ref: '#/components/schemas/error' description: forbidden method_not_allowed: content: application/json: schema: $ref: '#/components/schemas/error' description: method not allowed not_found: content: application/json: schema: $ref: '#/components/schemas/error' description: not found precondition_failed: content: application/json: schema: $ref: '#/components/schemas/error' description: precondition failed server_error: content: application/json: schema: $ref: '#/components/schemas/error' description: server error service_unavailable: content: application/json: schema: $ref: '#/components/schemas/error' description: Service unavailable too_many: content: application/json: schema: $ref: '#/components/schemas/error' description: too many requests unauthorized: content: application/json: schema: $ref: '#/components/schemas/error' description: unauthorized schemas: tab: properties: filters: type: string description: What filters are used for each tab (written in code) name: type: string description: What is the name for the tab action: type: string description: What should happen with the results onChangeSetChecked: type: boolean description: If the found resultats needs to be changed, set this on true of false. subtab: properties: name: type: string description: Name of subtab. shortname: type: string description: Shorter name of subtab. filters: type: string description: What filters are used (written in code). activity: type: array items: type: object properties: id: type: integer description: Id from the activity resultId: type: integer description: ResultId from the result memberId: type: integer description: Id from the account that did the activity. actor: type: integer description: User that did the activity actorUser: type: object description: Account Object activity: type: integer description: Activity type (you can lookup what the meaning for the Integer is configuration -> globals -> activities) subject: type: string description: The subject is depending on the type activity, for example 'Reply by activity 19 (log verint express)'. result: type: string description: Result for the activity time: type: string description: Timestamp in seconds when the activity took place taglist: type: array items: type: object description: Id from the label used as a key for the array properties: id: type: integer description: Id for the label for the array name: type: string description: Name tagged person description: type: string description: Description what the label means active: type: integer description: Online status 1 or 0 visibleInWebcare: type: integer description: If the label is visible in engagement view 1 or 0 configuration: type: object description: Configuration set properties: lastChange: type: string description: Timestamp of the last change made globals: type: array description: All the GLOBAL tracebuzz information within arrays. items: properties: sources: type: array description: All social platforms that are monitored via Tracebuzz. Each platform has an integer value. properties: key: type: string description: key value: type: integer description: value activities: type: array description: All the possible activities that we can log for each message. Mostly used as an Integer value. Within this list you can lookup what the value means. properties: key: type: string description: key value: type: integer description: value statusses: type: object description: All the possible statusses a message can be in. properties: key: type: string description: key value: type: integer description: value format: type: string description: This is the standard format to present data in the API. account: type: array description: Standard values available for this account. items: properties: memberId: type: string description: id of the member company: type: string description: comany name memberSince: type: string description: date of start membership standaardZoekopdracht: type: string description: default search query users: $ref: '#/components/schemas/user' searches: type: array description: All searches and search profiles. properties: searchid: type: string description: id of the search properties: id: type: string description: id of the search name: type: string description: name of search encodedName: type: string description: same as name but urlencoded visible: type: boolean description: 'true or false for visibility' servicelevel: type: integer description: 'level of service' webcareHideButtons: type: string description: '"0" for no "1" for hiding of webcare buttons' facebookLikeVisible: type: string description: '"0" for no "1" for yes' twitterFavVisible: type: string description: '"0" for no "1" for yes' webcareReplyAuthorOnly: type: string description: '"0" for no "1" for yes' categoriesAndLabels: type: array description: All labels and categories for this account, searchId = key. properties: catlabid: type: string description: 'id of the categorylabel' properties: id: type: string description: the id of the categorylabel name: type: string description: the name of the categorylabel active: type: boolean description: should this be active or not visibleInWebcare: type: boolean description: 'should this be visible in webcare' labels: type: array properties: labelid: type: array description: '' properties: id: type: string description: '' name: type: string description: '' description: type: string description: '' backgroundColor: type: string description: '' active: type: integer description: '' visibleInWebcare: type: string description: '' webcareTabs: type: array description: All possible engagement tabs for the account. properties: filters: type: string description: '' name: type: string description: '' action: type: string description: '' onChangeSetChecked: type: boolean description: '' subTabs: type: array description: '' properties: name: type: string description: '' shortname: type: string description: '' filters: type: string description: '' availableSources: type: array description: All possible sources for the account. properties: source: type: string description: source description user: properties: userid: type: array description: '' properties: memberId: type: string description: '' id: type: string description: '' name: type: string description: '' firstName: type: string description: '' email: type: string description: '' tag: type: string description: '' facebookTag: type: string description: '' admin: type: boolean description: '' sentiment: type: string description: '' response: type: string description: '' settings: type: string description: '' monitoring: type: string description: '' analysis: type: string description: '' reports: type: string description: '' engagement: type: string description: '' presenter: type: string description: '' publisher: type: string description: '' configuration: type: string description: '' qm: type: string description: '' language: type: string description: '' loginSearchId: type: integer description: '' webcareJumpSearchId: type: integer description: '' image: type: string description: '' userUploadedAvatar: type: boolean description: '' get_result: properties: data: type: object messages: type: array default: [] items: type: string status: type: string default: "SUCCES" metadata: type: object properties: values: type: object properties: url: type: integer method: type: string default: "get" duration: type: integer post_result: properties: data: type: object messages: type: array default: [] items: type: string status: type: string default: "SUCCES" metadata: type: object properties: values: type: object properties: url: type: integer method: type: string default: "post" duration: type: integer case_result: properties: data: type: object messages: type: array default: [] items: type: string status: type: string default: "SUCCES" metadata: type: object properties: values: type: object properties: url: type: integer method: type: string default: "post" duration: type: integer config_result: properties: data: type: object messages: type: array default: [] items: type: string status: type: string default: "SUCCES" metadata: type: object properties: values: type: object properties: url: type: integer method: type: string default: "get" duration: type: integer configuration: type: object properties: lastChange: type: string example: "1612430033" globals: type: object properties: sources: type: object example: {"irischat": 14, "facebook": 6,"twitter": 3,} activities: type: object example: {"open": 1,"check": 2,"respond": 3} statusses: type: object example: {"open": 1, "closed": 2, "deleted": 5} format: type: string example: "all" duration: type: integer account: type: object properties: memberId: type: string example: "53453423" company: type: string example: "ABC" memberSince: type: string example: "2021-01-01" standaardZoekopdracht: type: string example: "0" users: type: object searches: type: object connections: type: object categoriesAndLabels: type: object knowledgeBase: type: array default: [] items: type: string currentUser: type: object monitoring: type: string example: "1" result: type: integer example: 1 analysis: type: string example: "1" reports: type: string example: "1" engagement: type: string example: "1" tbmessenger: type: string example: "1" presenter: type: string example: "1" publisher: type: string example: "1" qmModule: type: string example: "1" fbInsights: type: string example: "1" chatModule: type: string example: "0" personView: type: string example: "0" rss: type: string example: null webcareTable: type: string example: null iframe: type: string example: null supportButton: type: string example: "1" workflowModule: type: string example: "1" webcareMagicModule: type: string example: "0" qm: type: string example: null timezone: type: string example: "Europe/Amsterdam" defaultCountry: type: string example: "nl-NL" disableAccount: type: boolean example: false error: properties: info: description: Additional information about error title: Info type: string message: description: Error message title: Error message type: string name: description: Error name title: Error name type: string status: description: Status title: Status type: string transactionId: description: transaction id of the the request title: Transaction ID type: string type: object securitySchemes: oauth2: flows: clientCredentials: tokenUrl: https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials scopes : {} type: oauth2