diff --git a/scripts/redoc.js b/scripts/redoc.js index 94dd725f5..11f8f5740 100644 --- a/scripts/redoc.js +++ b/scripts/redoc.js @@ -35,6 +35,7 @@ async function generateRedocHtml(name) { async function runAll() { await generateRedocHtml("global-accounts-api"); await generateRedocHtml("customer-accounts-api"); + await generateRedocHtml("customer-data-platform-api"); } runAll(); diff --git a/src/components/Page/index.js b/src/components/Page/index.js index a3a059309..a30f1b89b 100644 --- a/src/components/Page/index.js +++ b/src/components/Page/index.js @@ -166,6 +166,7 @@ const Page = ({ frontMatter, children }) => { "customer-accounts-api", "text-api", "chat-api", + "customer-data-platform-api", ].includes(subcategory) || ["Chat API"].includes(title); return ( diff --git a/src/configs/redoc/configs.js b/src/configs/redoc/configs.js index e01b60eb0..f283afb1f 100644 --- a/src/configs/redoc/configs.js +++ b/src/configs/redoc/configs.js @@ -1,11 +1,13 @@ const globalAccountsApiConfig = require("./global-accounts-api/config"); const customerAccountsApiConfig = require("./customer-accounts-api/config"); const textApiConfig = require("./text-api/config"); +const customerDataPlatformApiConfig = require("./customer-data-platform-api/config"); const configs = { "global-accounts-api": globalAccountsApiConfig, "customer-accounts-api": customerAccountsApiConfig, "customer-accounts-api-v2": customerAccountsApiConfig, + "customer-data-platform-api": customerDataPlatformApiConfig, "text-api": textApiConfig, }; diff --git a/src/configs/redoc/customer-data-platform-api/config.js b/src/configs/redoc/customer-data-platform-api/config.js new file mode 100644 index 000000000..6597c5ebb --- /dev/null +++ b/src/configs/redoc/customer-data-platform-api/config.js @@ -0,0 +1,29 @@ +module.exports = { + scrollYOffset: "180", + disableSearch: true, + hideLoading: true, + theme: { + colors: { + primary: { + main: "#424d57", + }, + }, + typography: { + fontSize: "16px", + fontFamily: "Source Sans Pro,Helvetica Neue,Helvetica,Roboto,sans-serif", + headings: { + fontFamily: + "Source Sans Pro,Helvetica Neue,Helvetica,Roboto,sans-serif", + }, + }, + sidebar: { + width: "260px", + backgroundColor: "#f6f6f7", + textColor: "#424d57", + activeTextColor: "#4384f5", + arrow: { + size: "1.2em", + }, + }, + }, +}; diff --git a/src/configs/redoc/customer-data-platform-api/spec.yml b/src/configs/redoc/customer-data-platform-api/spec.yml new file mode 100644 index 000000000..bbc69457a --- /dev/null +++ b/src/configs/redoc/customer-data-platform-api/spec.yml @@ -0,0 +1,921 @@ +openapi: 3.0.0 +info: + title: Customer Data Platform API + description: + Customer Data Platform API is a service for collecting, storing, and + managing end-user data. + version: 0.0.1 +servers: + - url: https://api.text.com/cdp +paths: + "/get_customer": + post: + summary: Get customer + description: "Returns customer's data. Required scope: 'customers:ro'" + parameters: + - "$ref": "#/components/parameters/AuthHeader" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + customer_id: + type: string + format: uuid + description: Requested customer's ID + responses: + "200": + description: customer + content: + application/json: + schema: + "$ref": "#/components/schemas/Customer" + "401": + description: Invalid access token + "403": + description: Insufficient scopes + "404": + description: Customer not found + "422": + description: Invalid request body + "500": + description: Internal error + "/get_merged_customer": + post: + summary: Get merged customer + description: "Returns merged customer's data. Required scope: 'customers:ro'" + parameters: + - "$ref": "#/components/parameters/AuthHeader" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + customer_id: + type: string + format: uuid + description: Requested customer's ID + responses: + "200": + description: customer + content: + application/json: + schema: + "$ref": "#/components/schemas/Customer" + "401": + description: Invalid access token + "403": + description: Insufficient scopes + "404": + description: Customer not found + "422": + description: Invalid request body + "500": + description: Internal error + "/get_merged_customer_chats": + post: + summary: Get merged customer chat IDs + description: "Returns merged customer's chat IDs. Required scope: 'customers:ro'" + parameters: + - "$ref": "#/components/parameters/AuthHeader" + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - customer_id + properties: + customer_id: + type: string + format: uuid + description: Requested customer's ID + responses: + "200": + description: customer + content: + application/json: + schema: + type: object + properties: + chat_ids: + type: array + items: + type: string + format: uuid + description: Requested customer's chat IDs + "401": + description: Invalid access token + "403": + description: Insufficient scopes + "404": + description: Customer not found + "422": + description: Invalid request body + "500": + description: Internal error + "/get_merged_customer_tickets": + post: + summary: Get merged customer ticket IDs + description: "Returns merged customer's ticket IDs. Required scope: 'customers:ro'" + parameters: + - "$ref": "#/components/parameters/AuthHeader" + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - customer_id + properties: + customer_id: + type: string + format: uuid + description: Requested customer's ID + silo: + type: string + enum: + - inbox + - archive + - spam + - trash + description: Optional ticket silo filter + responses: + "200": + description: customer + content: + application/json: + schema: + type: object + properties: + ticket_ids: + type: array + items: + type: string + format: uuid + description: Requested customer's ticket IDs + "401": + description: Invalid access token + "403": + description: Insufficient scopes + "404": + description: Customer not found + "422": + description: Invalid request body + "500": + description: Internal error + "/v1/list_customers": + post: + summary: v1/List customers + description: + "Search and list customers with filtering, sorting, and pagination. + Required scope: 'customers:ro'" + parameters: + - "$ref": "#/components/parameters/AuthHeader" + requestBody: + required: true + content: + application/json: + schema: + "$ref": "#/components/schemas/ListCustomersRequest" + examples: + simple_search: + summary: Simple free-text search + value: + query: john + results_per_page: 50 + advanced_filters: + summary: Advanced filtering with multiple criteria + value: + query: john + filters: + - operator: AND + clauses: + - field: name + operator: contains + values: + - john + - jane + - field: country + operator: is + values: + - Poland + - Latvia + negate: true + - field: last_activity + operator: range + range: + from: "2025-01-01T00:00:00Z" + to: "2025-03-01T00:00:00Z" + - field: threads_count + operator: range + range: + from: 50 + to: 100 + - field: tickets_count + operator: is + values: + - 10 + results_per_page: 50 + sort: + last_activity: desc + filter_groups_example: + summary: Multiple filter groups with OR logic + value: + filters: + - operator: AND + clauses: + - field: email + operator: is + values: + - user@example.com + - field: threads_count + operator: range + range: + from: 10 + to: 100 + - operator: OR + clauses: + - field: name + operator: exists + - field: phone_number + operator: starts_with + values: + - "+48" + - "+121" + results_per_page: 25 + responses: + "200": + description: List of customers matching search criteria + content: + application/json: + schema: + "$ref": "#/components/schemas/ListCustomersResponse" + example: + customers: + - customer_id: cf89fa3a-5ee9-4bdb-84ec-38824b2e2786 + organization_id: b7eff798-f8df-4364-8052-649c35c9ed0c + product: livechat + monitoring: + custom_fields: + statistics: + next_page_id: "2" + total: 1523 + page_id: "1" + "400": + description: Invalid request (validation error) + content: + application/json: + schema: + type: object + properties: + error: + type: string + example: + "validation error: invalid field 'city'. Allowed fields: + name, email, phone_number, country, and statistics fields" + "401": + description: Invalid access token + "403": + description: Insufficient scopes + "422": + description: Invalid request body + "500": + description: Internal error +components: + parameters: + AuthHeader: + name: Authorization + in: header + required: true + schema: + type: string + description: + A valid access token, either an OAuth2 Token (Bearer) or a Personal + Access Token (Basic). + schemas: + Customer: + type: object + required: + - customer_id + - organization_id + - product + - monitoring + - custom_fields + - statistics + properties: + customer_id: + type: string + format: uuid + organization_id: + type: string + format: uuid + product: + type: string + example: livechat + monitoring: + oneOf: + - "$ref": "#/components/schemas/Monitoring" + - type: "null" + custom_fields: + oneOf: + - "$ref": "#/components/schemas/CustomFields" + - type: "null" + statistics: + oneOf: + - "$ref": "#/components/schemas/Statistics" + - type: "null" + chat: + "$ref": "#/components/schemas/Chat" + invitation: + "$ref": "#/components/schemas/Invitation" + tickets: + type: object + additionalProperties: + "$ref": "#/components/schemas/Ticket" + omnichannel: + "$ref": "#/components/schemas/Omnichannel" + orders: + type: array + items: + "$ref": "#/components/schemas/Order" + Monitoring: + type: object + required: + - name + - email + - avatar_url + - phone_number + - session_fields + - visits + - version + - state + - online + - current_group_ids + - created_at + - master_id + properties: + name: + type: string + email: + type: string + avatar_url: + type: string + phone_number: + type: string + session_fields: + type: array + items: + type: object + properties: + key: + type: string + value: + type: string + visits: + type: array + items: + "$ref": "#/components/schemas/Visit" + version: + type: integer + state: + "$ref": "#/components/schemas/MonitoringState" + online: + type: boolean + current_group_ids: + type: array + items: + type: integer + created_at: + type: string + format: date-time + master_id: + type: string + format: uuid + MonitoringState: + type: string + enum: + - "" + - browsing + - queued + - invited + - chatting + - chat closed + - offline + Visit: + type: object + required: + - id + - started_at + - geolocation + properties: + id: + type: integer + started_at: + type: string + ended_at: + type: string + geolocation: + "$ref": "#/components/schemas/Geolocation" + ip: + type: string + user_agent: + type: string + page_referrer: + type: string + first_visited_page: + "$ref": "#/components/schemas/Page" + pages: + type: array + items: + "$ref": "#/components/schemas/Page" + Page: + type: object + required: + - id + - started_at + - url + - title + - group_ids + properties: + id: + type: integer + started_at: + type: string + url: + type: string + title: + type: string + group_ids: + type: array + items: + type: integer + Geolocation: + type: object + required: + - latitude + - longitude + - country + - country_code + - region + - city + - timezone + properties: + latitude: + type: string + longitude: + type: string + country: + type: string + country_code: + type: string + region: + type: string + city: + type: string + timezone: + type: string + CustomFields: + type: object + additionalProperties: + type: object + additionalProperties: + type: string + example: + 58737b5829e65621a45d598aa6f2ed8e: + phone: 0300 222 0000 + address: Prime Minister's Office, 10 Downing Street + Statistics: + type: object + required: + - chats_count + - threads_count + - visits_count + - page_views_count + - greetings_accepted_count + - greetings_converted_count + - tickets_count + - tickets_inbox_count + - tickets_archive_count + - tickets_spam_count + - tickets_trash_count + - orders_count + properties: + chats_count: + type: integer + threads_count: + type: integer + visits_count: + type: integer + page_views_count: + type: integer + greetings_accepted_count: + type: integer + greetings_converted_count: + type: integer + tickets_count: + type: integer + tickets_inbox_count: + type: integer + tickets_archive_count: + type: integer + tickets_spam_count: + type: integer + tickets_trash_count: + type: integer + orders_count: + type: integer + last_visit_started_at: + type: string + format: date-time + Chat: + type: object + required: + - active + - chat_id + - thread_id + - last_updated_at + - group_ids + properties: + active: + type: boolean + chat_id: + type: string + thread_id: + format: string + last_updated_at: + type: string + format: date-time + group_ids: + type: array + items: + type: integer + Invitation: + type: object + required: + - active + - greeting_id + - greeting_unique_id + - greeting_name + properties: + active: + type: boolean + greeting_id: + type: integer + greeting_unique_id: + format: uuid + greeting_name: + type: string + Ticket: + type: object + required: + - ticket_id + - hd_license_id + - status + - created_at + - last_updated_at + properties: + ticket_id: + type: string + format: uuid + hd_license_id: + type: string + status: + type: string + silo: + "$ref": "#/components/schemas/TicketSilo" + created_at: + type: string + format: date-time + last_updated_at: + type: string + format: date-time + TicketSilo: + type: string + enum: + - inbox + - archive + - spam + - trash + Omnichannel: + type: object + properties: + fbmessenger: + type: array + items: + "$ref": "#/components/schemas/OmnichannelFBMessenger" + twilio: + type: array + items: + "$ref": "#/components/schemas/OmnichannelTwilio" + OmnichannelFBMessenger: + type: object + required: + - id + - is_verified_user + properties: + id: + type: string + format: uuid + name: + type: string + first_name: + type: string + last_name: + type: string + profile_pic: + type: string + format: url + gender: + type: string + locale: + type: string + is_verified_user: + type: boolean + OmnichannelTwilio: + type: object + required: + - phone_number + properties: + phone_number: + type: string + Order: + type: object + required: + - customer_id + - store_platform + - store_uuid + - order_id + - order_number + - currency + - total_price + - created_at + - event_id + - event_client_id + properties: + customer_id: + type: string + format: uuid + store_platform: + type: string + store_uuid: + type: string + format: uuid + order_id: + type: string + order_number: + type: string + currency: + type: string + total_price: + type: number + format: double + created_at: + type: string + format: date-time + event_id: + type: string + format: uuid + event_client_id: + type: string + Clause: + type: object + required: + - operator + properties: + field: + type: string + enum: + - name + - email + - phone_number + - phone_number_country_code + - country + - country_code + - last_activity + - last_visit_started + - visits_count + - page_views_count + - chats_count + - threads_count + - greetings_accepted_count + - greetings_converted_count + - tickets_count + - tickets_inbox_count + - tickets_archive_count + - tickets_spam_count + - tickets_trash_count + - orders_count + description: Field name to filter on (required for all operators) + operator: + type: string + enum: + - contains + - is + - range + - exists + - starts_with + description: | + Filter operator: + - `exists`: Check if field exists/is populated (name, email, phone_number) + - `contains`: Partial string matching (name, email, phone_number) + - `is`: Exact match for single or multiple values (all fields) + - `range`: Range filter for dates or numbers (statistics fields) + - `starts_with`: Prefix match (phone_number only) + values: + type: array + items: + type: string + description: | + Array of values for operators: contains, is, starts_with. + Multiple values are combined with OR logic. + Maximum number of elements: 200. + - For 'starts_with' operator: minimum 3 characters per value + example: + - john + - jane + range: + type: object + properties: + from: + oneOf: + - type: string + format: date-time + - type: integer + description: | + Start of range (inclusive, gte). + For date fields (last_activity, last_visit_started): use RFC3339 date-time strings (e.g., '2025-01-01T00:00:00Z'). + For numeric fields (visits_count, threads_count, etc.): use integers. + to: + oneOf: + - type: string + format: date-time + - type: integer + description: | + End of range (inclusive, lte). + For date fields (last_activity, last_visit_started): use RFC3339 date-time strings (e.g., '2025-03-01T00:00:00Z'). + For numeric fields (visits_count, threads_count, etc.): use integers. + description: + "Range values for 'range' operator. \nFor date fields (last_activity, + last_visit_started): use RFC3339 format date-time strings.\nFor numeric + fields (visits_count, threads_count, etc.): use integers.\n" + example: + from: "2025-01-01T00:00:00Z" + to: "2025-03-01T00:00:00Z" + negate: + type: boolean + default: false + description: Negate the filter (apply NOT logic) + example: + field: name + operator: contains + values: + - john + - jane + FilterGroup: + type: object + required: + - operator + - clauses + properties: + operator: + type: string + enum: + - AND + - OR + description: Logical operator to combine clauses within this group + clauses: + type: array + minItems: 1 + description: Filter clauses to be combined with the specified operator + items: + "$ref": "#/components/schemas/Clause" + example: + operator: AND + clauses: + - field: name + operator: contains + values: + - john + - field: email + operator: exists + ListCustomersRequest: + type: object + properties: + query: + type: string + minLength: 3 + description: | + Free-text search query across name, email, and phone_number fields. + Automatically excludes fields that are explicitly filtered. + Minimum length: 3 characters. + example: john smith + filters: + type: array + description: Filter groups combined with AND logic at the top level + items: + "$ref": "#/components/schemas/FilterGroup" + results_per_page: + type: integer + minimum: 1 + maximum: 100 + default: 50 + description: | + Number of results to return per page. + Default: 50, Maximum: 100 + sort: + type: object + description: | + Sorting configuration (field -> order mapping). + Multiple sort fields can be specified. + Note: 'created_at' is always appended as the final sort field to ensure stable pagination. + additionalProperties: + type: string + enum: + - asc + - desc + example: + last_activity: desc + name: asc + page_id: + type: string + description: | + Page identifier for pagination. Should be a numeric string starting from "1". + Use the 'next_page_id' from the previous response to navigate to the next page. + Example: "1", "2", "3", etc. + example: "1" + example: + query: john + filters: + - operator: AND + clauses: + - field: name + operator: contains + values: + - john + - jane + - field: email + operator: is + values: + - user@example.com + - contact@example.com + - field: country_code + operator: is + values: + - US + negate: true + - field: last_activity + operator: range + range: + from: "2025-01-01T00:00:00Z" + to: "2025-03-01T00:00:00Z" + - field: threads_count + operator: range + range: + from: 50 + to: 100 + - operator: OR + clauses: + - field: name + operator: exists + - field: email + operator: exists + results_per_page: 50 + sort: + last_activity: desc + name: asc + page_id: "1" + ListCustomersResponse: + type: object + required: + - customers + - total + - page_id + properties: + customers: + type: array + items: + "$ref": "#/components/schemas/Customer" + description: Array of customer objects matching the search criteria + next_page_id: + type: string + description: | + Page identifier for the next page of results. + Empty string if there are no more pages. + Pass this value as 'page_id' in the next request to retrieve the next page. + example: "2" + total: + type: integer + format: int32 + description: Total number of customers matching the search criteria + example: 1523 + page_id: + type: string + description: Current page identifier + example: "1" diff --git a/src/configs/redoc/specs.js b/src/configs/redoc/specs.js index 221520354..0289306ce 100644 --- a/src/configs/redoc/specs.js +++ b/src/configs/redoc/specs.js @@ -2,12 +2,14 @@ const globalAccountsApiSpec = require("./global-accounts-api/spec.yml"); const customerAccountsApiSpec = require("./customer-accounts-api/spec.yml"); const customerAccountsApiSpecv2 = require("./customer-accounts-api/specv2.yml"); const textApiSpec = require("./text-api/spec.yml"); +const customerDataPlatformSpec = require("./customer-data-platform-api/spec.yml"); const specs = { "global-accounts-api": globalAccountsApiSpec, "customer-accounts-api": customerAccountsApiSpec, "customer-accounts-api-v2": customerAccountsApiSpecv2, "text-api": textApiSpec, + "customer-data-platform-api": customerDataPlatformSpec, }; module.exports = specs; diff --git a/src/pages/management/customer-data-platform-api/index.mdx b/src/pages/management/customer-data-platform-api/index.mdx new file mode 100644 index 000000000..0b5c34eb7 --- /dev/null +++ b/src/pages/management/customer-data-platform-api/index.mdx @@ -0,0 +1,12 @@ +--- +weight: 25 +category: "management" +subcategory: "customer-data-platform-api" +title: Customer Data Platform +tagline: "Learn how to use the Customer Data Platform API to manage end-user data." +desc: "Find out how to access and manage end-user data through the Customer Data Platform API." +--- + +import Redoc from "../../../components/extensions/Redoc"; + +