# Support # Conversations ## List conversations `client.support.conversations.list(ConversationListParamsparams?, RequestOptionsoptions?): CursorPage` **get** `/v2/conversations` Returns a list of conversations in your organization using cursor-based pagination. ### Query Parameters - `limit` - Number of conversations to return (1-100, default 10) - `cursor` - Cursor from previous response for pagination - `tagIds` - Optional tag filter as a comma-separated list of tag IDs. Matches conversations that contain all of the provided tags. ### Response Format Returns a list object with: - `object` - Always "list" - `data` - Array of conversation objects - `nextCursor` - Cursor for the next page, or null if no more results ### Conversation Object Each conversation includes: - `id` - Unique conversation identifier (short ID) - `title` - Conversation title - `state` - Current state ("open", "closed", or "snoozed") - `priority` - Whether the conversation is marked as priority - `adminAssigneeId` - ID of assigned admin (if any) - `teamAssigneeId` - ID of assigned team (if any) - `tags` - Current tags applied anywhere in the conversation - `participants` - Array of participants - `source` - Information about the first message - `createdAt` - Creation timestamp - `updatedAt` - Last update timestamp ### Example ```json { "object": "list", "data": [ { "object": "conversation", "id": "12345", "title": "Question about pricing", "state": "open", "priority": false, "adminAssigneeId": null, "participants": [ { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" } ], ... } ], "nextCursor": "eyJpZCI6IjEyMzQ1In0=" } ``` ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Parameters - `params: ConversationListParams` - `cursor?: string` Query param: An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page of results. - `limit?: number` Query param: A limit on the number of objects to be returned, between 1 and 100. - `tagIds?: string | Array` Query param: Filter conversations by one or more tag IDs using a comma-separated list. Conversations must contain all provided tags. - `string` - `Array` - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` Header param: API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `Conversation` - `id: string` Unique conversation identifier - `adminAssigneeId: string | null` ID of the assigned admin - `botConversationStateLastUpdatedAt: string | null` ISO timestamp when bot state last changed - `brandId: string | null` ID of the brand associated with this conversation - `createdAt: string` ISO timestamp when conversation was created - `hasAdminOverriddenLanguage: boolean` Whether an admin has manually overridden the language for this conversation. When true, automatic language detection is disabled. - `isBlocked: boolean` Whether the user is blocked - `lastActivityAt: string | null` ISO timestamp of last activity - `object: "conversation"` Object type identifier - `"conversation"` - `participants: Array` Participants in this conversation - `id: string` Participant ID - `type: "customer" | "lead" | "admin" | 3 more` Type of participant - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `priority: boolean` Whether this conversation is marked as priority - `prioritySetAt: string | null` ISO timestamp when priority was set - `snoozedUntil: string | null` ISO timestamp until which conversation is snoozed - `state: "open" | "closed" | "snoozed"` Current state of the conversation - `"open"` - `"closed"` - `"snoozed"` - `tags: Array` Current tags applied anywhere in this conversation - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `teamAssigneeId: string | null` ID of the assigned team - `updatedAt: string` ISO timestamp when conversation was last updated - `userPreferredLanguage: string` User's preferred language - `waitingSince: string | null` ISO timestamp when conversation started waiting - `awaitingCustomerReply?: boolean` Whether we are awaiting a customer reply - `botConversationState?: "active" | "handed_off_to_human" | "resolved"` State of AI agent handling for this conversation - `"active"` - `"handed_off_to_human"` - `"resolved"` - `conversationParts?: Array` Array of conversation parts (messages). Only included when fetching a single conversation by ID. - `UserMessage` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `id: string | null` Author ID - `type: "customer" | "lead" | "admin" | 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email?: string` Author email address - `name?: string` Author display name - `profilePicture?: string | null` Author profile picture URL - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `AdminMessage` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string | null` Note body content as HTML with signed image URLs - `bodyMarkdown: string | null` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMessage` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string | null` Email body content as HTML with signed image URLs - `bodyMarkdown: string | null` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMessage` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string | null` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `channel?: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOptions` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: Array` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResponse` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT request payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt?: string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt?: string` ISO timestamp after which late submission is no longer allowed - `ratedAgent?: CsatRatedAgent` - `type: "teammate" | "fibi" | "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id?: string` Identifier of the rated agent when applicable - `workflow?: CsatWorkflowLink` - `workflowActionId?: string` Workflow action ID associated with the CSAT request - `workflowId?: string` Workflow ID associated with the CSAT request - `workflowRunId?: string` Workflow run ID associated with the CSAT request - `workflowStepId?: string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT submission payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent?: CsatRatedAgent` - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the request was created - `workflow?: CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttributeCollectionPrompt` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: Form` Form configuration - `id: string` Form ID - `attributes: Array` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttributeCollectionComplete` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assignment` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId?: string | null` ID of the admin assigned to the conversation - `adminAssignerId?: string | null` ID of the admin who made the assignment - `teamAssigneeId?: string | null` ID of the team assigned to the conversation - `StatusChange` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" | "closed" | "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil?: string | null` ISO timestamp until conversation is snoozed (if snoozed) - `TagUpdate` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" | "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor?: ConversationTagMutationActor` Actor that applied the tag - `tagName?: string | null` Tag name at the time of the event or the best available current display name - `targetPartId?: string | null` Conversation part that the tag mutation targeted - `WorkflowWaitEvent` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: WorkflowWait` Workflow wait event payload for this thread event - `eventType: "started" | "finished" | "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType?: "admin" | "customer" | "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel?: string` Human-readable wait duration or preset label - `workflowId?: string` Workflow ID associated with the wait event - `workflowName?: string` Workflow display name at the time of the wait event - `PriorityChange` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `ParticipantAdded` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: Participant` The added participant - `id: string` Participant ID - `type: "customer" | "lead" | "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated - `csatDebug?: CsatDebug` Minimal CSAT diagnostics for the current effective request. - `requestId: string` Canonical CSAT request ID used for the latest debug snapshot - `status: "pending" | "rated" | "canceled" | "expired"` Lifecycle status of the request represented in the debug snapshot - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp when rating edits stop being accepted - `emailDelivery?: CsatEmailDelivery` - `status: "pending" | "sent" | "failed"` Email delivery status for the CSAT request when applicable - `"pending"` - `"sent"` - `"failed"` - `failedAt?: string` ISO timestamp when the CSAT email failed - `failureReason?: string` Operational failure reason for the CSAT email delivery - `messageId?: string` Email message ID associated with delivery - `sentAt?: string` ISO timestamp when the CSAT email was sent - `lateSubmitWindowEndsAt?: string` ISO timestamp when first-time submissions stop being accepted - `csatHistory?: Array` Historical CSAT requests for this conversation, ordered newest first. - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `isLatestEffective: boolean` Whether this row represents the currently effective CSAT request for the conversation - `lastUpdatedAt: string` ISO timestamp when the request last changed - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Lifecycle status for this historical CSAT request - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt?: string` ISO timestamp when the request was canceled - `changeLockWindowEndsAt?: string` ISO timestamp when edits to an existing rating stop being accepted - `emailDelivery?: CsatEmailDelivery` - `expiredAt?: string` ISO timestamp when the request expired - `lateSubmitWindowEndsAt?: string` ISO timestamp when first-time submissions stop being accepted - `ratedAgent?: CsatRatedAgent` - `ratedAt?: string` ISO timestamp when the request was rated - `remark?: string` Submitted remark when present - `score?: number` Submitted score when this request was rated - `workflow?: CsatWorkflowLink` - `csatSummary?: CsatSummary` Derived CSAT summary for this conversation when a rating request or rating exists. - `lastUpdatedAt: string` ISO timestamp when the summary last changed - `status: "pending" | "rated" | "canceled" | "expired"` Current summary status for CSAT on this conversation - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt?: string` ISO timestamp when the request was canceled - `channel?: "desktop" | "email"` Channel used for the latest CSAT request when known - `"desktop"` - `"email"` - `expiredAt?: string` ISO timestamp when the request expired - `ratedAgent?: CsatRatedAgent` - `ratedAt?: string` ISO timestamp when the customer submitted a rating - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the latest CSAT request was created - `requestId?: string` Canonical CSAT request ID - `requestSource?: "workflow"` Source of the latest CSAT request when known - `"workflow"` - `score?: number` CSAT score from 1 to 5 when rated - `workflow?: CsatWorkflowLink` - `disableCustomerReply?: boolean` Whether customer replies are disabled - `readReceipts?: Array` Read receipts indicating how far each participant has read in the conversation. Each receipt maps a user to their last-read conversation part. The tracked position reflects the system read state and may reference parts the user cannot directly view (e.g., a contact's read position may point to an internal admin note). Use these receipts to render read indicators and typing awareness, not to infer content access. - `id: string` The internal ID of the user - `lastReadPartId: string` The ID of the last conversation part this user has read. Note: This reflects the system-tracked read position and may reference a part the user cannot directly access (e.g., internal notes for contacts). The read state is advanced to the latest part in the conversation regardless of part visibility. - `userType: "admin" | "customer" | "lead"` Type of user who has read the conversation - `"admin"` - `"customer"` - `"lead"` - `source?: Source` - `bodyHtml: string` Body of the initial message as HTML with signed image URLs - `bodyMarkdown: string` Body of the initial message as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the conversation was initiated - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `author?: ConversationParticipant` - `id: string` Participant ID - `type: "customer" | "lead" | "admin" | 3 more` Type of participant - `deliveredAs?: "customer_initiated" | "admin_initiated"` How the conversation was initiated - `"customer_initiated"` - `"admin_initiated"` - `subject?: string` Subject line for email conversations - `url?: string` URL where the conversation was initiated - `title?: string` Conversation title ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const conversation of client.support.conversations.list()) { console.log(conversation.id); } ``` #### Response ```json { "data": [ { "id": "12345", "adminAssigneeId": "507f1f77bcf86cd799439011", "botConversationStateLastUpdatedAt": "2025-01-15T10:30:00.000Z", "brandId": "507f1f77bcf86cd799439011", "createdAt": "2025-01-15T10:30:00.000Z", "hasAdminOverriddenLanguage": false, "isBlocked": false, "lastActivityAt": "2025-01-15T12:30:00.000Z", "object": "conversation", "participants": [ { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" } ], "priority": false, "prioritySetAt": "2025-01-15T10:30:00.000Z", "snoozedUntil": "2025-01-16T09:00:00.000Z", "state": "open", "tags": [ { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } ], "teamAssigneeId": "507f1f77bcf86cd799439012", "updatedAt": "2025-01-15T12:30:00.000Z", "userPreferredLanguage": "en", "waitingSince": "2025-01-15T10:30:00.000Z", "awaitingCustomerReply": true, "botConversationState": "active", "conversationParts": [ { "id": "1", "bodyHtml": "

Hello, I have a question about your product.

", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ], "csatDebug": { "requestId": "csat_req_123", "status": "pending", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z" }, "csatHistory": [ { "channel": "desktop", "isLatestEffective": true, "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "status": "pending", "canceledAt": "2025-01-15T10:32:00.000Z", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "expiredAt": "2025-01-16T10:30:00.000Z", "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Thanks for the quick help.", "score": 4, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } } ], "csatSummary": { "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "status": "pending", "canceledAt": "2025-01-15T10:35:00.000Z", "channel": "desktop", "expiredAt": "2025-01-15T10:35:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Very helpful support.", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "score": 5, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } }, "disableCustomerReply": false, "readReceipts": [ { "id": "507f1f77bcf86cd799439011", "lastReadPartId": "8", "userType": "admin" } ], "source": { "bodyHtml": "

Hi, I have a question about your enterprise plan...

", "bodyMarkdown": "Hi, I have a question about your enterprise plan...", "channel": "desktop", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" }, "deliveredAs": "customer_initiated", "subject": "Question about pricing", "url": "https://example.com/pricing" }, "title": "Question about pricing" } ], "nextCursor": "eyJpZCI6IjEyMzQ1In0=", "object": "list" } ``` ## Create a conversation `client.support.conversations.create(ConversationCreateParamsparams, RequestOptionsoptions?): Conversation` **post** `/v2/conversations` Creates a new conversation. Supports both contact-initiated (customer/lead) and admin-initiated (outreach) conversations. ## Contact-Initiated Conversation For conversations started by a customer or lead: | Field | Type | Required | Description | | -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `from.type` | string | Yes | Must be "contact" | | `from.id` | string | Yes | The Featurebase contact ID (24-character ObjectId) | | `bodyMarkdown` | string | Yes | The initial message content in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. | | `channel` | string | No | The channel: "desktop" (default) or "email" | | `createdAt` | string | No | ISO timestamp for migrations | ### Example Contact-Initiated Request ```json { "from": { "type": "contact", "id": "676f0f6765bdaa7d7d760f88" }, "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop" } ``` ## Admin-Initiated Outreach For outreach conversations started by an admin: | Field | Type | Required | Description | | ---------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `from.type` | string | Yes | Must be "admin" | | `from.id` | string | Yes | The Featurebase admin ID (24-character ObjectId) | | `bodyMarkdown` | string | Yes | The initial message content in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. | | `channel` | string | No | The channel: "desktop" (default) or "email" | | `recipients` | object | Yes | Recipients for the outreach | | `recipients.to` | object | Yes | Primary recipients | | `recipients.to.emails` | string[] | No* | Email addresses | | `recipients.to.ids` | string[] | No* | Featurebase contact IDs | | `recipients.cc` | object | No | CC recipients (same structure as "to") | | `recipients.bcc` | object | No | BCC recipients (same structure as "to") | | `subject` | string | No** | Email subject line | | `createdAt` | string | No | ISO timestamp for migrations | \*At least one email or ID is required in `recipients.to` \**Required when channel is "email" ### Example Admin Outreach (In-App) ```json { "from": { "type": "admin", "id": "507f1f77bcf86cd799439011" }, "bodyMarkdown": "Hi! Just following up on your inquiry.", "channel": "desktop", "recipients": { "to": { "ids": ["676f0f6765bdaa7d7d760f88"] } } } ``` ### Example Admin Outreach (Email) ```json { "from": { "type": "admin", "id": "507f1f77bcf86cd799439011" }, "bodyMarkdown": "Hi! Just following up on your inquiry.", "channel": "email", "subject": "Following up on your inquiry", "recipients": { "to": { "emails": ["john@example.com"] }, "cc": { "emails": ["manager@example.com"] } } } ``` ### Response Returns the created conversation object with a **201 Created** status. ### Example Response ```json { "object": "conversation", "id": "12345", "state": "open", "priority": false, "adminAssigneeId": null, "participants": [ { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" } ], "source": { "channel": "desktop", "deliveredAs": "customer_initiated", "bodyHtml": "

Hello, I have a question about your product.

", "bodyMarkdown": "Hello, I have a question about your product.", "author": { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" } }, "createdAt": "2025-01-15T10:30:00.000Z", "updatedAt": "2025-01-15T10:30:00.000Z" } ``` ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Parameters - `params: ConversationCreateParams` - `bodyMarkdown: string` Body param: The content of the initial message in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. - `from: ContactFrom | AdminFrom` Body param: The author initiating the conversation. Use type "contact" for customer/lead or "admin" for outreach. - `ContactFrom` Conversation initiated by a contact - `id: string` The Featurebase contact ID - `type: "contact"` The type of author. Use "contact" for customer/lead initiated conversations. - `"contact"` - `AdminFrom` Conversation initiated by an admin (outreach) - `id: string` The Featurebase admin ID - `type: "admin"` The type of author. Use "admin" for admin initiated outreach conversations. - `"admin"` - `channel?: "desktop" | "email"` Body param: The channel for the conversation. Defaults to "desktop" (SDK/widget). - `"desktop"` - `"email"` - `createdAt?: string | null` Body param: The time the conversation was created as an ISO timestamp. If not provided, the current time will be used. This field is recommended for migrating past conversations from another source. - `recipients?: Recipients` Body param: Recipients for admin-initiated outreach. Required when from.type is "admin". Specify at least one recipient in the "to" field. - `to: EmailRecipients` Primary recipients (To field) - `emails?: Array` Array of email addresses - `ids?: Array` Array of Featurebase contact IDs - `bcc?: EmailRecipients` Primary recipients (To field) - `cc?: EmailRecipients` Primary recipients (To field) - `subject?: string` Body param: Subject line for the email. Required when channel is "email" and from.type is "admin". - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` Header param: API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `Conversation` - `id: string` Unique conversation identifier - `adminAssigneeId: string | null` ID of the assigned admin - `botConversationStateLastUpdatedAt: string | null` ISO timestamp when bot state last changed - `brandId: string | null` ID of the brand associated with this conversation - `createdAt: string` ISO timestamp when conversation was created - `hasAdminOverriddenLanguage: boolean` Whether an admin has manually overridden the language for this conversation. When true, automatic language detection is disabled. - `isBlocked: boolean` Whether the user is blocked - `lastActivityAt: string | null` ISO timestamp of last activity - `object: "conversation"` Object type identifier - `"conversation"` - `participants: Array` Participants in this conversation - `id: string` Participant ID - `type: "customer" | "lead" | "admin" | 3 more` Type of participant - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `priority: boolean` Whether this conversation is marked as priority - `prioritySetAt: string | null` ISO timestamp when priority was set - `snoozedUntil: string | null` ISO timestamp until which conversation is snoozed - `state: "open" | "closed" | "snoozed"` Current state of the conversation - `"open"` - `"closed"` - `"snoozed"` - `tags: Array` Current tags applied anywhere in this conversation - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `teamAssigneeId: string | null` ID of the assigned team - `updatedAt: string` ISO timestamp when conversation was last updated - `userPreferredLanguage: string` User's preferred language - `waitingSince: string | null` ISO timestamp when conversation started waiting - `awaitingCustomerReply?: boolean` Whether we are awaiting a customer reply - `botConversationState?: "active" | "handed_off_to_human" | "resolved"` State of AI agent handling for this conversation - `"active"` - `"handed_off_to_human"` - `"resolved"` - `conversationParts?: Array` Array of conversation parts (messages). Only included when fetching a single conversation by ID. - `UserMessage` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `id: string | null` Author ID - `type: "customer" | "lead" | "admin" | 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email?: string` Author email address - `name?: string` Author display name - `profilePicture?: string | null` Author profile picture URL - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `AdminMessage` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string | null` Note body content as HTML with signed image URLs - `bodyMarkdown: string | null` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMessage` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string | null` Email body content as HTML with signed image URLs - `bodyMarkdown: string | null` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMessage` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string | null` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `channel?: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOptions` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: Array` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResponse` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT request payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt?: string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt?: string` ISO timestamp after which late submission is no longer allowed - `ratedAgent?: CsatRatedAgent` - `type: "teammate" | "fibi" | "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id?: string` Identifier of the rated agent when applicable - `workflow?: CsatWorkflowLink` - `workflowActionId?: string` Workflow action ID associated with the CSAT request - `workflowId?: string` Workflow ID associated with the CSAT request - `workflowRunId?: string` Workflow run ID associated with the CSAT request - `workflowStepId?: string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT submission payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent?: CsatRatedAgent` - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the request was created - `workflow?: CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttributeCollectionPrompt` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: Form` Form configuration - `id: string` Form ID - `attributes: Array` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttributeCollectionComplete` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assignment` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId?: string | null` ID of the admin assigned to the conversation - `adminAssignerId?: string | null` ID of the admin who made the assignment - `teamAssigneeId?: string | null` ID of the team assigned to the conversation - `StatusChange` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" | "closed" | "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil?: string | null` ISO timestamp until conversation is snoozed (if snoozed) - `TagUpdate` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" | "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor?: ConversationTagMutationActor` Actor that applied the tag - `tagName?: string | null` Tag name at the time of the event or the best available current display name - `targetPartId?: string | null` Conversation part that the tag mutation targeted - `WorkflowWaitEvent` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: WorkflowWait` Workflow wait event payload for this thread event - `eventType: "started" | "finished" | "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType?: "admin" | "customer" | "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel?: string` Human-readable wait duration or preset label - `workflowId?: string` Workflow ID associated with the wait event - `workflowName?: string` Workflow display name at the time of the wait event - `PriorityChange` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `ParticipantAdded` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: Participant` The added participant - `id: string` Participant ID - `type: "customer" | "lead" | "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated - `csatDebug?: CsatDebug` Minimal CSAT diagnostics for the current effective request. - `requestId: string` Canonical CSAT request ID used for the latest debug snapshot - `status: "pending" | "rated" | "canceled" | "expired"` Lifecycle status of the request represented in the debug snapshot - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp when rating edits stop being accepted - `emailDelivery?: CsatEmailDelivery` - `status: "pending" | "sent" | "failed"` Email delivery status for the CSAT request when applicable - `"pending"` - `"sent"` - `"failed"` - `failedAt?: string` ISO timestamp when the CSAT email failed - `failureReason?: string` Operational failure reason for the CSAT email delivery - `messageId?: string` Email message ID associated with delivery - `sentAt?: string` ISO timestamp when the CSAT email was sent - `lateSubmitWindowEndsAt?: string` ISO timestamp when first-time submissions stop being accepted - `csatHistory?: Array` Historical CSAT requests for this conversation, ordered newest first. - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `isLatestEffective: boolean` Whether this row represents the currently effective CSAT request for the conversation - `lastUpdatedAt: string` ISO timestamp when the request last changed - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Lifecycle status for this historical CSAT request - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt?: string` ISO timestamp when the request was canceled - `changeLockWindowEndsAt?: string` ISO timestamp when edits to an existing rating stop being accepted - `emailDelivery?: CsatEmailDelivery` - `expiredAt?: string` ISO timestamp when the request expired - `lateSubmitWindowEndsAt?: string` ISO timestamp when first-time submissions stop being accepted - `ratedAgent?: CsatRatedAgent` - `ratedAt?: string` ISO timestamp when the request was rated - `remark?: string` Submitted remark when present - `score?: number` Submitted score when this request was rated - `workflow?: CsatWorkflowLink` - `csatSummary?: CsatSummary` Derived CSAT summary for this conversation when a rating request or rating exists. - `lastUpdatedAt: string` ISO timestamp when the summary last changed - `status: "pending" | "rated" | "canceled" | "expired"` Current summary status for CSAT on this conversation - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt?: string` ISO timestamp when the request was canceled - `channel?: "desktop" | "email"` Channel used for the latest CSAT request when known - `"desktop"` - `"email"` - `expiredAt?: string` ISO timestamp when the request expired - `ratedAgent?: CsatRatedAgent` - `ratedAt?: string` ISO timestamp when the customer submitted a rating - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the latest CSAT request was created - `requestId?: string` Canonical CSAT request ID - `requestSource?: "workflow"` Source of the latest CSAT request when known - `"workflow"` - `score?: number` CSAT score from 1 to 5 when rated - `workflow?: CsatWorkflowLink` - `disableCustomerReply?: boolean` Whether customer replies are disabled - `readReceipts?: Array` Read receipts indicating how far each participant has read in the conversation. Each receipt maps a user to their last-read conversation part. The tracked position reflects the system read state and may reference parts the user cannot directly view (e.g., a contact's read position may point to an internal admin note). Use these receipts to render read indicators and typing awareness, not to infer content access. - `id: string` The internal ID of the user - `lastReadPartId: string` The ID of the last conversation part this user has read. Note: This reflects the system-tracked read position and may reference a part the user cannot directly access (e.g., internal notes for contacts). The read state is advanced to the latest part in the conversation regardless of part visibility. - `userType: "admin" | "customer" | "lead"` Type of user who has read the conversation - `"admin"` - `"customer"` - `"lead"` - `source?: Source` - `bodyHtml: string` Body of the initial message as HTML with signed image URLs - `bodyMarkdown: string` Body of the initial message as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the conversation was initiated - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `author?: ConversationParticipant` - `id: string` Participant ID - `type: "customer" | "lead" | "admin" | 3 more` Type of participant - `deliveredAs?: "customer_initiated" | "admin_initiated"` How the conversation was initiated - `"customer_initiated"` - `"admin_initiated"` - `subject?: string` Subject line for email conversations - `url?: string` URL where the conversation was initiated - `title?: string` Conversation title ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); const conversation = await client.support.conversations.create({ bodyMarkdown: 'Hello, I have a question about your product.\n\n![screenshot](https://example.com/image.png)', from: { id: '676f0f6765bdaa7d7d760f88', type: 'contact' }, }); console.log(conversation.id); ``` #### Response ```json { "id": "12345", "adminAssigneeId": "507f1f77bcf86cd799439011", "botConversationStateLastUpdatedAt": "2025-01-15T10:30:00.000Z", "brandId": "507f1f77bcf86cd799439011", "createdAt": "2025-01-15T10:30:00.000Z", "hasAdminOverriddenLanguage": false, "isBlocked": false, "lastActivityAt": "2025-01-15T12:30:00.000Z", "object": "conversation", "participants": [ { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" } ], "priority": false, "prioritySetAt": "2025-01-15T10:30:00.000Z", "snoozedUntil": "2025-01-16T09:00:00.000Z", "state": "open", "tags": [ { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } ], "teamAssigneeId": "507f1f77bcf86cd799439012", "updatedAt": "2025-01-15T12:30:00.000Z", "userPreferredLanguage": "en", "waitingSince": "2025-01-15T10:30:00.000Z", "awaitingCustomerReply": true, "botConversationState": "active", "conversationParts": [ { "id": "1", "bodyHtml": "

Hello, I have a question about your product.

", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ], "csatDebug": { "requestId": "csat_req_123", "status": "pending", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z" }, "csatHistory": [ { "channel": "desktop", "isLatestEffective": true, "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "status": "pending", "canceledAt": "2025-01-15T10:32:00.000Z", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "expiredAt": "2025-01-16T10:30:00.000Z", "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Thanks for the quick help.", "score": 4, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } } ], "csatSummary": { "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "status": "pending", "canceledAt": "2025-01-15T10:35:00.000Z", "channel": "desktop", "expiredAt": "2025-01-15T10:35:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Very helpful support.", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "score": 5, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } }, "disableCustomerReply": false, "readReceipts": [ { "id": "507f1f77bcf86cd799439011", "lastReadPartId": "8", "userType": "admin" } ], "source": { "bodyHtml": "

Hi, I have a question about your enterprise plan...

", "bodyMarkdown": "Hi, I have a question about your enterprise plan...", "channel": "desktop", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" }, "deliveredAs": "customer_initiated", "subject": "Question about pricing", "url": "https://example.com/pricing" }, "title": "Question about pricing" } ``` ## Get conversation by ID `client.support.conversations.retrieve(stringid, ConversationRetrieveParamsparams?, RequestOptionsoptions?): Conversation` **get** `/v2/conversations/{id}` Retrieves a single conversation by its ID, including conversation parts (messages). ### Path Parameters - `id` - The conversation ID (short ID) ### Hard Limit of 500 Parts The maximum number of conversation parts that can be returned via the API is **500**. If a conversation has more than 500 parts, only the **500 most recent** conversation parts will be returned. ### Response Format Returns a single conversation object with: - `object` - Always "conversation" - `id` - Unique conversation identifier (short ID) - `title` - Conversation title - `state` - Current state ("open", "closed", or "snoozed") - `priority` - Whether the conversation is marked as priority - `adminAssigneeId` - ID of assigned admin (if any) - `teamAssigneeId` - ID of assigned team (if any) - `participants` - Array of participants - `source` - Information about the first message - `conversationParts` - Array of conversation parts (messages, max 500) - `createdAt` - Creation timestamp - `updatedAt` - Last update timestamp ### Conversation Parts Each conversation part includes: - `object` - Always "conversation_part" - `id` - Unique part identifier - `partType` - Type of part (e.g., "user_msg", "admin_msg", "bot_msg") - `body` - Message body (HTML content) - `author` - Author information with name, email, and profile picture - `channel` - Channel through which the message was sent - `createdAt` - Creation timestamp - `updatedAt` - Last update timestamp ### Example ```json { "object": "conversation", "id": "12345", "title": "Question about pricing", "state": "open", "priority": false, "adminAssigneeId": "507f1f77bcf86cd799439011", "participants": [ { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" } ], "conversationParts": [ { "object": "conversation_part", "id": "1", "partType": "user_msg", "bodyHtml": "

Hello, I have a question about your pricing plans.

", "bodyMarkdown": "Hello, I have a question about your pricing plans.", "author": { "type": "customer", "id": "676f0f6765bdaa7d7d760f88", "name": "John Doe", "email": "john@example.com" }, "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "updatedAt": "2025-01-15T10:30:00.000Z" }, { "object": "conversation_part", "id": "2", "partType": "admin_msg", "bodyHtml": "

Hi John! I'd be happy to help you with pricing information.

", "bodyMarkdown": "Hi John! I'd be happy to help you with pricing information.", "author": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "Support Agent" }, "channel": "desktop", "createdAt": "2025-01-15T10:35:00.000Z", "updatedAt": "2025-01-15T10:35:00.000Z" } ], "createdAt": "2025-01-15T10:30:00.000Z", "updatedAt": "2025-01-15T10:35:00.000Z" } ``` ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Parameters - `id: string` Conversation ID (short ID) - `params: ConversationRetrieveParams` - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `Conversation` - `id: string` Unique conversation identifier - `adminAssigneeId: string | null` ID of the assigned admin - `botConversationStateLastUpdatedAt: string | null` ISO timestamp when bot state last changed - `brandId: string | null` ID of the brand associated with this conversation - `createdAt: string` ISO timestamp when conversation was created - `hasAdminOverriddenLanguage: boolean` Whether an admin has manually overridden the language for this conversation. When true, automatic language detection is disabled. - `isBlocked: boolean` Whether the user is blocked - `lastActivityAt: string | null` ISO timestamp of last activity - `object: "conversation"` Object type identifier - `"conversation"` - `participants: Array` Participants in this conversation - `id: string` Participant ID - `type: "customer" | "lead" | "admin" | 3 more` Type of participant - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `priority: boolean` Whether this conversation is marked as priority - `prioritySetAt: string | null` ISO timestamp when priority was set - `snoozedUntil: string | null` ISO timestamp until which conversation is snoozed - `state: "open" | "closed" | "snoozed"` Current state of the conversation - `"open"` - `"closed"` - `"snoozed"` - `tags: Array` Current tags applied anywhere in this conversation - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `teamAssigneeId: string | null` ID of the assigned team - `updatedAt: string` ISO timestamp when conversation was last updated - `userPreferredLanguage: string` User's preferred language - `waitingSince: string | null` ISO timestamp when conversation started waiting - `awaitingCustomerReply?: boolean` Whether we are awaiting a customer reply - `botConversationState?: "active" | "handed_off_to_human" | "resolved"` State of AI agent handling for this conversation - `"active"` - `"handed_off_to_human"` - `"resolved"` - `conversationParts?: Array` Array of conversation parts (messages). Only included when fetching a single conversation by ID. - `UserMessage` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `id: string | null` Author ID - `type: "customer" | "lead" | "admin" | 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email?: string` Author email address - `name?: string` Author display name - `profilePicture?: string | null` Author profile picture URL - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `AdminMessage` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string | null` Note body content as HTML with signed image URLs - `bodyMarkdown: string | null` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMessage` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string | null` Email body content as HTML with signed image URLs - `bodyMarkdown: string | null` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMessage` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string | null` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `channel?: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOptions` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: Array` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResponse` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT request payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt?: string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt?: string` ISO timestamp after which late submission is no longer allowed - `ratedAgent?: CsatRatedAgent` - `type: "teammate" | "fibi" | "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id?: string` Identifier of the rated agent when applicable - `workflow?: CsatWorkflowLink` - `workflowActionId?: string` Workflow action ID associated with the CSAT request - `workflowId?: string` Workflow ID associated with the CSAT request - `workflowRunId?: string` Workflow run ID associated with the CSAT request - `workflowStepId?: string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT submission payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent?: CsatRatedAgent` - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the request was created - `workflow?: CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttributeCollectionPrompt` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: Form` Form configuration - `id: string` Form ID - `attributes: Array` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttributeCollectionComplete` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assignment` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId?: string | null` ID of the admin assigned to the conversation - `adminAssignerId?: string | null` ID of the admin who made the assignment - `teamAssigneeId?: string | null` ID of the team assigned to the conversation - `StatusChange` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" | "closed" | "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil?: string | null` ISO timestamp until conversation is snoozed (if snoozed) - `TagUpdate` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" | "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor?: ConversationTagMutationActor` Actor that applied the tag - `tagName?: string | null` Tag name at the time of the event or the best available current display name - `targetPartId?: string | null` Conversation part that the tag mutation targeted - `WorkflowWaitEvent` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: WorkflowWait` Workflow wait event payload for this thread event - `eventType: "started" | "finished" | "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType?: "admin" | "customer" | "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel?: string` Human-readable wait duration or preset label - `workflowId?: string` Workflow ID associated with the wait event - `workflowName?: string` Workflow display name at the time of the wait event - `PriorityChange` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `ParticipantAdded` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: Participant` The added participant - `id: string` Participant ID - `type: "customer" | "lead" | "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated - `csatDebug?: CsatDebug` Minimal CSAT diagnostics for the current effective request. - `requestId: string` Canonical CSAT request ID used for the latest debug snapshot - `status: "pending" | "rated" | "canceled" | "expired"` Lifecycle status of the request represented in the debug snapshot - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp when rating edits stop being accepted - `emailDelivery?: CsatEmailDelivery` - `status: "pending" | "sent" | "failed"` Email delivery status for the CSAT request when applicable - `"pending"` - `"sent"` - `"failed"` - `failedAt?: string` ISO timestamp when the CSAT email failed - `failureReason?: string` Operational failure reason for the CSAT email delivery - `messageId?: string` Email message ID associated with delivery - `sentAt?: string` ISO timestamp when the CSAT email was sent - `lateSubmitWindowEndsAt?: string` ISO timestamp when first-time submissions stop being accepted - `csatHistory?: Array` Historical CSAT requests for this conversation, ordered newest first. - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `isLatestEffective: boolean` Whether this row represents the currently effective CSAT request for the conversation - `lastUpdatedAt: string` ISO timestamp when the request last changed - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Lifecycle status for this historical CSAT request - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt?: string` ISO timestamp when the request was canceled - `changeLockWindowEndsAt?: string` ISO timestamp when edits to an existing rating stop being accepted - `emailDelivery?: CsatEmailDelivery` - `expiredAt?: string` ISO timestamp when the request expired - `lateSubmitWindowEndsAt?: string` ISO timestamp when first-time submissions stop being accepted - `ratedAgent?: CsatRatedAgent` - `ratedAt?: string` ISO timestamp when the request was rated - `remark?: string` Submitted remark when present - `score?: number` Submitted score when this request was rated - `workflow?: CsatWorkflowLink` - `csatSummary?: CsatSummary` Derived CSAT summary for this conversation when a rating request or rating exists. - `lastUpdatedAt: string` ISO timestamp when the summary last changed - `status: "pending" | "rated" | "canceled" | "expired"` Current summary status for CSAT on this conversation - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt?: string` ISO timestamp when the request was canceled - `channel?: "desktop" | "email"` Channel used for the latest CSAT request when known - `"desktop"` - `"email"` - `expiredAt?: string` ISO timestamp when the request expired - `ratedAgent?: CsatRatedAgent` - `ratedAt?: string` ISO timestamp when the customer submitted a rating - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the latest CSAT request was created - `requestId?: string` Canonical CSAT request ID - `requestSource?: "workflow"` Source of the latest CSAT request when known - `"workflow"` - `score?: number` CSAT score from 1 to 5 when rated - `workflow?: CsatWorkflowLink` - `disableCustomerReply?: boolean` Whether customer replies are disabled - `readReceipts?: Array` Read receipts indicating how far each participant has read in the conversation. Each receipt maps a user to their last-read conversation part. The tracked position reflects the system read state and may reference parts the user cannot directly view (e.g., a contact's read position may point to an internal admin note). Use these receipts to render read indicators and typing awareness, not to infer content access. - `id: string` The internal ID of the user - `lastReadPartId: string` The ID of the last conversation part this user has read. Note: This reflects the system-tracked read position and may reference a part the user cannot directly access (e.g., internal notes for contacts). The read state is advanced to the latest part in the conversation regardless of part visibility. - `userType: "admin" | "customer" | "lead"` Type of user who has read the conversation - `"admin"` - `"customer"` - `"lead"` - `source?: Source` - `bodyHtml: string` Body of the initial message as HTML with signed image URLs - `bodyMarkdown: string` Body of the initial message as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the conversation was initiated - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `author?: ConversationParticipant` - `id: string` Participant ID - `type: "customer" | "lead" | "admin" | 3 more` Type of participant - `deliveredAs?: "customer_initiated" | "admin_initiated"` How the conversation was initiated - `"customer_initiated"` - `"admin_initiated"` - `subject?: string` Subject line for email conversations - `url?: string` URL where the conversation was initiated - `title?: string` Conversation title ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); const conversation = await client.support.conversations.retrieve('12345'); console.log(conversation.id); ``` #### Response ```json { "id": "12345", "adminAssigneeId": "507f1f77bcf86cd799439011", "botConversationStateLastUpdatedAt": "2025-01-15T10:30:00.000Z", "brandId": "507f1f77bcf86cd799439011", "createdAt": "2025-01-15T10:30:00.000Z", "hasAdminOverriddenLanguage": false, "isBlocked": false, "lastActivityAt": "2025-01-15T12:30:00.000Z", "object": "conversation", "participants": [ { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" } ], "priority": false, "prioritySetAt": "2025-01-15T10:30:00.000Z", "snoozedUntil": "2025-01-16T09:00:00.000Z", "state": "open", "tags": [ { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } ], "teamAssigneeId": "507f1f77bcf86cd799439012", "updatedAt": "2025-01-15T12:30:00.000Z", "userPreferredLanguage": "en", "waitingSince": "2025-01-15T10:30:00.000Z", "awaitingCustomerReply": true, "botConversationState": "active", "conversationParts": [ { "id": "1", "bodyHtml": "

Hello, I have a question about your product.

", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ], "csatDebug": { "requestId": "csat_req_123", "status": "pending", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z" }, "csatHistory": [ { "channel": "desktop", "isLatestEffective": true, "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "status": "pending", "canceledAt": "2025-01-15T10:32:00.000Z", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "expiredAt": "2025-01-16T10:30:00.000Z", "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Thanks for the quick help.", "score": 4, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } } ], "csatSummary": { "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "status": "pending", "canceledAt": "2025-01-15T10:35:00.000Z", "channel": "desktop", "expiredAt": "2025-01-15T10:35:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Very helpful support.", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "score": 5, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } }, "disableCustomerReply": false, "readReceipts": [ { "id": "507f1f77bcf86cd799439011", "lastReadPartId": "8", "userType": "admin" } ], "source": { "bodyHtml": "

Hi, I have a question about your enterprise plan...

", "bodyMarkdown": "Hi, I have a question about your enterprise plan...", "channel": "desktop", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" }, "deliveredAs": "customer_initiated", "subject": "Question about pricing", "url": "https://example.com/pricing" }, "title": "Question about pricing" } ``` ## Delete a conversation `client.support.conversations.delete(stringid, ConversationDeleteParamsparams?, RequestOptionsoptions?): ConversationDeleteResponse` **delete** `/v2/conversations/{id}` Permanently deletes a conversation by its short ID. ### Path Parameters - `id` - The conversation short ID (numeric) ### Response Returns a deletion confirmation object: ```json { "id": "12345", "object": "conversation", "deleted": true } ``` ### Caution This operation is **irreversible**. The conversation and all its messages will be permanently deleted. ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Parameters - `id: string` Conversation ID (short ID) - `params: ConversationDeleteParams` - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `ConversationDeleteResponse` - `id: string` Unique identifier of the deleted conversation - `deleted: true` Indicates the resource was deleted - `true` - `object: "conversation"` Object type identifier - `"conversation"` ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); const conversation = await client.support.conversations.delete('12345'); console.log(conversation.id); ``` #### Response ```json { "id": "12345", "deleted": true, "object": "conversation" } ``` ## Update a conversation `client.support.conversations.update(stringid, ConversationUpdateParamsparams, RequestOptionsoptions?): Conversation` **patch** `/v2/conversations/{id}` Updates a conversation's properties. Supports partial updates - only provided fields will be updated. ### Path Parameters - `id` - The conversation ID (short ID) ### Request Body All fields are optional. Only provided fields will be updated. | Field | Type | Description | | ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `actingAdminId` | string | Admin ID performing the action (for attribution). If not provided, uses bot service user. Must be a member of the organization. | | `state` | string | Conversation state: "open", "closed", or "snoozed" | | `snoozedUntil` | string | ISO datetime when to unsnooze (required when state is "snoozed") | | `adminAssigneeId` | string/null | Admin ID to assign, or null to unassign | | `teamAssigneeId` | string/null | Team ID to assign, or null to unassign | | `title` | string | Conversation title | | `customAttributes` | object | Custom attributes to set on the conversation | | `markAsRead` | object | Mark conversation as read for specific users | ### markAsRead Object | Field | Type | Description | | ------------- | -------- | -------------------------------------------------------------- | | `allAdmins` | boolean | If true, marks all admins with existing readReceipts as read | | `adminIds` | string[] | Array of specific admin IDs to mark as read | | `allContacts` | boolean | If true, marks all contacts with existing readReceipts as read | | `contactIds` | string[] | Array of specific contact IDs to mark as read | Note: Only users with existing read receipts will be updated. Use `allAdmins`/`allContacts` OR `adminIds`/`contactIds` - the "all" flags take precedence. ### Response Returns the updated conversation object. ### Example: Close a Conversation (with attribution) ```json { "actingAdminId": "507f1f77bcf86cd799439011", "state": "closed" } ``` ### Example: Close a Conversation (bot user) ```json { "state": "closed" } ``` ### Example: Snooze a Conversation ```json { "state": "snoozed", "snoozedUntil": "2025-01-20T10:00:00.000Z" } ``` ### Example: Assign to an Admin ```json { "adminAssigneeId": "507f1f77bcf86cd799439011" } ``` ### Example: Update Title and Custom Attributes ```json { "title": "Billing Issue - Priority", "customAttributes": { "priority_level": "high", "category": "billing" } } ``` ### Example: Mark as Read (All Admins) ```json { "markAsRead": { "allAdmins": true } } ``` ### Example: Mark as Read (All Contacts) ```json { "markAsRead": { "allContacts": true } } ``` ### Example: Mark as Read (Specific IDs) ```json { "markAsRead": { "adminIds": ["507f1f77bcf86cd799439011"], "contactIds": ["676f0f6765bdaa7d7d760f88"] } } ``` ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Parameters - `id: string` Conversation ID (short ID) - `params: ConversationUpdateParams` - `actingAdminId?: string` Body param: The admin ID performing this action. Changes will be attributed to this admin. If not provided, changes are attributed to the system bot user. The admin must be a member of the organization. - `adminAssigneeId?: string | null` Body param: The admin ID to assign the conversation to, or null to unassign. - `customAttributes?: Record` Body param: Custom attributes to set on the conversation. Uses the same validation as v1 API. - `markAsRead?: MarkAsRead` Body param: Mark the conversation as read for specific admins and/or contacts. - `adminIds?: Array` Array of admin IDs to mark as read. Only admins with existing readReceipts will be updated. - `allAdmins?: boolean | null` If true, marks all admins with existing readReceipts as read. - `allContacts?: boolean | null` If true, marks all contacts (customers and leads) with existing readReceipts as read. - `contactIds?: Array` Array of contact IDs to mark as read. Only contacts with existing readReceipts will be updated. - `snoozedUntil?: string | null` Body param: ISO datetime when the conversation should be unsnoozed. Required when state is "snoozed". Must be a future date. - `state?: "open" | "closed" | "snoozed"` Body param: The state of the conversation. Use "snoozed" with snoozedUntil to snooze. - `"open"` - `"closed"` - `"snoozed"` - `teamAssigneeId?: string | null` Body param: The team ID to assign the conversation to, or null to unassign. - `title?: string` Body param: The title of the conversation. - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` Header param: API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `Conversation` - `id: string` Unique conversation identifier - `adminAssigneeId: string | null` ID of the assigned admin - `botConversationStateLastUpdatedAt: string | null` ISO timestamp when bot state last changed - `brandId: string | null` ID of the brand associated with this conversation - `createdAt: string` ISO timestamp when conversation was created - `hasAdminOverriddenLanguage: boolean` Whether an admin has manually overridden the language for this conversation. When true, automatic language detection is disabled. - `isBlocked: boolean` Whether the user is blocked - `lastActivityAt: string | null` ISO timestamp of last activity - `object: "conversation"` Object type identifier - `"conversation"` - `participants: Array` Participants in this conversation - `id: string` Participant ID - `type: "customer" | "lead" | "admin" | 3 more` Type of participant - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `priority: boolean` Whether this conversation is marked as priority - `prioritySetAt: string | null` ISO timestamp when priority was set - `snoozedUntil: string | null` ISO timestamp until which conversation is snoozed - `state: "open" | "closed" | "snoozed"` Current state of the conversation - `"open"` - `"closed"` - `"snoozed"` - `tags: Array` Current tags applied anywhere in this conversation - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `teamAssigneeId: string | null` ID of the assigned team - `updatedAt: string` ISO timestamp when conversation was last updated - `userPreferredLanguage: string` User's preferred language - `waitingSince: string | null` ISO timestamp when conversation started waiting - `awaitingCustomerReply?: boolean` Whether we are awaiting a customer reply - `botConversationState?: "active" | "handed_off_to_human" | "resolved"` State of AI agent handling for this conversation - `"active"` - `"handed_off_to_human"` - `"resolved"` - `conversationParts?: Array` Array of conversation parts (messages). Only included when fetching a single conversation by ID. - `UserMessage` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `id: string | null` Author ID - `type: "customer" | "lead" | "admin" | 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email?: string` Author email address - `name?: string` Author display name - `profilePicture?: string | null` Author profile picture URL - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `AdminMessage` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string | null` Note body content as HTML with signed image URLs - `bodyMarkdown: string | null` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMessage` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string | null` Email body content as HTML with signed image URLs - `bodyMarkdown: string | null` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMessage` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string | null` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `channel?: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOptions` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: Array` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResponse` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT request payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt?: string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt?: string` ISO timestamp after which late submission is no longer allowed - `ratedAgent?: CsatRatedAgent` - `type: "teammate" | "fibi" | "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id?: string` Identifier of the rated agent when applicable - `workflow?: CsatWorkflowLink` - `workflowActionId?: string` Workflow action ID associated with the CSAT request - `workflowId?: string` Workflow ID associated with the CSAT request - `workflowRunId?: string` Workflow run ID associated with the CSAT request - `workflowStepId?: string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT submission payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent?: CsatRatedAgent` - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the request was created - `workflow?: CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttributeCollectionPrompt` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: Form` Form configuration - `id: string` Form ID - `attributes: Array` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttributeCollectionComplete` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assignment` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId?: string | null` ID of the admin assigned to the conversation - `adminAssignerId?: string | null` ID of the admin who made the assignment - `teamAssigneeId?: string | null` ID of the team assigned to the conversation - `StatusChange` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" | "closed" | "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil?: string | null` ISO timestamp until conversation is snoozed (if snoozed) - `TagUpdate` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" | "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor?: ConversationTagMutationActor` Actor that applied the tag - `tagName?: string | null` Tag name at the time of the event or the best available current display name - `targetPartId?: string | null` Conversation part that the tag mutation targeted - `WorkflowWaitEvent` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: WorkflowWait` Workflow wait event payload for this thread event - `eventType: "started" | "finished" | "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType?: "admin" | "customer" | "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel?: string` Human-readable wait duration or preset label - `workflowId?: string` Workflow ID associated with the wait event - `workflowName?: string` Workflow display name at the time of the wait event - `PriorityChange` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `ParticipantAdded` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: Participant` The added participant - `id: string` Participant ID - `type: "customer" | "lead" | "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated - `csatDebug?: CsatDebug` Minimal CSAT diagnostics for the current effective request. - `requestId: string` Canonical CSAT request ID used for the latest debug snapshot - `status: "pending" | "rated" | "canceled" | "expired"` Lifecycle status of the request represented in the debug snapshot - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp when rating edits stop being accepted - `emailDelivery?: CsatEmailDelivery` - `status: "pending" | "sent" | "failed"` Email delivery status for the CSAT request when applicable - `"pending"` - `"sent"` - `"failed"` - `failedAt?: string` ISO timestamp when the CSAT email failed - `failureReason?: string` Operational failure reason for the CSAT email delivery - `messageId?: string` Email message ID associated with delivery - `sentAt?: string` ISO timestamp when the CSAT email was sent - `lateSubmitWindowEndsAt?: string` ISO timestamp when first-time submissions stop being accepted - `csatHistory?: Array` Historical CSAT requests for this conversation, ordered newest first. - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `isLatestEffective: boolean` Whether this row represents the currently effective CSAT request for the conversation - `lastUpdatedAt: string` ISO timestamp when the request last changed - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Lifecycle status for this historical CSAT request - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt?: string` ISO timestamp when the request was canceled - `changeLockWindowEndsAt?: string` ISO timestamp when edits to an existing rating stop being accepted - `emailDelivery?: CsatEmailDelivery` - `expiredAt?: string` ISO timestamp when the request expired - `lateSubmitWindowEndsAt?: string` ISO timestamp when first-time submissions stop being accepted - `ratedAgent?: CsatRatedAgent` - `ratedAt?: string` ISO timestamp when the request was rated - `remark?: string` Submitted remark when present - `score?: number` Submitted score when this request was rated - `workflow?: CsatWorkflowLink` - `csatSummary?: CsatSummary` Derived CSAT summary for this conversation when a rating request or rating exists. - `lastUpdatedAt: string` ISO timestamp when the summary last changed - `status: "pending" | "rated" | "canceled" | "expired"` Current summary status for CSAT on this conversation - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt?: string` ISO timestamp when the request was canceled - `channel?: "desktop" | "email"` Channel used for the latest CSAT request when known - `"desktop"` - `"email"` - `expiredAt?: string` ISO timestamp when the request expired - `ratedAgent?: CsatRatedAgent` - `ratedAt?: string` ISO timestamp when the customer submitted a rating - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the latest CSAT request was created - `requestId?: string` Canonical CSAT request ID - `requestSource?: "workflow"` Source of the latest CSAT request when known - `"workflow"` - `score?: number` CSAT score from 1 to 5 when rated - `workflow?: CsatWorkflowLink` - `disableCustomerReply?: boolean` Whether customer replies are disabled - `readReceipts?: Array` Read receipts indicating how far each participant has read in the conversation. Each receipt maps a user to their last-read conversation part. The tracked position reflects the system read state and may reference parts the user cannot directly view (e.g., a contact's read position may point to an internal admin note). Use these receipts to render read indicators and typing awareness, not to infer content access. - `id: string` The internal ID of the user - `lastReadPartId: string` The ID of the last conversation part this user has read. Note: This reflects the system-tracked read position and may reference a part the user cannot directly access (e.g., internal notes for contacts). The read state is advanced to the latest part in the conversation regardless of part visibility. - `userType: "admin" | "customer" | "lead"` Type of user who has read the conversation - `"admin"` - `"customer"` - `"lead"` - `source?: Source` - `bodyHtml: string` Body of the initial message as HTML with signed image URLs - `bodyMarkdown: string` Body of the initial message as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the conversation was initiated - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `author?: ConversationParticipant` - `id: string` Participant ID - `type: "customer" | "lead" | "admin" | 3 more` Type of participant - `deliveredAs?: "customer_initiated" | "admin_initiated"` How the conversation was initiated - `"customer_initiated"` - `"admin_initiated"` - `subject?: string` Subject line for email conversations - `url?: string` URL where the conversation was initiated - `title?: string` Conversation title ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); const conversation = await client.support.conversations.update('12345'); console.log(conversation.id); ``` #### Response ```json { "id": "12345", "adminAssigneeId": "507f1f77bcf86cd799439011", "botConversationStateLastUpdatedAt": "2025-01-15T10:30:00.000Z", "brandId": "507f1f77bcf86cd799439011", "createdAt": "2025-01-15T10:30:00.000Z", "hasAdminOverriddenLanguage": false, "isBlocked": false, "lastActivityAt": "2025-01-15T12:30:00.000Z", "object": "conversation", "participants": [ { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" } ], "priority": false, "prioritySetAt": "2025-01-15T10:30:00.000Z", "snoozedUntil": "2025-01-16T09:00:00.000Z", "state": "open", "tags": [ { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } ], "teamAssigneeId": "507f1f77bcf86cd799439012", "updatedAt": "2025-01-15T12:30:00.000Z", "userPreferredLanguage": "en", "waitingSince": "2025-01-15T10:30:00.000Z", "awaitingCustomerReply": true, "botConversationState": "active", "conversationParts": [ { "id": "1", "bodyHtml": "

