openapi: 3.1.0 info: title: klink.cloud Public API description: >- Use the K-LINK API to access contacts, tickets, call logs, messaging and more from the klink.cloud customer support platform. version: '1.0' contact: {} tags: - name: Contact - name: Tag - name: Channel - name: Ticket - name: Category - name: CX Log - name: Message - name: Media Manager - name: Agent Activity - name: Telephony - name: User - name: Automation Queue - name: Role - name: Webchat Identity Verification - name: AI Agent paths: /api/v1/contacts: get: summary: Listing deprecated: false description: >- This endpoint allows you to retrieve a paginated list of all your contacts. By default, a maximum of ten contacts are shown per page. **Looking up a contact by phone number:** pass the number in the `phone` query parameter, digits only with no leading `+` (for WhatsApp contacts this is the international number, e.g. `959123456789`). The match is partial, so send the full number and compare `contactPhones[].phone` in the response with your input to confirm an exact hit. An empty `data` array means no contact holds that number. Note: when `keyword` is sent, all other filters are ignored. operationId: ContactController_getAll tags: - Contact parameters: - name: page in: query description: Page number. Defaults to 1. required: false example: 1 schema: type: integer - name: pageSize in: query description: Contacts per page. Defaults to 10. required: false example: 10 schema: type: integer - name: keyword in: query description: >- Free-text search across name, address, notes, channel, company name, email, phone and custom-field values. Matching is case-insensitive and partial: a contact named "Kyaw Kyaw" is found by "kyaw", "Kya", "yaw" or "aw". When keyword is present, all other filters below are ignored. required: false example: kyaw schema: type: string - name: phone in: query description: >- Find contacts by phone number. Case-insensitive partial match against every phone stored on the contact. Send digits only, in the same form Klink stores them: WhatsApp contacts are stored as the international number without a leading "+" (e.g. 959123456789); contacts created from calls or entered manually are stored as typed. To confirm an exact match, compare contactPhones[].phone in the response with your input. Ignored if keyword is also sent. required: false example: '959123456789' schema: type: string - name: email in: query description: >- Find contacts by email address. Case-insensitive partial match against every email stored on the contact. Ignored if keyword is also sent. required: false example: someone@example.com schema: type: string - name: name in: query description: Case-insensitive partial match on the contact name. required: false schema: type: string - name: address in: query description: Case-insensitive partial match on the contact address. required: false schema: type: string - name: notes in: query description: >- Case-insensitive partial match on the contact notes. Ignored if keyword is also sent. required: false schema: type: string - name: channel in: query description: >- Filter by the channel the contact was created from. Repeat the parameter for multiple values (channel[]=whatsapp&channel[]=phone). required: false example: - whatsapp - phone schema: type: array items: type: string - name: company in: query description: >- Filter by company id (UUID). Repeat the parameter for multiple values. required: false schema: type: array items: type: string - name: tags in: query description: >- Filter by tag id (UUID). Repeat the parameter for multiple values. Ignored if keyword is also sent. required: false schema: type: array items: type: string - name: selectedDate in: query description: >- Restrict to contacts created on this date. Interpreted in the Asia/Rangoon (UTC+6:30) timezone. required: false schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: total: type: integer page: type: integer pageSize: type: integer lastPage: type: integer data: type: array items: type: object properties: id: type: string name: type: string address: type: string channel: type: string notes: type: 'null' socialProfileUrl: type: 'null' tags: type: array items: type: object properties: id: type: string name: type: string company: type: object properties: id: type: string name: type: string phone: type: 'null' address: type: 'null' industry: type: 'null' required: - id - name - phone - address - industry contactEmails: type: array items: type: object properties: email: type: string isPrimary: type: boolean contactPhones: type: array items: type: object properties: phone: type: string isPrimary: type: boolean customFields: type: array items: type: object properties: system_name: type: string display_name: type: string type: type: string value: type: string required: - total - page - pageSize - lastPage - data example: total: 65 page: 1 pageSize: 10 lastPage: 7 data: - id: eefdaf75-ed19-4291-8e47-913f1205d02d name: 'Aria ' address: Dagon Seikkan Township channel: phone notes: null socialProfileUrl: null tags: - id: 258fc2c9-738d-4889-806c-0955a3b892c3 name: platinum company: id: 5073bd60-dee4-4866-a798-42c37300171c name: Cool Entreprise phone: null address: null industry: null contactEmails: - email: mistercustomer@gmail.com isPrimary: false contactPhones: - phone: '09797877765' isPrimary: true customFields: - system_name: cf_sector display_name: sector` type: text value: Finance headers: {} security: - apiToken: [] post: summary: Create deprecated: false description: >- This endpoint allows you to add a new contact to your contact list in klink.cloud. To add a contact, you must provide their klink.cloud username and phone number. operationId: ContactController_create tags: - Contact parameters: [] requestBody: content: application/json: schema: type: object required: - username - email - phone properties: username: type: string description: The username for the contact. email: description: >- Accepts one of three formats: (1) an array of objects with email and isPrimary keys, (2) an array of email strings, or (3) a single string of semicolon-separated emails, e.g. "user_a@mih.com; user_b@mih.com;". For formats 2 and 3, the first email is treated as primary. (can be provided as an empty array or empty string) anyOf: - type: array title: Array of email objects description: >- An array of objects which has email and isPrimary as keys. (can be provided as empty array) items: type: object required: - email - isPrimary properties: email: type: string format: email isPrimary: type: boolean additionalProperties: false - type: array title: Array of email strings description: >- An array of email addresses. The first email is treated as primary. items: type: string format: email - type: string title: Semicolon-separated string description: >- One or more email addresses separated by semicolons, e.g. "user_a@mih.com; user_b@mih.com;". Whitespace and trailing semicolons are ignored. The first email is treated as primary. phone: type: array description: >- An array of objects which has phone and isPrimary as keys. (can be provided as empty array) items: type: object required: - phone - isPrimary properties: phone: type: string isPrimary: type: boolean additionalProperties: false company: type: string description: Name of the company associated with the contact. tags: type: array description: >- Associated tags with this contact. (an array of tags'names and will create new tag if not exists) items: type: string channel: type: string description: >- The channel where received the contact. Example: phone, email, viber, etc. (accept only name of the channel you have in app). address: type: string description: Address of the contact. notes: type: string description: The contact's note that saved by agent. customFields: type: object description: A key value pair object with name of custom field as key. additionalProperties: true properties: {} additionalProperties: false example: name: FrankMcCallister email: [] phone: - phone: 1-800-759-3000 isPrimary: true responses: '201': description: '' content: application/json: schema: type: object properties: name: type: string company: type: 'null' id: type: string email: type: array items: type: string phone: type: array items: type: object properties: phone: type: string isPrimary: type: boolean required: - name - company - id - email - phone example: name: FrankMcCallister4 company: null id: b10e10c4-1971-4ed4-ae88-ea571d786b9b email: [] phone: - phone: 1-800-759-3000 isPrimary: true headers: {} security: - apiToken: [] /api/v1/contacts/social-platform: get: summary: Filter By SocialPlatformId deprecated: false description: >- This endpoint allows you to retrieve a contact by providing their klink.cloud base on social media platform Id. Refer to the list at the top of this page to see which properties are included with contact objects. operationId: ContactController_getBySocialPlatformId tags: - Contact parameters: - name: socialPlatformId in: query description: The social platform Id for a channel. required: true schema: type: string - name: channelType in: query description: >- Channel type is only acceptable for "whatsapp", "messenger", "telegram", "instagram", "line", "viber", "shopee", "lazada", "webchat", "facebook_feed". required: false schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: status: type: string message: type: string data: type: array items: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' name: type: string address: type: 'null' channel: type: string notes: type: 'null' contactNumber: type: string contactProfile: type: string socialProfileUrl: type: string companyId: type: 'null' required: - status - message - data example: status: success message: contact data: - id: ... createdAt: '2025-02-28T07:35:02.659Z' updatedAt: '2025-02-28T07:35:03.978Z' deletedAt: null name: Nway address: null channel: facebook_feed notes: null contactNumber: '15879' contactProfile: ... socialProfileUrl: ... companyId: null headers: {} security: - apiToken: [] /api/v1/contacts/fields: get: summary: Form Fields deprecated: false description: >- This endpoint allows you to get available contact fields including the custom fields you have created. operationId: ContactController_getAllContactCustomFields tags: - Contact parameters: [] responses: '200': description: '' content: application/json: schema: type: object properties: total: type: integer page: type: integer pageSize: type: integer lastPage: type: integer data: type: array items: type: object properties: id: type: string system_name: type: string display_name: type: string type: type: string is_default: type: boolean is_archived: type: boolean is_required: type: boolean is_unique: type: boolean options: type: array items: type: object properties: value: type: string label: type: string is_default: type: boolean required: - value - label - is_default required: - total - page - pageSize - lastPage - data example: total: 49 page: 1 pageSize: 10 lastPage: 5 data: - id: 464b7eef-22ed-435e-9bef-35b58e435eda system_name: channel display_name: Channel type: select is_default: true is_archived: true is_required: true is_unique: false options: - value: phone label: Phone is_default: true - value: G-Mail label: G-Mail is_default: false headers: {} security: - apiToken: [] /api/v1/contacts/{id}: get: summary: Detail deprecated: false description: >- This endpoint allows you to retrieve a contact by providing their klink.cloud id. Refer to the list at the top of this page to see which properties are included with contact objects. operationId: ContactController_getById tags: - Contact parameters: - name: id in: path description: '' required: true example: '' schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: status: type: string message: type: string data: type: object properties: id: type: string name: type: string address: type: 'null' channel: type: 'null' notes: type: 'null' socialProfileUrl: type: string tags: type: array items: type: object properties: id: type: string name: type: string company: type: object properties: id: type: string name: type: string phone: type: 'null' address: type: 'null' industry: type: 'null' required: - id - name - phone - address - industry email: type: array items: type: object properties: email: type: string isPrimary: type: boolean phone: type: array items: type: object properties: phone: type: string isPrimary: type: boolean customFields: type: array items: type: object properties: system_name: type: string display_name: type: string type: type: string value: type: string required: - id - name - address - channel - notes - socialProfileUrl - tags - company - email - phone - customFields required: - status - message - data example: status: success message: contact data: id: c786bb40-a58e-4d60-afe6-061e2b819811 name: FrankMcCallister address: null channel: null notes: null socialProfileUrl: https://assets.protocol.chat/avatars/frank.jpg tags: - id: 4d45ba6c-728e-4ca8-91cb-91bac1572622 name: platinum company: id: 547f2af6-1e6d-420e-aaed-b6448d37fd08 name: K-Link phone: null address: null industry: null email: - email: frankmccallister@gmail.com isPrimary: true phone: - phone: 1-800-759-3000 isPrimary: true customFields: - system_name: demo_test display_name: demo test ddddfee erefesf type: text value: another field headers: {} security: - apiToken: [] patch: summary: Update deprecated: false description: This endpoint allows you to perform an update on a contact. operationId: ContactController_update tags: - Contact parameters: - name: id in: path description: Contact ID required: true example: '' schema: type: string requestBody: content: application/json: schema: type: object properties: username: type: string description: The username for the contact. email: type: array description: >- An array of objects which has email and isPrimary as keys. (can be provided as empty array). Provide empty array to update all fields you have included in request body. items: type: object properties: email: type: string isPrimary: type: boolean required: - email - isPrimary additionalProperties: false phone: type: array description: >- An array of objects which has phone and isPrimary as keys. (can be provided as empty array). Provide empty array to update all fields you have included in request body. items: type: object properties: phone: type: string isPrimary: type: boolean required: - phone - isPrimary additionalProperties: false company: type: string description: Name of the company associated with the contact. tags: type: array description: >- Associated tags with this contact. (an array of tags'names and will create new tag if not exists) items: type: string channel: type: string description: >- The channel where received the contact. Example: phone, email, viber, etc. (accept only name of the channel you have in app). address: type: string description: Address of the contact. notes: type: string description: The contact's note that saved by agent. customFields: type: object description: A key value pair object with name of custom field as key. additionalProperties: true properties: {} required: - username - email - phone additionalProperties: true example: name: FrankMcCallister email: [] phone: - phone: 1-800-759-3000 isPrimary: true responses: '200': description: '' content: application/json: schema: type: object properties: status: type: string message: type: string data: type: 'null' required: - status - message - data example: status: success message: updating contact data: null headers: {} security: - apiToken: [] delete: summary: Delete deprecated: false description: >- This endpoint allows you to delete contacts from your contact list in klink.cloud. Note: This will also delete your conversation with the given contact. operationId: ContactController_delete tags: - Contact parameters: - name: id in: path description: Contact ID required: true example: '' schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: status: type: string message: type: string data: type: 'null' required: - status - message - data example: status: success message: deleting contact data: null headers: {} security: - apiToken: [] /api/v1/contacts/groups: get: summary: Fetch Contact Groups deprecated: false description: >- This endpoint allows you to get contact groups. You can use this endpoint to get ids of contact groups to include in create contact endpoint. operationId: ContactController_getAllContactCustomFields tags: - Contact parameters: [] responses: '200': description: '' content: application/json: schema: type: object properties: total: type: integer page: type: integer pageSize: type: integer lastPage: type: integer data: type: array items: type: object properties: id: type: string value: type: string label: type: string is_default: type: boolean system_name: type: string display_name: type: string type: type: string is_archived: type: boolean is_required: type: boolean is_unique: type: boolean options: type: array items: type: object properties: value: type: string label: type: string is_default: type: boolean required: - value - label - is_default required: - total - page - pageSize - lastPage - data example: total: 49 page: 1 pageSize: 10 lastPage: 5 data: - id: 7b03581e-78d1-47fa-aaf0-8f5b3733a803 value: new label: new is_default: false headers: {} security: - apiToken: [] /api/v1/contacts/{id}/tags: patch: summary: Update tags deprecated: false description: This endpoint allows you to perform an update only tags on a contact. operationId: ContactController_update_tags tags: - Contact parameters: - name: id in: path description: Contact ID required: true example: '' schema: type: string requestBody: content: application/json: schema: type: object properties: tags: type: array description: >- Associated tags with this contact. (an array of tags'names and will create new tag if not exists) items: type: string actionType: type: string enum: - MERGE - REPLACE description: >- MERGE: Appends new tags to the existing tags, keeping all current tags; REPLACE: Discards existing tags and uses only the new tags. required: - tags - actionType additionalProperties: false example: actionType: MERGE tags: - vip - new responses: '200': description: '' content: application/json: schema: type: object properties: status: type: string message: type: string data: type: 'null' required: - status - message - data example: status: success message: Contact tags updated successfully data: null headers: {} '400': description: '' content: application/json: schema: type: object properties: message: type: array items: type: string error: type: string statusCode: type: integer required: - message - error - statusCode example: message: - tags should not be empty - tags must be an array error: Bad Request statusCode: 400 headers: {} security: - apiToken: [] /api/v1/contacts/phone/{phone}: get: summary: Filter By Phone Number deprecated: false description: >- Retrieve a single contact by phone number. The number is compared **digits-only**: a leading `+`, spaces, dashes and brackets in your input are ignored, and every phone stored on a contact is compared the same way. So `+959123456789`, `959123456789` and `959-123-456-789` all resolve to the same contact. WhatsApp contacts are stored as the international number without `+` (the WhatsApp ID); contacts created from calls or entered manually are stored as typed. **When several contacts share the number**, the one where it is the *primary* phone is returned, then the most recently created. Returns the same object as *Detail* (`GET /api/v1/contacts/{id}`), including `platformContacts` and their rooms/channels. - `404` — no contact holds that number. - `400` — the value is not a phone number (must contain digits; only `+`, spaces, dashes and brackets are allowed around them). tags: - Contact parameters: - name: phone in: path description: >- Phone number. Digits with an optional leading +, spaces, dashes or brackets. Compared digits-only. required: true example: '959123456789' schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: status: type: string message: type: string data: type: object properties: id: type: string name: type: string address: type: 'null' channel: type: 'null' notes: type: 'null' socialProfileUrl: type: string tags: type: array items: type: object properties: id: type: string name: type: string company: type: object properties: id: type: string name: type: string phone: type: 'null' address: type: 'null' industry: type: 'null' required: - id - name - phone - address - industry email: type: array items: type: object properties: email: type: string isPrimary: type: boolean phone: type: array items: type: object properties: phone: type: string isPrimary: type: boolean customFields: type: array items: type: object properties: system_name: type: string display_name: type: string type: type: string value: type: string required: - id - name - address - channel - notes - socialProfileUrl - tags - company - email - phone - customFields required: - status - message - data example: status: success message: contact data: id: c786bb40-a58e-4d60-afe6-061e2b819811 name: FrankMcCallister address: null channel: null notes: null socialProfileUrl: https://assets.protocol.chat/avatars/frank.jpg tags: - id: 4d45ba6c-728e-4ca8-91cb-91bac1572622 name: platinum company: id: 547f2af6-1e6d-420e-aaed-b6448d37fd08 name: K-Link phone: null address: null industry: null email: - email: frankmccallister@gmail.com isPrimary: true phone: - phone: 1-800-759-3000 isPrimary: true customFields: - system_name: demo_test display_name: demo test ddddfee erefesf type: text value: another field headers: {} '400': description: '' content: application/json: schema: type: object properties: statusCode: type: integer message: type: array items: type: string error: type: string example: message: - >- phone must be a phone number: digits, optionally with a leading +, spaces, dashes or brackets error: Bad Request statusCode: 400 headers: {} '404': description: '' content: application/json: schema: type: object properties: statusCode: type: integer message: type: string error: type: string example: message: No Contact Found error: Not Found statusCode: 404 headers: {} security: - apiToken: [] /api/v1/tags: get: summary: Listing deprecated: false description: >- This endpoint allows you to retrieve a paginated list of all your tags. By default, a maximum of ten tags are shown per page. You can filter tags by group using the group ```query``` parameter. operationId: TagController_getTags tags: - Tag parameters: - name: group in: query description: 'Available tag groups: general, contact and cdr' required: false example: general schema: type: string enum: - general - contact - cdr responses: '200': description: '' content: application/json: schema: type: array items: type: object properties: id: type: string name: type: string group: type: string example: - id: df06d42a-f47b-4629-abd3-ec587f8b6612 name: coupon group: general headers: {} security: - apiToken: [] /api/v1/channels: get: summary: Listing deprecated: false description: >- This endpoint allows you to retrieve a paginated list of all your channel. By default, a maximum of ten channel are shown per page. operationId: ChannelController_getChannels tags: - Channel parameters: - name: keyword in: query description: >- Search the channels by keywords. You cannot search with a substring. For example, a channel "Kyaw Kyaw" can be looked up using "kyaw", "Kya", "yaw" and "aw". required: false schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: requestId: type: string page: type: integer pageSize: type: integer lastPage: type: integer total: type: integer data: type: array items: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' name: type: string type: type: string brandName: type: string required: - requestId - page - pageSize - lastPage - total - data example: | { "requestId": "557520e4-7197-4d56-8a24-ee8c2782d6e4", "page": 1, "pageSize": 10, "lastPage": 8, "total": 73 "data":[ { "id": "f6154dda-bd9a-4d03-8a77-ff3421070009", "createdAt": "2025-03-02T16:42:53.796Z", "updatedAt": "2025-03-02T16:42:54.078Z", "deletedAt": null, "name": "K-Link BSS UAT DEMO KURO", "type": "line", "brandName": "K-Link BSS UAT DEMO KURO" }, { "id": ............... } ] } headers: {} security: - apiToken: [] post: summary: Create deprecated: false description: >- This endpoint allows you to create a custom channel for your own messaging platform. operationId: ChannelController_createChannel tags: - Channel parameters: [] requestBody: content: application/json: schema: type: object properties: name: type: string brandName: type: string metadata: type: object properties: platform_channel_id: type: string inbound: type: object properties: verify_token: type: string required: - verify_token outbound: type: object properties: url: type: string headers: type: array items: type: object properties: key: type: string value: type: string required: - url - headers required: - platform_channel_id - inbound - outbound required: - name - brandName - metadata example: name: Your Custom Channel Name brandName: Your Custom Channel metadata: platform_channel_id: 03939393k3kk3k3 inbound: verify_token: '3939393939203902930' outbound: url: https://webhook.test headers: - key: MyKey value: testing required: true responses: '201': description: '' headers: {} security: - apiToken: [] /api/v1/tickets: get: summary: Listing deprecated: false description: >- This endpoint allows you to retrieve a paginated list of all your tickets. By default, a maximum of ten tickets are shown per page. operationId: TicketController_getTickets tags: - Ticket parameters: - name: page in: query description: Page number for pagination. schema: type: number - name: pageSize in: query description: Number of tickets to return per page. schema: type: number - name: selectedDate in: query description: Filter tickets by date range. schema: type: string - name: ticketNumber in: query description: Filter tickets by ticket number. schema: type: string - name: keyword in: query description: Search tickets by keyword. schema: type: string - name: title in: query description: Filter tickets by title. schema: type: string - name: description in: query description: Filter tickets by description. schema: type: string - name: status in: query description: Filter tickets by status. schema: type: array items: type: string - name: priority in: query description: Filter tickets by priority level. schema: type: array items: type: string - name: channel in: query description: Filter tickets by channel. schema: type: array items: type: string - name: type in: query description: Filter tickets by type. schema: type: array items: type: string - name: ticketType in: query description: Filter tickets by ticket type. schema: type: array items: type: string - name: contact in: query description: Filter tickets by associated contact. schema: type: array items: type: string - name: tags in: query description: Filter tickets by associated tags. schema: type: array items: type: string - name: categories in: query description: Filter tickets by categories. schema: type: array items: type: string - name: assignee in: query description: Filter tickets by assigned agent. schema: type: array items: type: string - name: customFields in: query description: >- Filter tickets by custom fields. Each object should contain attributeId, type, and value. schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: total: type: integer page: type: integer pageSize: type: integer lastPage: type: integer data: type: array items: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' title: type: string description: type: string type: type: string channel: type: string priority: type: string status: type: string contactId: type: string creatorId: type: string assigneeId: type: string reasonToAssign: type: string ticketNumber: type: integer assignee: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' name: type: string email: type: string address: type: 'null' phone: type: string notificationCount: type: 'null' provider: type: 'null' providerId: type: 'null' firstName: type: 'null' lastName: type: 'null' required: - id - createdAt - updatedAt - deletedAt - name - email - address - phone - notificationCount - provider - providerId - firstName - lastName contact: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' name: type: string address: type: string channel: type: string notes: type: string contactNumber: type: integer companyId: type: 'null' contactProfile: type: string socialProfileUrl: type: 'null' required: - id - createdAt - updatedAt - deletedAt - name - address - channel - notes - contactNumber - companyId - contactProfile - socialProfileUrl creator: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' name: type: string email: type: string address: type: 'null' phone: type: string notificationCount: type: integer provider: type: 'null' providerId: type: 'null' firstName: type: 'null' lastName: type: 'null' required: - id - createdAt - updatedAt - deletedAt - name - email - address - phone - notificationCount - provider - providerId - firstName - lastName categories: type: array items: type: string tags: type: array items: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' name: type: string position: type: integer customFields: type: array items: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' textValue: type: string booleanValue: type: 'null' numberValue: type: 'null' dateValue: type: 'null' entityId: type: string attributeId: type: string attribute: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' systemName: type: string displayName: type: string type: type: string position: type: integer isDefault: type: boolean isArchived: type: boolean isRequired: type: boolean isUnique: type: boolean groupId: type: string required: - id - createdAt - updatedAt - deletedAt - systemName - displayName - type - position - isDefault - isArchived - isRequired - isUnique - groupId uploads: type: array items: type: string required: - id - createdAt - updatedAt - deletedAt - title - description - type - channel - priority - status - contactId - creatorId - assigneeId - reasonToAssign - ticketNumber required: - total - page - pageSize - lastPage - data example: total: 100 page: 1 pageSize: 10 lastPage: 1 data: - id: string createdAt: string updatedAt: string deletedAt: null title: string description: string type: string channel: string priority: string status: string contactId: string creatorId: string assigneeId: string reasonToAssign: string ticketNumber: 38838 assignee: id: string createdAt: string updatedAt: string deletedAt: null name: string email: string address: null phone: string notificationCount: null provider: null providerId: null firstName: null lastName: null contact: id: string createdAt: string updatedAt: string deletedAt: null name: string address: string channel: string notes: string contactNumber: 23423 companyId: null contactProfile: string socialProfileUrl: null creator: id: string createdAt: string updatedAt: string deletedAt: null name: string email: string address: null phone: string notificationCount: 2 provider: null providerId: null firstName: null lastName: null categories: [] tags: - id: string createdAt: string updatedAt: string deletedAt: null name: string position: 1 customFields: - id: string createdAt: string updatedAt: string deletedAt: null textValue: string booleanValue: null numberValue: null dateValue: null entityId: string attributeId: string attribute: id: string createdAt: string updatedAt: string deletedAt: null systemName: string displayName: string type: string position: 1 isDefault: false isArchived: false isRequired: false isUnique: false groupId: string uploads: [] - id: string createdAt: string updatedAt: string deletedAt: null title: string description: string type: string channel: string priority: string status: string contactId: string creatorId: string assigneeId: string reasonToAssign: string ticketNumber: 323 headers: {} security: - apiToken: [] post: summary: Create deprecated: false description: This endpoint allows you to create a new ticket in the system. operationId: TicketController_createTicket tags: - Ticket parameters: [] requestBody: content: application/json: schema: type: object properties: title: type: string description: The title or subject of the ticket. description: type: string description: Detailed description of the ticket issue or request. status: type: string description: Status of the ticket (e.g., open, in progress, resolved). type: type: string description: The type of the ticket. priority: type: string description: Priority level of the ticket (e.g., low, medium, high). contact_id: type: string description: The ID of the contact associated with this ticket. channel: type: string description: The channel through which the ticket was created. tags: type: array description: Array of tag IDs to associate with the ticket. items: type: string categories: type: array description: Array of category IDs to associate with the ticket. items: type: string customFields: type: object description: >- Custom fields to associate with the ticket, as key-value pairs. additionalProperties: true properties: {} reasonToAssign: type: string description: Reason for assigning the ticket to a specific agent. required: - title - contact_id example: title: Customer cannot access account description: Customer reports being unable to log in after password reset status: open priority: high contact_id: 51f5f68f-6a63-4c2e-8a68-53d268d93ae1 channel: email tags: - f8d7a5b2-9c63-4e2f-8d1a-5b2c9e6d3f8a customFields: cf_trackingid: Id-1001 cf_date: '2025-10-23' responses: '201': description: '' content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' title: type: string description: type: string type: type: string channel: type: string priority: type: string status: type: string contactId: type: string creatorId: type: string assigneeId: type: string reasonToAssign: type: string ticketNumber: type: integer assignee: type: object properties: id: type: string name: type: string email: type: string required: - id - name - email contact: type: object properties: id: type: string name: type: string required: - id - name tags: type: array items: type: object properties: id: type: string name: type: string customFields: type: array items: type: object properties: id: type: string textValue: type: string attribute: type: object properties: id: type: string systemName: type: string displayName: type: string type: type: string required: - id - systemName - displayName - type required: - id - createdAt - updatedAt - deletedAt - title - description - type - channel - priority - status - contactId - creatorId - assigneeId - reasonToAssign - ticketNumber - assignee - contact - tags - customFields required: - success - data example: success: true data: id: string createdAt: string updatedAt: string deletedAt: null title: string description: string type: string channel: string priority: string status: string contactId: string creatorId: string assigneeId: string reasonToAssign: string ticketNumber: 2323 assignee: id: string name: string email: string contact: id: string name: string tags: - id: string name: string customFields: - id: string textValue: string attribute: id: string systemName: string displayName: string type: string headers: {} security: - apiToken: [] /api/v1/tickets/contact/{id}: get: summary: Filter by Contact ID deprecated: false description: '' operationId: TicketController_getTicketsByContactId tags: - Ticket parameters: - name: id in: path description: The unique identifier of the contact. required: true example: '' schema: type: string - name: page in: query description: 'Page number for pagination (default: 1).' required: false schema: type: number - name: pageSize in: query description: 'Number of tickets to return per page (default: 10).' required: false schema: type: number responses: '200': description: '' content: application/json: schema: type: object properties: total: type: integer page: type: integer pageSize: type: integer lastPage: type: integer data: type: array items: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' title: type: string description: type: string type: type: string channel: type: string priority: type: string status: type: string contactId: type: string creatorId: type: string assigneeId: type: string reasonToAssign: type: string ticketNumber: type: integer assignee: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' name: type: string email: type: string address: type: 'null' phone: type: string notificationCount: type: 'null' provider: type: 'null' providerId: type: 'null' firstName: type: 'null' lastName: type: 'null' required: - id - createdAt - updatedAt - deletedAt - name - email - address - phone - notificationCount - provider - providerId - firstName - lastName contact: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' name: type: string address: type: string channel: type: string notes: type: string contactNumber: type: integer companyId: type: 'null' contactProfile: type: string socialProfileUrl: type: 'null' required: - id - createdAt - updatedAt - deletedAt - name - address - channel - notes - contactNumber - companyId - contactProfile - socialProfileUrl creator: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' name: type: string email: type: string address: type: 'null' phone: type: string notificationCount: type: integer provider: type: 'null' providerId: type: 'null' firstName: type: 'null' lastName: type: 'null' required: - id - createdAt - updatedAt - deletedAt - name - email - address - phone - notificationCount - provider - providerId - firstName - lastName categories: type: array items: type: string tags: type: array items: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' name: type: string position: type: integer customFields: type: array items: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' textValue: type: string booleanValue: type: 'null' numberValue: type: 'null' dateValue: type: 'null' entityId: type: string attributeId: type: string attribute: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' systemName: type: string displayName: type: string type: type: string position: type: integer isDefault: type: boolean isArchived: type: boolean isRequired: type: boolean isUnique: type: boolean groupId: type: string required: - id - createdAt - updatedAt - deletedAt - systemName - displayName - type - position - isDefault - isArchived - isRequired - isUnique - groupId uploads: type: array items: type: string required: - total - page - pageSize - lastPage - data example: total: 32 page: 1 pageSize: 10 lastPage: 1 data: - id: string createdAt: string updatedAt: string deletedAt: null title: string description: string type: string channel: string priority: string status: string contactId: string creatorId: string assigneeId: string reasonToAssign: string ticketNumber: 2323 assignee: id: string createdAt: string updatedAt: string deletedAt: null name: string email: string address: null phone: string notificationCount: null provider: null providerId: null firstName: null lastName: null contact: id: string createdAt: string updatedAt: string deletedAt: null name: string address: string channel: string notes: string contactNumber: 343 companyId: null contactProfile: string socialProfileUrl: null creator: id: string createdAt: string updatedAt: string deletedAt: null name: string email: string address: null phone: string notificationCount: 23 provider: null providerId: null firstName: null lastName: null categories: [] tags: - id: string createdAt: string updatedAt: string deletedAt: null name: string position: 1 customFields: - id: string createdAt: string updatedAt: string deletedAt: null textValue: string booleanValue: null numberValue: null dateValue: null entityId: string attributeId: string attribute: id: string createdAt: string updatedAt: string deletedAt: null systemName: string displayName: string type: string position: 1 isDefault: false isArchived: false isRequired: false isUnique: false groupId: string uploads: [] headers: {} security: - apiToken: [] /api/v1/tickets/fields: get: summary: Form Fields deprecated: false description: >- This endpoint allows you to retrieve a paginated list of custom fields available for tickets. operationId: TicketController_getAllTicketFields tags: - Ticket parameters: [] responses: '200': description: '' content: application/json: schema: type: object properties: page: type: integer pageSize: type: integer total: type: integer lastPage: type: integer data: type: array items: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' systemName: type: string displayName: type: string type: type: string position: type: integer isDefault: type: boolean isArchived: type: boolean isRequired: type: boolean isUnique: type: boolean groupId: type: string required: - page - pageSize - total - lastPage - data example: page: 1 pageSize: 10 total: 25 lastPage: 3 data: - id: string createdAt: string updatedAt: string deletedAt: null systemName: string displayName: string type: string position: 1 isDefault: true isArchived: false isRequired: true isUnique: true groupId: string headers: {} security: - apiToken: [] /api/v1/tickets/{id}: patch: summary: Update deprecated: false description: This endpoint allows you to update an existing ticket by its ID. operationId: TicketController_updateTicket tags: - Ticket parameters: - name: id in: path description: The unique identifier of the ticket to update. required: true example: '' schema: type: string requestBody: content: application/json: schema: type: object properties: title: type: string description: The title or subject of the ticket. description: type: string description: Detailed description of the ticket issue or request. status: type: string description: Status of the ticket (e.g., open, in progress, resolved). type: type: string description: The type of the ticket. priority: type: string description: Priority level of the ticket (e.g., low, medium, high). contact: type: string description: The ID of the contact associated with this ticket. assignee: type: string description: The ID of the agent to assign to this ticket. channel: type: string description: The channel through which the ticket was created. tags: type: array items: type: string description: Array of tag IDs to associate with the ticket. categories: type: array items: type: string description: Array of category IDs to associate with the ticket. customFields: type: object description: >- Custom fields to associate with the ticket, as key-value pairs. properties: {} reasonToAssign: type: string description: Reason for assigning the ticket to a specific agent. example: title: Customer cannot access account updated description: Customer reports being unable to log in after password reset status: open priority: high contact_id: 51f5f68f-6a63-4c2e-8a68-53d268d93ae1 channel: email tags: - f8d7a5b2-9c63-4e2f-8d1a-5b2c9e6d3f8a customFields: cf_trackingid: Id-1001 cf_date: '2025-10-23' responses: '200': description: '' content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' title: type: string description: type: string type: type: string channel: type: string priority: type: string status: type: string contactId: type: string creatorId: type: string assigneeId: type: string reasonToAssign: type: string ticketNumber: type: integer assignee: type: object properties: id: type: string name: type: string email: type: string required: - id - name - email contact: type: object properties: id: type: string name: type: string required: - id - name tags: type: array items: type: object properties: id: type: string name: type: string customFields: type: array items: type: object properties: id: type: string textValue: type: string attribute: type: object properties: id: type: string systemName: type: string displayName: type: string type: type: string required: - id - systemName - displayName - type required: - id - createdAt - updatedAt - deletedAt - title - description - type - channel - priority - status - contactId - creatorId - assigneeId - reasonToAssign - ticketNumber - assignee - contact - tags - customFields required: - success - data example: success: true data: id: string createdAt: string updatedAt: string deletedAt: null title: string description: string type: string channel: string priority: string status: string contactId: string creatorId: string assigneeId: string reasonToAssign: string ticketNumber: 3232 assignee: id: string name: string email: string contact: id: string name: string tags: - id: string name: string customFields: - id: string textValue: string attribute: id: string systemName: string displayName: string type: string headers: {} security: - apiToken: [] /api/v1/tickets/{id}/status: put: summary: Update status deprecated: false description: >- This endpoint allows you to update the status of an existing ticket by its ID. operationId: TicketController_updateTicketStatus tags: - Ticket parameters: - name: id in: path description: The unique identifier of the ticket to update. required: true example: '' schema: type: string requestBody: content: application/json: schema: type: object properties: status: type: string description: >- The new status to set for the ticket (e.g., open, in_progress, resolved, pending). required: - status examples: {} responses: '200': description: '' content: application/json: schema: type: object properties: success: type: boolean message: type: string required: - success - message example: success: true message: Ticket status updated successfully headers: {} security: - apiToken: [] /api/v1/categories: get: summary: Listing deprecated: false description: '' operationId: CategoryController_getCategories tags: - Category parameters: [] responses: '200': description: '' content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' value: type: string parentId: type: 'null' level: type: integer sortOrder: type: integer childCategoryList: type: array items: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' value: type: string parentId: type: string level: type: integer sortOrder: type: integer childCategoryList: type: array items: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' value: type: string parentId: type: string level: type: integer sortOrder: type: integer required: - id - createdAt - updatedAt - deletedAt - value - parentId - level - sortOrder required: - id - createdAt - updatedAt - deletedAt - value - parentId - level - sortOrder - childCategoryList required: - id - createdAt - updatedAt - deletedAt - value - parentId - level - sortOrder - childCategoryList total: type: integer required: - data - total example: data: - id: b5efc76a-4fc2-48df-b6c9-0083b3e341c4 createdAt: '2026-01-08T04:42:59.028Z' updatedAt: '2026-01-08T04:42:59.028Z' deletedAt: null value: '' parentId: null level: 1 sortOrder: 0 childCategoryList: [] - id: 2ee98c63-24b2-49ed-a867-e20b0f83c7e0 createdAt: '2026-01-08T04:42:22.040Z' updatedAt: '2026-01-08T04:43:02.292Z' deletedAt: null value: testing four parentId: null level: 1 sortOrder: 0 childCategoryList: [] - id: a1e384de-bc5c-48f0-91a1-e7c5c0c90ebf createdAt: '2026-01-08T04:42:11.869Z' updatedAt: '2026-01-08T04:42:24.061Z' deletedAt: null value: testing three parentId: null level: 1 sortOrder: 0 childCategoryList: [] - id: e862e40c-7e3f-456e-bf46-ed44b6860d5e createdAt: '2025-12-12T08:52:48.901Z' updatedAt: '2025-12-12T08:53:10.719Z' deletedAt: null value: Environment parentId: null level: 1 sortOrder: 0 childCategoryList: - id: dddf4d31-9099-44e5-95cd-48b6d04ac671 createdAt: '2025-12-12T08:53:35.405Z' updatedAt: '2026-01-08T04:39:37.616Z' deletedAt: null value: Enterprise parentId: e862e40c-7e3f-456e-bf46-ed44b6860d5e level: 2 sortOrder: 3 childCategoryList: [] - id: 2af1b100-7c62-4984-bdfe-47c551de7068 createdAt: '2025-11-02T17:13:53.549Z' updatedAt: '2025-12-12T08:50:51.012Z' deletedAt: null value: Main Category parentId: null level: 1 sortOrder: 1 childCategoryList: - id: c743c316-19f4-47c7-a5ed-6ef3fe36507c createdAt: '2025-12-12T08:49:12.184Z' updatedAt: '2025-12-12T08:50:51.012Z' deletedAt: null value: Sub Category 3 parentId: 2af1b100-7c62-4984-bdfe-47c551de7068 level: 2 sortOrder: 2 childCategoryList: [] - id: 3a8cf739-d846-4b7a-9cde-8c85158544ff createdAt: '2025-11-02T17:17:56.036Z' updatedAt: '2025-12-12T08:50:51.012Z' deletedAt: null value: Sub Category 2 parentId: 2af1b100-7c62-4984-bdfe-47c551de7068 level: 2 sortOrder: 1 childCategoryList: [] - id: 58769fad-0ecb-4a6e-bd00-c7972a6274cf createdAt: '2025-11-02T17:14:04.861Z' updatedAt: '2025-12-12T08:50:51.012Z' deletedAt: null value: sub 1 parentId: 2af1b100-7c62-4984-bdfe-47c551de7068 level: 2 sortOrder: 0 childCategoryList: - id: 1acc13dd-7d67-411c-976b-731cadaf2174 createdAt: '2025-12-12T08:50:32.234Z' updatedAt: '2025-12-12T08:50:51.012Z' deletedAt: null value: Item 1.4 parentId: 58769fad-0ecb-4a6e-bd00-c7972a6274cf level: 3 sortOrder: 3 - id: c16013b0-d95a-48c4-b665-0d05a1fdc884 createdAt: '2025-12-12T08:50:26.081Z' updatedAt: '2025-12-12T08:50:51.012Z' deletedAt: null value: Item 1.3 parentId: 58769fad-0ecb-4a6e-bd00-c7972a6274cf level: 3 sortOrder: 2 - id: f7f07618-710e-431d-a366-c6b68a4fb82d createdAt: '2025-12-12T08:50:18.511Z' updatedAt: '2025-12-12T08:50:51.012Z' deletedAt: null value: Item 1.2 parentId: 58769fad-0ecb-4a6e-bd00-c7972a6274cf level: 3 sortOrder: 1 - id: 608cc95e-573a-4756-914e-162a1a4049dd createdAt: '2025-12-12T08:50:08.888Z' updatedAt: '2025-12-12T08:50:51.012Z' deletedAt: null value: Item 1.1 parentId: 58769fad-0ecb-4a6e-bd00-c7972a6274cf level: 3 sortOrder: 0 total: 10 headers: {} security: - apiToken: [] /api/v1/cx-logs: get: summary: Listing deprecated: false description: >- As the name suggests, cx logs are a core part of klink.cloud — the very reason klink.cloud exists is so you can have check daily call logs conversations with your cx logs. On this page, we'll dive into the different cx logs endpoints you can use to manage cx logs programmatically. We'll look at how to query, create, update, and delete tags. operationId: CxLogController_getCxLogs tags: - CX Log parameters: - name: selectedDate in: query description: >- The selectedDate for the cx logs (example. 2025/04/01 00:00:00-2025/04/25 23:59:00). required: true example: 2026/04/01 00:00:00-2026/04/30 23:59:59 schema: type: string - name: page in: query description: Page number of cx logs. required: false example: 1 schema: type: number - name: pageSize in: query description: Page size that is showing the data amout of cx logs. required: false example: 20 schema: type: number - name: direction[] in: query description: Direction of the cxlog chatroom when first created. required: false example: - outbound schema: type: array items: type: string - name: channelIds[] in: query description: A list of ID of channel required: false example: - 4da39031-79b0-4fec-9800-4d9199ec82d5 schema: type: array items: type: string - name: contactChannel[] in: query description: Filter by Channel type such as line, whatsapp,mail, etc required: false example: - mail schema: type: array items: type: string - name: closedAt in: query description: >- Filter by closed at for th cx logs ( 2026/04/01 00:00:00-2026/04/01 23:59:59) required: false example: 2026/04/01 00:00:00-2026/04/02 23:59:59 schema: type: string - name: roomStatuses[] in: query description: filter by current chat room status required: false example: unassigned, active, hold, closed schema: type: string - name: queueIds[] in: query description: '' required: false example: ID of queue schema: type: string - name: x-client-timezone in: header description: >- The time zone base on country. (example. x-client-timezone : Asia/Bangkok). required: true example: Asia/Singapore schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: requestId: type: string cxLogs: type: object properties: data: type: array items: type: object properties: id: type: - string - 'null' caseId: type: - integer - 'null' entityId: type: - string - 'null' entityName: type: - string - 'null' contactId: type: - string - 'null' channel: type: - string - 'null' queueId: type: - string - 'null' agentId: type: - string - 'null' direction: type: - string - 'null' startedDate: type: - string - 'null' closedAt: type: - string - 'null' handledTime: type: - integer - 'null' totalHoldDuration: type: - integer - 'null' firstResponseTime: type: - integer - 'null' disposition: type: - string - 'null' channelType: type: - string - 'null' customerPhone: type: - string - 'null' contactLabel: type: - array - 'null' items: type: string queueName: type: - string - 'null' uid: type: - string - 'null' createdAt: type: - string - 'null' updatedAt: type: - string - 'null' deletedAt: type: 'null' wrapUpFormId: type: - string - 'null' wrapUpDuration: type: - integer - 'null' slaStatus: type: - string - 'null' firstAssigneeId: type: - string - 'null' closedAssigneeId: type: - string - 'null' fullHandledTime: type: - integer - 'null' resolutionTime: type: - integer - 'null' fullResolutionTime: type: - integer - 'null' cxIntelligenceStatus: type: - string - 'null' firstRepliedTime: type: - integer - 'null' contact: type: - object - 'null' properties: id: type: - string - 'null' createdAt: type: - string - 'null' updatedAt: type: - string - 'null' deletedAt: type: 'null' name: type: - string - 'null' address: type: - string - 'null' channel: type: - string - 'null' notes: type: - string - 'null' contactNumber: type: - string - integer - 'null' companyId: type: - string - 'null' contactProfile: type: - string - 'null' socialProfileUrl: type: - string - 'null' tags: type: - array - 'null' items: type: object properties: id: type: - string - 'null' name: type: - string - 'null' position: type: - integer - 'null' createdAt: type: - string - 'null' updatedAt: type: - string - 'null' deletedAt: type: 'null' platformContacts: type: - array - 'null' items: type: object properties: id: type: - string - 'null' createdAt: type: - string - 'null' updatedAt: type: - string - 'null' deletedAt: type: 'null' channelId: type: - string - 'null' socialPlatformId: type: - string - 'null' type: type: - string - 'null' botpress_user_metadata: type: - object - array - 'null' firstAssignee: type: - object - 'null' properties: id: type: - string - 'null' name: type: - string - 'null' email: type: - string - 'null' address: type: - string - 'null' phone: type: - string - 'null' notificationCount: type: - integer - 'null' deletedaAt: type: 'null' createdAt: type: - string - 'null' updatedAt: type: - string - 'null' provider: type: - string - 'null' providerId: type: - string - 'null' firstName: type: - string - 'null' lastName: type: - string - 'null' agent: type: - object - 'null' properties: id: type: - string - 'null' name: type: - string - 'null' email: type: - string - 'null' address: type: - string - 'null' phone: type: - string - 'null' notificationCount: type: - integer - 'null' deletedaAt: type: 'null' createdAt: type: - string - 'null' updatedAt: type: - string - 'null' provider: type: - string - 'null' providerId: type: - string - 'null' firstName: type: - string - 'null' lastName: type: - string - 'null' closedAssignee: type: - object - 'null' properties: id: type: - string - 'null' name: type: - string - 'null' email: type: - string - 'null' address: type: - string - 'null' phone: type: - string - 'null' notificationCount: type: - integer - 'null' deletedaAt: type: 'null' createdAt: type: - string - 'null' updatedAt: type: - string - 'null' provider: type: - string - 'null' providerId: type: - string - 'null' firstName: type: - string - 'null' lastName: type: - string - 'null' mailRoom: type: - object - 'null' properties: {} room: type: - object - 'null' properties: id: type: - string - 'null' channel_id: type: - string - 'null' platform_contact_id: type: - string - 'null' actor_id: type: - string - 'null' assignee_id: type: - string - 'null' last_message: type: - string - 'null' handled_time: type: - integer - 'null' first_response_at: type: - string - 'null' unread_count: type: - integer - 'null' closed_at: type: - string - 'null' direction: type: - string - 'null' is_latest: type: - boolean - 'null' created_at: type: - string - 'null' updated_at: type: - string - 'null' status: type: - integer - 'null' last_message_at: type: - string - 'null' actor_type: type: - string - 'null' is_bot_room: type: - boolean - 'null' csat_status: type: - string - 'null' notes: type: - string - 'null' first_response_time: type: - integer - 'null' automation_queue_id: type: - string - 'null' telegram_business_connection_id: type: - string - 'null' is_group: type: - boolean - 'null' first_assignee_id: type: - string - 'null' closed_assignee_id: type: - string - 'null' holding_time: type: - integer - 'null' unhold_label_id: type: - string - 'null' first_replied_at: type: - string - 'null' first_replied_time: type: - integer - 'null' is_ai_agent_room: type: - boolean - 'null' thread_id: type: - string - 'null' subject: type: - string - 'null' cx_log_partition_key: type: - string - 'null' channel: type: - object - 'null' properties: id: type: - string - 'null' name: type: - string - 'null' type: type: - string - 'null' brand_name: type: - string - 'null' platform_id: type: - string - 'null' status: type: - boolean - 'null' created_at: type: - string - 'null' updated_at: type: - string - 'null' is_relogin_required: type: - boolean - 'null' connected_user_name: type: - string - 'null' connected_user_id: type: - string - 'null' actor_id: type: - string - 'null' botpress_bot_id: type: - string - 'null' csat_preferences: type: - object - 'null' properties: image: type: - string - 'null' headline: type: - string - 'null' dispositions: type: - array - 'null' items: type: string scaleOptions: type: - array - 'null' items: type: object properties: label: type: - string - 'null' value: type: - integer - string - 'null' last_assigned_message: type: - object - 'null' properties: id: type: - string - 'null' partition_key: type: - string - 'null' room_id: type: - string - 'null' sender_id: type: - string - 'null' actor_id: type: - string - 'null' assignee_id: type: - string - 'null' upload_id: type: - string - 'null' message: type: - string - 'null' direction: type: - string - 'null' type: type: - string - 'null' metadata: type: - object - 'null' properties: {} platform_id: type: - string - 'null' reply_platform_message_id: type: - string - 'null' platform_message_id: type: - string - 'null' template: type: - string - 'null' locale: type: - string - 'null' url: type: - string - 'null' read_at: type: - string - 'null' created_at: type: - string - 'null' updated_at: type: - string - 'null' deleted_at: type: 'null' preview_url: type: - string - 'null' image_set_id: type: - string - 'null' actor_type: type: - string - 'null' parent_message_id: type: - string - 'null' reply_reaction: type: - string - 'null' feed_post_id: type: - string - 'null' link_message_id: type: - string - 'null' edited_message_id: type: - string - 'null' is_edited: type: - boolean - 'null' edited_at: type: - string - 'null' label: type: - string - 'null' contact_id: type: - string - 'null' link_message_partition_key: type: - string - 'null' edited_message_partition_key: type: - string - 'null' parent_message_partition_key: type: - string - 'null' client_request_id: type: - string - 'null' queue: type: - object - 'null' properties: {} automationQueue: type: - object - 'null' properties: {} wrapUpForm: type: - object - 'null' properties: id: type: - string - 'null' disposition: type: - string - 'null' note: type: - string - 'null' deletedAt: type: 'null' callFrom: type: - string - 'null' callTo: type: - string - 'null' createdAt: type: - string - 'null' updatedAt: type: - string - 'null' type: type: - string - 'null' categories: type: - array - 'null' items: type: object properties: id: type: - string - 'null' createdAt: type: - string - 'null' updatedAt: type: - string - 'null' deletedAt: type: 'null' value: type: - string - 'null' parentId: type: - string - 'null' level: type: - integer - 'null' tags: type: - array - 'null' items: type: object properties: id: type: - string - 'null' name: type: - string - 'null' customFields: type: - array - 'null' items: type: object properties: id: type: - string - 'null' createdAt: type: - string - 'null' updatedAt: type: - string - 'null' deletedAt: type: 'null' textValue: type: - string - 'null' booleanValue: type: - boolean - 'null' numberValue: type: - integer - number - 'null' dateValue: type: - string - 'null' entityId: type: - string - 'null' attributeId: type: - string - 'null' attribute: type: - object - 'null' properties: id: type: - string - 'null' createdAt: type: - string - 'null' updatedAt: type: - string - 'null' deletedAt: type: 'null' displayName: type: - string - 'null' systemName: type: - string - 'null' type: type: - string - 'null' position: type: - integer - 'null' isDefault: type: - boolean - 'null' isArchived: type: - boolean - 'null' isRequired: type: - boolean - 'null' isUnique: type: - boolean - 'null' groupId: type: - string - 'null' evaluateForm: type: - object - 'null' properties: {} holdLogs: type: - array - 'null' items: type: object properties: id: type: - string - 'null' started_at: type: - string - 'null' ended_at: type: - string - 'null' duration: type: - integer - 'null' hold_label_id: type: - string - 'null' cx_log_id: type: - string - 'null' created_at: type: - string - 'null' updated_at: type: - string - 'null' deleted_at: type: 'null' cx_log_partition_key: type: - string - 'null' telephonyCdr: type: - object - 'null' properties: id: type: - string - 'null' uniqueCallId: type: - string - 'null' timeStart: type: - string - 'null' callFrom: type: - string - 'null' callTo: type: - string - 'null' callDuration: type: - integer - 'null' talkDuration: type: - integer - 'null' srcTrunkName: type: - string - 'null' dstTrunkName: type: - string - 'null' status: type: - string - 'null' type: type: - string - 'null' recording: type: - string - 'null' didNumber: type: - string - 'null' agentRingTime: type: - integer - 'null' uploadId: type: - string - 'null' serialNumber: type: - string - 'null' extensionId: type: - string - 'null' telephonyQueueId: type: - string - 'null' contactId: type: - string - 'null' createdAt: type: - string - 'null' updatedAt: type: - string - 'null' deletedAt: type: 'null' isQueueMissedCall: type: - boolean - 'null' callParticipants: type: - array - 'null' items: type: string wrapUpFormId: type: - string - 'null' telephonyIvrId: type: - string - 'null' transcript: type: - string - 'null' total: type: integer page: type: integer pageSize: type: integer lastPage: type: integer required: - data - total - page - pageSize - lastPage required: - requestId - cxLogs example: requestId: uuid-string cxLogs: data: - id: uuid-string caseId: 12540 entityId: uuid-string entityName: room contactId: uuid-string channel: messenger queueId: uuid-string agentId: uuid-string direction: inbound startedDate: '2026-03-30 08:30:00.000+00' closedAt: '2026-03-30 09:15:20+00' handledTime: 2720 totalHoldDuration: 45 firstResponseTime: 120 disposition: Resolved channelType: messenger customerPhone: null contactLabel: - Premium Support - Technical-V2 queueName: Tier 2 Technical Support uid: PSID-1029384756 createdAt: '2026-03-30T08:30:05.123Z' updatedAt: '2026-03-30T09:15:25.000Z' deletedAt: null wrapUpFormId: uuid-string wrapUpDuration: 180 slaStatus: meet firstAssigneeId: uuid-string closedAssigneeId: uuid-string fullHandledTime: 2765 resolutionTime: 2905 fullResolutionTime: 2965 cxIntelligenceStatus: processed firstRepliedTime: 125 contact: id: uuid-string createdAt: '2026-01-15T10:00:00.000Z' updatedAt: '2026-03-30T08:30:00.000Z' deletedAt: null name: John Doe address: 123 Business Ave, Singapore channel: messenger notes: 'Preferred contact method: Messenger' contactNumber: '+6591234567' companyId: uuid-string contactProfile: >- https://cdn.klink.cloud/assets/profiles/john_doe_avatar.jpg socialProfileUrl: https://facebook.com/john.doe.sample tags: - id: uuid-string name: VIP platformContacts: - id: uuid-string createdAt: '2026-01-15T10:00:00.000Z' updatedAt: '2026-03-30T08:30:00.000Z' deletedAt: null channelId: uuid-string socialPlatformId: PSID-1029384756 type: messenger botpress_user_metadata: null firstAssignee: id: uuid-string name: Sarah Jenkins email: sarah.j@klink.cloud address: null phone: null notificationCount: 0 deletedaAt: null createdAt: '2024-05-10T09:00:00.000Z' updatedAt: '2026-03-25T14:20:00.000Z' provider: google providerId: uuid-string firstName: Sarah lastName: Jenkins agent: id: uuid-string name: Sarah Jenkins email: sarah.j@klink.cloud phone: null closedAssignee: id: uuid-string name: Sarah Jenkins email: sarah.j@klink.cloud mailRoom: null room: id: uuid-string channel_id: uuid-string platform_contact_id: uuid-string actor_id: uuid-string assignee_id: uuid-string last_message: >- Thank you for the update, your issue has been resolved. handled_time: 2720 first_response_at: '2026-03-30 08:32:00+00' unread_count: 0 closed_at: '2026-03-30 09:15:20+00' direction: outgoing is_latest: true created_at: '2026-03-30T08:30:00.000Z' updated_at: '2026-03-30T09:15:20.000Z' status: 1 last_message_at: '2026-03-30 09:12:00+00' actor_type: user is_bot_room: false csat_status: sent notes: >- Issue related to account sync. Resolved by resetting session tokens. first_response_time: 120 automation_queue_id: null telegram_business_connection_id: null is_group: false first_assignee_id: uuid-string closed_assignee_id: uuid-string holding_time: 45 unhold_label_id: uuid-string first_replied_at: '2026-03-30 08:32:05+00' first_replied_time: 125 is_ai_agent_room: false thread_id: uuid-string-thread subject: Account Sync Issue cx_log_partition_key: 2026_03 channel: id: uuid-string name: Klink Asia Facebook type: messenger brand_name: Klink Official platform_id: uuid-string-platform status: true created_at: '2024-01-01T00:00:00.000Z' updated_at: '2026-01-01T10:00:00.000Z' is_relogin_required: false connected_user_name: Klink Support connected_user_id: uuid-string-user actor_id: uuid-string-actor wrapUpForm: id: uuid-string disposition: Resolved note: Customer account successfully synced and verified. createdAt: '2026-03-30T09:12:00.000Z' updatedAt: '2026-03-30T09:15:00.000Z' categories: - id: uuid-string value: Technical Support parentId: null level: 1 - id: uuid-string value: Account Issues parentId: uuid-string level: 2 tags: - id: uuid-string name: First-Contact Resolution customFields: - id: uuid-string textValue: v2.5.1 attribute: id: uuid-string displayName: Software Version systemName: software_version type: text - id: uuid-string textValue: High attribute: id: uuid-string displayName: Urgency Level systemName: urgency type: select holdLogs: - id: uuid-string started_at: '2026-03-30 08:45:00.000+00' ended_at: '2026-03-30 08:45:45.000+00' duration: 45 hold_label_id: uuid-string cx_log_id: uuid-string cx_log_partition_key: 2026_03 telephonyCdr: null transcript: empty total: 14 page: 1 pageSize: 14 lastPage: 1 headers: {} security: - bearerAuth: [] /api/v1/cx-logs/{id}/transcript: get: summary: Get the live transcript deprecated: false description: > Returns one line per customer or agent message, oldest first, in the form `[] (customer|agent): `. System events and internal comments are left out. A message with no text shows as `[]`, for example `[image]`. An empty string means the room has no messages yet. operationId: getCxLogTranscript tags: - CX Log parameters: - name: id in: path description: The CX log id (UUID) or its numeric case id. required: true example: 5b0c8f9e-1d2a-4c3b-9e8f-7a6b5c4d3e2f schema: type: string pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[1-9][0-9]{0,17})$ responses: '200': description: The transcript. content: application/json: schema: $ref: '#/components/schemas/CxLogTranscriptResponse' example: requestId: 3f1d6c9e-8a43-4f0e-9b7a-2d6a1c0e5b11 data: cxLogId: 5b0c8f9e-1d2a-4c3b-9e8f-7a6b5c4d3e2f caseId: 1042 roomId: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d channel: line transcript: >- [2026-10-24T03:12:05+00:00] Jane Doe(customer): Hi, my order hasn't arrived [2026-10-24T03:13:40+00:00] Sam(agent): Sorry to hear that, let me check headers: {} '400': description: '`id` is not a UUID or a numeric case id.' content: application/json: schema: $ref: '#/components/schemas/ValidationError' example: message: - id must be a cx log id (uuid) or a numeric case id error: Bad Request statusCode: 400 headers: {} '401': description: The API token is missing or invalid. headers: {} '404': description: > No CX log with this id exists for the token's tenant, or its chat room was not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: cxLog: summary: cxLog value: message: CX log not found. error: Not Found statusCode: 404 room: summary: room value: message: Chat room not found for this CX log. error: Not Found statusCode: 404 headers: {} '422': description: The CX log is not a chat case (for example a call or an email). content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Transcripts are only available for chat cases. error: Unprocessable Entity statusCode: 422 headers: {} '429': description: Too many requests. headers: {} '502': description: The chat service could not be reached. Retry later. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: The chat service is unavailable. error: Bad Gateway statusCode: 502 headers: {} security: - bearerAuth: [] /api/v1/messages/send: post: summary: Send message deprecated: false description: > This endpoint allows you to send an outgoing message to a specific contact via the Klink platform. ### Sending files from your own URL (`externalMedia`) - Only `url` is required. `fileName`, `fileType` and `fileSize` are filled in automatically when omitted: the name from the URL, the type from the file extension, and the size from your server's `Content-Length`. - The customer receives your original URL. Klink does not re-host the file, so keep it publicly reachable. - LINE only accepts HTTPS URLs for images and videos. - To upload a file to Klink instead, use **Upload File (multipart)** in Media Manager and send its ID as `mediaFileId`. ### Sending a WhatsApp template (`whatsappTemplate`) Send an approved WhatsApp template, for example to message a customer outside WhatsApp's 24-hour window. - Works only when the contact's latest conversation is on an **official WhatsApp channel** (360dialog / Meta). QR-linked WhatsApp numbers have no templates. - `name` is the template name. `language` is only needed when the same name exists in more than one language. - `variables` fills the body placeholders: `"1"` for `{{1}}`, or the name for a named placeholder such as `{{first_name}}`. Every placeholder needs a value. - `messageType` can be omitted; templates are always sent as `text`. `message` is optional: by default the Klink inbox shows the template text with your variables filled in. - Only `APPROVED` templates can be sent. Use **List WhatsApp templates** to see a channel's templates and the variables each one needs. - Can't be combined with `mediaFileId`, `externalMedia` or `platformUserId`. - Returns **400** with the reason if the contact has no conversation, the channel isn't official WhatsApp, the template isn't found or approved, or a variable is missing. operationId: MessageController_createMessage tags: - Message parameters: [] requestBody: content: application/json: schema: type: object properties: contactId: type: string messageType: type: string description: '`text`, `image`, `video`, `audio` or `file`.' message: type: string mediaFileId: type: string title: media manager file id description: >- Only use one, externalMedia or mediaFileId when sending video, image, file externalMedia: type: object description: >- Send a file hosted on your own server. Use either `externalMedia` or `mediaFileId`, not both. The file is delivered from your URL as-is (Klink does not copy it), so it must stay publicly reachable. LINE requires HTTPS for images and videos. properties: url: type: string description: Public URL of the file (https recommended). examples: - https://example.com/files/report.pdf fileType: type: string description: >- MIME type (`application/pdf`) or file extension (`pdf`). Optional: inferred from the file name or the server's Content-Type. examples: - application/pdf fileName: type: string description: >- Name shown to the customer. Defaults to the last segment of the URL (e.g. `report.pdf`). examples: - report.pdf fileSize: type: integer description: >- Size in bytes. Optional: read from the server's Content-Length when omitted. examples: - 1005148 width: type: integer description: Image/video width in pixels (optional). height: type: integer description: Image/video height in pixels (optional). required: - url createdAt: type: string whatsappTemplate: type: object properties: name: type: string description: Template name, e.g. welcomemessage language: type: string description: >- Language code, e.g. en; only needed when the name exists in several languages variables: type: object properties: {} description: >- Values keyed by placeholder: "1" for {{1}}, or first_name for {{first_name}} required: - name description: Send an approved WhatsApp template instead of free text required: - contactId - messageType - message - createdAt examples: '1': value: contactId: 81d8f399-e4d3-4fd4-a8ec-61bb3c3dc8c4 messageType: text message: It is your message. createdAt: '2026-01-08T16:03:39.923Z' summary: Text message '2': value: contactId: b1c2d3e4-5f6a-7b8c-9d0e-1f2a3b4c5d6e messageType: video createdAt: '2025-11-06T16:31:49.293Z' message: '' externalMedia: url: https://example.com/videos/migrated_video.mp4 fileName: migrated_video.mp4 fileType: video/mp4 fileSize: 1570024 width: 480 height: 270 summary: Message with your own file URL '3': value: contactId: b1c2d3e4-5f6a-7b8c-9d0e-1f2a3b4c5d6e messageType: file message: '' createdAt: '2026-01-08T16:03:39.923Z' externalMedia: url: https://example.com/files/report.pdf fileType: pdf summary: File (PDF) from your own URL '4': value: contactId: b1c2d3e4-5f6a-7b8c-9d0e-1f2a3b4c5d6e messageType: video message: '' createdAt: '2025-11-06T16:31:49.293Z' mediaFileId: uuid-string summary: Message with Media Manager '5': value: contactId: 81d8f399-e4d3-4fd4-a8ec-61bb3c3dc8c4 createdAt: '2026-10-20T08:00:00.000Z' whatsappTemplate: name: welcomemessage language: en variables: first_name: Ko Ko summary: WhatsApp template required: true responses: '200': description: '' content: application/json: schema: type: object properties: status: type: integer message: type: string data: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: 'null' clientRequestId: type: string partition_key: type: string message: type: string direction: type: string type: type: string readAt: type: 'null' metadata: type: object properties: {} platformId: type: string platformMessageId: type: string replyPlatformMessageId: type: 'null' replyReaction: type: 'null' linkMessageId: type: 'null' linkMessagePartitionKey: type: 'null' template: type: 'null' locale: type: string url: type: string previewUrl: type: string imageSetId: type: string roomId: type: string room: type: object properties: {} actorId: type: 'null' actorType: type: string actor: type: 'null' uploadId: type: string upload: type: object properties: createdAt: type: string updatedAt: type: string deletedAt: type: 'null' fileName: type: string fileSize: type: integer originalUrl: type: string fileUrl: type: string required: - createdAt - updatedAt - deletedAt - fileName - fileSize - originalUrl - fileUrl senderId: type: 'null' workflowRule: type: 'null' assigneeId: type: 'null' assignee: type: 'null' repliedMessage: type: 'null' editedMessageId: type: 'null' editedMessagePartitionKey: type: 'null' editedMessage: type: 'null' isEdited: type: boolean editedAt: type: 'null' label: type: string contactId: type: 'null' receiverMetadata: type: 'null' attachments: type: 'null' required: - id - createdAt - updatedAt - deletedAt - clientRequestId - partition_key - message - direction - type - readAt - metadata - platformId - platformMessageId - replyPlatformMessageId - replyReaction - linkMessageId - linkMessagePartitionKey - template - locale - url - previewUrl - imageSetId - roomId - room - actorId - actorType - actor - uploadId - upload - senderId - workflowRule - assigneeId - assignee - repliedMessage - editedMessageId - editedMessagePartitionKey - editedMessage - isEdited - editedAt - label - contactId - receiverMetadata - attachments required: - status - message - data example: status: 200 message: Message sent successfully data: id: 0b01ac59-81b4-436f-9b36-8ad40e0761f7 createdAt: '2026-02-20T11:46:31.61603869Z' updatedAt: '2026-02-20T11:46:31.61603869Z' deletedAt: null clientRequestId: '' partition_key: 2026_02 message: '' direction: outgoing type: image readAt: null metadata: {} platformId: '614318778436396' platformMessageId: >- m_mzGEtSseyHjNuahzh0kqvZphJxcgEGdTfCuMgYD8ikTs5F8tYuWSSXmbdjJ2P53vKyWenEmg9kG_wvEtQAi8nQ replyPlatformMessageId: null replyReaction: null linkMessageId: null linkMessagePartitionKey: null template: null locale: '' url: '' previewUrl: '' imageSetId: '' roomId: dcccf921-dd40-4c49-8c8d-f755ee157ff1 room: {} actorId: null actorType: api actor: null uploadId: 0dfde389-2314-4ba2-bf10-27112fdaa9d3 upload: createdAt: '2026-02-20T11:46:36.121295122Z' updatedAt: '2026-02-20T11:46:36.136286748Z' deletedAt: null fileName: red-pixel.png fileSize: 70 originalUrl: '' fileUrl: >- https://cdn.klink.cloud/media-manager/038ec0fe-9ea9-4050-8c77-67b802663f43/3dc8ede4-72e3-4c58-bfc0-4d278aacbfa0/red-pixel.png?response-content-disposition=attachment&Expires=1866195996&Signature=YJBUtXXxTG8iT~p9HyX4Xut5zWmVa9YfpyEKbD6ljfvCp4BHmO3ASFR1uVhMdSd~tItjMm65y2EKw2OoRqGA~nqjCBSnn4YsrlOoiy5XBAAucSwFRRhirVnI5v8sr3yQhxAKthwZl0wjh2G4tUio1mixJnTub~UsR8KhIreiQu9NrkwMMhJ-b8hQ~YXvigmcA4LAVD6I3lz2PnIe~~Q2GA3us7lnwxXXgD1fpudGNwHDcP8C0~wzQktTPyV8yW2Aw3FRgC47zhoLdzWpgK4GPVnDY5px3mLy-AfoBzpuHIbIvPsXccf6qzVYPIsN~4YgxOROq8sDT0E12-0MpHU37A__&Key-Pair-Id=K2HIX5T4LSGPEG senderId: null workflowRule: null assigneeId: null assignee: null repliedMessage: null editedMessageId: null editedMessagePartitionKey: null editedMessage: null isEdited: false editedAt: null label: '' contactId: null receiverMetadata: null attachments: null headers: {} '400': description: '' content: application/json: schema: type: object properties: message: type: array items: type: string error: type: string statusCode: type: integer required: - message - error - statusCode example: message: - contactId should not be empty - contactId must be a string error: Bad Request statusCode: 400 headers: {} security: - bearer: [] /api/v1/comments: post: summary: Create comments deprecated: false description: >- Create a new comment in a specified room, optionally mentioning one or more users. tags: - Message parameters: [] requestBody: content: application/json: schema: type: object properties: text: type: string mentions: type: array items: type: object properties: index: type: integer userId: type: string required: - index - userId contactId: type: string format: uuid required: - text - mentions - contactId example: text: Hey {0}, can you review this with {1} when you have a moment? mentions: - index: 0 userId: uuid-string - index: 1 userId: uuid-string contactId: uuid-string required: true responses: '201': description: '' content: application/json: schema: type: object properties: requestId: type: string data: type: object properties: id: type: string roomId: type: string text: type: string type: type: string mentions: type: array items: type: object properties: userId: type: string name: type: string required: - userId - name sender: type: object properties: id: type: string name: type: string required: - id - name createdAt: type: string required: - id - roomId - text - type - mentions - sender - createdAt required: - requestId - data example: requestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx data: id: comment-uuid-002 roomId: room-uuid-abc text: Hey @John Doe, can you review this with @Jane Smith? type: comment mentions: - userId: user-uuid-456 name: John Doe - userId: user-uuid-789 name: Jane Smith sender: id: user-uuid-123 name: Current Auth User createdAt: '2026-02-27T12:20:00.000000Z' headers: {} security: - apiToken: [] get: summary: Get Comments deprecated: false description: Retrieve a paginated list of comments in a chat room. tags: - Message parameters: - name: page in: query description: '' required: false schema: type: integer default: 1 - name: pageSize in: query description: '' required: false schema: type: integer default: 20 - name: contactId in: query description: '' required: true schema: type: string format: uuid responses: '200': description: '' content: application/json: schema: type: object properties: requestId: type: string data: type: array items: type: object properties: id: type: string roomId: type: string text: type: string type: type: string mentions: type: array items: type: object properties: userId: type: string name: type: string sender: type: object properties: id: type: string name: type: string required: - id - name createdAt: type: string required: - id - roomId - text - type - mentions - sender - createdAt page: type: integer pageSize: type: integer total: type: integer lastPage: type: integer required: - requestId - data - page - pageSize - total - lastPage example: requestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx data: - id: comment-uuid-002 roomId: room-uuid-abc text: The issue has been resolved. type: comment mentions: [] sender: id: user-uuid-456 name: Agent Name createdAt: '2026-02-27T11:05:00Z' - id: comment-uuid-001 roomId: room-uuid-abc text: '@John Doe Please review this case.' type: comment mentions: - userId: user-uuid-123 name: John Doe sender: id: user-uuid-789 name: Admin User createdAt: '2026-02-27T11:00:00Z' page: 1 pageSize: 20 total: 2 lastPage: 1 headers: {} security: - apiToken: [] /api/v1/whatsapp/templates: get: summary: List WhatsApp templates deprecated: false description: > Lists the message templates of an official WhatsApp channel (360dialog / Meta), with each template's status and the `variables` to fill when sending it with **Send message** → `whatsappTemplate`. - Only `APPROVED` templates can be sent. - `variables` lists the body placeholders in order: `"1"`, `"2"` for positional placeholders, or names such as `first_name` for named ones. Send a value for each. - QR-linked WhatsApp numbers have no templates. ### Errors - **400**: the channel isn't an official WhatsApp channel, has no API key yet (reconnect it), or 360dialog couldn't be reached. - **404**: the channel wasn't found. tags: - Message parameters: - name: channelId in: query description: >- ID of the official WhatsApp channel (uuid). Find it with the Channel endpoints. required: true schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: status: type: integer body: type: object properties: requestId: type: string data: type: array items: type: object properties: name: type: string language: type: string category: type: string status: type: string components: type: array items: type: object properties: type: type: string text: type: string variables: type: array items: type: string required: - requestId - data required: - status - body example: status: 200 body: requestId: 8a1f2c3d-5e6f-4a7b-9c8d-0e1f2a3b4c5d data: - name: welcomemessage language: en category: MARKETING status: APPROVED components: - type: BODY text: |- Hey {{first_name}} 👋 Thanks for signing up for klink.cloud! variables: - first_name security: - apiToken: [] /api/v1/media-manager/files/upload: post: summary: Upload File (multipart) deprecated: false description: > Upload a file to the Media Manager as `multipart/form-data`. The file is streamed straight to storage, so large files aren't held in a JSON body. - One `file` part per request, **max 25 MB**. Larger files return `413`. - File names in any language (e.g. Thai) are preserved. - Use the returned `data.id` as `mediaFileId` in **Send message**. > For very small files you can also send Base64 in a JSON body with **Create File** (about 700 KB or less). ```bash curl -X POST https://apigw.klinkcx.com/api/v1/media-manager/files/upload \ -H "Authorization: Bearer " \ -F "file=@report.pdf;type=application/pdf" \ -F "title=Monthly report" ``` tags: - Media Manager parameters: [] requestBody: content: multipart/form-data: schema: type: object properties: file: description: The file to upload (max 25 MB). type: string format: binary fileName: description: >- Override the stored file name. Defaults to the uploaded file's name. type: string title: description: Title shown in the Media Manager. example: Monthly report type: string description: description: Description. type: string folderId: description: Target folder ID (UUID). type: string isFavorite: description: '`true` or `false`.' example: 'false' type: boolean isPrivate: description: '`true` or `false`.' example: 'false' type: boolean required: - file example: title: Monthly report isFavorite: 'false' isPrivate: 'false' required: true responses: '200': description: '' content: application/json: schema: type: object properties: data: type: object properties: id: type: string uploadId: type: string folderId: type: 'null' title: type: string description: type: string altText: type: string sortOrder: type: integer isFavorite: type: boolean isPrivate: type: boolean createdAt: type: string updatedAt: type: string upload: type: object properties: id: type: string fileName: type: string fileSize: type: integer fileUrl: type: string required: - id - fileName - fileSize - fileUrl required: - id - uploadId - folderId - title - description - altText - sortOrder - isFavorite - isPrivate - createdAt - updatedAt - upload required: - data headers: {} '400': description: Missing `file` part or invalid field (e.g. `folderId` not a UUID). content: application/json: schema: type: object properties: message: {} error: type: string statusCode: type: integer headers: {} '413': description: The file exceeds 25 MB. content: application/json: schema: type: object properties: message: type: string error: type: string statusCode: type: integer headers: {} security: - bearer: [] /api/v1/media-manager/folders: get: summary: Get Folders deprecated: false description: List folders with pagination and optional filters. tags: - Media Manager parameters: - name: parentId in: query description: Optional folder ID; when omitted, returns root folders. required: false example: '' schema: type: string - name: keyword in: query description: Filter by folder name (ILIKE). required: false example: '' schema: type: string - name: withDeleted in: query description: Boolean; include soft-deleted folders. required: false example: '' schema: type: string - name: pageSize in: query description: Items per page (1-200). Default 50. required: false example: '' schema: type: string - name: page in: query description: Page number (>=1). required: false example: '' schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string name: type: string slug: type: string path: type: string sortOrder: type: integer parentId: type: 'null' isPrivate: type: boolean createdAt: type: string updatedAt: type: string childrenCount: type: integer filesCount: type: integer required: - id - name - slug - path - sortOrder - parentId - isPrivate - createdAt - updatedAt - childrenCount - filesCount total: type: integer page: type: integer pageSize: type: integer lastPage: type: integer required: - data - total - page - pageSize - lastPage example: data: - id: 019b666f-5b1e-738e-b88f-6e08c466a4f7 name: testing slug: testing path: testing sortOrder: 0 parentId: null isPrivate: false createdAt: '2025-12-28T19:28:52.000000Z' updatedAt: '2025-12-28T19:28:52.000000Z' childrenCount: 0 filesCount: 0 - id: 019b6670-a56b-7115-a16c-3a4da0e1c8d4 name: testing slug: testing-2 path: testing-2 sortOrder: 0 parentId: null isPrivate: false createdAt: '2025-12-28T19:30:17.000000Z' updatedAt: '2025-12-28T19:30:17.000000Z' childrenCount: 0 filesCount: 0 total: 2 page: 1 pageSize: 2 lastPage: 1 headers: {} security: - apiToken: [] post: summary: Create Folder deprecated: false description: Create a new folder. tags: - Media Manager parameters: - name: Content-Type in: header description: '' required: true example: application/json schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string parentId: type: 'null' isPrivate: type: boolean sortOrder: type: integer required: - name - parentId - isPrivate - sortOrder example: name: API NEW FOLDER 7 parentId: null isPrivate: false sortOrder: 0 responses: '200': description: '' content: application/json: schema: type: object properties: {} headers: {} security: - bearer: [] /api/v1/media-manager/folders/{folderId}: get: summary: Get Folder By ID deprecated: false description: Get a single folder by ID. tags: - Media Manager parameters: - name: folderId in: path description: '' required: true example: 019b666f-5b1e-738e-b88f-6e08c466a4f7 schema: type: string - name: withDeleted in: query description: Boolean; include soft-deleted folder. required: false example: '' schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: data: type: object properties: id: type: string name: type: string slug: type: string path: type: string sortOrder: type: integer parentId: type: 'null' isPrivate: type: boolean createdAt: type: string updatedAt: type: string childrenCount: type: integer filesCount: type: integer required: - id - name - slug - path - sortOrder - parentId - isPrivate - createdAt - updatedAt - childrenCount - filesCount required: - data example: data: id: 019b6670-b4e9-71d5-ab51-b047253619b8 name: testing slug: testing-4 path: testing-4 sortOrder: 0 parentId: null isPrivate: false createdAt: '2025-12-28T19:30:21.000000Z' updatedAt: '2025-12-28T19:30:21.000000Z' childrenCount: 0 filesCount: 0 headers: {} security: - apiToken: [] /media-manager/folders/{id}: patch: summary: Update Folder deprecated: false description: Update folder properties. tags: - Media Manager parameters: - name: id in: path description: Folder ID required: true example: 019b3b7e-9c45-7344-b6ae-c9f86a9e5a52 schema: type: string - name: Content-Type in: header description: '' required: true example: application/json schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: 'null' parentId: type: string isPrivate: type: boolean sortOrder: type: integer required: - name - parentId - isPrivate - sortOrder example: name: null parentId: 019b3b81-c1b0-7213-8d00-fc6c6f1f0f5f isPrivate: true sortOrder: 10 responses: '200': description: '' content: application/json: schema: type: object properties: {} security: - apiToken: [] delete: summary: Delete Folder deprecated: false description: Delete a folder and its descendant folders and files. tags: - Media Manager parameters: - name: id in: path description: Folder ID required: true example: '' schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: {} security: - apiToken: [] /api/v1/media-manager/files: get: summary: Get Files deprecated: false description: List files with pagination and filters. tags: - Media Manager parameters: - name: folderId in: query description: Optional folder ID; omit for root files. required: false example: a0b11fa2-2f89-42b3-b3e7-95e63ac14b46 schema: type: string - name: keyword in: query description: Filter by title/description/upload.file_name (ILIKE). required: false example: '' schema: type: string - name: isFavorite in: query description: Boolean; filter favorite files. required: false example: '' schema: type: string - name: withDeleted in: query description: Boolean; include soft-deleted files. required: false example: '' schema: type: string - name: pageSize in: query description: Items per page (1-200). Default 50. required: false example: '' schema: type: string - name: page in: query description: Page number (>=1). required: false example: '' schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: {} headers: {} security: - bearer: [] post: summary: Create File deprecated: false description: >- Create a media file from Base64 data in a JSON body. > **Prefer [Upload File (multipart)](#) for real files.** Base64 inflates the payload by about a third, and JSON request bodies are limited to 100 KB, so this endpoint only suits very small files (about 75 KB or less). The multipart endpoint streams files up to 25 MB. tags: - Media Manager parameters: [] requestBody: content: application/json: schema: type: object properties: data: type: string description: File content, Base64-encoded. fileName: type: string description: File name including extension. mimeType: type: string description: MIME type, e.g. `image/png`. title: type: string description: type: string altText: type: string folderId: type: - string - 'null' description: Target folder ID (optional). isFavorite: type: boolean isPrivate: type: boolean sortOrder: type: integer required: - data - fileName - mimeType example: data: >- iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg== fileName: red-pixel.png mimeType: image/png title: Red Pixel Test description: A tiny test image to verify upload altText: Alt text isPrivate: false folderId: 019b666f-5b1e-738e-b88f-6e08c466a4f7 isFavorite: true sortOrder: 0 required: true responses: '200': description: '' content: application/json: schema: type: object properties: data: type: object properties: id: type: string uploadId: type: string folderId: type: 'null' title: type: string description: type: string altText: type: string sortOrder: type: integer isFavorite: type: boolean isPrivate: type: boolean createdAt: type: string updatedAt: type: string upload: type: object properties: id: type: string fileName: type: string fileSize: type: integer fileUrl: type: string required: - id - fileName - fileSize - fileUrl required: - id - uploadId - folderId - title - description - altText - sortOrder - isFavorite - isPrivate - createdAt - updatedAt - upload required: - data example: data: id: a1196518-4c90-4ed0-ab9f-d5a1c8d58870 uploadId: a1196518-035f-49b6-9d22-951f6f0a7a39 folderId: null title: Red Pixel Test description: A tiny test image to verify upload altText: Alt text sortOrder: 0 isFavorite: true isPrivate: false createdAt: '2026-02-17T05:00:23.000000Z' updatedAt: '2026-02-17T05:00:23.000000Z' upload: id: a1196518-035f-49b6-9d22-951f6f0a7a39 fileName: red-pixel.png fileSize: 70 fileUrl: https://cdn.klink.cloud/media-manager/your-image-url headers: {} security: - bearer: [] /api/v1/media-manager/files/{fileId}: get: summary: Get File By ID deprecated: false description: Get file details by ID. tags: - Media Manager parameters: - name: fileId in: path description: '' required: true example: a11ff961-cf00-4f9f-bb7b-c2c04a274605 schema: type: string - name: withDeleted in: query description: Boolean; include soft-deleted file. required: false example: '' schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: data: type: object properties: id: type: string uploadId: type: string folderId: type: string title: type: string description: type: string altText: type: string sortOrder: type: integer isFavorite: type: boolean isPrivate: type: boolean createdAt: type: string updatedAt: type: string upload: type: object properties: id: type: string fileName: type: string fileSize: type: integer fileUrl: type: string required: - id - fileName - fileSize - fileUrl required: - id - uploadId - folderId - title - description - altText - sortOrder - isFavorite - isPrivate - createdAt - updatedAt - upload required: - data example: data: id: a11ff961-cf00-4f9f-bb7b-c2c04a274605 uploadId: a11ff961-ca9e-4bf0-ae5d-bbf6b5346ded folderId: 019b666f-5b1e-738e-b88f-6e08c466a4f7 title: Red Pixel Test description: A tiny test image to verify upload altText: Alt text sortOrder: 0 isFavorite: true isPrivate: false createdAt: '2026-02-20T11:29:59.000000Z' updatedAt: '2026-02-20T11:29:59.000000Z' upload: id: a11ff961-ca9e-4bf0-ae5d-bbf6b5346ded fileName: red-pixel.png fileSize: 70 fileUrl: >- https://cdn.klink.cloud/media-manager/038ec0fe-9ea9-4050-8c77-67b802663f43/3dc8ede4-72e3-4c58-bfc0-4d278aacbfa0/red-pixel.png?Expires=1771590808&Signature=PbGvpM7qXGv293GcJ7FjZDRSWyhbsbRo2qjEhAUrlRDBBVm97atGT3LqX5WFGu-jJOE0-Z3zWVKOYSpxfIiTttUTRf1M6Jp541i12UXKb5jP3Tckcof7YxkQesLAI5EjKykEs96s-I6rpwamQnlUjRGC-F8T47H8sjVphtwP0M8DvjceGN-GTtzgZWWhy4THoJnLGvAQql1wEEeb48i98GwOnwbqnlHntTs73BfCw2HwHpF3OqmfJVDCCCOvxGxou3qTqwTs7wamKJTQFhCFdj7G7JoBNxi-oO~TaXfe50Krcbmkr567R6g1vAu-65bY6yxDbRv5XdxCACYg7VkKQw__&Key-Pair-Id=K2HIX5T4LSGPEG headers: {} security: - apiToken: [] /media-manager/files/{id}: patch: summary: Update File deprecated: false description: Update file properties. tags: - Media Manager parameters: - name: id in: path description: File ID required: true example: 019b3c21-4e10-7084-abc7-0fecd8e4f9aa schema: type: string - name: Content-Type in: header description: '' required: true example: application/json schema: type: string requestBody: content: application/json: schema: type: object properties: title: type: string required: - title example: title: video-file.webp responses: '200': description: '' content: application/json: schema: type: object properties: {} security: - apiToken: [] delete: summary: Delete File deprecated: false description: Soft-delete a file. tags: - Media Manager parameters: - name: id in: path description: File ID required: true example: '' schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: {} security: - apiToken: [] /api/v1/user-presence-status-log: get: summary: Get Agents Activities deprecated: false description: '' tags: - Agent Activity parameters: - name: page in: query description: '' required: false schema: type: integer - name: pageSize in: query description: '' required: false schema: type: integer responses: '200': description: '' content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string createdAt: type: string previousPresenceStatus: type: object properties: id: type: string systemName: type: string displayName: type: string emoji: type: string required: - id - systemName - displayName - emoji newPresenceStatus: type: object properties: id: type: string systemName: type: string displayName: type: string emoji: type: string required: - id - systemName - displayName - emoji reason: type: string user: type: object properties: id: type: string name: type: string required: - id - name required: - id - createdAt - previousPresenceStatus - newPresenceStatus - reason - user page: type: integer pageSize: type: integer total: type: integer lastPage: type: integer required: - data - page - pageSize - total - lastPage example: data: - id: uuid-string createdAt: '2026-02-12T04:46:24.491Z' previousPresenceStatus: id: uuid-string systemName: available displayName: Available emoji: 🟢 newPresenceStatus: id: uuid-string systemName: in_meeting displayName: In meeting emoji: 🗓️ reason: '' user: id: uuid-string name: John - id: uuid-string createdAt: '2025-11-11T04:08:14.860Z' previousPresenceStatus: id: uuid-string systemName: available displayName: Available emoji: 🟢 newPresenceStatus: id: uuid-string systemName: in_meeting displayName: In meeting emoji: 🗓️ reason: x user: id: uuid-string name: NangXmue - id: uuid-string createdAt: '2025-10-21T10:56:47.836Z' previousPresenceStatus: id: uuid-string systemName: away displayName: Away emoji: ⛔ newPresenceStatus: id: uuid-string systemName: available displayName: Available emoji: 🟢 reason: x user: id: uuid-string name: NangXmue page: 1 pageSize: 3 total: 247 lastPage: 83 headers: {} security: - apiToken: [] /api/v1/telephony-cdr: get: summary: Get Telephony CDR deprecated: false description: '' tags: - Telephony parameters: - name: selectedDate in: query description: >- Date filter applied by the service; used with x-client-timezone to interpret the date. required: false example: '' schema: type: string - name: type in: query description: >- Filter by call type(s). Values depend on your telephony CDR type enum (e.g., Inbound/Outbound/Internal). required: false example: '' schema: type: array items: type: string - name: status in: query description: >- Filter by call status(es). Values depend on your telephony CDR status enum (e.g., Answered/No Answer/Busy/Failed). required: false example: '' schema: type: array items: type: string - name: callFrom in: query description: >- Filters by caller. The service expands this across contact phones, queue numbers, and extensions before filtering. required: false example: '' schema: type: string - name: callTo in: query description: >- Filters by callee. Also expands across contact phones, queue numbers, and extensions. required: false example: '' schema: type: string - name: trunk in: query description: Filter by trunk name(s). required: false example: '' schema: type: array items: type: string - name: agentIds in: query description: Filter by multiple agent IDs. required: false example: '' schema: type: array items: type: string - name: contactId in: query description: Filter CDRs by a specific contact. required: false example: '' schema: type: string - name: recordingsOnly in: query description: If true, returns only calls with recordings. required: false example: '' schema: type: boolean - name: page in: query description: Page index (1-based). Default 1. required: false example: '' schema: type: integer - name: pageSize in: query description: Page size. Default 10. Max 200 enforced upstream. required: false example: '' schema: type: integer - name: userId in: query description: Filter CDRs by a specific user ID (agent). required: false example: '' schema: type: string - name: queueStatus in: query description: true if answered, or false if no-answered required: false example: '' schema: type: boolean - name: agentCallsOnly in: query description: If true, returns only agent-related calls. required: false example: '' schema: type: boolean - name: tagIds in: query description: Filter CDRs that have any of the specified tag IDs. required: false example: '' schema: type: array items: type: string responses: '200': description: '' content: application/json: schema: type: object properties: requestId: type: string data: type: array items: type: object properties: id: type: string uniqueCallId: type: string timeStart: type: string callFrom: type: string callTo: type: string callDuration: type: integer talkDuration: type: integer srcTrunkName: type: string dstTrunkName: type: string status: type: string type: type: string recording: type: string didNumber: type: string agentRingTime: type: integer uploadId: type: string serialNumber: type: string extensionId: type: string telephonyQueueId: type: string contactId: type: string createdAt: type: string updatedAt: type: string deletedAt: type: string isQueueMissedCall: type: boolean callParticipants: type: string wrapUpFormId: type: string telephonyIvrId: type: string recordingFileUrl: type: string description: Temporary recording file URL. Expires in 1 hour. extension: type: object properties: id: type: string userId: type: string user: type: object properties: id: type: string createdAt: type: string updatedAt: type: string name: type: string phone: type: string required: - id - createdAt - updatedAt - name - phone extensionId: type: string extensionName: type: string createdAt: type: string updatedAt: type: string deletedAt: type: string required: - id - userId - user - extensionId - extensionName - createdAt - updatedAt - deletedAt telephonyQueue: type: object properties: id: type: string name: type: string status: type: string ringStrategy: type: string callTimeout: type: integer companyId: type: string wrapUpTime: type: integer createdAt: type: string updatedAt: type: string deletedAt: type: string required: - id - name - status - ringStrategy - callTimeout - companyId - wrapUpTime - createdAt - updatedAt - deletedAt contact: type: object properties: id: type: string createdAt: type: string updatedAt: type: string deletedAt: type: string name: type: string address: type: string channel: type: string notes: type: string contactNumber: type: integer companyId: type: string contactProfile: type: string socialProfileUrl: type: string required: - id - createdAt - updatedAt - deletedAt - name - address - channel - notes - contactNumber - companyId - contactProfile - socialProfileUrl tags: type: array items: type: object properties: id: type: string name: type: string color: type: string total: type: integer page: type: integer pageSize: type: integer lastPage: type: integer required: - requestId - data - total - page - pageSize - lastPage example: requestId: uuid string data: - id: uuid string uniqueCallId: string timeStart: datetime string (YYYY-MM-DD HH:mm:ss) callFrom: string callTo: string callDuration: 0 talkDuration: 0 srcTrunkName: string dstTrunkName: string status: string type: string recording: string didNumber: string agentRingTime: 0 uploadId: uuid string or null serialNumber: string extensionId: uuid string or null telephonyQueueId: uuid string or null contactId: uuid string or null createdAt: datetime string updatedAt: datetime string deletedAt: datetime string or null isQueueMissedCall: false callParticipants: array or null wrapUpFormId: uuid string or null telephonyIvrId: uuid string or null recordingFileUrl: string extension: id: uuid string userId: uuid string user: id: uuid string createdAt: datetime string updatedAt: datetime string name: string phone: string extensionId: string extensionName: string createdAt: datetime string updatedAt: datetime string deletedAt: datetime string or null telephonyQueue: id: uuid string name: string status: string ringStrategy: string callTimeout: 0 companyId: uuid string wrapUpTime: 0 createdAt: datetime string updatedAt: datetime string deletedAt: datetime string or null contact: id: uuid string createdAt: datetime string updatedAt: datetime string deletedAt: datetime string or null name: string address: string or null channel: string notes: string or null contactNumber: 0 companyId: uuid string or null contactProfile: object or null socialProfileUrl: url string or null tags: - id: uuid string name: string color: string hex total: 0 page: 1 pageSize: 10 lastPage: 0 headers: {} security: - apiToken: [] /api/v1/users: post: summary: Create deprecated: false description: >- Creates a user (agent) in your workspace. The account is usable immediately — the person does not need to be invited or to log in first, which is the point of this endpoint. `roleIds` must contain at least one role ID from **Role → Listing**. An unrecognised ID is rejected with `422`, so fetch the list once and cache it. **The account becomes loginable a moment after this call returns.** The response is `201` as soon as the user is stored, while the sign-in directory is updated asynchronously. In practice this is a second or two. If a caller reports that a brand-new account cannot sign in, re-read it with **Detail** and retry the login rather than creating the user again. An email address must be unique across all of klink.cloud, not just your workspace. Reusing one returns `422`. operationId: PublicUserController_create tags: - User parameters: [] requestBody: content: application/json: schema: type: object properties: name: type: string description: Display name. Cannot contain `@`. email: type: string description: Sign-in address. Must be globally unique. password: type: string description: >- Initial sign-in password. Sent to you only in this request; never returned by any endpoint. roleIds: type: array items: type: string description: One or more role IDs from Role → Listing. phone: type: - string - 'null' address: type: - string - 'null' globalAgentCapacity: type: - integer - 'null' description: Optional cap on concurrent conversations. required: - name - email - password - roleIds responses: '201': description: '' content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. data: type: object properties: id: type: string name: type: string email: type: string phone: type: - string - 'null' address: type: - string - 'null' globalAgentCapacity: type: - integer - 'null' description: >- Maximum concurrent conversations for this agent, or null to fall back to the queue setting. roles: type: array items: type: object properties: id: type: string description: >- Role ID. Use this in `roleIds` when creating or updating a user. systemName: type: string displayName: type: string description: type: - string - 'null' required: - id - systemName - displayName - description createdAt: type: string updatedAt: type: string required: - id - name - email - phone - address - globalAgentCapacity - roles - createdAt - updatedAt required: - requestId - data '401': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '422': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '429': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '503': description: '' content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] get: summary: Listing deprecated: false description: >- Returns a paginated list of the users in your workspace. `keyword` matches on name and email. Search is substring-based, so `kyaw` finds "Kyaw Kyaw". operationId: PublicUserController_list tags: - User parameters: - name: page in: query description: Page number. Defaults to 1. required: false example: '1' schema: type: - integer - 'null' - name: pageSize in: query description: Records per page. Defaults to 10, maximum 200. required: false example: '10' schema: type: - integer - 'null' - name: keyword in: query description: Filter by name or email substring. required: false example: '' schema: type: - string - 'null' responses: '200': description: '' content: application/json: schema: type: object properties: page: type: integer pageSize: type: integer total: type: integer lastPage: type: - integer - 'null' data: type: array items: type: object properties: id: type: string name: type: string email: type: string phone: type: - string - 'null' address: type: - string - 'null' globalAgentCapacity: type: - integer - 'null' description: >- Maximum concurrent conversations for this agent, or null to fall back to the queue setting. roles: type: array items: type: object properties: id: type: string description: >- Role ID. Use this in `roleIds` when creating or updating a user. systemName: type: string displayName: type: string description: type: - string - 'null' required: - id - systemName - displayName - description createdAt: type: string updatedAt: type: string required: - id - name - email - phone - address - globalAgentCapacity - roles - createdAt - updatedAt required: - page - pageSize - total - lastPage - data headers: {} '401': description: '' content: application/json: schema: type: object properties: message: type: string required: - message headers: {} '429': description: '' content: application/json: schema: type: object properties: message: type: string required: - message headers: {} security: - apiToken: [] /api/v1/users/{id}: get: summary: Detail deprecated: false description: >- Returns a single user. Also the quickest way to confirm that a newly created account has finished provisioning. operationId: PublicUserController_detail tags: - User parameters: - name: id in: path description: User ID. required: true example: '' schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. data: type: object properties: id: type: string name: type: string email: type: string phone: type: - string - 'null' address: type: - string - 'null' globalAgentCapacity: type: - integer - 'null' description: >- Maximum concurrent conversations for this agent, or null to fall back to the queue setting. roles: type: array items: type: object properties: id: type: string description: >- Role ID. Use this in `roleIds` when creating or updating a user. systemName: type: string displayName: type: string description: type: - string - 'null' required: - id - systemName - displayName - description createdAt: type: string updatedAt: type: string required: - id - name - email - phone - address - globalAgentCapacity - roles - createdAt - updatedAt required: - requestId - data '401': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '404': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '429': description: '' content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] patch: summary: Update deprecated: false description: >- Updates a user. **Send only the fields you want to change** — anything you omit is left exactly as it was, including roles. Supply `password` only when you intend to reset it. Omit it and the existing password is preserved. Supplying `roleIds` **replaces** the user's roles rather than adding to them. Read the current roles with **Detail** first if you mean to append. operationId: PublicUserController_update tags: - User parameters: - name: id in: path description: User ID. required: true example: '' schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string description: Cannot contain `@`. email: type: string password: type: string description: New password. Omit to keep the current one. roleIds: type: array items: type: string description: Replaces the existing roles. phone: type: - string - 'null' address: type: - string - 'null' globalAgentCapacity: type: - integer - 'null' responses: '200': description: '' content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. data: type: object properties: id: type: string name: type: string email: type: string phone: type: - string - 'null' address: type: - string - 'null' globalAgentCapacity: type: - integer - 'null' description: >- Maximum concurrent conversations for this agent, or null to fall back to the queue setting. roles: type: array items: type: object properties: id: type: string description: >- Role ID. Use this in `roleIds` when creating or updating a user. systemName: type: string displayName: type: string description: type: - string - 'null' required: - id - systemName - displayName - description createdAt: type: string updatedAt: type: string required: - id - name - email - phone - address - globalAgentCapacity - roles - createdAt - updatedAt required: - requestId - data '401': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '404': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '422': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '429': description: '' content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] delete: summary: Delete deprecated: false description: >- Deactivates a user and removes them from every queue they belong to. **A user who still owns open conversations cannot be deleted** — the request returns `409` and nothing changes. Close or reassign their conversations first, otherwise those chats would be left pointing at a deleted agent. Deletion is reversible only by support, and the email address is not immediately reusable. operationId: PublicUserController_delete tags: - User parameters: - name: id in: path description: User ID. required: true example: '' schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. message: type: string required: - requestId - message '401': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '404': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '409': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '429': description: '' content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] /api/v1/queues: post: summary: Create deprecated: false description: >- Creates an automation queue — the mechanism that routes incoming conversations to agents. `agentIds` and `managerIds` each need at least one user; use **User → Listing** to find IDs. The same person may be both. Set `maximumAssignPerAgent` deliberately: omitted, it defaults to **1**, so each agent holds a single conversation at a time. operationId: PublicAutomationQueueController_create tags: - Automation Queue parameters: [] requestBody: content: application/json: schema: type: object properties: name: type: string description: Queue name. Must be unique in your workspace. agentIds: type: array items: type: string description: >- Users who receive conversations from this queue. At least one. managerIds: type: array items: type: string description: Users who supervise this queue. At least one. description: type: - string - 'null' emoji: type: string description: Icon shown beside the queue name. Defaults to 📥. distributionStrategy: type: - string - 'null' enum: - round-robin - fewest-assignments - random - notify-all - null description: >- How conversations are handed out: `round-robin` in turn, `fewest-assignments` to the least busy agent, `random`, or `notify-all` to alert everyone. maximumAssignPerAgent: type: - integer - 'null' description: >- Concurrent conversations per agent. Defaults to 1 when omitted — set it explicitly for anything busier. useGlobalAgentCapacity: type: boolean description: Use each agent's own capacity instead of the queue limit. offlineAssignment: type: boolean description: Assign conversations to agents who are offline. autoAssign: type: - boolean - 'null' description: >- Hand out conversations automatically. When false, a supervisor assigns them manually. required: - name - agentIds - managerIds responses: '201': description: '' content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. data: type: object properties: id: type: string name: type: string description: type: - string - 'null' emoji: type: string distributionStrategy: type: - string - 'null' enum: - round-robin - fewest-assignments - random - notify-all - null maximumAssignPerAgent: type: - integer - 'null' useGlobalAgentCapacity: type: boolean offlineAssignment: type: boolean autoAssign: type: - boolean - 'null' members: type: array items: type: object properties: userId: type: string name: type: string email: type: string membershipRole: type: string enum: - agent - manager description: >- `agent` receives conversations from the queue; `manager` supervises it. required: - userId - name - email - membershipRole createdAt: type: string updatedAt: type: string required: - id - name - description - emoji - distributionStrategy - maximumAssignPerAgent - useGlobalAgentCapacity - offlineAssignment - autoAssign - members - createdAt - updatedAt required: - requestId - data '401': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '409': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '422': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '429': description: '' content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] get: summary: Listing deprecated: false description: >- Returns every automation queue in your workspace, each with its full member list. This endpoint is not paginated. operationId: PublicAutomationQueueController_list tags: - Automation Queue parameters: [] responses: '200': description: '' content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. data: type: array items: type: object properties: id: type: string name: type: string description: type: - string - 'null' emoji: type: string distributionStrategy: type: - string - 'null' enum: - round-robin - fewest-assignments - random - notify-all - null maximumAssignPerAgent: type: - integer - 'null' useGlobalAgentCapacity: type: boolean offlineAssignment: type: boolean autoAssign: type: - boolean - 'null' members: type: array items: type: object properties: userId: type: string name: type: string email: type: string membershipRole: type: string enum: - agent - manager description: >- `agent` receives conversations from the queue; `manager` supervises it. required: - userId - name - email - membershipRole createdAt: type: string updatedAt: type: string required: - id - name - description - emoji - distributionStrategy - maximumAssignPerAgent - useGlobalAgentCapacity - offlineAssignment - autoAssign - members - createdAt - updatedAt required: - requestId - data '401': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '429': description: '' content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] /api/v1/queues/{id}: get: summary: Detail deprecated: false description: Returns a single queue with its members and routing settings. operationId: PublicAutomationQueueController_detail tags: - Automation Queue parameters: - name: id in: path description: Queue ID. required: true example: '' schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. data: type: object properties: id: type: string name: type: string description: type: - string - 'null' emoji: type: string distributionStrategy: type: - string - 'null' enum: - round-robin - fewest-assignments - random - notify-all - null maximumAssignPerAgent: type: - integer - 'null' useGlobalAgentCapacity: type: boolean offlineAssignment: type: boolean autoAssign: type: - boolean - 'null' members: type: array items: type: object properties: userId: type: string name: type: string email: type: string membershipRole: type: string enum: - agent - manager description: >- `agent` receives conversations from the queue; `manager` supervises it. required: - userId - name - email - membershipRole createdAt: type: string updatedAt: type: string required: - id - name - description - emoji - distributionStrategy - maximumAssignPerAgent - useGlobalAgentCapacity - offlineAssignment - autoAssign - members - createdAt - updatedAt required: - requestId - data '401': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '404': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '429': description: '' content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] patch: summary: Update deprecated: false description: >- Updates a queue. **Send only the fields you want to change** — omitted fields keep their current values, and the member list is left untouched. Supplying `agentIds` or `managerIds` **replaces** that list. To add or remove one person, prefer **Add Member** / **Remove Member**, which are safer under concurrent updates. operationId: PublicAutomationQueueController_update tags: - Automation Queue parameters: - name: id in: path description: Queue ID. required: true example: '' schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string description: Queue name. Must be unique in your workspace. agentIds: type: array items: type: string description: >- Users who receive conversations from this queue. At least one. managerIds: type: array items: type: string description: Users who supervise this queue. At least one. description: type: - string - 'null' emoji: type: string description: Icon shown beside the queue name. Defaults to 📥. distributionStrategy: type: - string - 'null' enum: - round-robin - fewest-assignments - random - notify-all - null description: >- How conversations are handed out: `round-robin` in turn, `fewest-assignments` to the least busy agent, `random`, or `notify-all` to alert everyone. maximumAssignPerAgent: type: - integer - 'null' description: >- Concurrent conversations per agent. Defaults to 1 when omitted — set it explicitly for anything busier. useGlobalAgentCapacity: type: boolean description: Use each agent's own capacity instead of the queue limit. offlineAssignment: type: boolean description: Assign conversations to agents who are offline. autoAssign: type: - boolean - 'null' description: >- Hand out conversations automatically. When false, a supervisor assigns them manually. responses: '200': description: '' content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. data: type: object properties: id: type: string name: type: string description: type: - string - 'null' emoji: type: string distributionStrategy: type: - string - 'null' enum: - round-robin - fewest-assignments - random - notify-all - null maximumAssignPerAgent: type: - integer - 'null' useGlobalAgentCapacity: type: boolean offlineAssignment: type: boolean autoAssign: type: - boolean - 'null' members: type: array items: type: object properties: userId: type: string name: type: string email: type: string membershipRole: type: string enum: - agent - manager description: >- `agent` receives conversations from the queue; `manager` supervises it. required: - userId - name - email - membershipRole createdAt: type: string updatedAt: type: string required: - id - name - description - emoji - distributionStrategy - maximumAssignPerAgent - useGlobalAgentCapacity - offlineAssignment - autoAssign - members - createdAt - updatedAt required: - requestId - data '401': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '404': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '409': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '429': description: '' content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] delete: summary: Delete deprecated: false description: >- Deletes a queue and its membership records. **A queue still holding open conversations cannot be deleted** — the request returns `409` and nothing changes. This includes conversations waiting in the queue as well as ones already assigned from it. operationId: PublicAutomationQueueController_delete tags: - Automation Queue parameters: - name: id in: path description: Queue ID. required: true example: '' schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. message: type: string required: - requestId - message '401': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '404': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '409': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '429': description: '' content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] /api/v1/queues/{id}/members: post: summary: Add Member deprecated: false description: >- Adds one user to a queue, as either an agent or a manager. Use this rather than **Update** when adding a single person: it will not disturb the other members and is safe when several additions happen at once. A user may hold both roles on the same queue: add them twice with different `membershipRole` values. Adding someone who already holds that exact role returns `409`; use **Remove Member** with `membershipRole` to drop one role without the other. If the queue assigns automatically, a new agent starts receiving waiting conversations right away. operationId: PublicAutomationQueueController_addMember tags: - Automation Queue parameters: - name: id in: path description: Queue ID. required: true example: '' schema: type: string requestBody: content: application/json: schema: type: object properties: userId: type: string description: User ID from User → Listing. membershipRole: type: string enum: - agent - manager description: >- `agent` receives conversations; `manager` supervises the queue. required: - userId - membershipRole responses: '201': description: '' content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. data: type: object properties: userId: type: string name: type: string email: type: string membershipRole: type: string enum: - agent - manager description: >- `agent` receives conversations from the queue; `manager` supervises it. required: - userId - name - email - membershipRole required: - requestId - data '401': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '404': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '409': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '429': description: '' content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] /api/v1/queues/{id}/members/{userId}: delete: summary: Remove Member deprecated: false description: >- Removes a user from a queue. Their other queue memberships are unaffected, and the account itself is not deleted. A user may be both an agent and a manager of the same queue. Pass `membershipRole` to remove only that role and keep the other; omit it to remove every membership the user holds on the queue. Removing someone who does not hold that membership returns `404`. operationId: PublicAutomationQueueController_removeMember tags: - Automation Queue parameters: - name: id in: path description: Queue ID. required: true example: '' schema: type: string - name: userId in: path description: User ID to remove. required: true example: '' schema: type: string - name: membershipRole in: query description: >- Which membership to remove: `agent` or `manager`. Omit to remove the user from the queue entirely (both roles). required: false example: agent schema: type: string enum: - agent - manager responses: '200': description: '' content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. message: type: string required: - requestId - message '401': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '404': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '429': description: '' content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] /api/v1/roles: get: summary: Listing deprecated: false description: >- Returns the roles defined in your workspace. A role is a bundle of permissions. Call this first when creating or updating users: the `id` values here are what `roleIds` expects. Roles change rarely, so fetching once per run is enough. Note this is unrelated to a user's role *within a queue* (agent or manager), which is set by **Automation Queue → Add Member**. operationId: PublicRoleController_list tags: - Role parameters: [] responses: '200': description: '' content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. data: type: array items: type: object properties: id: type: string description: >- Role ID. Use this in `roleIds` when creating or updating a user. systemName: type: string displayName: type: string description: type: - string - 'null' required: - id - systemName - displayName - description required: - requestId - data '401': description: '' content: application/json: schema: type: object properties: message: type: string required: - message '429': description: '' content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] /api/v1/webchat/channels/{channelId}/identity-verification: get: summary: Get identity verification settings deprecated: false description: > Returns whether a secret is configured and which verification rules are active. The secret itself is never returned by this endpoint. operationId: getIdentityVerification tags: - Webchat Identity Verification parameters: - name: channelId in: path description: '' required: true example: '' schema: type: string responses: '200': description: Current settings. content: application/json: schema: $ref: '#/components/schemas/IdentityVerificationStatus' example: requestId: 3f2b6c1e-9d7a-4e1b-8c55-2a9f0e7d4b10 secretConfigured: true enforceIdentityVerification: true requireIdentityToken: false headers: {} '400': $ref: '#/components/responses/BadRequest' description: Invalid request, e.g. `channelId` is not a UUID. '401': $ref: '#/components/responses/Unauthorized' description: The API token is missing, invalid, expired or revoked. '404': $ref: '#/components/responses/ChannelNotFound' description: No web chat channel with this ID exists in your account. '429': $ref: '#/components/responses/TooManyRequests' description: Rate limit exceeded (10 requests per second). '502': $ref: '#/components/responses/BadGateway' description: The chat service couldn't be reached. Retry shortly. security: - apiToken: [] put: summary: Update identity verification settings deprecated: false description: > Turn verification rules on or off. Send `enforce`, `requireToken`, or both. Fields you leave out keep their current value. - **`enforce: true`** means a logged-in user **must** be verified. Unverified identities are treated as anonymous guests. - **`requireToken: true`** means only expiring `userToken`s are accepted. The non-expiring legacy `userHash` is refused. Both require an identity secret (create one with `POST …/secret` first). Turn on `requireToken` only when every page and every supported app version sends `userToken`. Otherwise those users chat as guests. operationId: updateIdentityVerification tags: - Webchat Identity Verification parameters: - name: channelId in: path description: '' required: true example: '' schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/IdentityVerificationUpdate' examples: enforce: value: enforce: true summary: Require verified identities tokensOnly: value: requireToken: true summary: Accept only expiring userTokens both: value: enforce: true requireToken: true summary: Both rules required: true responses: '200': description: Settings updated. content: application/json: schema: $ref: '#/components/schemas/IdentityVerificationSettings' example: requestId: 7c0d4e2a-1b3f-4a6d-9e8c-5f2b1a0d3c47 enforceIdentityVerification: true requireIdentityToken: true headers: {} '400': description: > Invalid request. Either neither field was sent, a value isn't a boolean, or enforcement was requested before an identity secret exists. content: application/json: schema: $ref: '#/components/schemas/Error' examples: noSecret: summary: noSecret value: statusCode: 400 message: >- Generate an identity secret before enforcing identity verification invalidType: summary: invalidType value: statusCode: 400 message: - enforce must be a boolean value error: Bad Request headers: {} '401': $ref: '#/components/responses/Unauthorized' description: The API token is missing, invalid, expired or revoked. '404': $ref: '#/components/responses/ChannelNotFound' description: No web chat channel with this ID exists in your account. '429': $ref: '#/components/responses/TooManyRequests' description: Rate limit exceeded (10 requests per second). '502': $ref: '#/components/responses/BadGateway' description: The chat service couldn't be reached. Retry shortly. security: - apiToken: [] /api/v1/webchat/channels/{channelId}/identity-verification/secret: post: summary: Create or rotate the identity secret deprecated: false description: > Creates the channel's identity secret, or replaces it if one exists. **The secret is returned only in this response.** Store it in your server's secret manager. Never put it in a website, mobile app or source code. Rotating takes effect immediately: - every `userToken` and `userHash` made with the old secret stops working; - every active chat session ends, and the user continues as a guest until your page or app provides a new token. Deploy the new secret to your servers at the same time. operationId: rotateIdentitySecret tags: - Webchat Identity Verification parameters: - name: channelId in: path description: '' required: true example: '' schema: type: string responses: '201': description: New secret created. content: application/json: schema: $ref: '#/components/schemas/IdentitySecret' example: requestId: 9a1e3b5c-7d2f-4c8a-b6e4-0f1d2c3b4a59 secret: >- 9f2c4a7e1b3d5f60a8c2e4b6d8f0a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5 headers: {} '400': $ref: '#/components/responses/BadRequest' description: Invalid request, e.g. `channelId` is not a UUID. '401': $ref: '#/components/responses/Unauthorized' description: The API token is missing, invalid, expired or revoked. '404': $ref: '#/components/responses/ChannelNotFound' description: No web chat channel with this ID exists in your account. '429': $ref: '#/components/responses/TooManyRequests' description: Rate limit exceeded (10 requests per second). '502': $ref: '#/components/responses/BadGateway' description: The chat service couldn't be reached. Retry shortly. security: - apiToken: [] /api/v1/ai-agent-models: get: summary: List Models deprecated: false description: >- Lists the models an AI agent flow can use. Send a `slug` as `model` when saving a flow. Models marked `legacy` are listed for reference only and are rejected on save. tags: - AI Agent parameters: [] responses: '200': description: '' content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. data: type: array items: type: object properties: slug: type: string description: Value to send as `model`. name: type: string description: type: - string - 'null' legacy: type: boolean description: Legacy models cannot be used in new flows. required: - slug - name - description - legacy required: - requestId - data '401': description: API key missing, invalid, revoked or expired. content: application/json: schema: type: object properties: message: type: string required: - message '429': description: Rate limit reached. Retry after a short pause. content: application/json: schema: type: object properties: message: type: string required: - message '502': description: The AI agent service is temporarily unavailable. Retry shortly. content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] /api/v1/ai-agents: get: summary: Listing deprecated: false description: Lists the AI agents in your workspace. tags: - AI Agent parameters: - name: status in: query description: >- `all` (default), `draft` (has a saved draft) or `live` (has been published). required: false example: all schema: type: string enum: - all - draft - live default: all - name: page in: query description: Default 1. required: false example: 1 schema: type: integer minimum: 1 default: 1 - name: pageSize in: query description: Default 10, max 100. required: false example: 10 schema: type: integer minimum: 1 maximum: 100 default: 10 responses: '200': description: '' content: application/json: schema: type: object properties: page: type: integer pageSize: type: integer total: type: integer lastPage: type: integer data: type: array items: type: object properties: id: type: string description: AI agent ID. Use it in every `/ai-agents/{id}` path. name: type: string inactivityTimeout: type: integer description: >- Seconds of customer silence before the conversation session expires and the next message starts fresh. hasDraft: type: boolean description: True once a draft flow has been saved. hasLive: type: boolean description: >- True once a flow has been published. Only live agents answer customers. required: - id - name - inactivityTimeout - hasDraft - hasLive required: - page - pageSize - total - lastPage - data '400': description: >- Invalid body or parameters, e.g. an empty name, an unknown node type or a malformed ID. content: application/json: schema: type: object properties: message: type: string required: - message '401': description: API key missing, invalid, revoked or expired. content: application/json: schema: type: object properties: message: type: string required: - message '429': description: Rate limit reached. Retry after a short pause. content: application/json: schema: type: object properties: message: type: string required: - message '502': description: The AI agent service is temporarily unavailable. Retry shortly. content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] post: summary: Create deprecated: false description: >- Creates an AI agent with no flow. Next, save a flow with **Update Flow** and publish it with **Publish**. A new agent does not answer any channel by itself. A workflow rule in the dashboard (*Automation → Workflows*, action **Assign AI Agent**) decides which conversations it handles. tags: - AI Agent parameters: [] requestBody: content: application/json: schema: type: object properties: name: type: string description: 1-200 characters. inactivityTimeout: type: integer minimum: 1 maximum: 604800 default: 180 description: >- Seconds of customer silence before the conversation session expires. Default 180. required: - name examples: - name: Sales Assistant inactivityTimeout: 180 required: true responses: '201': description: '' content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. data: type: object properties: id: type: string description: AI agent ID. Use it in every `/ai-agents/{id}` path. name: type: string inactivityTimeout: type: integer description: >- Seconds of customer silence before the conversation session expires and the next message starts fresh. hasDraft: type: boolean description: True once a draft flow has been saved. hasLive: type: boolean description: >- True once a flow has been published. Only live agents answer customers. required: - id - name - inactivityTimeout - hasDraft - hasLive required: - requestId - data '400': description: >- Invalid body or parameters, e.g. an empty name, an unknown node type or a malformed ID. content: application/json: schema: type: object properties: message: type: string required: - message '401': description: API key missing, invalid, revoked or expired. content: application/json: schema: type: object properties: message: type: string required: - message '429': description: Rate limit reached. Retry after a short pause. content: application/json: schema: type: object properties: message: type: string required: - message '502': description: The AI agent service is temporarily unavailable. Retry shortly. content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] /api/v1/ai-agents/{id}: get: summary: Detail deprecated: false description: >- Returns an AI agent with a summary of its draft and live flows. Use **Get Flow** for the flow content. tags: - AI Agent parameters: - name: id in: path description: AI agent ID. required: true example: 6ad97ee52845b4f2c8daca55 schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. data: type: object properties: id: type: string description: AI agent ID. Use it in every `/ai-agents/{id}` path. name: type: string inactivityTimeout: type: integer description: >- Seconds of customer silence before the conversation session expires and the next message starts fresh. hasDraft: type: boolean description: True once a draft flow has been saved. hasLive: type: boolean description: >- True once a flow has been published. Only live agents answer customers. draft: type: - object - 'null' properties: id: type: string description: Draft flow ID. model: type: string savedAt: type: - string - 'null' description: When the draft was last saved (ISO 8601). description: The working copy. Null until a flow is saved. live: type: - object - 'null' properties: id: type: string description: Live flow version ID. version: type: string description: Label given when it was published. model: type: string publishedAt: type: - string - 'null' description: ISO 8601. description: >- The published version customers talk to. Null until the first publish. required: - id - name - inactivityTimeout - hasDraft - hasLive required: - requestId - data '400': description: >- Invalid body or parameters, e.g. an empty name, an unknown node type or a malformed ID. content: application/json: schema: type: object properties: message: type: string required: - message '401': description: API key missing, invalid, revoked or expired. content: application/json: schema: type: object properties: message: type: string required: - message '404': description: No AI agent with this ID in your workspace. content: application/json: schema: type: object properties: message: type: string required: - message '429': description: Rate limit reached. Retry after a short pause. content: application/json: schema: type: object properties: message: type: string required: - message '502': description: The AI agent service is temporarily unavailable. Retry shortly. content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] patch: summary: Update deprecated: false description: >- Renames an AI agent or changes its session timeout. **Send only the fields you want to change**; anything you leave out stays as it is. To change the flow, use **Update Flow**. tags: - AI Agent parameters: - name: id in: path description: AI agent ID. required: true example: 6ad97ee52845b4f2c8daca55 schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string description: 1-200 characters. inactivityTimeout: type: integer minimum: 1 maximum: 604800 examples: - name: Sales Assistant v2 required: true responses: '200': description: '' content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. data: type: object properties: id: type: string description: AI agent ID. Use it in every `/ai-agents/{id}` path. name: type: string inactivityTimeout: type: integer description: >- Seconds of customer silence before the conversation session expires and the next message starts fresh. hasDraft: type: boolean description: True once a draft flow has been saved. hasLive: type: boolean description: >- True once a flow has been published. Only live agents answer customers. required: - id - name - inactivityTimeout - hasDraft - hasLive required: - requestId - data '400': description: >- Invalid body or parameters, e.g. an empty name, an unknown node type or a malformed ID. content: application/json: schema: type: object properties: message: type: string required: - message '401': description: API key missing, invalid, revoked or expired. content: application/json: schema: type: object properties: message: type: string required: - message '404': description: No AI agent with this ID in your workspace. content: application/json: schema: type: object properties: message: type: string required: - message '429': description: Rate limit reached. Retry after a short pause. content: application/json: schema: type: object properties: message: type: string required: - message '502': description: The AI agent service is temporarily unavailable. Retry shortly. content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] delete: summary: Delete deprecated: false description: >- Permanently deletes an AI agent and cannot be undone. Refused with `409` while a workflow rule still assigns conversations to the agent, or while it is still handling open conversations. Remove it from those workflows, or wait for the conversations to close, and try again. tags: - AI Agent parameters: - name: id in: path description: AI agent ID. required: true example: 6ad97ee52845b4f2c8daca55 schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. message: type: string required: - requestId - message '400': description: >- Invalid body or parameters, e.g. an empty name, an unknown node type or a malformed ID. content: application/json: schema: type: object properties: message: type: string required: - message '401': description: API key missing, invalid, revoked or expired. content: application/json: schema: type: object properties: message: type: string required: - message '404': description: No AI agent with this ID in your workspace. content: application/json: schema: type: object properties: message: type: string required: - message '409': description: >- The agent is used by a workflow rule (the message names it) or still has open conversations. content: application/json: schema: type: object properties: message: type: string required: - message '429': description: Rate limit reached. Retry after a short pause. content: application/json: schema: type: object properties: message: type: string required: - message '502': description: The AI agent service is temporarily unavailable. Retry shortly. content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] /api/v1/ai-agents/{id}/flow: get: summary: Get Flow deprecated: false description: >- Returns the agent's draft (default) or live flow. The response is shaped so you can edit it and send it back to **Update Flow**: keep the node `id`s and send `toolIds`. `tools` and `providerTools` are for reading only. tags: - AI Agent parameters: - name: id in: path description: AI agent ID. required: true example: 6ad97ee52845b4f2c8daca55 schema: type: string - name: version in: query description: '`draft` (default) or `live`.' required: false example: draft schema: type: string enum: - draft - live default: draft responses: '200': description: '' content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. data: type: object properties: id: type: string description: Flow version ID. status: type: string enum: - draft - live version: type: string description: '`draft`, or the label given at publish.' model: type: string savedAt: type: - string - 'null' description: ISO 8601. nodes: type: array items: type: object properties: id: type: string description: >- Your own unique ID, e.g. `agent-main`. Keep it stable across saves: settings added in the dashboard are kept per node ID. type: type: string enum: - startingPoint - agentNode - conditionNode - humanAgentNode - knowledgeBaseNode - endingPoint - waitNode - replyCheckerNode description: >- `startingPoint` entry (exactly one per flow) · `agentNode` the AI that replies, `instruction` is its prompt · `conditionNode` a decision, `instruction` is the condition in plain language · `humanAgentNode` hands the chat to human agents (may only follow a `conditionNode`) · `knowledgeBaseNode` answers from `knowledgeSourceIds`. `endingPoint`, `waitNode` and `replyCheckerNode` are best configured in the dashboard builder. label: type: string description: Name shown in the dashboard builder. position: type: - object - 'null' properties: x: type: number 'y': type: number instruction: type: string description: >- Plain text, newlines allowed. Prompt for `agentNode`, condition for `conditionNode`, handoff note for `humanAgentNode`. Use `[contact name]` for the customer's name. toolIds: type: array items: type: string description: >- IDs of tools already set up in this workspace (copy them from an existing flow). Unknown IDs are rejected with `422`. tools: type: array items: type: object properties: id: type: string name: type: - string - 'null' description: type: - string - 'null' description: >- Names of the attached tools, read only. Send `toolIds` when saving. providerTools: type: array items: type: object properties: id: type: - string - 'null' name: type: - string - 'null' description: >- Integration tools, read only. Attached in the dashboard and kept when you save, as long as the node `id` and `type` are unchanged. knowledgeSourceIds: type: array items: type: string description: >- Knowledge base source IDs already set up in this workspace. vectorStoreIds: type: array items: type: string description: >- OpenAI vector store IDs (`vs_...`) attached in this workspace. correction: type: boolean description: Apply saved corrections. correctionGroupIds: type: array items: type: string description: Limit corrections to these groups. Empty = all. waitSeconds: type: - integer - 'null' required: - id - type - label - instruction - toolIds - tools - providerTools - knowledgeSourceIds - vectorStoreIds - correction - correctionGroupIds edges: type: array items: type: object properties: id: type: string description: Unique edge ID. source: type: string description: Node ID the edge leaves. target: type: string description: Node ID the edge enters. sourceHandle: type: - string - 'null' description: >- Reply-checker branch: `replied` or `timeout`. Otherwise omit. targetHandle: type: - string - 'null' required: - id - source - target required: - id - status - version - model - nodes - edges required: - requestId - data '400': description: >- Invalid body or parameters, e.g. an empty name, an unknown node type or a malformed ID. content: application/json: schema: type: object properties: message: type: string required: - message '401': description: API key missing, invalid, revoked or expired. content: application/json: schema: type: object properties: message: type: string required: - message '404': description: >- Unknown agent, or the agent has no flow of that version yet (no draft saved / never published). content: application/json: schema: type: object properties: message: type: string required: - message '429': description: Rate limit reached. Retry after a short pause. content: application/json: schema: type: object properties: message: type: string required: - message '502': description: The AI agent service is temporarily unavailable. Retry shortly. content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] put: summary: Update Flow deprecated: false description: >- **Replaces** the agent's whole draft flow. Customers are not affected until you **Publish**. Because this is a full replace, send every node and edge. To change one prompt, **Get Flow** first, edit it, and send everything back. Builder-only settings (integration tools, layout) are kept for nodes whose `id` and `type` are unchanged. Takes about 4 seconds. **Flow rules.** Exactly one `startingPoint`, and it must connect to another node. Node and edge IDs must be unique, and every edge must point at existing nodes. Also follow the builder's wiring rules, which the API does not check: a `humanAgentNode` may only be reached from a `conditionNode`; a `conditionNode` has exactly one outgoing edge and never leads to another `conditionNode`; an `agentNode` never connects directly to a `knowledgeBaseNode`. Typical shape: `startingPoint → agentNode → conditionNode → humanAgentNode`. tags: - AI Agent parameters: - name: id in: path description: AI agent ID. required: true example: 6ad97ee52845b4f2c8daca55 schema: type: string requestBody: content: application/json: schema: type: object properties: model: type: string description: >- A `slug` from **AI Agent → List Models** that is not `legacy`. Anything else is `422`. nodes: type: array items: type: object properties: id: type: string description: >- Your own unique ID, e.g. `agent-main`. Keep it stable across saves: settings added in the dashboard are kept per node ID. type: type: string enum: - startingPoint - agentNode - conditionNode - humanAgentNode - knowledgeBaseNode - endingPoint - waitNode - replyCheckerNode description: >- `startingPoint` entry (exactly one per flow) · `agentNode` the AI that replies, `instruction` is its prompt · `conditionNode` a decision, `instruction` is the condition in plain language · `humanAgentNode` hands the chat to human agents (may only follow a `conditionNode`) · `knowledgeBaseNode` answers from `knowledgeSourceIds`. `endingPoint`, `waitNode` and `replyCheckerNode` are best configured in the dashboard builder. label: type: string description: Name shown in the dashboard builder. position: type: object properties: x: type: number 'y': type: number required: - x - 'y' description: >- Canvas position. Optional; nodes are laid out left to right when omitted. instruction: type: string description: >- Plain text, newlines allowed. Prompt for `agentNode`, condition for `conditionNode`, handoff note for `humanAgentNode`. Use `[contact name]` for the customer's name. toolIds: type: array items: type: string description: >- IDs of tools already set up in this workspace (copy them from an existing flow). Unknown IDs are rejected with `422`. knowledgeSourceIds: type: array items: type: string description: >- Knowledge base source IDs already set up in this workspace. vectorStoreIds: type: array items: type: string description: >- OpenAI vector store IDs (`vs_...`) attached in this workspace. correction: type: boolean description: Apply saved corrections. correctionGroupIds: type: array items: type: string description: Limit corrections to these groups. Empty = all. waitSeconds: type: integer description: '`waitNode` only: how long to wait.' required: - id - type - label description: Every node of the flow (up to 200). edges: type: array items: type: object properties: id: type: string description: Unique edge ID. source: type: string description: Node ID the edge leaves. target: type: string description: Node ID the edge enters. sourceHandle: type: - string - 'null' description: >- Reply-checker branch: `replied` or `timeout`. Otherwise omit. targetHandle: type: - string - 'null' required: - id - source - target description: Every edge of the flow (up to 500). required: - model - nodes - edges examples: - model: gpt-6-luna nodes: - id: start type: startingPoint label: Start position: x: 0 'y': 0 - id: agent-main type: agentNode label: Sales Assistant position: x: 320 'y': 0 instruction: >- You are the sales assistant for Example Co. Reply in the customer's language. Greet [contact name] and ask how you can help. Opening hours: Mon-Fri 9:00-18:00. - id: cond-human type: conditionNode label: Needs a human position: x: 640 'y': 0 instruction: >- The customer asks to talk to a person, wants to place an order, or complains. Otherwise, no. - id: human type: humanAgentNode label: Sales team position: x: 960 'y': 0 instruction: Tell the customer a sales specialist will join shortly. edges: - id: e1 source: start target: agent-main - id: e2 source: agent-main target: cond-human - id: e3 source: cond-human target: human required: true responses: '200': description: The saved draft flow. content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. data: type: object properties: id: type: string description: Flow version ID. status: type: string enum: - draft - live version: type: string description: '`draft`, or the label given at publish.' model: type: string savedAt: type: - string - 'null' description: ISO 8601. nodes: type: array items: type: object properties: id: type: string description: >- Your own unique ID, e.g. `agent-main`. Keep it stable across saves: settings added in the dashboard are kept per node ID. type: type: string enum: - startingPoint - agentNode - conditionNode - humanAgentNode - knowledgeBaseNode - endingPoint - waitNode - replyCheckerNode description: >- `startingPoint` entry (exactly one per flow) · `agentNode` the AI that replies, `instruction` is its prompt · `conditionNode` a decision, `instruction` is the condition in plain language · `humanAgentNode` hands the chat to human agents (may only follow a `conditionNode`) · `knowledgeBaseNode` answers from `knowledgeSourceIds`. `endingPoint`, `waitNode` and `replyCheckerNode` are best configured in the dashboard builder. label: type: string description: Name shown in the dashboard builder. position: type: - object - 'null' properties: x: type: number 'y': type: number instruction: type: string description: >- Plain text, newlines allowed. Prompt for `agentNode`, condition for `conditionNode`, handoff note for `humanAgentNode`. Use `[contact name]` for the customer's name. toolIds: type: array items: type: string description: >- IDs of tools already set up in this workspace (copy them from an existing flow). Unknown IDs are rejected with `422`. tools: type: array items: type: object properties: id: type: string name: type: - string - 'null' description: type: - string - 'null' description: >- Names of the attached tools, read only. Send `toolIds` when saving. providerTools: type: array items: type: object properties: id: type: - string - 'null' name: type: - string - 'null' description: >- Integration tools, read only. Attached in the dashboard and kept when you save, as long as the node `id` and `type` are unchanged. knowledgeSourceIds: type: array items: type: string description: >- Knowledge base source IDs already set up in this workspace. vectorStoreIds: type: array items: type: string description: >- OpenAI vector store IDs (`vs_...`) attached in this workspace. correction: type: boolean description: Apply saved corrections. correctionGroupIds: type: array items: type: string description: Limit corrections to these groups. Empty = all. waitSeconds: type: - integer - 'null' required: - id - type - label - instruction - toolIds - tools - providerTools - knowledgeSourceIds - vectorStoreIds - correction - correctionGroupIds edges: type: array items: type: object properties: id: type: string description: Unique edge ID. source: type: string description: Node ID the edge leaves. target: type: string description: Node ID the edge enters. sourceHandle: type: - string - 'null' description: >- Reply-checker branch: `replied` or `timeout`. Otherwise omit. targetHandle: type: - string - 'null' required: - id - source - target required: - id - status - version - model - nodes - edges required: - requestId - data '400': description: >- Invalid body or parameters, e.g. an empty name, an unknown node type or a malformed ID. content: application/json: schema: type: object properties: message: type: string required: - message '401': description: API key missing, invalid, revoked or expired. content: application/json: schema: type: object properties: message: type: string required: - message '404': description: No AI agent with this ID in your workspace. content: application/json: schema: type: object properties: message: type: string required: - message '422': description: >- Flow rejected: `problems` lists graph errors, `supportedModels` is returned for an unknown or legacy model, and `toolIds` lists tools that are not in your workspace. content: application/json: schema: type: object properties: message: type: string required: - message '429': description: Rate limit reached. Retry after a short pause. content: application/json: schema: type: object properties: message: type: string required: - message '502': description: The AI agent service is temporarily unavailable. Retry shortly. content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] /api/v1/ai-agents/{id}/flow/versions: get: summary: List Versions deprecated: false description: >- Lists every published version of the agent's flow. `isLive` marks the one customers currently get. tags: - AI Agent parameters: - name: id in: path description: AI agent ID. required: true example: 6ad97ee52845b4f2c8daca55 schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. data: type: array items: type: object properties: id: type: string version: type: string model: type: string publishedAt: type: - string - 'null' description: ISO 8601. isLive: type: boolean required: - id - version - model - isLive required: - requestId - data '400': description: >- Invalid body or parameters, e.g. an empty name, an unknown node type or a malformed ID. content: application/json: schema: type: object properties: message: type: string required: - message '401': description: API key missing, invalid, revoked or expired. content: application/json: schema: type: object properties: message: type: string required: - message '404': description: No AI agent with this ID in your workspace. content: application/json: schema: type: object properties: message: type: string required: - message '429': description: Rate limit reached. Retry after a short pause. content: application/json: schema: type: object properties: message: type: string required: - message '502': description: The AI agent service is temporarily unavailable. Retry shortly. content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] /api/v1/ai-agents/{id}/publish: post: summary: Publish deprecated: false description: >- Publishes the current draft as a new live version. **This affects real customers**: new conversations get the new version right away, while conversations already in progress keep their version until they have been inactive for `inactivityTimeout` seconds. Every publish is kept in **List Versions**. Takes about 4 seconds. tags: - AI Agent parameters: - name: id in: path description: AI agent ID. required: true example: 6ad97ee52845b4f2c8daca55 schema: type: string requestBody: content: application/json: schema: type: object properties: version: type: string description: >- Label for this version, 1-100 characters, e.g. `v3 - pricing FAQ`. required: - version examples: - version: v1 required: true responses: '200': description: The agent, with `live` now pointing at the new version. content: application/json: schema: type: object properties: requestId: type: string description: >- Unique ID for this request. Quote it when reporting a problem. data: type: object properties: id: type: string description: AI agent ID. Use it in every `/ai-agents/{id}` path. name: type: string inactivityTimeout: type: integer description: >- Seconds of customer silence before the conversation session expires and the next message starts fresh. hasDraft: type: boolean description: True once a draft flow has been saved. hasLive: type: boolean description: >- True once a flow has been published. Only live agents answer customers. draft: type: - object - 'null' properties: id: type: string description: Draft flow ID. model: type: string savedAt: type: - string - 'null' description: When the draft was last saved (ISO 8601). description: The working copy. Null until a flow is saved. live: type: - object - 'null' properties: id: type: string description: Live flow version ID. version: type: string description: Label given when it was published. model: type: string publishedAt: type: - string - 'null' description: ISO 8601. description: >- The published version customers talk to. Null until the first publish. required: - id - name - inactivityTimeout - hasDraft - hasLive required: - requestId - data '400': description: >- Invalid body or parameters, e.g. an empty name, an unknown node type or a malformed ID. content: application/json: schema: type: object properties: message: type: string required: - message '401': description: API key missing, invalid, revoked or expired. content: application/json: schema: type: object properties: message: type: string required: - message '404': description: No AI agent with this ID in your workspace. content: application/json: schema: type: object properties: message: type: string required: - message '409': description: The agent has no draft flow. Save one with **Update Flow** first. content: application/json: schema: type: object properties: message: type: string required: - message '422': description: The draft flow is invalid; `problems` lists why. content: application/json: schema: type: object properties: message: type: string required: - message '429': description: Rate limit reached. Retry after a short pause. content: application/json: schema: type: object properties: message: type: string required: - message '502': description: The AI agent service is temporarily unavailable. Retry shortly. content: application/json: schema: type: object properties: message: type: string required: - message security: - apiToken: [] webhooks: {} components: schemas: RequestId: type: string format: uuid description: Unique ID for this request, useful when contacting support. IdentityVerificationStatus: type: object required: - requestId - secretConfigured - enforceIdentityVerification - requireIdentityToken properties: requestId: $ref: '#/components/schemas/RequestId' secretConfigured: type: boolean description: Whether an identity secret exists for this channel. enforceIdentityVerification: type: boolean description: When `true`, unverified identities are treated as anonymous guests. requireIdentityToken: type: boolean description: >- When `true`, only expiring `userToken`s are accepted, and the legacy `userHash` is refused. IdentityVerificationUpdate: type: object description: Send at least one field. minProperties: 1 additionalProperties: false properties: enforce: type: boolean description: Require every logged-in user to be verified. requireToken: type: boolean description: Accept only expiring `userToken`s, and refuse the legacy `userHash`. IdentityVerificationSettings: type: object required: - requestId - enforceIdentityVerification - requireIdentityToken properties: requestId: $ref: '#/components/schemas/RequestId' enforceIdentityVerification: type: boolean requireIdentityToken: type: boolean IdentitySecret: type: object required: - requestId - secret properties: requestId: $ref: '#/components/schemas/RequestId' secret: type: string pattern: ^[0-9a-f]{64}$ description: 64 hex characters. Shown only once. Keep it on your server. UserTokenClaims: type: object title: userToken (JWT claims) description: > **Not an API response.** This describes the token **your server** creates and passes to the widget as `authUser.userToken`, or to the hosted chat page as `?userToken=`. Sign it as a JWT with algorithm **HS256**, using the channel secret. Only HS256 is accepted. Create a fresh token each time the chat opens. required: - sub - exp properties: sub: type: string description: > Your user's unique, stable ID. It must never change for that user. To identify users by email, set `sub` to the email and also include `email`. examples: - cust_9931 exp: type: integer format: int64 description: > Expiry time in unix seconds. Recommended: 10 minutes from now. Tokens valid for more than 24 hours are rejected. Up to 60 seconds of clock difference is tolerated. examples: - 1790661969 iat: type: integer format: int64 description: Issue time in unix seconds. Recommended. examples: - 1790661369 nbf: type: integer format: int64 description: Optional "not before" time in unix seconds. name: type: string description: >- Display name shown to agents. It's signed, so visitors can't change it. examples: - Jane Doe email: type: string format: email description: Email shown to agents. Signed. phone: type: string description: Phone number shown to agents. Signed. examples: - '+95912345678' Error: type: object required: - message - statusCode properties: message: type: string error: type: string statusCode: type: integer CxLogTranscriptResponse: type: object required: - requestId - data properties: requestId: type: string format: uuid data: $ref: '#/components/schemas/CxLogTranscript' CxLogTranscript: type: object required: - cxLogId - caseId - roomId - channel - transcript properties: cxLogId: type: string format: uuid caseId: type: integer format: int64 roomId: type: string format: uuid description: The chat room the case belongs to. channel: type: - string - 'null' examples: - line transcript: type: string description: Newline-separated transcript lines, oldest first. ValidationError: type: object required: - message - statusCode properties: message: type: array items: type: string error: type: string statusCode: type: integer responses: '400': description: '' content: application/json: schema: type: object properties: message: type: array items: type: string error: type: string statusCode: type: integer required: - message - error - statusCode examples: Bad request 400: summary: Bad request 400 value: message: - contactId should not be empty - contactId must be a string error: Bad Request statusCode: 400 BadRequest: description: Invalid request, e.g. `channelId` is not a UUID. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Success: summary: Success value: statusCode: 400 message: Validation failed (uuid is expected) error: Bad Request Unauthorized: description: The API token is missing, invalid, expired or revoked. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Success: summary: Success value: statusCode: 401 message: Invalid API token error: Unauthorized ChannelNotFound: description: No web chat channel with this ID exists in your account. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Success: summary: Success value: statusCode: 404 message: Webchat channel not found error: Not Found TooManyRequests: description: Rate limit exceeded (10 requests per second). content: application/json: schema: $ref: '#/components/schemas/Error' examples: Success: summary: Success value: statusCode: 429 message: 'ThrottlerException: Too Many Requests' BadGateway: description: The chat service couldn't be reached. Retry shortly. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Success: summary: Success value: statusCode: 502 message: Failed to reach webchat service error: Bad Gateway securitySchemes: apiToken: type: http scheme: bearer description: Your klink.cloud API token, e.g. `kpt_…`. bearerAuth: type: http scheme: bearer description: Public API token. bearer: type: http scheme: bearer parameters: ChannelId: name: channelId in: path required: true description: >- Your web chat channel ID. It's the same value you pass to the widget as `scId`. schema: type: string format: uuid example: dd66629b-6488-4a5f-b060-48315518ebe0 servers: - url: https://apigw.klinkcx.com description: KC Public API (Prod) security: - apiToken: []