Hello, I have a question about your product.

", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ], "csatDebug": { "requestId": "csat_req_123", "status": "pending", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z" }, "csatHistory": [ { "channel": "desktop", "isLatestEffective": true, "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "status": "pending", "canceledAt": "2025-01-15T10:32:00.000Z", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "expiredAt": "2025-01-16T10:30:00.000Z", "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Thanks for the quick help.", "score": 4, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } } ], "csatSummary": { "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "status": "pending", "canceledAt": "2025-01-15T10:35:00.000Z", "channel": "desktop", "expiredAt": "2025-01-15T10:35:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Very helpful support.", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "score": 5, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } }, "disableCustomerReply": false, "readReceipts": [ { "id": "507f1f77bcf86cd799439011", "lastReadPartId": "8", "userType": "admin" } ], "source": { "bodyHtml": "

Hi, I have a question about your enterprise plan...

", "bodyMarkdown": "Hi, I have a question about your enterprise plan...", "channel": "desktop", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" }, "deliveredAs": "customer_initiated", "subject": "Question about pricing", "url": "https://example.com/pricing" }, "title": "Question about pricing" } ``` ## Reply to a conversation `client.support.conversations.reply(stringid, ConversationReplyParamsparams, RequestOptionsoptions?): ConversationPart` **post** `/v2/conversations/{id}/reply` Adds a reply to an existing conversation. Supports both contact (customer/lead) and admin replies. ### Path Parameters - `id` - The conversation ID (short ID) ### Request Body The request body varies based on who is sending the reply: #### Contact Reply (customer/lead) | Field | Type | Required | Description | | ------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `type` | string | Yes | Must be "contact" | | `userId` | string | No* | External user ID from your system | | `id` | string | No* | Featurebase contact ID (24-character ObjectId) | | `bodyMarkdown` | string | Yes | The message content in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. | | `messageType` | string | Yes | Must be "reply" | | `skipNotifications` | boolean | No | Skip sending notifications (default: false). Useful for bulk imports. | \*At least one of `userId` or `id` is required. #### Admin Reply | Field | Type | Required | Description | | ------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `type` | string | Yes | Must be "admin" | | `id` | string | Yes | Featurebase admin ID (24-character ObjectId) | | `bodyMarkdown` | string | Yes | The message content in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. | | `messageType` | string | Yes | "reply" for customer-visible reply, "note" for internal note | | `skipNotifications` | boolean | No | Skip sending notifications (default: false). Useful for bulk imports. | ### Response Returns the created conversation part object with a **201 Created** status. The response includes both `bodyHtml` (with signed image URLs) and `bodyMarkdown` fields. ### Example Contact Reply ```json { "type": "contact", "userId": "user_123", "bodyMarkdown": "Thank you for your help!", "messageType": "reply" } ``` ### Example Admin Reply ```json { "type": "admin", "id": "507f1f77bcf86cd799439011", "bodyMarkdown": "I'm happy to help! Here's what you need to do...", "messageType": "reply" } ``` ### Example Admin Note (Internal) ```json { "type": "admin", "id": "507f1f77bcf86cd799439011", "bodyMarkdown": "Customer seems frustrated, escalating to tier 2.", "messageType": "note" } ``` ### Example Response ```json { "object": "conversation_part", "id": "3", "partType": "user_msg", "bodyHtml": "

Thank you for your help!

", "bodyMarkdown": "Thank you for your help!", "author": { "type": "customer", "id": "676f0f6765bdaa7d7d760f88", "name": "John Doe", "email": "john@example.com" }, "channel": "desktop", "createdAt": "2025-01-15T10:40:00.000Z", "updatedAt": "2025-01-15T10:40:00.000Z" } ``` ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Parameters - `id: string` Conversation ID (short ID) - `ConversationReplyParams = ContactReplyBody | AdminReplyBody` - `ConversationReplyParamsBase` - `bodyMarkdown: string` Body param: The content of the reply message in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. - `messageType: "reply"` Body param: The type of message. Always "reply" for contact replies. - `"reply"` - `type: "contact"` Body param: The type of author. Use "contact" for customer/lead replies. - `"contact"` - `id?: string` Body param: The Featurebase contact ID - `skipNotifications?: boolean` Body param: Skip sending notifications (default: false). Useful for bulk imports. - `userId?: string` Body param: The external user ID from your system - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` Header param: API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` - `ContactReplyBody extends ConversationReplyParamsBase` - `AdminReplyBody extends ConversationReplyParamsBase` ### Returns - `ConversationPart = UserMessage | AdminMessage | AdminNote | 14 more` Message from a customer or lead - `UserMessage` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `id: string | null` Author ID - `type: "customer" | "lead" | "admin" | 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email?: string` Author email address - `name?: string` Author display name - `profilePicture?: string | null` Author profile picture URL - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `AdminMessage` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string | null` Note body content as HTML with signed image URLs - `bodyMarkdown: string | null` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMessage` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string | null` Email body content as HTML with signed image URLs - `bodyMarkdown: string | null` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMessage` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string | null` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `channel?: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOptions` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: Array` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResponse` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT request payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt?: string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt?: string` ISO timestamp after which late submission is no longer allowed - `ratedAgent?: CsatRatedAgent` - `type: "teammate" | "fibi" | "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id?: string` Identifier of the rated agent when applicable - `workflow?: CsatWorkflowLink` - `workflowActionId?: string` Workflow action ID associated with the CSAT request - `workflowId?: string` Workflow ID associated with the CSAT request - `workflowRunId?: string` Workflow run ID associated with the CSAT request - `workflowStepId?: string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT submission payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent?: CsatRatedAgent` - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the request was created - `workflow?: CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttributeCollectionPrompt` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: Form` Form configuration - `id: string` Form ID - `attributes: Array` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttributeCollectionComplete` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assignment` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId?: string | null` ID of the admin assigned to the conversation - `adminAssignerId?: string | null` ID of the admin who made the assignment - `teamAssigneeId?: string | null` ID of the team assigned to the conversation - `StatusChange` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" | "closed" | "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil?: string | null` ISO timestamp until conversation is snoozed (if snoozed) - `TagUpdate` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" | "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor?: ConversationTagMutationActor` Actor that applied the tag - `tagName?: string | null` Tag name at the time of the event or the best available current display name - `targetPartId?: string | null` Conversation part that the tag mutation targeted - `WorkflowWaitEvent` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: WorkflowWait` Workflow wait event payload for this thread event - `eventType: "started" | "finished" | "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType?: "admin" | "customer" | "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel?: string` Human-readable wait duration or preset label - `workflowId?: string` Workflow ID associated with the wait event - `workflowName?: string` Workflow display name at the time of the wait event - `PriorityChange` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `ParticipantAdded` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: Participant` The added participant - `id: string` Participant ID - `type: "customer" | "lead" | "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); const conversationPart = await client.support.conversations.reply('12345', { bodyMarkdown: 'Thank you for your help!', messageType: 'reply', type: 'contact', }); console.log(conversationPart); ``` #### Response ```json { "id": "1", "bodyHtml": "

Hello, I have a question about your product.

", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ``` ## Redact a conversation part `client.support.conversations.redact(ConversationRedactParamsparams, RequestOptionsoptions?): Conversation` **post** `/v2/conversations/redact` Redacts a conversation part (message) from a conversation. Redaction permanently removes the message content while preserving the conversation structure. Only human message types can be redacted: - `user_msg` - Messages from customers/leads - `admin_msg` - Messages from admins - `email_msg` - Email messages - `bot_msg` - Bot messages System-generated conversation parts (assignments, status changes, etc.) cannot be redacted. ### Request Body | Field | Type | Required | Description | | -------------------- | ------ | -------- | ------------------------------------------------------------------------------ | | `type` | string | Yes | The type of item to redact. Currently only `"conversation_part"` is supported. | | `conversationId` | string | Yes | The conversation short ID containing the part to redact | | `conversationPartId` | string | Yes | The conversation part short ID to redact | | `actingAdminId` | string | No | Admin ID performing the action (for attribution) | ### Response Returns the updated conversation object. ### Example Request ```json { "type": "conversation_part", "conversationId": "12345", "conversationPartId": "67890", "actingAdminId": "507f1f77bcf86cd799439011" } ``` ### Example Response ```json { "object": "conversation", "id": "12345", "conversationParts": [ { "object": "conversation_part", "id": "67890", "partType": "user_msg", "bodyHtml": "", "bodyMarkdown": "", "redacted": true, ... } ], ... } ``` ### Error Cases - **400 Bad Request** - Only human messages can be redacted - **404 Not Found** - Conversation or conversation part not found ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Parameters - `params: ConversationRedactParams` - `conversationId: string` Body param: The conversation short ID that contains the part to redact - `conversationPartId: string` Body param: The conversation part short ID to redact - `type: "conversation_part"` Body param: The type of item to redact. Currently only "conversation_part" is supported. - `"conversation_part"` - `actingAdminId?: string` Body param: The admin ID performing this action. If not provided, changes are attributed to the system bot user. - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` Header param: API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `Conversation` - `id: string` Unique conversation identifier - `adminAssigneeId: string | null` ID of the assigned admin - `botConversationStateLastUpdatedAt: string | null` ISO timestamp when bot state last changed - `brandId: string | null` ID of the brand associated with this conversation - `createdAt: string` ISO timestamp when conversation was created - `hasAdminOverriddenLanguage: boolean` Whether an admin has manually overridden the language for this conversation. When true, automatic language detection is disabled. - `isBlocked: boolean` Whether the user is blocked - `lastActivityAt: string | null` ISO timestamp of last activity - `object: "conversation"` Object type identifier - `"conversation"` - `participants: Array` Participants in this conversation - `id: string` Participant ID - `type: "customer" | "lead" | "admin" | 3 more` Type of participant - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `priority: boolean` Whether this conversation is marked as priority - `prioritySetAt: string | null` ISO timestamp when priority was set - `snoozedUntil: string | null` ISO timestamp until which conversation is snoozed - `state: "open" | "closed" | "snoozed"` Current state of the conversation - `"open"` - `"closed"` - `"snoozed"` - `tags: Array` Current tags applied anywhere in this conversation - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `teamAssigneeId: string | null` ID of the assigned team - `updatedAt: string` ISO timestamp when conversation was last updated - `userPreferredLanguage: string` User's preferred language - `waitingSince: string | null` ISO timestamp when conversation started waiting - `awaitingCustomerReply?: boolean` Whether we are awaiting a customer reply - `botConversationState?: "active" | "handed_off_to_human" | "resolved"` State of AI agent handling for this conversation - `"active"` - `"handed_off_to_human"` - `"resolved"` - `conversationParts?: Array` Array of conversation parts (messages). Only included when fetching a single conversation by ID. - `UserMessage` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `id: string | null` Author ID - `type: "customer" | "lead" | "admin" | 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email?: string` Author email address - `name?: string` Author display name - `profilePicture?: string | null` Author profile picture URL - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `AdminMessage` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string | null` Note body content as HTML with signed image URLs - `bodyMarkdown: string | null` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMessage` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string | null` Email body content as HTML with signed image URLs - `bodyMarkdown: string | null` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMessage` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string | null` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `channel?: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOptions` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: Array` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResponse` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT request payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt?: string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt?: string` ISO timestamp after which late submission is no longer allowed - `ratedAgent?: CsatRatedAgent` - `type: "teammate" | "fibi" | "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id?: string` Identifier of the rated agent when applicable - `workflow?: CsatWorkflowLink` - `workflowActionId?: string` Workflow action ID associated with the CSAT request - `workflowId?: string` Workflow ID associated with the CSAT request - `workflowRunId?: string` Workflow run ID associated with the CSAT request - `workflowStepId?: string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT submission payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent?: CsatRatedAgent` - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the request was created - `workflow?: CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttributeCollectionPrompt` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: Form` Form configuration - `id: string` Form ID - `attributes: Array` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttributeCollectionComplete` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assignment` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId?: string | null` ID of the admin assigned to the conversation - `adminAssignerId?: string | null` ID of the admin who made the assignment - `teamAssigneeId?: string | null` ID of the team assigned to the conversation - `StatusChange` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" | "closed" | "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil?: string | null` ISO timestamp until conversation is snoozed (if snoozed) - `TagUpdate` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" | "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor?: ConversationTagMutationActor` Actor that applied the tag - `tagName?: string | null` Tag name at the time of the event or the best available current display name - `targetPartId?: string | null` Conversation part that the tag mutation targeted - `WorkflowWaitEvent` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: WorkflowWait` Workflow wait event payload for this thread event - `eventType: "started" | "finished" | "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType?: "admin" | "customer" | "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel?: string` Human-readable wait duration or preset label - `workflowId?: string` Workflow ID associated with the wait event - `workflowName?: string` Workflow display name at the time of the wait event - `PriorityChange` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `ParticipantAdded` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: Participant` The added participant - `id: string` Participant ID - `type: "customer" | "lead" | "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated - `csatDebug?: CsatDebug` Minimal CSAT diagnostics for the current effective request. - `requestId: string` Canonical CSAT request ID used for the latest debug snapshot - `status: "pending" | "rated" | "canceled" | "expired"` Lifecycle status of the request represented in the debug snapshot - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp when rating edits stop being accepted - `emailDelivery?: CsatEmailDelivery` - `status: "pending" | "sent" | "failed"` Email delivery status for the CSAT request when applicable - `"pending"` - `"sent"` - `"failed"` - `failedAt?: string` ISO timestamp when the CSAT email failed - `failureReason?: string` Operational failure reason for the CSAT email delivery - `messageId?: string` Email message ID associated with delivery - `sentAt?: string` ISO timestamp when the CSAT email was sent - `lateSubmitWindowEndsAt?: string` ISO timestamp when first-time submissions stop being accepted - `csatHistory?: Array` Historical CSAT requests for this conversation, ordered newest first. - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `isLatestEffective: boolean` Whether this row represents the currently effective CSAT request for the conversation - `lastUpdatedAt: string` ISO timestamp when the request last changed - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Lifecycle status for this historical CSAT request - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt?: string` ISO timestamp when the request was canceled - `changeLockWindowEndsAt?: string` ISO timestamp when edits to an existing rating stop being accepted - `emailDelivery?: CsatEmailDelivery` - `expiredAt?: string` ISO timestamp when the request expired - `lateSubmitWindowEndsAt?: string` ISO timestamp when first-time submissions stop being accepted - `ratedAgent?: CsatRatedAgent` - `ratedAt?: string` ISO timestamp when the request was rated - `remark?: string` Submitted remark when present - `score?: number` Submitted score when this request was rated - `workflow?: CsatWorkflowLink` - `csatSummary?: CsatSummary` Derived CSAT summary for this conversation when a rating request or rating exists. - `lastUpdatedAt: string` ISO timestamp when the summary last changed - `status: "pending" | "rated" | "canceled" | "expired"` Current summary status for CSAT on this conversation - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt?: string` ISO timestamp when the request was canceled - `channel?: "desktop" | "email"` Channel used for the latest CSAT request when known - `"desktop"` - `"email"` - `expiredAt?: string` ISO timestamp when the request expired - `ratedAgent?: CsatRatedAgent` - `ratedAt?: string` ISO timestamp when the customer submitted a rating - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the latest CSAT request was created - `requestId?: string` Canonical CSAT request ID - `requestSource?: "workflow"` Source of the latest CSAT request when known - `"workflow"` - `score?: number` CSAT score from 1 to 5 when rated - `workflow?: CsatWorkflowLink` - `disableCustomerReply?: boolean` Whether customer replies are disabled - `readReceipts?: Array` Read receipts indicating how far each participant has read in the conversation. Each receipt maps a user to their last-read conversation part. The tracked position reflects the system read state and may reference parts the user cannot directly view (e.g., a contact's read position may point to an internal admin note). Use these receipts to render read indicators and typing awareness, not to infer content access. - `id: string` The internal ID of the user - `lastReadPartId: string` The ID of the last conversation part this user has read. Note: This reflects the system-tracked read position and may reference a part the user cannot directly access (e.g., internal notes for contacts). The read state is advanced to the latest part in the conversation regardless of part visibility. - `userType: "admin" | "customer" | "lead"` Type of user who has read the conversation - `"admin"` - `"customer"` - `"lead"` - `source?: Source` - `bodyHtml: string` Body of the initial message as HTML with signed image URLs - `bodyMarkdown: string` Body of the initial message as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the conversation was initiated - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `author?: ConversationParticipant` - `id: string` Participant ID - `type: "customer" | "lead" | "admin" | 3 more` Type of participant - `deliveredAs?: "customer_initiated" | "admin_initiated"` How the conversation was initiated - `"customer_initiated"` - `"admin_initiated"` - `subject?: string` Subject line for email conversations - `url?: string` URL where the conversation was initiated - `title?: string` Conversation title ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); const conversation = await client.support.conversations.redact({ conversationId: '12345', conversationPartId: '67890', type: 'conversation_part', }); console.log(conversation.id); ``` #### Response ```json { "id": "12345", "adminAssigneeId": "507f1f77bcf86cd799439011", "botConversationStateLastUpdatedAt": "2025-01-15T10:30:00.000Z", "brandId": "507f1f77bcf86cd799439011", "createdAt": "2025-01-15T10:30:00.000Z", "hasAdminOverriddenLanguage": false, "isBlocked": false, "lastActivityAt": "2025-01-15T12:30:00.000Z", "object": "conversation", "participants": [ { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" } ], "priority": false, "prioritySetAt": "2025-01-15T10:30:00.000Z", "snoozedUntil": "2025-01-16T09:00:00.000Z", "state": "open", "tags": [ { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } ], "teamAssigneeId": "507f1f77bcf86cd799439012", "updatedAt": "2025-01-15T12:30:00.000Z", "userPreferredLanguage": "en", "waitingSince": "2025-01-15T10:30:00.000Z", "awaitingCustomerReply": true, "botConversationState": "active", "conversationParts": [ { "id": "1", "bodyHtml": "

Hello, I have a question about your product.

", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ], "csatDebug": { "requestId": "csat_req_123", "status": "pending", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z" }, "csatHistory": [ { "channel": "desktop", "isLatestEffective": true, "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "status": "pending", "canceledAt": "2025-01-15T10:32:00.000Z", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "expiredAt": "2025-01-16T10:30:00.000Z", "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Thanks for the quick help.", "score": 4, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } } ], "csatSummary": { "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "status": "pending", "canceledAt": "2025-01-15T10:35:00.000Z", "channel": "desktop", "expiredAt": "2025-01-15T10:35:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Very helpful support.", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "score": 5, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } }, "disableCustomerReply": false, "readReceipts": [ { "id": "507f1f77bcf86cd799439011", "lastReadPartId": "8", "userType": "admin" } ], "source": { "bodyHtml": "

Hi, I have a question about your enterprise plan...

", "bodyMarkdown": "Hi, I have a question about your enterprise plan...", "channel": "desktop", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" }, "deliveredAs": "customer_initiated", "subject": "Question about pricing", "url": "https://example.com/pricing" }, "title": "Question about pricing" } ``` ## Domain Types ### Conversation - `Conversation` - `id: string` Unique conversation identifier - `adminAssigneeId: string | null` ID of the assigned admin - `botConversationStateLastUpdatedAt: string | null` ISO timestamp when bot state last changed - `brandId: string | null` ID of the brand associated with this conversation - `createdAt: string` ISO timestamp when conversation was created - `hasAdminOverriddenLanguage: boolean` Whether an admin has manually overridden the language for this conversation. When true, automatic language detection is disabled. - `isBlocked: boolean` Whether the user is blocked - `lastActivityAt: string | null` ISO timestamp of last activity - `object: "conversation"` Object type identifier - `"conversation"` - `participants: Array` Participants in this conversation - `id: string` Participant ID - `type: "customer" | "lead" | "admin" | 3 more` Type of participant - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `priority: boolean` Whether this conversation is marked as priority - `prioritySetAt: string | null` ISO timestamp when priority was set - `snoozedUntil: string | null` ISO timestamp until which conversation is snoozed - `state: "open" | "closed" | "snoozed"` Current state of the conversation - `"open"` - `"closed"` - `"snoozed"` - `tags: Array` Current tags applied anywhere in this conversation - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `teamAssigneeId: string | null` ID of the assigned team - `updatedAt: string` ISO timestamp when conversation was last updated - `userPreferredLanguage: string` User's preferred language - `waitingSince: string | null` ISO timestamp when conversation started waiting - `awaitingCustomerReply?: boolean` Whether we are awaiting a customer reply - `botConversationState?: "active" | "handed_off_to_human" | "resolved"` State of AI agent handling for this conversation - `"active"` - `"handed_off_to_human"` - `"resolved"` - `conversationParts?: Array` Array of conversation parts (messages). Only included when fetching a single conversation by ID. - `UserMessage` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `id: string | null` Author ID - `type: "customer" | "lead" | "admin" | 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email?: string` Author email address - `name?: string` Author display name - `profilePicture?: string | null` Author profile picture URL - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `AdminMessage` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string | null` Note body content as HTML with signed image URLs - `bodyMarkdown: string | null` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMessage` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string | null` Email body content as HTML with signed image URLs - `bodyMarkdown: string | null` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMessage` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string | null` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `channel?: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOptions` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: Array` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResponse` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT request payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt?: string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt?: string` ISO timestamp after which late submission is no longer allowed - `ratedAgent?: CsatRatedAgent` - `type: "teammate" | "fibi" | "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id?: string` Identifier of the rated agent when applicable - `workflow?: CsatWorkflowLink` - `workflowActionId?: string` Workflow action ID associated with the CSAT request - `workflowId?: string` Workflow ID associated with the CSAT request - `workflowRunId?: string` Workflow run ID associated with the CSAT request - `workflowStepId?: string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT submission payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent?: CsatRatedAgent` - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the request was created - `workflow?: CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttributeCollectionPrompt` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: Form` Form configuration - `id: string` Form ID - `attributes: Array` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttributeCollectionComplete` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assignment` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId?: string | null` ID of the admin assigned to the conversation - `adminAssignerId?: string | null` ID of the admin who made the assignment - `teamAssigneeId?: string | null` ID of the team assigned to the conversation - `StatusChange` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" | "closed" | "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil?: string | null` ISO timestamp until conversation is snoozed (if snoozed) - `TagUpdate` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" | "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor?: ConversationTagMutationActor` Actor that applied the tag - `tagName?: string | null` Tag name at the time of the event or the best available current display name - `targetPartId?: string | null` Conversation part that the tag mutation targeted - `WorkflowWaitEvent` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: WorkflowWait` Workflow wait event payload for this thread event - `eventType: "started" | "finished" | "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType?: "admin" | "customer" | "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel?: string` Human-readable wait duration or preset label - `workflowId?: string` Workflow ID associated with the wait event - `workflowName?: string` Workflow display name at the time of the wait event - `PriorityChange` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `ParticipantAdded` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: Participant` The added participant - `id: string` Participant ID - `type: "customer" | "lead" | "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated - `csatDebug?: CsatDebug` Minimal CSAT diagnostics for the current effective request. - `requestId: string` Canonical CSAT request ID used for the latest debug snapshot - `status: "pending" | "rated" | "canceled" | "expired"` Lifecycle status of the request represented in the debug snapshot - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp when rating edits stop being accepted - `emailDelivery?: CsatEmailDelivery` - `status: "pending" | "sent" | "failed"` Email delivery status for the CSAT request when applicable - `"pending"` - `"sent"` - `"failed"` - `failedAt?: string` ISO timestamp when the CSAT email failed - `failureReason?: string` Operational failure reason for the CSAT email delivery - `messageId?: string` Email message ID associated with delivery - `sentAt?: string` ISO timestamp when the CSAT email was sent - `lateSubmitWindowEndsAt?: string` ISO timestamp when first-time submissions stop being accepted - `csatHistory?: Array` Historical CSAT requests for this conversation, ordered newest first. - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `isLatestEffective: boolean` Whether this row represents the currently effective CSAT request for the conversation - `lastUpdatedAt: string` ISO timestamp when the request last changed - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Lifecycle status for this historical CSAT request - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt?: string` ISO timestamp when the request was canceled - `changeLockWindowEndsAt?: string` ISO timestamp when edits to an existing rating stop being accepted - `emailDelivery?: CsatEmailDelivery` - `expiredAt?: string` ISO timestamp when the request expired - `lateSubmitWindowEndsAt?: string` ISO timestamp when first-time submissions stop being accepted - `ratedAgent?: CsatRatedAgent` - `ratedAt?: string` ISO timestamp when the request was rated - `remark?: string` Submitted remark when present - `score?: number` Submitted score when this request was rated - `workflow?: CsatWorkflowLink` - `csatSummary?: CsatSummary` Derived CSAT summary for this conversation when a rating request or rating exists. - `lastUpdatedAt: string` ISO timestamp when the summary last changed - `status: "pending" | "rated" | "canceled" | "expired"` Current summary status for CSAT on this conversation - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt?: string` ISO timestamp when the request was canceled - `channel?: "desktop" | "email"` Channel used for the latest CSAT request when known - `"desktop"` - `"email"` - `expiredAt?: string` ISO timestamp when the request expired - `ratedAgent?: CsatRatedAgent` - `ratedAt?: string` ISO timestamp when the customer submitted a rating - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the latest CSAT request was created - `requestId?: string` Canonical CSAT request ID - `requestSource?: "workflow"` Source of the latest CSAT request when known - `"workflow"` - `score?: number` CSAT score from 1 to 5 when rated - `workflow?: CsatWorkflowLink` - `disableCustomerReply?: boolean` Whether customer replies are disabled - `readReceipts?: Array` Read receipts indicating how far each participant has read in the conversation. Each receipt maps a user to their last-read conversation part. The tracked position reflects the system read state and may reference parts the user cannot directly view (e.g., a contact's read position may point to an internal admin note). Use these receipts to render read indicators and typing awareness, not to infer content access. - `id: string` The internal ID of the user - `lastReadPartId: string` The ID of the last conversation part this user has read. Note: This reflects the system-tracked read position and may reference a part the user cannot directly access (e.g., internal notes for contacts). The read state is advanced to the latest part in the conversation regardless of part visibility. - `userType: "admin" | "customer" | "lead"` Type of user who has read the conversation - `"admin"` - `"customer"` - `"lead"` - `source?: Source` - `bodyHtml: string` Body of the initial message as HTML with signed image URLs - `bodyMarkdown: string` Body of the initial message as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the conversation was initiated - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `author?: ConversationParticipant` - `id: string` Participant ID - `type: "customer" | "lead" | "admin" | 3 more` Type of participant - `deliveredAs?: "customer_initiated" | "admin_initiated"` How the conversation was initiated - `"customer_initiated"` - `"admin_initiated"` - `subject?: string` Subject line for email conversations - `url?: string` URL where the conversation was initiated - `title?: string` Conversation title ### Conversation Part - `ConversationPart = UserMessage | AdminMessage | AdminNote | 14 more` Message from a customer or lead - `UserMessage` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `id: string | null` Author ID - `type: "customer" | "lead" | "admin" | 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email?: string` Author email address - `name?: string` Author display name - `profilePicture?: string | null` Author profile picture URL - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `AdminMessage` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string | null` Note body content as HTML with signed image URLs - `bodyMarkdown: string | null` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMessage` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string | null` Email body content as HTML with signed image URLs - `bodyMarkdown: string | null` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMessage` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string | null` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `channel?: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOptions` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: Array` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResponse` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT request payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt?: string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt?: string` ISO timestamp after which late submission is no longer allowed - `ratedAgent?: CsatRatedAgent` - `type: "teammate" | "fibi" | "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id?: string` Identifier of the rated agent when applicable - `workflow?: CsatWorkflowLink` - `workflowActionId?: string` Workflow action ID associated with the CSAT request - `workflowId?: string` Workflow ID associated with the CSAT request - `workflowRunId?: string` Workflow run ID associated with the CSAT request - `workflowStepId?: string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT submission payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent?: CsatRatedAgent` - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the request was created - `workflow?: CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttributeCollectionPrompt` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: Form` Form configuration - `id: string` Form ID - `attributes: Array` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttributeCollectionComplete` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assignment` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId?: string | null` ID of the admin assigned to the conversation - `adminAssignerId?: string | null` ID of the admin who made the assignment - `teamAssigneeId?: string | null` ID of the team assigned to the conversation - `StatusChange` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" | "closed" | "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil?: string | null` ISO timestamp until conversation is snoozed (if snoozed) - `TagUpdate` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" | "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor?: ConversationTagMutationActor` Actor that applied the tag - `tagName?: string | null` Tag name at the time of the event or the best available current display name - `targetPartId?: string | null` Conversation part that the tag mutation targeted - `WorkflowWaitEvent` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: WorkflowWait` Workflow wait event payload for this thread event - `eventType: "started" | "finished" | "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType?: "admin" | "customer" | "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel?: string` Human-readable wait duration or preset label - `workflowId?: string` Workflow ID associated with the wait event - `workflowName?: string` Workflow display name at the time of the wait event - `PriorityChange` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `ParticipantAdded` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: Participant` The added participant - `id: string` Participant ID - `type: "customer" | "lead" | "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated ### Conversation Part Author - `ConversationPartAuthor` - `id: string | null` Author ID - `type: "customer" | "lead" | "admin" | 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email?: string` Author email address - `name?: string` Author display name - `profilePicture?: string | null` Author profile picture URL ### Conversation Participant - `ConversationParticipant` - `id: string` Participant ID - `type: "customer" | "lead" | "admin" | 3 more` Type of participant - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` ### Conversation Tag Application - `ConversationTagApplication` - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` ### Csat Email Delivery - `CsatEmailDelivery` - `status: "pending" | "sent" | "failed"` Email delivery status for the CSAT request when applicable - `"pending"` - `"sent"` - `"failed"` - `failedAt?: string` ISO timestamp when the CSAT email failed - `failureReason?: string` Operational failure reason for the CSAT email delivery - `messageId?: string` Email message ID associated with delivery - `sentAt?: string` ISO timestamp when the CSAT email was sent ### Csat Rated Agent - `CsatRatedAgent` - `type: "teammate" | "fibi" | "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id?: string` Identifier of the rated agent when applicable ### Csat Workflow Link - `CsatWorkflowLink` - `workflowActionId?: string` Workflow action ID associated with the CSAT request - `workflowId?: string` Workflow ID associated with the CSAT request - `workflowRunId?: string` Workflow run ID associated with the CSAT request - `workflowStepId?: string` Workflow step ID associated with the CSAT request ### Email Recipients - `EmailRecipients` Primary recipients (To field) - `emails?: Array` Array of email addresses - `ids?: Array` Array of Featurebase contact IDs ### Conversation Delete Response - `ConversationDeleteResponse` - `id: string` Unique identifier of the deleted conversation - `deleted: true` Indicates the resource was deleted - `true` - `object: "conversation"` Object type identifier - `"conversation"` # Tags ## Attach a tag to a conversation `client.support.conversations.tags.attach(stringid, TagAttachParamsparams, RequestOptionsoptions?): AttachedConversationTag` **post** `/v2/conversations/{id}/tags` Attaches a workspace tag to a conversation. This endpoint requires both the tag ID to attach and the `actingAdminId` of the admin on whose behalf the mutation is recorded. ### Path Parameters - `id` - The conversation ID (short ID) ### Request Body | Field | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------------------------------------------ | | `tagId` | string | Yes | The Featurebase tag ID to attach | | `actingAdminId` | string | Yes | The admin performing the mutation. Must be a member of the organization. | ### Behavior Featurebase resolves the latest taggable reply/message in the conversation and records the tag attachment against that part so audit metadata remains deterministic. ### Response Returns the affected tag plus attachment metadata such as `targetPartId`, `appliedAt`, and `appliedBy`. ### Example Request ```json { "tagId": "67ec1234abcd5678ef901234", "actingAdminId": "507f1f77bcf86cd799439011" } ``` ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Parameters - `id: string` Conversation ID (short ID) - `params: TagAttachParams` - `actingAdminId: string` Body param: Required admin ID performing this tag attachment. Must be a member of the organization so the mutation can be attributed to a real admin actor. - `tagId: string` Body param: The Featurebase tag ID to attach to the conversation. - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` Header param: API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `AttachedConversationTag` - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `appliedAt?: string | null` ISO timestamp when the tag was applied - `appliedBy?: ConversationTagMutationActor | null` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available - `removedAt?: string | null` ISO timestamp when the tag was removed, if applicable - `removedBy?: ConversationTagMutationActor | null` Actor that applied the tag - `targetPartId?: string | null` Reply/message ID used as the deterministic attachment target for this conversation tag mutation. ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); const attachedConversationTag = await client.support.conversations.tags.attach('12345', { actingAdminId: '507f1f77bcf86cd799439011', tagId: '67ec1234abcd5678ef901234', }); console.log(attachedConversationTag.id); ``` #### Response ```json { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag", "appliedAt": "2025-01-15T10:30:00.000Z", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "targetPartId": "67890" } ``` ## Detach a tag from a conversation `client.support.conversations.tags.detach(stringtagID, TagDetachParamsparams, RequestOptionsoptions?): AttachedConversationTag` **delete** `/v2/conversations/{id}/tags/{tagId}` Removes a workspace tag from a conversation. This endpoint requires the `actingAdminId` of the admin on whose behalf the mutation is recorded. ### Path Parameters - `id` - The conversation ID (short ID) - `tagId` - The Featurebase tag ID to remove ### Request Body | Field | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------------------------------------------ | | `actingAdminId` | string | Yes | The admin performing the mutation. Must be a member of the organization. | ### Behavior Featurebase resolves the latest taggable reply/message in the conversation and records the tag removal against that part so audit metadata remains deterministic. ### Response Returns the affected tag payload with the most relevant attachment metadata available for that relationship. ### Example Request ```json { "actingAdminId": "507f1f77bcf86cd799439011" } ``` ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Parameters - `tagID: string` The Featurebase tag ID to remove from the conversation. - `params: TagDetachParams` - `id: string` Path param: Conversation ID (short ID) - `actingAdminId: string` Body param: Required admin ID performing this tag removal. Must be a member of the organization so the mutation can be attributed to a real admin actor. - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` Header param: API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `AttachedConversationTag` - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `appliedAt?: string | null` ISO timestamp when the tag was applied - `appliedBy?: ConversationTagMutationActor | null` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available - `removedAt?: string | null` ISO timestamp when the tag was removed, if applicable - `removedBy?: ConversationTagMutationActor | null` Actor that applied the tag - `targetPartId?: string | null` Reply/message ID used as the deterministic attachment target for this conversation tag mutation. ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); const attachedConversationTag = await client.support.conversations.tags.detach( '67ec1234abcd5678ef901234', { id: '12345', actingAdminId: '507f1f77bcf86cd799439011' }, ); console.log(attachedConversationTag.id); ``` #### Response ```json { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag", "appliedAt": "2025-01-15T10:30:00.000Z", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "targetPartId": "67890" } ``` ## Domain Types ### Attached Conversation Tag - `AttachedConversationTag` - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `appliedAt?: string | null` ISO timestamp when the tag was applied - `appliedBy?: ConversationTagMutationActor | null` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available - `removedAt?: string | null` ISO timestamp when the tag was removed, if applicable - `removedBy?: ConversationTagMutationActor | null` Actor that applied the tag - `targetPartId?: string | null` Reply/message ID used as the deterministic attachment target for this conversation tag mutation. ### Conversation Tag Mutation Actor - `ConversationTagMutationActor` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available # Participants ## Add a contact to a conversation `client.support.conversations.participants.add(stringid, ParticipantAddParamsparams, RequestOptionsoptions?): Conversation` **post** `/v2/conversations/{id}/participants` Adds a contact (customer or lead) as a participant to an existing conversation. ### Path Parameters - `id` - The conversation ID (short ID) ### Request Body | Field | Type | Required | Description | | -------------------- | ------ | -------- | --------------------------------------------------------------------- | | `participant` | object | Yes | The contact to add (see below) | | `participant.id` | string | No* | The Featurebase ID (24-character ObjectId) - matches customer or lead | | `participant.userId` | string | No* | External user ID from your system - matches customer only | | `participant.email` | string | No* | Email address - matches customer only | | `actingAdminId` | string | No | Admin ID performing the action (for attribution) | \*At least one of `id`, `userId`, or `email` is required in the participant object. ### Lookup Priority 1. If `id` is provided, looks up by Featurebase ID (matches both customer and lead types) 1. If `userId` is provided, looks up by external user ID (matches customer type only) 1. If `email` is provided, looks up by email address (matches customer type only) ### Response Returns the updated conversation object. ### Example Request (by Featurebase ID) ```json { "participant": { "id": "676f0f6765bdaa7d7d760f88" }, "actingAdminId": "507f1f77bcf86cd799439011" } ``` ### Example Request (by external userId) ```json { "participant": { "userId": "user_123" } } ``` ### Example Request (by email) ```json { "participant": { "email": "john@example.com" } } ``` ### Example Response ```json { "object": "conversation", "id": "12345", "participants": [ { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" }, { "type": "customer", "id": "676f0f6765bdaa7d7d760f89" } ], ... } ``` ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Parameters - `id: string` Conversation ID (short ID) - `params: ParticipantAddParams` - `participant: Participant` Body param: The contact to add as a participant. At least one of id, userId, or email is required. - `id?: string` The Featurebase ID of the contact (customer or lead) - `email?: string` The email address of the contact (matches customer type only) - `userId?: string` The external user ID from your system (matches customer type only) - `actingAdminId?: string` Body param: The admin ID performing this action. If not provided, changes are attributed to the system bot user. - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` Header param: API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `Conversation` - `id: string` Unique conversation identifier - `adminAssigneeId: string | null` ID of the assigned admin - `botConversationStateLastUpdatedAt: string | null` ISO timestamp when bot state last changed - `brandId: string | null` ID of the brand associated with this conversation - `createdAt: string` ISO timestamp when conversation was created - `hasAdminOverriddenLanguage: boolean` Whether an admin has manually overridden the language for this conversation. When true, automatic language detection is disabled. - `isBlocked: boolean` Whether the user is blocked - `lastActivityAt: string | null` ISO timestamp of last activity - `object: "conversation"` Object type identifier - `"conversation"` - `participants: Array` Participants in this conversation - `id: string` Participant ID - `type: "customer" | "lead" | "admin" | 3 more` Type of participant - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `priority: boolean` Whether this conversation is marked as priority - `prioritySetAt: string | null` ISO timestamp when priority was set - `snoozedUntil: string | null` ISO timestamp until which conversation is snoozed - `state: "open" | "closed" | "snoozed"` Current state of the conversation - `"open"` - `"closed"` - `"snoozed"` - `tags: Array` Current tags applied anywhere in this conversation - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `teamAssigneeId: string | null` ID of the assigned team - `updatedAt: string` ISO timestamp when conversation was last updated - `userPreferredLanguage: string` User's preferred language - `waitingSince: string | null` ISO timestamp when conversation started waiting - `awaitingCustomerReply?: boolean` Whether we are awaiting a customer reply - `botConversationState?: "active" | "handed_off_to_human" | "resolved"` State of AI agent handling for this conversation - `"active"` - `"handed_off_to_human"` - `"resolved"` - `conversationParts?: Array` Array of conversation parts (messages). Only included when fetching a single conversation by ID. - `UserMessage` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `id: string | null` Author ID - `type: "customer" | "lead" | "admin" | 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email?: string` Author email address - `name?: string` Author display name - `profilePicture?: string | null` Author profile picture URL - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `AdminMessage` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string | null` Note body content as HTML with signed image URLs - `bodyMarkdown: string | null` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMessage` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string | null` Email body content as HTML with signed image URLs - `bodyMarkdown: string | null` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMessage` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string | null` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `channel?: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOptions` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: Array` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResponse` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT request payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt?: string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt?: string` ISO timestamp after which late submission is no longer allowed - `ratedAgent?: CsatRatedAgent` - `type: "teammate" | "fibi" | "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id?: string` Identifier of the rated agent when applicable - `workflow?: CsatWorkflowLink` - `workflowActionId?: string` Workflow action ID associated with the CSAT request - `workflowId?: string` Workflow ID associated with the CSAT request - `workflowRunId?: string` Workflow run ID associated with the CSAT request - `workflowStepId?: string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT submission payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent?: CsatRatedAgent` - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the request was created - `workflow?: CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttributeCollectionPrompt` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: Form` Form configuration - `id: string` Form ID - `attributes: Array` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttributeCollectionComplete` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assignment` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId?: string | null` ID of the admin assigned to the conversation - `adminAssignerId?: string | null` ID of the admin who made the assignment - `teamAssigneeId?: string | null` ID of the team assigned to the conversation - `StatusChange` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" | "closed" | "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil?: string | null` ISO timestamp until conversation is snoozed (if snoozed) - `TagUpdate` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" | "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor?: ConversationTagMutationActor` Actor that applied the tag - `tagName?: string | null` Tag name at the time of the event or the best available current display name - `targetPartId?: string | null` Conversation part that the tag mutation targeted - `WorkflowWaitEvent` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: WorkflowWait` Workflow wait event payload for this thread event - `eventType: "started" | "finished" | "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType?: "admin" | "customer" | "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel?: string` Human-readable wait duration or preset label - `workflowId?: string` Workflow ID associated with the wait event - `workflowName?: string` Workflow display name at the time of the wait event - `PriorityChange` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `ParticipantAdded` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: Participant` The added participant - `id: string` Participant ID - `type: "customer" | "lead" | "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated - `csatDebug?: CsatDebug` Minimal CSAT diagnostics for the current effective request. - `requestId: string` Canonical CSAT request ID used for the latest debug snapshot - `status: "pending" | "rated" | "canceled" | "expired"` Lifecycle status of the request represented in the debug snapshot - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp when rating edits stop being accepted - `emailDelivery?: CsatEmailDelivery` - `status: "pending" | "sent" | "failed"` Email delivery status for the CSAT request when applicable - `"pending"` - `"sent"` - `"failed"` - `failedAt?: string` ISO timestamp when the CSAT email failed - `failureReason?: string` Operational failure reason for the CSAT email delivery - `messageId?: string` Email message ID associated with delivery - `sentAt?: string` ISO timestamp when the CSAT email was sent - `lateSubmitWindowEndsAt?: string` ISO timestamp when first-time submissions stop being accepted - `csatHistory?: Array` Historical CSAT requests for this conversation, ordered newest first. - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `isLatestEffective: boolean` Whether this row represents the currently effective CSAT request for the conversation - `lastUpdatedAt: string` ISO timestamp when the request last changed - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Lifecycle status for this historical CSAT request - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt?: string` ISO timestamp when the request was canceled - `changeLockWindowEndsAt?: string` ISO timestamp when edits to an existing rating stop being accepted - `emailDelivery?: CsatEmailDelivery` - `expiredAt?: string` ISO timestamp when the request expired - `lateSubmitWindowEndsAt?: string` ISO timestamp when first-time submissions stop being accepted - `ratedAgent?: CsatRatedAgent` - `ratedAt?: string` ISO timestamp when the request was rated - `remark?: string` Submitted remark when present - `score?: number` Submitted score when this request was rated - `workflow?: CsatWorkflowLink` - `csatSummary?: CsatSummary` Derived CSAT summary for this conversation when a rating request or rating exists. - `lastUpdatedAt: string` ISO timestamp when the summary last changed - `status: "pending" | "rated" | "canceled" | "expired"` Current summary status for CSAT on this conversation - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt?: string` ISO timestamp when the request was canceled - `channel?: "desktop" | "email"` Channel used for the latest CSAT request when known - `"desktop"` - `"email"` - `expiredAt?: string` ISO timestamp when the request expired - `ratedAgent?: CsatRatedAgent` - `ratedAt?: string` ISO timestamp when the customer submitted a rating - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the latest CSAT request was created - `requestId?: string` Canonical CSAT request ID - `requestSource?: "workflow"` Source of the latest CSAT request when known - `"workflow"` - `score?: number` CSAT score from 1 to 5 when rated - `workflow?: CsatWorkflowLink` - `disableCustomerReply?: boolean` Whether customer replies are disabled - `readReceipts?: Array` Read receipts indicating how far each participant has read in the conversation. Each receipt maps a user to their last-read conversation part. The tracked position reflects the system read state and may reference parts the user cannot directly view (e.g., a contact's read position may point to an internal admin note). Use these receipts to render read indicators and typing awareness, not to infer content access. - `id: string` The internal ID of the user - `lastReadPartId: string` The ID of the last conversation part this user has read. Note: This reflects the system-tracked read position and may reference a part the user cannot directly access (e.g., internal notes for contacts). The read state is advanced to the latest part in the conversation regardless of part visibility. - `userType: "admin" | "customer" | "lead"` Type of user who has read the conversation - `"admin"` - `"customer"` - `"lead"` - `source?: Source` - `bodyHtml: string` Body of the initial message as HTML with signed image URLs - `bodyMarkdown: string` Body of the initial message as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the conversation was initiated - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `author?: ConversationParticipant` - `id: string` Participant ID - `type: "customer" | "lead" | "admin" | 3 more` Type of participant - `deliveredAs?: "customer_initiated" | "admin_initiated"` How the conversation was initiated - `"customer_initiated"` - `"admin_initiated"` - `subject?: string` Subject line for email conversations - `url?: string` URL where the conversation was initiated - `title?: string` Conversation title ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); const conversation = await client.support.conversations.participants.add('12345', { participant: {}, }); console.log(conversation.id); ``` #### Response ```json { "id": "12345", "adminAssigneeId": "507f1f77bcf86cd799439011", "botConversationStateLastUpdatedAt": "2025-01-15T10:30:00.000Z", "brandId": "507f1f77bcf86cd799439011", "createdAt": "2025-01-15T10:30:00.000Z", "hasAdminOverriddenLanguage": false, "isBlocked": false, "lastActivityAt": "2025-01-15T12:30:00.000Z", "object": "conversation", "participants": [ { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" } ], "priority": false, "prioritySetAt": "2025-01-15T10:30:00.000Z", "snoozedUntil": "2025-01-16T09:00:00.000Z", "state": "open", "tags": [ { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } ], "teamAssigneeId": "507f1f77bcf86cd799439012", "updatedAt": "2025-01-15T12:30:00.000Z", "userPreferredLanguage": "en", "waitingSince": "2025-01-15T10:30:00.000Z", "awaitingCustomerReply": true, "botConversationState": "active", "conversationParts": [ { "id": "1", "bodyHtml": "

Hello, I have a question about your product.

", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ], "csatDebug": { "requestId": "csat_req_123", "status": "pending", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z" }, "csatHistory": [ { "channel": "desktop", "isLatestEffective": true, "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "status": "pending", "canceledAt": "2025-01-15T10:32:00.000Z", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "expiredAt": "2025-01-16T10:30:00.000Z", "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Thanks for the quick help.", "score": 4, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } } ], "csatSummary": { "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "status": "pending", "canceledAt": "2025-01-15T10:35:00.000Z", "channel": "desktop", "expiredAt": "2025-01-15T10:35:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Very helpful support.", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "score": 5, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } }, "disableCustomerReply": false, "readReceipts": [ { "id": "507f1f77bcf86cd799439011", "lastReadPartId": "8", "userType": "admin" } ], "source": { "bodyHtml": "

Hi, I have a question about your enterprise plan...

", "bodyMarkdown": "Hi, I have a question about your enterprise plan...", "channel": "desktop", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" }, "deliveredAs": "customer_initiated", "subject": "Question about pricing", "url": "https://example.com/pricing" }, "title": "Question about pricing" } ``` ## Remove a contact from a conversation `client.support.conversations.participants.remove(stringid, ParticipantRemoveParamsparams, RequestOptionsoptions?): Conversation` **delete** `/v2/conversations/{id}/participants` Removes a contact (customer or lead) from an existing conversation. **Note:** You cannot remove the last participant from a conversation. ### Path Parameters - `id` - The conversation ID (short ID) ### Request Body | Field | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------------------------------------- | | `id` | string | Yes | The Featurebase ID of the contact to remove (24-character ObjectId) | | `actingAdminId` | string | No | Admin ID performing the action (for attribution) | ### Response Returns the updated conversation object. ### Example Request ```json { "id": "676f0f6765bdaa7d7d760f88", "actingAdminId": "507f1f77bcf86cd799439011" } ``` ### Example Response ```json { "object": "conversation", "id": "12345", "participants": [ { "type": "customer", "id": "676f0f6765bdaa7d7d760f89" } ], ... } ``` ### Error Cases - **400 Bad Request** - Cannot remove the last participant from a conversation - **404 Not Found** - Conversation or contact not found in participants ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Parameters - `id: string` Conversation ID (short ID) - `params: ParticipantRemoveParams` - `id: string` Body param: The Featurebase ID of the contact (customer or lead) to remove - `actingAdminId?: string` Body param: The admin ID performing this action. If not provided, changes are attributed to the system bot user. - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` Header param: API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `Conversation` - `id: string` Unique conversation identifier - `adminAssigneeId: string | null` ID of the assigned admin - `botConversationStateLastUpdatedAt: string | null` ISO timestamp when bot state last changed - `brandId: string | null` ID of the brand associated with this conversation - `createdAt: string` ISO timestamp when conversation was created - `hasAdminOverriddenLanguage: boolean` Whether an admin has manually overridden the language for this conversation. When true, automatic language detection is disabled. - `isBlocked: boolean` Whether the user is blocked - `lastActivityAt: string | null` ISO timestamp of last activity - `object: "conversation"` Object type identifier - `"conversation"` - `participants: Array` Participants in this conversation - `id: string` Participant ID - `type: "customer" | "lead" | "admin" | 3 more` Type of participant - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `priority: boolean` Whether this conversation is marked as priority - `prioritySetAt: string | null` ISO timestamp when priority was set - `snoozedUntil: string | null` ISO timestamp until which conversation is snoozed - `state: "open" | "closed" | "snoozed"` Current state of the conversation - `"open"` - `"closed"` - `"snoozed"` - `tags: Array` Current tags applied anywhere in this conversation - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `teamAssigneeId: string | null` ID of the assigned team - `updatedAt: string` ISO timestamp when conversation was last updated - `userPreferredLanguage: string` User's preferred language - `waitingSince: string | null` ISO timestamp when conversation started waiting - `awaitingCustomerReply?: boolean` Whether we are awaiting a customer reply - `botConversationState?: "active" | "handed_off_to_human" | "resolved"` State of AI agent handling for this conversation - `"active"` - `"handed_off_to_human"` - `"resolved"` - `conversationParts?: Array` Array of conversation parts (messages). Only included when fetching a single conversation by ID. - `UserMessage` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `id: string | null` Author ID - `type: "customer" | "lead" | "admin" | 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email?: string` Author email address - `name?: string` Author display name - `profilePicture?: string | null` Author profile picture URL - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `AdminMessage` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string | null` Note body content as HTML with signed image URLs - `bodyMarkdown: string | null` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMessage` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string | null` Email body content as HTML with signed image URLs - `bodyMarkdown: string | null` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMessage` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string | null` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `channel?: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOptions` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: Array` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResponse` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT request payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt?: string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt?: string` ISO timestamp after which late submission is no longer allowed - `ratedAgent?: CsatRatedAgent` - `type: "teammate" | "fibi" | "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id?: string` Identifier of the rated agent when applicable - `workflow?: CsatWorkflowLink` - `workflowActionId?: string` Workflow action ID associated with the CSAT request - `workflowId?: string` Workflow ID associated with the CSAT request - `workflowRunId?: string` Workflow run ID associated with the CSAT request - `workflowStepId?: string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT submission payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent?: CsatRatedAgent` - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the request was created - `workflow?: CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttributeCollectionPrompt` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: Form` Form configuration - `id: string` Form ID - `attributes: Array` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttributeCollectionComplete` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assignment` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId?: string | null` ID of the admin assigned to the conversation - `adminAssignerId?: string | null` ID of the admin who made the assignment - `teamAssigneeId?: string | null` ID of the team assigned to the conversation - `StatusChange` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" | "closed" | "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil?: string | null` ISO timestamp until conversation is snoozed (if snoozed) - `TagUpdate` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" | "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor?: ConversationTagMutationActor` Actor that applied the tag - `tagName?: string | null` Tag name at the time of the event or the best available current display name - `targetPartId?: string | null` Conversation part that the tag mutation targeted - `WorkflowWaitEvent` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: WorkflowWait` Workflow wait event payload for this thread event - `eventType: "started" | "finished" | "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType?: "admin" | "customer" | "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel?: string` Human-readable wait duration or preset label - `workflowId?: string` Workflow ID associated with the wait event - `workflowName?: string` Workflow display name at the time of the wait event - `PriorityChange` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `ParticipantAdded` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: Participant` The added participant - `id: string` Participant ID - `type: "customer" | "lead" | "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated - `csatDebug?: CsatDebug` Minimal CSAT diagnostics for the current effective request. - `requestId: string` Canonical CSAT request ID used for the latest debug snapshot - `status: "pending" | "rated" | "canceled" | "expired"` Lifecycle status of the request represented in the debug snapshot - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp when rating edits stop being accepted - `emailDelivery?: CsatEmailDelivery` - `status: "pending" | "sent" | "failed"` Email delivery status for the CSAT request when applicable - `"pending"` - `"sent"` - `"failed"` - `failedAt?: string` ISO timestamp when the CSAT email failed - `failureReason?: string` Operational failure reason for the CSAT email delivery - `messageId?: string` Email message ID associated with delivery - `sentAt?: string` ISO timestamp when the CSAT email was sent - `lateSubmitWindowEndsAt?: string` ISO timestamp when first-time submissions stop being accepted - `csatHistory?: Array` Historical CSAT requests for this conversation, ordered newest first. - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `isLatestEffective: boolean` Whether this row represents the currently effective CSAT request for the conversation - `lastUpdatedAt: string` ISO timestamp when the request last changed - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Lifecycle status for this historical CSAT request - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt?: string` ISO timestamp when the request was canceled - `changeLockWindowEndsAt?: string` ISO timestamp when edits to an existing rating stop being accepted - `emailDelivery?: CsatEmailDelivery` - `expiredAt?: string` ISO timestamp when the request expired - `lateSubmitWindowEndsAt?: string` ISO timestamp when first-time submissions stop being accepted - `ratedAgent?: CsatRatedAgent` - `ratedAt?: string` ISO timestamp when the request was rated - `remark?: string` Submitted remark when present - `score?: number` Submitted score when this request was rated - `workflow?: CsatWorkflowLink` - `csatSummary?: CsatSummary` Derived CSAT summary for this conversation when a rating request or rating exists. - `lastUpdatedAt: string` ISO timestamp when the summary last changed - `status: "pending" | "rated" | "canceled" | "expired"` Current summary status for CSAT on this conversation - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt?: string` ISO timestamp when the request was canceled - `channel?: "desktop" | "email"` Channel used for the latest CSAT request when known - `"desktop"` - `"email"` - `expiredAt?: string` ISO timestamp when the request expired - `ratedAgent?: CsatRatedAgent` - `ratedAt?: string` ISO timestamp when the customer submitted a rating - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the latest CSAT request was created - `requestId?: string` Canonical CSAT request ID - `requestSource?: "workflow"` Source of the latest CSAT request when known - `"workflow"` - `score?: number` CSAT score from 1 to 5 when rated - `workflow?: CsatWorkflowLink` - `disableCustomerReply?: boolean` Whether customer replies are disabled - `readReceipts?: Array` Read receipts indicating how far each participant has read in the conversation. Each receipt maps a user to their last-read conversation part. The tracked position reflects the system read state and may reference parts the user cannot directly view (e.g., a contact's read position may point to an internal admin note). Use these receipts to render read indicators and typing awareness, not to infer content access. - `id: string` The internal ID of the user - `lastReadPartId: string` The ID of the last conversation part this user has read. Note: This reflects the system-tracked read position and may reference a part the user cannot directly access (e.g., internal notes for contacts). The read state is advanced to the latest part in the conversation regardless of part visibility. - `userType: "admin" | "customer" | "lead"` Type of user who has read the conversation - `"admin"` - `"customer"` - `"lead"` - `source?: Source` - `bodyHtml: string` Body of the initial message as HTML with signed image URLs - `bodyMarkdown: string` Body of the initial message as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the conversation was initiated - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `author?: ConversationParticipant` - `id: string` Participant ID - `type: "customer" | "lead" | "admin" | 3 more` Type of participant - `deliveredAs?: "customer_initiated" | "admin_initiated"` How the conversation was initiated - `"customer_initiated"` - `"admin_initiated"` - `subject?: string` Subject line for email conversations - `url?: string` URL where the conversation was initiated - `title?: string` Conversation title ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); const conversation = await client.support.conversations.participants.remove('12345', { id: '676f0f6765bdaa7d7d760f88', }); console.log(conversation.id); ``` #### Response ```json { "id": "12345", "adminAssigneeId": "507f1f77bcf86cd799439011", "botConversationStateLastUpdatedAt": "2025-01-15T10:30:00.000Z", "brandId": "507f1f77bcf86cd799439011", "createdAt": "2025-01-15T10:30:00.000Z", "hasAdminOverriddenLanguage": false, "isBlocked": false, "lastActivityAt": "2025-01-15T12:30:00.000Z", "object": "conversation", "participants": [ { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" } ], "priority": false, "prioritySetAt": "2025-01-15T10:30:00.000Z", "snoozedUntil": "2025-01-16T09:00:00.000Z", "state": "open", "tags": [ { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } ], "teamAssigneeId": "507f1f77bcf86cd799439012", "updatedAt": "2025-01-15T12:30:00.000Z", "userPreferredLanguage": "en", "waitingSince": "2025-01-15T10:30:00.000Z", "awaitingCustomerReply": true, "botConversationState": "active", "conversationParts": [ { "id": "1", "bodyHtml": "

Hello, I have a question about your product.

", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ], "csatDebug": { "requestId": "csat_req_123", "status": "pending", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z" }, "csatHistory": [ { "channel": "desktop", "isLatestEffective": true, "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "status": "pending", "canceledAt": "2025-01-15T10:32:00.000Z", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "expiredAt": "2025-01-16T10:30:00.000Z", "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Thanks for the quick help.", "score": 4, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } } ], "csatSummary": { "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "status": "pending", "canceledAt": "2025-01-15T10:35:00.000Z", "channel": "desktop", "expiredAt": "2025-01-15T10:35:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Very helpful support.", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "score": 5, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } }, "disableCustomerReply": false, "readReceipts": [ { "id": "507f1f77bcf86cd799439011", "lastReadPartId": "8", "userType": "admin" } ], "source": { "bodyHtml": "

Hi, I have a question about your enterprise plan...

", "bodyMarkdown": "Hi, I have a question about your enterprise plan...", "channel": "desktop", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" }, "deliveredAs": "customer_initiated", "subject": "Question about pricing", "url": "https://example.com/pricing" }, "title": "Question about pricing" } ``` # Conversation Tags ## List workspace tags `client.support.conversationTags.list(ConversationTagListParamsparams?, RequestOptionsoptions?): ConversationTagListResponse` **get** `/v2/tags` Returns the live conversation tags available in the workspace tag catalog. These are the canonical tags that power conversation payloads, filters, and tag mutation endpoints. ### Parameters - `params: ConversationTagListParams` - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `ConversationTagListResponse` - `data: Array` Array containing the actual response elements - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `nextCursor: string | null` Cursor to use for fetching the next page. Null if there are no more results. - `object: "list"` String representing the object type - `"list"` ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); const conversationTags = await client.support.conversationTags.list(); console.log(conversationTags.data); ``` #### Response ```json { "data": [ { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } ], "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9", "object": "list" } ``` ## Create or rename a tag `client.support.conversationTags.createOrRename(ConversationTagCreateOrRenameParamsparams, RequestOptionsoptions?): ConversationTag` **post** `/v2/tags` Creates a new workspace conversation tag when only `name` is provided. If `id` is also provided, the existing tag is renamed instead. ### Parameters - `params: ConversationTagCreateOrRenameParams` - `name: string` Body param: Tag name - `id?: string` Body param: Optional existing tag ID. Provide this to rename an existing tag instead of creating a new one. - `actingAdminId?: string` Body param: Optional admin ID for actor attribution and permission checks. - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` Header param: API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `ConversationTag` - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); const conversationTag = await client.support.conversationTags.createOrRename({ name: 'Churn' }); console.log(conversationTag.id); ``` #### Response ```json { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } ``` ## Get tag by ID `client.support.conversationTags.retrieve(stringid, ConversationTagRetrieveParamsparams?, RequestOptionsoptions?): ConversationTag` **get** `/v2/tags/{id}` Returns a single conversation tag by its Featurebase tag ID. Archived tags can still be retrieved directly by ID, while permanently deleted tags return `404`. ### Parameters - `id: string` The Featurebase tag ID - `params: ConversationTagRetrieveParams` - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `ConversationTag` - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); const conversationTag = await client.support.conversationTags.retrieve('67ec1234abcd5678ef901234'); console.log(conversationTag.id); ``` #### Response ```json { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } ``` ## Delete a tag `client.support.conversationTags.delete(stringid, ConversationTagDeleteParamsparams?, RequestOptionsoptions?): ConversationTagDeleteResponse` **delete** `/v2/tags/{id}` Deletes a conversation tag from the workspace catalog and removes it from aggregate conversation tag state. Archived and historical part applications remain part of the audit trail where applicable. ### Parameters - `id: string` The Featurebase tag ID - `params: ConversationTagDeleteParams` - `actingAdminId?: string` Body param: Optional admin ID for actor attribution and permission checks. - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` Header param: API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `ConversationTagDeleteResponse` - `id: string` Unique tag identifier - `deleted: true` Whether the tag has been deleted - `true` - `object: "tag"` Object type identifier - `"tag"` ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); const conversationTag = await client.support.conversationTags.delete('67ec1234abcd5678ef901234'); console.log(conversationTag.id); ``` #### Response ```json { "id": "67ec1234abcd5678ef901234", "deleted": true, "object": "tag" } ``` ## Domain Types ### Conversation Tag - `ConversationTag` - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` ### Conversation Tag List Response - `ConversationTagListResponse` - `data: Array` Array containing the actual response elements - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `nextCursor: string | null` Cursor to use for fetching the next page. Null if there are no more results. - `object: "list"` String representing the object type - `"list"` ### Conversation Tag Delete Response - `ConversationTagDeleteResponse` - `id: string` Unique tag identifier - `deleted: true` Whether the tag has been deleted - `true` - `object: "tag"` Object type identifier - `"tag"` # Tickets ## List tickets `client.support.tickets.list(TicketListParamsparams?, RequestOptionsoptions?): CursorPage` **get** `/v2/tickets` Returns a list of tickets in your organization using cursor-based pagination. ### Query Parameters | Parameter | Type | Description | | ------------------- | -------- | ---------------------------------------------------------------- | | `limit` | number | Number of tickets to return (1-100, default 10) | | `cursor` | string | Cursor from previous response for pagination | | `ticketCategoryIds` | string[] | Filter by ticket category IDs | | `statusIds` | string[] | Filter by status IDs | | `q` | string | Search query | | `assigneeId` | string | Filter by assignee ID | | `categoryType` | string | Filter by category type: "customer", "tracker", or "back-office" | | `sortBy` | string | Sort field: "date" (default), "recent", or "ticketNumber" | | `sortOrder` | string | Sort direction: "asc" or "desc" (default) | ### Response Returns a list object with `data` (array of ticket objects) and `nextCursor`. ### Parameters - `params: TicketListParams` - `assigneeId?: string` Query param - `categoryType?: "customer" | "tracker" | "back-office"` Query param - `"customer"` - `"tracker"` - `"back-office"` - `cursor?: string` Query param: An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page of results. - `limit?: number` Query param - `q?: string` Query param - `sortBy?: "date" | "recent" | "ticketNumber"` Query param - `"date"` - `"recent"` - `"ticketNumber"` - `sortOrder?: "asc" | "desc"` Query param - `"asc"` - `"desc"` - `statusIds?: Array` Query param - `ticketCategoryIds?: Array` Query param - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` Header param: API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `Ticket` - `id: string` Unique identifier (MongoDB ID) - `assigneeId: string | null` Assigned admin ID - `author: Author | null` Contact who created the ticket - `id: string | null` Author unique identifier - `email: string | null` Author email - `name: string` Author display name - `profilePicture: string | null` Author profile picture URL - `type: "admin" | "customer" | "guest" | 3 more` Type of user - `"admin"` - `"customer"` - `"guest"` - `"integration"` - `"bot"` - `"lead"` - `categoryType: "customer" | "tracker" | "back-office"` Ticket category type - `"customer"` - `"tracker"` - `"back-office"` - `companyId: string | null` Associated company ID - `content: string` Ticket content/description (HTML) - `createdAt: string` ISO 8601 creation timestamp - `customFields: Record` Custom field values keyed by field ID. File-type fields contain a JSON string of { key, name, url } with a signed download URL (1 hour expiry). For allowMultiple file fields, the value is a JSON string of an array of these objects. - `integrations: Integrations` Third-party integration links - `clickup: Array` - `id: string` ClickUp task ID - `title: string` ClickUp task title - `url: string` URL to the ClickUp task - `devops: Array` - `id: number` Azure DevOps work item ID - `projectId: string` Azure DevOps project ID - `projectName: string` Azure DevOps project name - `title: string` Work item title - `url: string` URL to the work item - `github: Array` - `id: string` GitHub issue ID - `number: string` GitHub issue number - `repositoryFullName: string` Full repository name (owner/repo) - `repositoryName: string` Repository name - `title: string` GitHub issue title - `url: string` URL to the GitHub issue - `hubspot: Array` - `dealAmount: number | null` Deal amount (for DEAL type) - `dealClosed: boolean | null` Whether the deal is closed (for DEAL type) - `objectId: number` HubSpot object ID - `type: "TICKET" | "DEAL" | "CONTACT"` HubSpot object type - `"TICKET"` - `"DEAL"` - `"CONTACT"` - `jira: Array` - `issueId: string` Jira issue ID - `issueUrl: string | null` URL to the Jira issue - `linear: Array` - `issueId: string` Linear issue ID - `issueUrl: string | null` URL to the Linear issue - `linkedConversations: Array` Linked conversations - `id: string` Conversation ID - `role: "customer" | "tracker" | "back-office"` Link role - `"customer"` - `"tracker"` - `"back-office"` - `object: "ticket"` Object type identifier - `"ticket"` - `open: boolean` Whether the ticket is open - `snoozedUntil: string | null` ISO 8601 timestamp until snoozed (from linked conversation) - `status: PostStatus` Current ticket status - `id: string` Unique identifier - `color: string` Color for UI display - `isDefault: boolean` Whether this is the default status for new posts - `name: string` Display name - `object: "post_status"` Object type identifier - `"post_status"` - `type: "reviewing" | "unstarted" | "active" | 2 more` The workflow stage this status represents - `"reviewing"` - `"unstarted"` - `"active"` - `"completed"` - `"canceled"` - `teamAssigneeId: string | null` Assigned team ID (from linked conversation) - `ticketCategoryId: string` Ticket category ID - `ticketNumber: number` Sequential display ID (e.g. TK-42) - `ticketUrl: string` Full URL to view the ticket - `title: string` Ticket title - `updatedAt: string` ISO 8601 last updated timestamp - `conversationParts?: Array` Conversation message history. Only included when fetching a single ticket by ID. - `UserMessage` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `id: string | null` Author ID - `type: "customer" | "lead" | "admin" | 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email?: string` Author email address - `name?: string` Author display name - `profilePicture?: string | null` Author profile picture URL - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `AdminMessage` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string | null` Note body content as HTML with signed image URLs - `bodyMarkdown: string | null` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMessage` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string | null` Email body content as HTML with signed image URLs - `bodyMarkdown: string | null` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMessage` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string | null` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `channel?: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOptions` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: Array` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResponse` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT request payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt?: string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt?: string` ISO timestamp after which late submission is no longer allowed - `ratedAgent?: CsatRatedAgent` - `type: "teammate" | "fibi" | "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id?: string` Identifier of the rated agent when applicable - `workflow?: CsatWorkflowLink` - `workflowActionId?: string` Workflow action ID associated with the CSAT request - `workflowId?: string` Workflow ID associated with the CSAT request - `workflowRunId?: string` Workflow run ID associated with the CSAT request - `workflowStepId?: string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT submission payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent?: CsatRatedAgent` - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the request was created - `workflow?: CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttributeCollectionPrompt` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: Form` Form configuration - `id: string` Form ID - `attributes: Array` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttributeCollectionComplete` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assignment` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId?: string | null` ID of the admin assigned to the conversation - `adminAssignerId?: string | null` ID of the admin who made the assignment - `teamAssigneeId?: string | null` ID of the team assigned to the conversation - `StatusChange` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" | "closed" | "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil?: string | null` ISO timestamp until conversation is snoozed (if snoozed) - `TagUpdate` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" | "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor?: ConversationTagMutationActor` Actor that applied the tag - `tagName?: string | null` Tag name at the time of the event or the best available current display name - `targetPartId?: string | null` Conversation part that the tag mutation targeted - `WorkflowWaitEvent` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: WorkflowWait` Workflow wait event payload for this thread event - `eventType: "started" | "finished" | "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType?: "admin" | "customer" | "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel?: string` Human-readable wait duration or preset label - `workflowId?: string` Workflow ID associated with the wait event - `workflowName?: string` Workflow display name at the time of the wait event - `PriorityChange` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `ParticipantAdded` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: Participant` The added participant - `id: string` Participant ID - `type: "customer" | "lead" | "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const ticket of client.support.tickets.list()) { console.log(ticket.id); } ``` #### Response ```json { "data": [ { "id": "507f1f77bcf86cd799439011", "assigneeId": "507f1f77bcf86cd799439013", "author": { "id": "507f1f77bcf86cd799439011", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/john.png", "type": "customer" }, "categoryType": "customer", "companyId": "507f1f77bcf86cd799439015", "content": "

I get a 403 error when logging in.

", "createdAt": "2025-01-15T10:30:00.000Z", "customFields": { "priority": "bar", "507f1f77bcf86cd799439099": "bar" }, "integrations": { "clickup": [ { "id": "86a1b2c3d", "title": "Fix login bug", "url": "https://app.clickup.com/t/86a1b2c3d" } ], "devops": [ { "id": 789, "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "projectName": "My Project", "title": "Implement SSO", "url": "https://dev.azure.com/org/project/_workitems/edit/789" } ], "github": [ { "id": "1234567890", "number": "42", "repositoryFullName": "acme/frontend", "repositoryName": "frontend", "title": "Login page returns 403", "url": "https://github.com/acme/frontend/issues/42" } ], "hubspot": [ { "dealAmount": 5000, "dealClosed": false, "objectId": 12345, "type": "DEAL" } ], "jira": [ { "issueId": "PROJ-456", "issueUrl": "https://company.atlassian.net/browse/PROJ-456" } ], "linear": [ { "issueId": "LIN-123", "issueUrl": "https://linear.app/team/issue/LIN-123" } ] }, "linkedConversations": [ { "id": "507f1f77bcf86cd799439011", "role": "customer" } ], "object": "ticket", "open": true, "snoozedUntil": "2025-01-16T09:00:00.000Z", "status": { "id": "507f1f77bcf86cd799439011", "color": "Blue", "isDefault": false, "name": "In Progress", "object": "post_status", "type": "active" }, "teamAssigneeId": "507f1f77bcf86cd799439014", "ticketCategoryId": "507f1f77bcf86cd799439011", "ticketNumber": 42, "ticketUrl": "https://feedback.example.com/p/cannot-login", "title": "Cannot login to dashboard", "updatedAt": "2025-01-15T12:30:00.000Z", "conversationParts": [ { "id": "1", "bodyHtml": "

Hello, I have a question about your product.

", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ] } ], "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9", "object": "list" } ``` ## Create a ticket `client.support.tickets.create(TicketCreateParamsparams, RequestOptionsoptions?): Ticket` **post** `/v2/tickets` Creates a new ticket. ### Required Fields | Field | Type | Description | | ------------------ | ------ | ------------------------------------------------------------- | | `ticketCategoryId` | string | Ticket category ID | | `title` | string | Ticket title (min 2 characters) | | `author` | object | Author/contact info (id, userId, email, name, profilePicture) | ### Optional Fields | Field | Type | Description | | ---------------------- | ------- | ------------------------------------------ | | `content` | string | Ticket description (HTML) | | `customFields` | object | Custom field values | | `companyId` | string | Company to associate | | `linkedConversationId` | string | Conversation to link | | `assigneeId` | string | Admin to assign | | `statusId` | string | Initial status | | `createdAt` | string | ISO 8601 timestamp for backdating | | `skipNotifications` | boolean | Skip sending notifications (default false) | ### File Custom Fields File-type custom fields can be provided in two ways: **Method 1: Multipart upload** — Send the request as `multipart/form-data`. Put the JSON body in a field named `data`, and attach files with field names like `customFields.`. For `allowMultiple` fields, send multiple files with the same field name. **Method 2: External URL** — In the JSON body, set the file custom field value to `{ "url": "https://..." }`. Optionally include `"name"` to set the filename (e.g. `{ "url": "https://...", "name": "report.pdf" }`); if omitted, the filename is extracted from the download response. For `allowMultiple` fields, use an array: `[{ "url": "..." }, ...]`. The server downloads the file (max 10MB, HTTPS only) and stores it. Both methods produce signed download URLs in the response. **Limits:** Max 10 files per request, 400MB total upload size. Executable file types (.exe, .bat, .js, .sh, etc.) are blocked. **Response format:** File custom field values in the response are JSON strings containing `{ "key": "...", "name": "...", "url": "https://signed-url..." }`. For `allowMultiple` fields, an array of these objects. The `url` is a time-limited signed download URL (expires in 1 hour). ### Response Returns the created ticket object with **201 Created** status. ### Parameters - `params: TicketCreateParams` - `author: AuthorInput` Body param: Author to attribute the post to. If not provided, uses the authenticated user. Supports multiple identification methods: id (Featurebase ID), userId (external SSO ID), or email. - `id?: string` Featurebase user ID to attribute content to - `email?: string` Author email (used to find or create user) - `name?: string` Author display name - `profilePicture?: string` Author profile picture URL - `userId?: string` External user ID from your system (matched via SSO) - `ticketCategoryId: string` Body param - `title: string` Body param - `assigneeId?: string` Body param - `companyId?: string` Body param - `content?: string` Body param - `createdAt?: string | null` Body param - `customFields?: Record` Body param - `linkedConversationId?: string` Body param - `skipNotifications?: boolean` Body param - `statusId?: string` Body param - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` Header param: API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `Ticket` - `id: string` Unique identifier (MongoDB ID) - `assigneeId: string | null` Assigned admin ID - `author: Author | null` Contact who created the ticket - `id: string | null` Author unique identifier - `email: string | null` Author email - `name: string` Author display name - `profilePicture: string | null` Author profile picture URL - `type: "admin" | "customer" | "guest" | 3 more` Type of user - `"admin"` - `"customer"` - `"guest"` - `"integration"` - `"bot"` - `"lead"` - `categoryType: "customer" | "tracker" | "back-office"` Ticket category type - `"customer"` - `"tracker"` - `"back-office"` - `companyId: string | null` Associated company ID - `content: string` Ticket content/description (HTML) - `createdAt: string` ISO 8601 creation timestamp - `customFields: Record` Custom field values keyed by field ID. File-type fields contain a JSON string of { key, name, url } with a signed download URL (1 hour expiry). For allowMultiple file fields, the value is a JSON string of an array of these objects. - `integrations: Integrations` Third-party integration links - `clickup: Array` - `id: string` ClickUp task ID - `title: string` ClickUp task title - `url: string` URL to the ClickUp task - `devops: Array` - `id: number` Azure DevOps work item ID - `projectId: string` Azure DevOps project ID - `projectName: string` Azure DevOps project name - `title: string` Work item title - `url: string` URL to the work item - `github: Array` - `id: string` GitHub issue ID - `number: string` GitHub issue number - `repositoryFullName: string` Full repository name (owner/repo) - `repositoryName: string` Repository name - `title: string` GitHub issue title - `url: string` URL to the GitHub issue - `hubspot: Array` - `dealAmount: number | null` Deal amount (for DEAL type) - `dealClosed: boolean | null` Whether the deal is closed (for DEAL type) - `objectId: number` HubSpot object ID - `type: "TICKET" | "DEAL" | "CONTACT"` HubSpot object type - `"TICKET"` - `"DEAL"` - `"CONTACT"` - `jira: Array` - `issueId: string` Jira issue ID - `issueUrl: string | null` URL to the Jira issue - `linear: Array` - `issueId: string` Linear issue ID - `issueUrl: string | null` URL to the Linear issue - `linkedConversations: Array` Linked conversations - `id: string` Conversation ID - `role: "customer" | "tracker" | "back-office"` Link role - `"customer"` - `"tracker"` - `"back-office"` - `object: "ticket"` Object type identifier - `"ticket"` - `open: boolean` Whether the ticket is open - `snoozedUntil: string | null` ISO 8601 timestamp until snoozed (from linked conversation) - `status: PostStatus` Current ticket status - `id: string` Unique identifier - `color: string` Color for UI display - `isDefault: boolean` Whether this is the default status for new posts - `name: string` Display name - `object: "post_status"` Object type identifier - `"post_status"` - `type: "reviewing" | "unstarted" | "active" | 2 more` The workflow stage this status represents - `"reviewing"` - `"unstarted"` - `"active"` - `"completed"` - `"canceled"` - `teamAssigneeId: string | null` Assigned team ID (from linked conversation) - `ticketCategoryId: string` Ticket category ID - `ticketNumber: number` Sequential display ID (e.g. TK-42) - `ticketUrl: string` Full URL to view the ticket - `title: string` Ticket title - `updatedAt: string` ISO 8601 last updated timestamp - `conversationParts?: Array` Conversation message history. Only included when fetching a single ticket by ID. - `UserMessage` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `id: string | null` Author ID - `type: "customer" | "lead" | "admin" | 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email?: string` Author email address - `name?: string` Author display name - `profilePicture?: string | null` Author profile picture URL - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `AdminMessage` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string | null` Note body content as HTML with signed image URLs - `bodyMarkdown: string | null` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMessage` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string | null` Email body content as HTML with signed image URLs - `bodyMarkdown: string | null` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMessage` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string | null` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `channel?: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOptions` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: Array` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResponse` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT request payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt?: string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt?: string` ISO timestamp after which late submission is no longer allowed - `ratedAgent?: CsatRatedAgent` - `type: "teammate" | "fibi" | "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id?: string` Identifier of the rated agent when applicable - `workflow?: CsatWorkflowLink` - `workflowActionId?: string` Workflow action ID associated with the CSAT request - `workflowId?: string` Workflow ID associated with the CSAT request - `workflowRunId?: string` Workflow run ID associated with the CSAT request - `workflowStepId?: string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT submission payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent?: CsatRatedAgent` - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the request was created - `workflow?: CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttributeCollectionPrompt` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: Form` Form configuration - `id: string` Form ID - `attributes: Array` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttributeCollectionComplete` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assignment` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId?: string | null` ID of the admin assigned to the conversation - `adminAssignerId?: string | null` ID of the admin who made the assignment - `teamAssigneeId?: string | null` ID of the team assigned to the conversation - `StatusChange` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" | "closed" | "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil?: string | null` ISO timestamp until conversation is snoozed (if snoozed) - `TagUpdate` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" | "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor?: ConversationTagMutationActor` Actor that applied the tag - `tagName?: string | null` Tag name at the time of the event or the best available current display name - `targetPartId?: string | null` Conversation part that the tag mutation targeted - `WorkflowWaitEvent` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: WorkflowWait` Workflow wait event payload for this thread event - `eventType: "started" | "finished" | "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType?: "admin" | "customer" | "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel?: string` Human-readable wait duration or preset label - `workflowId?: string` Workflow ID associated with the wait event - `workflowName?: string` Workflow display name at the time of the wait event - `PriorityChange` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `ParticipantAdded` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: Participant` The added participant - `id: string` Participant ID - `type: "customer" | "lead" | "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); const ticket = await client.support.tickets.create({ author: {}, ticketCategoryId: '507f1f77bcf86cd799439011', title: 'Cannot login to dashboard', }); console.log(ticket.id); ``` #### Response ```json { "id": "507f1f77bcf86cd799439011", "assigneeId": "507f1f77bcf86cd799439013", "author": { "id": "507f1f77bcf86cd799439011", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/john.png", "type": "customer" }, "categoryType": "customer", "companyId": "507f1f77bcf86cd799439015", "content": "

I get a 403 error when logging in.

", "createdAt": "2025-01-15T10:30:00.000Z", "customFields": { "priority": "bar", "507f1f77bcf86cd799439099": "bar" }, "integrations": { "clickup": [ { "id": "86a1b2c3d", "title": "Fix login bug", "url": "https://app.clickup.com/t/86a1b2c3d" } ], "devops": [ { "id": 789, "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "projectName": "My Project", "title": "Implement SSO", "url": "https://dev.azure.com/org/project/_workitems/edit/789" } ], "github": [ { "id": "1234567890", "number": "42", "repositoryFullName": "acme/frontend", "repositoryName": "frontend", "title": "Login page returns 403", "url": "https://github.com/acme/frontend/issues/42" } ], "hubspot": [ { "dealAmount": 5000, "dealClosed": false, "objectId": 12345, "type": "DEAL" } ], "jira": [ { "issueId": "PROJ-456", "issueUrl": "https://company.atlassian.net/browse/PROJ-456" } ], "linear": [ { "issueId": "LIN-123", "issueUrl": "https://linear.app/team/issue/LIN-123" } ] }, "linkedConversations": [ { "id": "507f1f77bcf86cd799439011", "role": "customer" } ], "object": "ticket", "open": true, "snoozedUntil": "2025-01-16T09:00:00.000Z", "status": { "id": "507f1f77bcf86cd799439011", "color": "Blue", "isDefault": false, "name": "In Progress", "object": "post_status", "type": "active" }, "teamAssigneeId": "507f1f77bcf86cd799439014", "ticketCategoryId": "507f1f77bcf86cd799439011", "ticketNumber": 42, "ticketUrl": "https://feedback.example.com/p/cannot-login", "title": "Cannot login to dashboard", "updatedAt": "2025-01-15T12:30:00.000Z", "conversationParts": [ { "id": "1", "bodyHtml": "

Hello, I have a question about your product.

", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ] } ``` ## Get a ticket `client.support.tickets.retrieve(numberid, TicketRetrieveParamsparams?, RequestOptionsoptions?): Ticket` **get** `/v2/tickets/{id}` Retrieves a single ticket by its ticket number. ### Path Parameters - `id` - The ticket number (e.g. 42 from TK-42) ### Response Returns the ticket object, including `conversationParts` from the linked conversation (message history). ### Parameters - `id: number` - `params: TicketRetrieveParams` - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `Ticket` - `id: string` Unique identifier (MongoDB ID) - `assigneeId: string | null` Assigned admin ID - `author: Author | null` Contact who created the ticket - `id: string | null` Author unique identifier - `email: string | null` Author email - `name: string` Author display name - `profilePicture: string | null` Author profile picture URL - `type: "admin" | "customer" | "guest" | 3 more` Type of user - `"admin"` - `"customer"` - `"guest"` - `"integration"` - `"bot"` - `"lead"` - `categoryType: "customer" | "tracker" | "back-office"` Ticket category type - `"customer"` - `"tracker"` - `"back-office"` - `companyId: string | null` Associated company ID - `content: string` Ticket content/description (HTML) - `createdAt: string` ISO 8601 creation timestamp - `customFields: Record` Custom field values keyed by field ID. File-type fields contain a JSON string of { key, name, url } with a signed download URL (1 hour expiry). For allowMultiple file fields, the value is a JSON string of an array of these objects. - `integrations: Integrations` Third-party integration links - `clickup: Array` - `id: string` ClickUp task ID - `title: string` ClickUp task title - `url: string` URL to the ClickUp task - `devops: Array` - `id: number` Azure DevOps work item ID - `projectId: string` Azure DevOps project ID - `projectName: string` Azure DevOps project name - `title: string` Work item title - `url: string` URL to the work item - `github: Array` - `id: string` GitHub issue ID - `number: string` GitHub issue number - `repositoryFullName: string` Full repository name (owner/repo) - `repositoryName: string` Repository name - `title: string` GitHub issue title - `url: string` URL to the GitHub issue - `hubspot: Array` - `dealAmount: number | null` Deal amount (for DEAL type) - `dealClosed: boolean | null` Whether the deal is closed (for DEAL type) - `objectId: number` HubSpot object ID - `type: "TICKET" | "DEAL" | "CONTACT"` HubSpot object type - `"TICKET"` - `"DEAL"` - `"CONTACT"` - `jira: Array` - `issueId: string` Jira issue ID - `issueUrl: string | null` URL to the Jira issue - `linear: Array` - `issueId: string` Linear issue ID - `issueUrl: string | null` URL to the Linear issue - `linkedConversations: Array` Linked conversations - `id: string` Conversation ID - `role: "customer" | "tracker" | "back-office"` Link role - `"customer"` - `"tracker"` - `"back-office"` - `object: "ticket"` Object type identifier - `"ticket"` - `open: boolean` Whether the ticket is open - `snoozedUntil: string | null` ISO 8601 timestamp until snoozed (from linked conversation) - `status: PostStatus` Current ticket status - `id: string` Unique identifier - `color: string` Color for UI display - `isDefault: boolean` Whether this is the default status for new posts - `name: string` Display name - `object: "post_status"` Object type identifier - `"post_status"` - `type: "reviewing" | "unstarted" | "active" | 2 more` The workflow stage this status represents - `"reviewing"` - `"unstarted"` - `"active"` - `"completed"` - `"canceled"` - `teamAssigneeId: string | null` Assigned team ID (from linked conversation) - `ticketCategoryId: string` Ticket category ID - `ticketNumber: number` Sequential display ID (e.g. TK-42) - `ticketUrl: string` Full URL to view the ticket - `title: string` Ticket title - `updatedAt: string` ISO 8601 last updated timestamp - `conversationParts?: Array` Conversation message history. Only included when fetching a single ticket by ID. - `UserMessage` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `id: string | null` Author ID - `type: "customer" | "lead" | "admin" | 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email?: string` Author email address - `name?: string` Author display name - `profilePicture?: string | null` Author profile picture URL - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `AdminMessage` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string | null` Note body content as HTML with signed image URLs - `bodyMarkdown: string | null` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMessage` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string | null` Email body content as HTML with signed image URLs - `bodyMarkdown: string | null` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMessage` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string | null` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `channel?: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOptions` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: Array` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResponse` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT request payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt?: string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt?: string` ISO timestamp after which late submission is no longer allowed - `ratedAgent?: CsatRatedAgent` - `type: "teammate" | "fibi" | "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id?: string` Identifier of the rated agent when applicable - `workflow?: CsatWorkflowLink` - `workflowActionId?: string` Workflow action ID associated with the CSAT request - `workflowId?: string` Workflow ID associated with the CSAT request - `workflowRunId?: string` Workflow run ID associated with the CSAT request - `workflowStepId?: string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT submission payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent?: CsatRatedAgent` - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the request was created - `workflow?: CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttributeCollectionPrompt` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: Form` Form configuration - `id: string` Form ID - `attributes: Array` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttributeCollectionComplete` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assignment` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId?: string | null` ID of the admin assigned to the conversation - `adminAssignerId?: string | null` ID of the admin who made the assignment - `teamAssigneeId?: string | null` ID of the team assigned to the conversation - `StatusChange` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" | "closed" | "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil?: string | null` ISO timestamp until conversation is snoozed (if snoozed) - `TagUpdate` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" | "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor?: ConversationTagMutationActor` Actor that applied the tag - `tagName?: string | null` Tag name at the time of the event or the best available current display name - `targetPartId?: string | null` Conversation part that the tag mutation targeted - `WorkflowWaitEvent` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: WorkflowWait` Workflow wait event payload for this thread event - `eventType: "started" | "finished" | "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType?: "admin" | "customer" | "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel?: string` Human-readable wait duration or preset label - `workflowId?: string` Workflow ID associated with the wait event - `workflowName?: string` Workflow display name at the time of the wait event - `PriorityChange` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `ParticipantAdded` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: Participant` The added participant - `id: string` Participant ID - `type: "customer" | "lead" | "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); const ticket = await client.support.tickets.retrieve(1); console.log(ticket.id); ``` #### Response ```json { "id": "507f1f77bcf86cd799439011", "assigneeId": "507f1f77bcf86cd799439013", "author": { "id": "507f1f77bcf86cd799439011", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/john.png", "type": "customer" }, "categoryType": "customer", "companyId": "507f1f77bcf86cd799439015", "content": "

I get a 403 error when logging in.

", "createdAt": "2025-01-15T10:30:00.000Z", "customFields": { "priority": "bar", "507f1f77bcf86cd799439099": "bar" }, "integrations": { "clickup": [ { "id": "86a1b2c3d", "title": "Fix login bug", "url": "https://app.clickup.com/t/86a1b2c3d" } ], "devops": [ { "id": 789, "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "projectName": "My Project", "title": "Implement SSO", "url": "https://dev.azure.com/org/project/_workitems/edit/789" } ], "github": [ { "id": "1234567890", "number": "42", "repositoryFullName": "acme/frontend", "repositoryName": "frontend", "title": "Login page returns 403", "url": "https://github.com/acme/frontend/issues/42" } ], "hubspot": [ { "dealAmount": 5000, "dealClosed": false, "objectId": 12345, "type": "DEAL" } ], "jira": [ { "issueId": "PROJ-456", "issueUrl": "https://company.atlassian.net/browse/PROJ-456" } ], "linear": [ { "issueId": "LIN-123", "issueUrl": "https://linear.app/team/issue/LIN-123" } ] }, "linkedConversations": [ { "id": "507f1f77bcf86cd799439011", "role": "customer" } ], "object": "ticket", "open": true, "snoozedUntil": "2025-01-16T09:00:00.000Z", "status": { "id": "507f1f77bcf86cd799439011", "color": "Blue", "isDefault": false, "name": "In Progress", "object": "post_status", "type": "active" }, "teamAssigneeId": "507f1f77bcf86cd799439014", "ticketCategoryId": "507f1f77bcf86cd799439011", "ticketNumber": 42, "ticketUrl": "https://feedback.example.com/p/cannot-login", "title": "Cannot login to dashboard", "updatedAt": "2025-01-15T12:30:00.000Z", "conversationParts": [ { "id": "1", "bodyHtml": "

Hello, I have a question about your product.

", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ] } ``` ## Update a ticket `client.support.tickets.update(numberid, TicketUpdateParamsparams, RequestOptionsoptions?): Ticket` **patch** `/v2/tickets/{id}` Updates a ticket's properties. Only provided fields will be updated. ### Path Parameters - `id` - The ticket number ### Request Body All fields are optional. | Field | Type | Description | | ------------------- | ----------- | -------------------------------------------------- | | `title` | string | Update title | | `content` | string | Update description (HTML) | | `statusId` | string | Set status by ID | | `open` | boolean | Close (false) or reopen (true) the ticket | | `assigneeId` | string/null | Assign/unassign admin | | `companyId` | string/null | Update company association | | `customFields` | object | Update custom field values | | `snoozedUntil` | string/null | Snooze until ISO 8601 timestamp (null to unsnooze) | | `skipNotifications` | boolean | Skip notifications (default false) | ### Closing a Ticket Set `open: false` to close the ticket. Closing a ticket will also unsnooze it. The status is not changed automatically — use `statusId` to change the status explicitly. ### File Custom Fields File-type custom fields support the same two upload methods as ticket creation: multipart upload (`customFields.` file parts with JSON in the `data` field) and external URLs (`{ "url": "https://..." }` with optional `"name"` in the custom field value). Same limits apply (10 files, 400MB total, executable types blocked). ### Response Returns the updated ticket object. ### Parameters - `id: number` - `params: TicketUpdateParams` - `assigneeId?: string | null` Body param - `companyId?: string | null` Body param - `content?: string` Body param - `customFields?: Record` Body param - `open?: boolean` Body param - `skipNotifications?: boolean` Body param - `snoozedUntil?: string | null` Body param - `statusId?: string` Body param - `title?: string` Body param - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` Header param: API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `Ticket` - `id: string` Unique identifier (MongoDB ID) - `assigneeId: string | null` Assigned admin ID - `author: Author | null` Contact who created the ticket - `id: string | null` Author unique identifier - `email: string | null` Author email - `name: string` Author display name - `profilePicture: string | null` Author profile picture URL - `type: "admin" | "customer" | "guest" | 3 more` Type of user - `"admin"` - `"customer"` - `"guest"` - `"integration"` - `"bot"` - `"lead"` - `categoryType: "customer" | "tracker" | "back-office"` Ticket category type - `"customer"` - `"tracker"` - `"back-office"` - `companyId: string | null` Associated company ID - `content: string` Ticket content/description (HTML) - `createdAt: string` ISO 8601 creation timestamp - `customFields: Record` Custom field values keyed by field ID. File-type fields contain a JSON string of { key, name, url } with a signed download URL (1 hour expiry). For allowMultiple file fields, the value is a JSON string of an array of these objects. - `integrations: Integrations` Third-party integration links - `clickup: Array` - `id: string` ClickUp task ID - `title: string` ClickUp task title - `url: string` URL to the ClickUp task - `devops: Array` - `id: number` Azure DevOps work item ID - `projectId: string` Azure DevOps project ID - `projectName: string` Azure DevOps project name - `title: string` Work item title - `url: string` URL to the work item - `github: Array` - `id: string` GitHub issue ID - `number: string` GitHub issue number - `repositoryFullName: string` Full repository name (owner/repo) - `repositoryName: string` Repository name - `title: string` GitHub issue title - `url: string` URL to the GitHub issue - `hubspot: Array` - `dealAmount: number | null` Deal amount (for DEAL type) - `dealClosed: boolean | null` Whether the deal is closed (for DEAL type) - `objectId: number` HubSpot object ID - `type: "TICKET" | "DEAL" | "CONTACT"` HubSpot object type - `"TICKET"` - `"DEAL"` - `"CONTACT"` - `jira: Array` - `issueId: string` Jira issue ID - `issueUrl: string | null` URL to the Jira issue - `linear: Array` - `issueId: string` Linear issue ID - `issueUrl: string | null` URL to the Linear issue - `linkedConversations: Array` Linked conversations - `id: string` Conversation ID - `role: "customer" | "tracker" | "back-office"` Link role - `"customer"` - `"tracker"` - `"back-office"` - `object: "ticket"` Object type identifier - `"ticket"` - `open: boolean` Whether the ticket is open - `snoozedUntil: string | null` ISO 8601 timestamp until snoozed (from linked conversation) - `status: PostStatus` Current ticket status - `id: string` Unique identifier - `color: string` Color for UI display - `isDefault: boolean` Whether this is the default status for new posts - `name: string` Display name - `object: "post_status"` Object type identifier - `"post_status"` - `type: "reviewing" | "unstarted" | "active" | 2 more` The workflow stage this status represents - `"reviewing"` - `"unstarted"` - `"active"` - `"completed"` - `"canceled"` - `teamAssigneeId: string | null` Assigned team ID (from linked conversation) - `ticketCategoryId: string` Ticket category ID - `ticketNumber: number` Sequential display ID (e.g. TK-42) - `ticketUrl: string` Full URL to view the ticket - `title: string` Ticket title - `updatedAt: string` ISO 8601 last updated timestamp - `conversationParts?: Array` Conversation message history. Only included when fetching a single ticket by ID. - `UserMessage` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `id: string | null` Author ID - `type: "customer" | "lead" | "admin" | 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email?: string` Author email address - `name?: string` Author display name - `profilePicture?: string | null` Author profile picture URL - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `AdminMessage` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string | null` Note body content as HTML with signed image URLs - `bodyMarkdown: string | null` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMessage` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string | null` Email body content as HTML with signed image URLs - `bodyMarkdown: string | null` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMessage` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string | null` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `channel?: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOptions` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: Array` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResponse` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT request payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt?: string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt?: string` ISO timestamp after which late submission is no longer allowed - `ratedAgent?: CsatRatedAgent` - `type: "teammate" | "fibi" | "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id?: string` Identifier of the rated agent when applicable - `workflow?: CsatWorkflowLink` - `workflowActionId?: string` Workflow action ID associated with the CSAT request - `workflowId?: string` Workflow ID associated with the CSAT request - `workflowRunId?: string` Workflow run ID associated with the CSAT request - `workflowStepId?: string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT submission payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent?: CsatRatedAgent` - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the request was created - `workflow?: CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttributeCollectionPrompt` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: Form` Form configuration - `id: string` Form ID - `attributes: Array` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttributeCollectionComplete` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assignment` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId?: string | null` ID of the admin assigned to the conversation - `adminAssignerId?: string | null` ID of the admin who made the assignment - `teamAssigneeId?: string | null` ID of the team assigned to the conversation - `StatusChange` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" | "closed" | "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil?: string | null` ISO timestamp until conversation is snoozed (if snoozed) - `TagUpdate` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" | "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor?: ConversationTagMutationActor` Actor that applied the tag - `tagName?: string | null` Tag name at the time of the event or the best available current display name - `targetPartId?: string | null` Conversation part that the tag mutation targeted - `WorkflowWaitEvent` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: WorkflowWait` Workflow wait event payload for this thread event - `eventType: "started" | "finished" | "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType?: "admin" | "customer" | "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel?: string` Human-readable wait duration or preset label - `workflowId?: string` Workflow ID associated with the wait event - `workflowName?: string` Workflow display name at the time of the wait event - `PriorityChange` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `ParticipantAdded` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: Participant` The added participant - `id: string` Participant ID - `type: "customer" | "lead" | "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); const ticket = await client.support.tickets.update(1); console.log(ticket.id); ``` #### Response ```json { "id": "507f1f77bcf86cd799439011", "assigneeId": "507f1f77bcf86cd799439013", "author": { "id": "507f1f77bcf86cd799439011", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/john.png", "type": "customer" }, "categoryType": "customer", "companyId": "507f1f77bcf86cd799439015", "content": "

I get a 403 error when logging in.

", "createdAt": "2025-01-15T10:30:00.000Z", "customFields": { "priority": "bar", "507f1f77bcf86cd799439099": "bar" }, "integrations": { "clickup": [ { "id": "86a1b2c3d", "title": "Fix login bug", "url": "https://app.clickup.com/t/86a1b2c3d" } ], "devops": [ { "id": 789, "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "projectName": "My Project", "title": "Implement SSO", "url": "https://dev.azure.com/org/project/_workitems/edit/789" } ], "github": [ { "id": "1234567890", "number": "42", "repositoryFullName": "acme/frontend", "repositoryName": "frontend", "title": "Login page returns 403", "url": "https://github.com/acme/frontend/issues/42" } ], "hubspot": [ { "dealAmount": 5000, "dealClosed": false, "objectId": 12345, "type": "DEAL" } ], "jira": [ { "issueId": "PROJ-456", "issueUrl": "https://company.atlassian.net/browse/PROJ-456" } ], "linear": [ { "issueId": "LIN-123", "issueUrl": "https://linear.app/team/issue/LIN-123" } ] }, "linkedConversations": [ { "id": "507f1f77bcf86cd799439011", "role": "customer" } ], "object": "ticket", "open": true, "snoozedUntil": "2025-01-16T09:00:00.000Z", "status": { "id": "507f1f77bcf86cd799439011", "color": "Blue", "isDefault": false, "name": "In Progress", "object": "post_status", "type": "active" }, "teamAssigneeId": "507f1f77bcf86cd799439014", "ticketCategoryId": "507f1f77bcf86cd799439011", "ticketNumber": 42, "ticketUrl": "https://feedback.example.com/p/cannot-login", "title": "Cannot login to dashboard", "updatedAt": "2025-01-15T12:30:00.000Z", "conversationParts": [ { "id": "1", "bodyHtml": "

Hello, I have a question about your product.

", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ] } ``` ## Delete a ticket `client.support.tickets.delete(numberid, TicketDeleteParamsparams?, RequestOptionsoptions?): TicketDeleteResponse` **delete** `/v2/tickets/{id}` Permanently deletes a ticket by its ticket number. ### Path Parameters - `id` - The ticket number ### Response Returns a deletion confirmation: ```json { "id": "507f1f77bcf86cd799439011", "object": "ticket", "deleted": true } ``` ### Behavior - **Customer-facing tickets**: Deletes the ticket and its linked conversation. - **Back-office / tracker tickets**: Deletes the ticket and unlinks it from the conversation (conversation is preserved). ### Caution This operation is **irreversible**. ### Parameters - `id: number` - `params: TicketDeleteParams` - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `TicketDeleteResponse` - `id: string` Unique identifier of the deleted ticket - `deleted: true` Indicates the resource was deleted - `true` - `object: "ticket"` Object type identifier - `"ticket"` ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); const ticket = await client.support.tickets.delete(1); console.log(ticket.id); ``` #### Response ```json { "id": "507f1f77bcf86cd799439011", "deleted": true, "object": "ticket" } ``` ## Reply to a ticket `client.support.tickets.reply(numberid, TicketReplyParamsparams, RequestOptionsoptions?): Ticket` **post** `/v2/tickets/{id}/reply` Adds a reply to a ticket's linked conversation. Supports both contact and admin replies. ### Path Parameters - `id` - The ticket number ### Contact Reply | Field | Type | Required | Description | | ------------------- | -------- | -------- | ---------------------------------------- | | `type` | string | Yes | Must be "contact" | | `contactId` | string | No* | Featurebase contact ID | | `contactEmail` | string | No* | Contact email | | `body` | string | Yes | Message content (HTML) | | `messageType` | string | No | Always "comment" for contacts | | `attachmentUrls` | string[] | No | Attachment URLs (max 10) | | `skipNotifications` | boolean | No | Skip notifications (default false) | | `createdAt` | string | No | ISO 8601 timestamp to backdate the reply | \*At least one of `contactId` or `contactEmail` is required. ### Admin Reply | Field | Type | Required | Description | | ------------------- | -------- | -------- | ------------------------------------------------ | | `type` | string | Yes | Must be "admin" | | `adminId` | string | Yes | ID of the admin authoring the reply | | `body` | string | Yes | Message content (HTML) | | `messageType` | string | No | "comment" (default) or "note" for internal notes | | `attachmentUrls` | string[] | No | Attachment URLs (max 10) | | `skipNotifications` | boolean | No | Skip notifications (default false) | | `createdAt` | string | No | ISO 8601 timestamp to backdate the reply | ### Response Returns a reply confirmation object. ### Parameters - `id: number` - `TicketReplyParams = Variant0 | Variant1` - `TicketReplyParamsBase` - `body: string` Body param - `type: "contact"` Body param - `"contact"` - `attachmentUrls?: Array` Body param - `contactEmail?: string` Body param - `contactId?: string` Body param - `createdAt?: string | null` Body param - `messageType?: "comment"` Body param - `"comment"` - `skipNotifications?: boolean` Body param - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` Header param: API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` - `Variant0 extends TicketReplyParamsBase` - `Variant1 extends TicketReplyParamsBase` ### Returns - `Ticket` - `id: string` Unique identifier (MongoDB ID) - `assigneeId: string | null` Assigned admin ID - `author: Author | null` Contact who created the ticket - `id: string | null` Author unique identifier - `email: string | null` Author email - `name: string` Author display name - `profilePicture: string | null` Author profile picture URL - `type: "admin" | "customer" | "guest" | 3 more` Type of user - `"admin"` - `"customer"` - `"guest"` - `"integration"` - `"bot"` - `"lead"` - `categoryType: "customer" | "tracker" | "back-office"` Ticket category type - `"customer"` - `"tracker"` - `"back-office"` - `companyId: string | null` Associated company ID - `content: string` Ticket content/description (HTML) - `createdAt: string` ISO 8601 creation timestamp - `customFields: Record` Custom field values keyed by field ID. File-type fields contain a JSON string of { key, name, url } with a signed download URL (1 hour expiry). For allowMultiple file fields, the value is a JSON string of an array of these objects. - `integrations: Integrations` Third-party integration links - `clickup: Array` - `id: string` ClickUp task ID - `title: string` ClickUp task title - `url: string` URL to the ClickUp task - `devops: Array` - `id: number` Azure DevOps work item ID - `projectId: string` Azure DevOps project ID - `projectName: string` Azure DevOps project name - `title: string` Work item title - `url: string` URL to the work item - `github: Array` - `id: string` GitHub issue ID - `number: string` GitHub issue number - `repositoryFullName: string` Full repository name (owner/repo) - `repositoryName: string` Repository name - `title: string` GitHub issue title - `url: string` URL to the GitHub issue - `hubspot: Array` - `dealAmount: number | null` Deal amount (for DEAL type) - `dealClosed: boolean | null` Whether the deal is closed (for DEAL type) - `objectId: number` HubSpot object ID - `type: "TICKET" | "DEAL" | "CONTACT"` HubSpot object type - `"TICKET"` - `"DEAL"` - `"CONTACT"` - `jira: Array` - `issueId: string` Jira issue ID - `issueUrl: string | null` URL to the Jira issue - `linear: Array` - `issueId: string` Linear issue ID - `issueUrl: string | null` URL to the Linear issue - `linkedConversations: Array` Linked conversations - `id: string` Conversation ID - `role: "customer" | "tracker" | "back-office"` Link role - `"customer"` - `"tracker"` - `"back-office"` - `object: "ticket"` Object type identifier - `"ticket"` - `open: boolean` Whether the ticket is open - `snoozedUntil: string | null` ISO 8601 timestamp until snoozed (from linked conversation) - `status: PostStatus` Current ticket status - `id: string` Unique identifier - `color: string` Color for UI display - `isDefault: boolean` Whether this is the default status for new posts - `name: string` Display name - `object: "post_status"` Object type identifier - `"post_status"` - `type: "reviewing" | "unstarted" | "active" | 2 more` The workflow stage this status represents - `"reviewing"` - `"unstarted"` - `"active"` - `"completed"` - `"canceled"` - `teamAssigneeId: string | null` Assigned team ID (from linked conversation) - `ticketCategoryId: string` Ticket category ID - `ticketNumber: number` Sequential display ID (e.g. TK-42) - `ticketUrl: string` Full URL to view the ticket - `title: string` Ticket title - `updatedAt: string` ISO 8601 last updated timestamp - `conversationParts?: Array` Conversation message history. Only included when fetching a single ticket by ID. - `UserMessage` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `id: string | null` Author ID - `type: "customer" | "lead" | "admin" | 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email?: string` Author email address - `name?: string` Author display name - `profilePicture?: string | null` Author profile picture URL - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `AdminMessage` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string | null` Note body content as HTML with signed image URLs - `bodyMarkdown: string | null` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMessage` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string | null` Email body content as HTML with signed image URLs - `bodyMarkdown: string | null` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMessage` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string | null` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `channel?: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOptions` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: Array` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResponse` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT request payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt?: string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt?: string` ISO timestamp after which late submission is no longer allowed - `ratedAgent?: CsatRatedAgent` - `type: "teammate" | "fibi" | "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id?: string` Identifier of the rated agent when applicable - `workflow?: CsatWorkflowLink` - `workflowActionId?: string` Workflow action ID associated with the CSAT request - `workflowId?: string` Workflow ID associated with the CSAT request - `workflowRunId?: string` Workflow run ID associated with the CSAT request - `workflowStepId?: string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT submission payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent?: CsatRatedAgent` - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the request was created - `workflow?: CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttributeCollectionPrompt` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: Form` Form configuration - `id: string` Form ID - `attributes: Array` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttributeCollectionComplete` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assignment` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId?: string | null` ID of the admin assigned to the conversation - `adminAssignerId?: string | null` ID of the admin who made the assignment - `teamAssigneeId?: string | null` ID of the team assigned to the conversation - `StatusChange` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" | "closed" | "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil?: string | null` ISO timestamp until conversation is snoozed (if snoozed) - `TagUpdate` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" | "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor?: ConversationTagMutationActor` Actor that applied the tag - `tagName?: string | null` Tag name at the time of the event or the best available current display name - `targetPartId?: string | null` Conversation part that the tag mutation targeted - `WorkflowWaitEvent` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: WorkflowWait` Workflow wait event payload for this thread event - `eventType: "started" | "finished" | "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType?: "admin" | "customer" | "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel?: string` Human-readable wait duration or preset label - `workflowId?: string` Workflow ID associated with the wait event - `workflowName?: string` Workflow display name at the time of the wait event - `PriorityChange` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `ParticipantAdded` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: Participant` The added participant - `id: string` Participant ID - `type: "customer" | "lead" | "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); const ticket = await client.support.tickets.reply(1, { body: '

Thank you for your help!

', type: 'contact', }); console.log(ticket.id); ``` #### Response ```json { "id": "507f1f77bcf86cd799439011", "assigneeId": "507f1f77bcf86cd799439013", "author": { "id": "507f1f77bcf86cd799439011", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/john.png", "type": "customer" }, "categoryType": "customer", "companyId": "507f1f77bcf86cd799439015", "content": "

I get a 403 error when logging in.

", "createdAt": "2025-01-15T10:30:00.000Z", "customFields": { "priority": "bar", "507f1f77bcf86cd799439099": "bar" }, "integrations": { "clickup": [ { "id": "86a1b2c3d", "title": "Fix login bug", "url": "https://app.clickup.com/t/86a1b2c3d" } ], "devops": [ { "id": 789, "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "projectName": "My Project", "title": "Implement SSO", "url": "https://dev.azure.com/org/project/_workitems/edit/789" } ], "github": [ { "id": "1234567890", "number": "42", "repositoryFullName": "acme/frontend", "repositoryName": "frontend", "title": "Login page returns 403", "url": "https://github.com/acme/frontend/issues/42" } ], "hubspot": [ { "dealAmount": 5000, "dealClosed": false, "objectId": 12345, "type": "DEAL" } ], "jira": [ { "issueId": "PROJ-456", "issueUrl": "https://company.atlassian.net/browse/PROJ-456" } ], "linear": [ { "issueId": "LIN-123", "issueUrl": "https://linear.app/team/issue/LIN-123" } ] }, "linkedConversations": [ { "id": "507f1f77bcf86cd799439011", "role": "customer" } ], "object": "ticket", "open": true, "snoozedUntil": "2025-01-16T09:00:00.000Z", "status": { "id": "507f1f77bcf86cd799439011", "color": "Blue", "isDefault": false, "name": "In Progress", "object": "post_status", "type": "active" }, "teamAssigneeId": "507f1f77bcf86cd799439014", "ticketCategoryId": "507f1f77bcf86cd799439011", "ticketNumber": 42, "ticketUrl": "https://feedback.example.com/p/cannot-login", "title": "Cannot login to dashboard", "updatedAt": "2025-01-15T12:30:00.000Z", "conversationParts": [ { "id": "1", "bodyHtml": "

Hello, I have a question about your product.

", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ] } ``` ## Domain Types ### Author Input - `AuthorInput` Author to attribute the post to. If not provided, uses the authenticated user. Supports multiple identification methods: id (Featurebase ID), userId (external SSO ID), or email. - `id?: string` Featurebase user ID to attribute content to - `email?: string` Author email (used to find or create user) - `name?: string` Author display name - `profilePicture?: string` Author profile picture URL - `userId?: string` External user ID from your system (matched via SSO) ### Ticket - `Ticket` - `id: string` Unique identifier (MongoDB ID) - `assigneeId: string | null` Assigned admin ID - `author: Author | null` Contact who created the ticket - `id: string | null` Author unique identifier - `email: string | null` Author email - `name: string` Author display name - `profilePicture: string | null` Author profile picture URL - `type: "admin" | "customer" | "guest" | 3 more` Type of user - `"admin"` - `"customer"` - `"guest"` - `"integration"` - `"bot"` - `"lead"` - `categoryType: "customer" | "tracker" | "back-office"` Ticket category type - `"customer"` - `"tracker"` - `"back-office"` - `companyId: string | null` Associated company ID - `content: string` Ticket content/description (HTML) - `createdAt: string` ISO 8601 creation timestamp - `customFields: Record` Custom field values keyed by field ID. File-type fields contain a JSON string of { key, name, url } with a signed download URL (1 hour expiry). For allowMultiple file fields, the value is a JSON string of an array of these objects. - `integrations: Integrations` Third-party integration links - `clickup: Array` - `id: string` ClickUp task ID - `title: string` ClickUp task title - `url: string` URL to the ClickUp task - `devops: Array` - `id: number` Azure DevOps work item ID - `projectId: string` Azure DevOps project ID - `projectName: string` Azure DevOps project name - `title: string` Work item title - `url: string` URL to the work item - `github: Array` - `id: string` GitHub issue ID - `number: string` GitHub issue number - `repositoryFullName: string` Full repository name (owner/repo) - `repositoryName: string` Repository name - `title: string` GitHub issue title - `url: string` URL to the GitHub issue - `hubspot: Array` - `dealAmount: number | null` Deal amount (for DEAL type) - `dealClosed: boolean | null` Whether the deal is closed (for DEAL type) - `objectId: number` HubSpot object ID - `type: "TICKET" | "DEAL" | "CONTACT"` HubSpot object type - `"TICKET"` - `"DEAL"` - `"CONTACT"` - `jira: Array` - `issueId: string` Jira issue ID - `issueUrl: string | null` URL to the Jira issue - `linear: Array` - `issueId: string` Linear issue ID - `issueUrl: string | null` URL to the Linear issue - `linkedConversations: Array` Linked conversations - `id: string` Conversation ID - `role: "customer" | "tracker" | "back-office"` Link role - `"customer"` - `"tracker"` - `"back-office"` - `object: "ticket"` Object type identifier - `"ticket"` - `open: boolean` Whether the ticket is open - `snoozedUntil: string | null` ISO 8601 timestamp until snoozed (from linked conversation) - `status: PostStatus` Current ticket status - `id: string` Unique identifier - `color: string` Color for UI display - `isDefault: boolean` Whether this is the default status for new posts - `name: string` Display name - `object: "post_status"` Object type identifier - `"post_status"` - `type: "reviewing" | "unstarted" | "active" | 2 more` The workflow stage this status represents - `"reviewing"` - `"unstarted"` - `"active"` - `"completed"` - `"canceled"` - `teamAssigneeId: string | null` Assigned team ID (from linked conversation) - `ticketCategoryId: string` Ticket category ID - `ticketNumber: number` Sequential display ID (e.g. TK-42) - `ticketUrl: string` Full URL to view the ticket - `title: string` Ticket title - `updatedAt: string` ISO 8601 last updated timestamp - `conversationParts?: Array` Conversation message history. Only included when fetching a single ticket by ID. - `UserMessage` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `id: string | null` Author ID - `type: "customer" | "lead" | "admin" | 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email?: string` Author email address - `name?: string` Author display name - `profilePicture?: string | null` Author profile picture URL - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `type: "admin" | "customer" | "lead" | 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id?: string | null` Actor identifier when available - `name?: string | null` Actor display name when available - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `AdminMessage` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string | null` Message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Message body content as markdown - `channel: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string | null` Note body content as HTML with signed image URLs - `bodyMarkdown: string | null` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMessage` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string | null` Email body content as HTML with signed image URLs - `bodyMarkdown: string | null` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMessage` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string | null` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string | null` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `channel?: "unknown" | "desktop" | "android" | 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOptions` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: Array` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResponse` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT request payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" | "rated" | "canceled" | "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt?: string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt?: string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt?: string` ISO timestamp after which late submission is no longer allowed - `ratedAgent?: CsatRatedAgent` - `type: "teammate" | "fibi" | "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id?: string` Identifier of the rated agent when applicable - `workflow?: CsatWorkflowLink` - `workflowActionId?: string` Workflow action ID associated with the CSAT request - `workflowId?: string` Workflow ID associated with the CSAT request - `workflowRunId?: string` Workflow run ID associated with the CSAT request - `workflowStepId?: string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: Csat` Canonical CSAT submission payload for this thread event - `channel: "desktop" | "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent?: CsatRatedAgent` - `remark?: string` Optional remark left with the rating - `requestedAt?: string` ISO timestamp when the request was created - `workflow?: CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttributeCollectionPrompt` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: Form` Form configuration - `id: string` Form ID - `attributes: Array` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author?: ConversationPartAuthor | null` - `redacted?: boolean` Whether this message has been redacted - `tagApplications?: Array` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy?: ConversationTagMutationActor` Actor that applied the tag - `removedAt?: string | null` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy?: ConversationTagMutationActor` Actor that applied the tag - `tag?: ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttributeCollectionComplete` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assignment` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId?: string | null` ID of the admin assigned to the conversation - `adminAssignerId?: string | null` ID of the admin who made the assignment - `teamAssigneeId?: string | null` ID of the team assigned to the conversation - `StatusChange` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" | "closed" | "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil?: string | null` ISO timestamp until conversation is snoozed (if snoozed) - `TagUpdate` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" | "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor?: ConversationTagMutationActor` Actor that applied the tag - `tagName?: string | null` Tag name at the time of the event or the best available current display name - `targetPartId?: string | null` Conversation part that the tag mutation targeted - `WorkflowWaitEvent` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: WorkflowWait` Workflow wait event payload for this thread event - `eventType: "started" | "finished" | "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType?: "admin" | "customer" | "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel?: string` Human-readable wait duration or preset label - `workflowId?: string` Workflow ID associated with the wait event - `workflowName?: string` Workflow display name at the time of the wait event - `PriorityChange` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `ParticipantAdded` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: Participant` The added participant - `id: string` Participant ID - `type: "customer" | "lead" | "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated ### Ticket Delete Response - `TicketDeleteResponse` - `id: string` Unique identifier of the deleted ticket - `deleted: true` Indicates the resource was deleted - `true` - `object: "ticket"` Object type identifier - `"ticket"` # Custom Fields ## List custom fields `client.support.tickets.customFields.list(CustomFieldListParamsparams?, RequestOptionsoptions?): CustomFieldList` **get** `/v2/tickets/custom_fields` Returns all custom fields configured in your organization that can be used on tickets. This endpoint returns all custom fields at once. No pagination is supported. ### Custom Field Object Each custom field includes: - `id` - Unique field identifier - `label` - Field label displayed to users - `type` - Field type (text, number, select, multi-select, checkbox, date, file) - `required` - Whether the field is required - `placeholder` - Placeholder text (for text/number fields) - `public` - Whether the field value is publicly visible - `internal` - Whether the field is for internal use only - `options` - Array of options (for select/multi-select fields) - `allowMultiple` - Whether multiple files can be uploaded (file fields only) ### Parameters - `params: CustomFieldListParams` - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `CustomFieldList` - `data: Array` Array of custom fields - `id: string` Unique identifier - `label: string` Field label displayed to users - `object: "custom_field"` Object type identifier - `"custom_field"` - `type: "text" | "number" | "select" | 4 more` Field type - `"text"` - `"number"` - `"select"` - `"multi-select"` - `"checkbox"` - `"date"` - `"file"` - `allowMultiple?: boolean` Whether multiple files can be uploaded (file fields only) - `createdAt?: string` ISO timestamp when created - `internal?: boolean` Whether the field is for internal use only - `options?: Array