featurebase-node 0.0.2

package/src/resources/conversations/conversations.ts

@@ -0,0 +1,2721 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as ConversationsAPI from './conversations';
+import * as TagsAPI from '../tags';
+import * as ParticipantsAPI from './participants';
+import { ParticipantAddParams, ParticipantRemoveParams, Participants } from './participants';
+import * as ConversationsTagsAPI from './tags';
+import {
+  AttachedConversationTag,
+  ConversationTagMutationActor,
+  TagAttachParams,
+  TagDetachParams,
+  Tags,
+} from './tags';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Conversations are messenger/inbox conversations in your Featurebase organization. Use this endpoint to list and retrieve conversation information.
+ */
+export class Conversations extends APIResource {
+  tags: ConversationsTagsAPI.Tags = new ConversationsTagsAPI.Tags(this._client);
+  participants: ParticipantsAPI.Participants = new ParticipantsAPI.Participants(this._client);
+
+  /**
+   * 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": "<p>Hello, I have a question about your product.</p>",
+   *     "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.
+   *
+   * @example
+   * ```ts
+   * const conversation = await client.conversations.create({
+   *   bodyMarkdown:
+   *     'Hello, I have a question about your product.\n\n![screenshot](https://example.com/image.png)',
+   *   from: { id: '676f0f6765bdaa7d7d760f88', type: 'contact' },
+   * });
+   * ```
+   */
+  create(params: ConversationCreateParams, options?: RequestOptions): APIPromise<Conversation> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post('/v2/conversations', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * 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": "<p>Hello, I have a question about your pricing plans.</p>",
+   *       "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": "<p>Hi John! I'd be happy to help you with pricing information.</p>",
+   *       "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.
+   *
+   * @example
+   * ```ts
+   * const conversation = await client.conversations.retrieve(
+   *   '12345',
+   * );
+   * ```
+   */
+  retrieve(
+    id: string,
+    params: ConversationRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Conversation> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.get(path`/v2/conversations/${id}`, {
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * 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.
+   *
+   * @example
+   * ```ts
+   * const conversation = await client.conversations.update(
+   *   '12345',
+   * );
+   * ```
+   */
+  update(id: string, params: ConversationUpdateParams, options?: RequestOptions): APIPromise<Conversation> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.patch(path`/v2/conversations/${id}`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * 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.
+   *
+   * @example
+   * ```ts
+   * const conversations = await client.conversations.list();
+   * ```
+   */
+  list(
+    params: ConversationListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ConversationListResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
+    return this._client.get('/v2/conversations', {
+      query,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * 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.
+   *
+   * @example
+   * ```ts
+   * const conversation = await client.conversations.delete(
+   *   '12345',
+   * );
+   * ```
+   */
+  delete(
+    id: string,
+    params: ConversationDeleteParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ConversationDeleteResponse> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.delete(path`/v2/conversations/${id}`, {
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * 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.
+   *
+   * @example
+   * ```ts
+   * const conversation = await client.conversations.redact({
+   *   conversationId: '12345',
+   *   conversationPartId: '67890',
+   *   type: 'conversation_part',
+   * });
+   * ```
+   */
+  redact(params: ConversationRedactParams, options?: RequestOptions): APIPromise<Conversation> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post('/v2/conversations/redact', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * 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": "<p>Thank you for your help!</p>",
+   *   "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.
+   *
+   * @example
+   * ```ts
+   * const conversationPart = await client.conversations.reply(
+   *   '12345',
+   *   {
+   *     bodyMarkdown: 'Thank you for your help!',
+   *     messageType: 'reply',
+   *     type: 'contact',
+   *   },
+   * );
+   * ```
+   */
+  reply(id: string, params: ConversationReplyParams, options?: RequestOptions): APIPromise<ConversationPart> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post(path`/v2/conversations/${id}/reply`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface Conversation {
+  /**
+   * Unique conversation identifier
+   */
+  id: string;
+
+  /**
+   * ID of the assigned admin
+   */
+  adminAssigneeId: string | null;
+
+  /**
+   * ISO timestamp when bot state last changed
+   */
+  botConversationStateLastUpdatedAt: string | null;
+
+  /**
+   * ID of the brand associated with this conversation
+   */
+  brandId: string | null;
+
+  /**
+   * ISO timestamp when conversation was created
+   */
+  createdAt: string;
+
+  /**
+   * Whether an admin has manually overridden the language for this conversation.
+   * When true, automatic language detection is disabled.
+   */
+  hasAdminOverriddenLanguage: boolean;
+
+  /**
+   * Whether the user is blocked
+   */
+  isBlocked: boolean;
+
+  /**
+   * ISO timestamp of last activity
+   */
+  lastActivityAt: string | null;
+
+  /**
+   * Object type identifier
+   */
+  object: 'conversation';
+
+  /**
+   * Participants in this conversation
+   */
+  participants: Array<ConversationParticipant>;
+
+  /**
+   * Whether this conversation is marked as priority
+   */
+  priority: boolean;
+
+  /**
+   * ISO timestamp when priority was set
+   */
+  prioritySetAt: string | null;
+
+  /**
+   * ISO timestamp until which conversation is snoozed
+   */
+  snoozedUntil: string | null;
+
+  /**
+   * Current state of the conversation
+   */
+  state: 'open' | 'closed' | 'snoozed';
+
+  /**
+   * Current tags applied anywhere in this conversation
+   */
+  tags: Array<TagsAPI.ConversationTag>;
+
+  /**
+   * ID of the assigned team
+   */
+  teamAssigneeId: string | null;
+
+  /**
+   * ISO timestamp when conversation was last updated
+   */
+  updatedAt: string;
+
+  /**
+   * User's preferred language
+   */
+  userPreferredLanguage: string;
+
+  /**
+   * ISO timestamp when conversation started waiting
+   */
+  waitingSince: string | null;
+
+  /**
+   * Whether we are awaiting a customer reply
+   */
+  awaitingCustomerReply?: boolean;
+
+  /**
+   * State of AI agent handling for this conversation
+   */
+  botConversationState?: 'active' | 'handed_off_to_human' | 'resolved';
+
+  /**
+   * Array of conversation parts (messages). Only included when fetching a single
+   * conversation by ID.
+   */
+  conversationParts?: Array<ConversationPart>;
+
+  /**
+   * Minimal CSAT diagnostics for the current effective request.
+   */
+  csatDebug?: Conversation.CsatDebug;
+
+  /**
+   * Historical CSAT requests for this conversation, ordered newest first.
+   */
+  csatHistory?: Array<Conversation.CsatHistory>;
+
+  /**
+   * Derived CSAT summary for this conversation when a rating request or rating
+   * exists.
+   */
+  csatSummary?: Conversation.CsatSummary;
+
+  /**
+   * Whether customer replies are disabled
+   */
+  disableCustomerReply?: boolean;
+
+  /**
+   * 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.
+   */
+  readReceipts?: Array<Conversation.ReadReceipt>;
+
+  source?: Conversation.Source;
+
+  /**
+   * Conversation title
+   */
+  title?: string;
+}
+
+export namespace Conversation {
+  /**
+   * Minimal CSAT diagnostics for the current effective request.
+   */
+  export interface CsatDebug {
+    /**
+     * Canonical CSAT request ID used for the latest debug snapshot
+     */
+    requestId: string;
+
+    /**
+     * Lifecycle status of the request represented in the debug snapshot
+     */
+    status: 'pending' | 'rated' | 'canceled' | 'expired';
+
+    /**
+     * ISO timestamp when rating edits stop being accepted
+     */
+    changeLockWindowEndsAt?: string;
+
+    emailDelivery?: ConversationsAPI.CsatEmailDelivery;
+
+    /**
+     * ISO timestamp when first-time submissions stop being accepted
+     */
+    lateSubmitWindowEndsAt?: string;
+  }
+
+  export interface CsatHistory {
+    /**
+     * Channel used for the CSAT request
+     */
+    channel: 'desktop' | 'email';
+
+    /**
+     * Whether this row represents the currently effective CSAT request for the
+     * conversation
+     */
+    isLatestEffective: boolean;
+
+    /**
+     * ISO timestamp when the request last changed
+     */
+    lastUpdatedAt: string;
+
+    /**
+     * ISO timestamp when the request was created
+     */
+    requestedAt: string;
+
+    /**
+     * Canonical CSAT request ID
+     */
+    requestId: string;
+
+    /**
+     * Source that created the CSAT request
+     */
+    requestSource: 'workflow';
+
+    /**
+     * Lifecycle status for this historical CSAT request
+     */
+    status: 'pending' | 'rated' | 'canceled' | 'expired';
+
+    /**
+     * ISO timestamp when the request was canceled
+     */
+    canceledAt?: string;
+
+    /**
+     * ISO timestamp when edits to an existing rating stop being accepted
+     */
+    changeLockWindowEndsAt?: string;
+
+    emailDelivery?: ConversationsAPI.CsatEmailDelivery;
+
+    /**
+     * ISO timestamp when the request expired
+     */
+    expiredAt?: string;
+
+    /**
+     * ISO timestamp when first-time submissions stop being accepted
+     */
+    lateSubmitWindowEndsAt?: string;
+
+    ratedAgent?: ConversationsAPI.CsatRatedAgent;
+
+    /**
+     * ISO timestamp when the request was rated
+     */
+    ratedAt?: string;
+
+    /**
+     * Submitted remark when present
+     */
+    remark?: string;
+
+    /**
+     * Submitted score when this request was rated
+     */
+    score?: number;
+
+    workflow?: ConversationsAPI.CsatWorkflowLink;
+  }
+
+  /**
+   * Derived CSAT summary for this conversation when a rating request or rating
+   * exists.
+   */
+  export interface CsatSummary {
+    /**
+     * ISO timestamp when the summary last changed
+     */
+    lastUpdatedAt: string;
+
+    /**
+     * Current summary status for CSAT on this conversation
+     */
+    status: 'pending' | 'rated' | 'canceled' | 'expired';
+
+    /**
+     * ISO timestamp when the request was canceled
+     */
+    canceledAt?: string;
+
+    /**
+     * Channel used for the latest CSAT request when known
+     */
+    channel?: 'desktop' | 'email';
+
+    /**
+     * ISO timestamp when the request expired
+     */
+    expiredAt?: string;
+
+    ratedAgent?: ConversationsAPI.CsatRatedAgent;
+
+    /**
+     * ISO timestamp when the customer submitted a rating
+     */
+    ratedAt?: string;
+
+    /**
+     * Optional remark left with the rating
+     */
+    remark?: string;
+
+    /**
+     * ISO timestamp when the latest CSAT request was created
+     */
+    requestedAt?: string;
+
+    /**
+     * Canonical CSAT request ID
+     */
+    requestId?: string;
+
+    /**
+     * Source of the latest CSAT request when known
+     */
+    requestSource?: 'workflow';
+
+    /**
+     * CSAT score from 1 to 5 when rated
+     */
+    score?: number;
+
+    workflow?: ConversationsAPI.CsatWorkflowLink;
+  }
+
+  export interface ReadReceipt {
+    /**
+     * The internal ID of the user
+     */
+    id: 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.
+     */
+    lastReadPartId: string;
+
+    /**
+     * Type of user who has read the conversation
+     */
+    userType: 'admin' | 'customer' | 'lead';
+  }
+
+  export interface Source {
+    /**
+     * Body of the initial message as HTML with signed image URLs
+     */
+    bodyHtml: string;
+
+    /**
+     * Body of the initial message as markdown
+     */
+    bodyMarkdown: string;
+
+    /**
+     * Channel through which the conversation was initiated
+     */
+    channel: 'unknown' | 'desktop' | 'android' | 'ios' | 'email';
+
+    author?: ConversationsAPI.ConversationParticipant;
+
+    /**
+     * How the conversation was initiated
+     */
+    deliveredAs?: 'customer_initiated' | 'admin_initiated';
+
+    /**
+     * Subject line for email conversations
+     */
+    subject?: string;
+
+    /**
+     * URL where the conversation was initiated
+     */
+    url?: string;
+  }
+}
+
+/**
+ * Message from a customer or lead
+ */
+export type ConversationPart =
+  | ConversationPart.UserMessage
+  | ConversationPart.AdminMessage
+  | ConversationPart.AdminNote
+  | ConversationPart.EmailMessage
+  | ConversationPart.BotMessage
+  | ConversationPart.QuickReplyOptions
+  | ConversationPart.QuickReplyResponse
+  | ConversationPart.RatingRequested
+  | ConversationPart.RatingSubmitted
+  | ConversationPart.AttributeCollectionPrompt
+  | ConversationPart.AttributeCollectionComplete
+  | ConversationPart.Assignment
+  | ConversationPart.StatusChange
+  | ConversationPart.TagUpdate
+  | ConversationPart.WorkflowWaitEvent
+  | ConversationPart.PriorityChange
+  | ConversationPart.ParticipantAdded;
+
+export namespace ConversationPart {
+  /**
+   * Message from a customer or lead
+   */
+  export interface UserMessage {
+    /**
+     * Unique part identifier
+     */
+    id: string;
+
+    /**
+     * Message body content as HTML with signed image URLs
+     */
+    bodyHtml: string | null;
+
+    /**
+     * Message body content as markdown
+     */
+    bodyMarkdown: string | null;
+
+    /**
+     * Channel through which the message was sent
+     */
+    channel: 'unknown' | 'desktop' | 'android' | 'ios' | 'email';
+
+    /**
+     * ISO timestamp when the part was created
+     */
+    createdAt: string;
+
+    /**
+     * Object type identifier
+     */
+    object: 'conversation_part';
+
+    /**
+     * User message type
+     */
+    partType: 'user_msg';
+
+    /**
+     * ISO timestamp when the part was last updated
+     */
+    updatedAt: string;
+
+    author?: ConversationsAPI.ConversationPartAuthor | null;
+
+    /**
+     * Whether this message has been redacted
+     */
+    redacted?: boolean;
+
+    /**
+     * Reply-level tag applications and provenance for this conversation part
+     */
+    tagApplications?: Array<ConversationsAPI.ConversationTagApplication>;
+  }
+
+  /**
+   * Message from an admin or support agent
+   */
+  export interface AdminMessage {
+    /**
+     * Unique part identifier
+     */
+    id: string;
+
+    /**
+     * Message body content as HTML with signed image URLs
+     */
+    bodyHtml: string | null;
+
+    /**
+     * Message body content as markdown
+     */
+    bodyMarkdown: string | null;
+
+    /**
+     * Channel through which the message was sent
+     */
+    channel: 'unknown' | 'desktop' | 'android' | 'ios' | 'email';
+
+    /**
+     * ISO timestamp when the part was created
+     */
+    createdAt: string;
+
+    /**
+     * Object type identifier
+     */
+    object: 'conversation_part';
+
+    /**
+     * Admin message type
+     */
+    partType: 'admin_msg';
+
+    /**
+     * ISO timestamp when the part was last updated
+     */
+    updatedAt: string;
+
+    author?: ConversationsAPI.ConversationPartAuthor | null;
+
+    /**
+     * Whether this message has been redacted
+     */
+    redacted?: boolean;
+
+    /**
+     * Reply-level tag applications and provenance for this conversation part
+     */
+    tagApplications?: Array<ConversationsAPI.ConversationTagApplication>;
+  }
+
+  /**
+   * Internal note visible only to admins
+   */
+  export interface AdminNote {
+    /**
+     * Unique part identifier
+     */
+    id: string;
+
+    /**
+     * Note body content as HTML with signed image URLs
+     */
+    bodyHtml: string | null;
+
+    /**
+     * Note body content as markdown
+     */
+    bodyMarkdown: string | null;
+
+    /**
+     * ISO timestamp when the part was created
+     */
+    createdAt: string;
+
+    /**
+     * Object type identifier
+     */
+    object: 'conversation_part';
+
+    /**
+     * Admin internal note type
+     */
+    partType: 'admin_note';
+
+    /**
+     * ISO timestamp when the part was last updated
+     */
+    updatedAt: string;
+
+    author?: ConversationsAPI.ConversationPartAuthor | null;
+
+    /**
+     * Whether this message has been redacted
+     */
+    redacted?: boolean;
+
+    /**
+     * Reply-level tag applications and provenance for this conversation part
+     */
+    tagApplications?: Array<ConversationsAPI.ConversationTagApplication>;
+  }
+
+  /**
+   * Message sent via email
+   */
+  export interface EmailMessage {
+    /**
+     * Unique part identifier
+     */
+    id: string;
+
+    /**
+     * Email body content as HTML with signed image URLs
+     */
+    bodyHtml: string | null;
+
+    /**
+     * Email body content as markdown
+     */
+    bodyMarkdown: string | null;
+
+    /**
+     * Email channel
+     */
+    channel: 'email';
+
+    /**
+     * ISO timestamp when the part was created
+     */
+    createdAt: string;
+
+    /**
+     * Object type identifier
+     */
+    object: 'conversation_part';
+
+    /**
+     * Email message type
+     */
+    partType: 'email_msg';
+
+    /**
+     * ISO timestamp when the part was last updated
+     */
+    updatedAt: string;
+
+    author?: ConversationsAPI.ConversationPartAuthor | null;
+
+    /**
+     * Whether this message has been redacted
+     */
+    redacted?: boolean;
+
+    /**
+     * Reply-level tag applications and provenance for this conversation part
+     */
+    tagApplications?: Array<ConversationsAPI.ConversationTagApplication>;
+  }
+
+  /**
+   * Automated message from AI or bot
+   */
+  export interface BotMessage {
+    /**
+     * Unique part identifier
+     */
+    id: string;
+
+    /**
+     * Bot message body content as HTML with signed image URLs
+     */
+    bodyHtml: string | null;
+
+    /**
+     * Bot message body content as markdown
+     */
+    bodyMarkdown: string | null;
+
+    /**
+     * ISO timestamp when the part was created
+     */
+    createdAt: string;
+
+    /**
+     * Object type identifier
+     */
+    object: 'conversation_part';
+
+    /**
+     * Bot message type
+     */
+    partType: 'bot_msg';
+
+    /**
+     * ISO timestamp when the part was last updated
+     */
+    updatedAt: string;
+
+    author?: ConversationsAPI.ConversationPartAuthor | null;
+
+    /**
+     * Channel through which the message was sent
+     */
+    channel?: 'unknown' | 'desktop' | 'android' | 'ios' | 'email';
+
+    /**
+     * Whether this message has been redacted
+     */
+    redacted?: boolean;
+
+    /**
+     * Reply-level tag applications and provenance for this conversation part
+     */
+    tagApplications?: Array<ConversationsAPI.ConversationTagApplication>;
+  }
+
+  /**
+   * Presents options for user to choose from
+   */
+  export interface QuickReplyOptions {
+    /**
+     * Unique part identifier
+     */
+    id: string;
+
+    /**
+     * ISO timestamp when the part was created
+     */
+    createdAt: string;
+
+    /**
+     * Object type identifier
+     */
+    object: 'conversation_part';
+
+    /**
+     * Quick reply options type
+     */
+    partType: 'quick_reply_opts';
+
+    /**
+     * Available reply options
+     */
+    replyOptions: Array<QuickReplyOptions.ReplyOption>;
+
+    /**
+     * ISO timestamp when the part was last updated
+     */
+    updatedAt: string;
+
+    author?: ConversationsAPI.ConversationPartAuthor | null;
+
+    /**
+     * Whether this message has been redacted
+     */
+    redacted?: boolean;
+
+    /**
+     * Reply-level tag applications and provenance for this conversation part
+     */
+    tagApplications?: Array<ConversationsAPI.ConversationTagApplication>;
+  }
+
+  export namespace QuickReplyOptions {
+    export interface ReplyOption {
+      /**
+       * Option ID
+       */
+      id: string;
+
+      /**
+       * Option text
+       */
+      text: string;
+    }
+  }
+
+  /**
+   * User's selection from quick reply options
+   */
+  export interface QuickReplyResponse {
+    /**
+     * Unique part identifier
+     */
+    id: string;
+
+    /**
+     * The selected option text as HTML
+     */
+    bodyHtml: string;
+
+    /**
+     * The selected option text as markdown
+     */
+    bodyMarkdown: string;
+
+    /**
+     * ISO timestamp when the part was created
+     */
+    createdAt: string;
+
+    /**
+     * Object type identifier
+     */
+    object: 'conversation_part';
+
+    /**
+     * Quick reply response type
+     */
+    partType: 'quick_reply_resp';
+
+    /**
+     * ID of the selected option
+     */
+    selectedOptionId: string;
+
+    /**
+     * ISO timestamp when the part was last updated
+     */
+    updatedAt: string;
+
+    author?: ConversationsAPI.ConversationPartAuthor | null;
+
+    /**
+     * Whether this message has been redacted
+     */
+    redacted?: boolean;
+
+    /**
+     * Reply-level tag applications and provenance for this conversation part
+     */
+    tagApplications?: Array<ConversationsAPI.ConversationTagApplication>;
+  }
+
+  /**
+   * Represents a persisted CSAT request in the conversation thread
+   */
+  export interface RatingRequested {
+    /**
+     * Unique part identifier
+     */
+    id: string;
+
+    /**
+     * ISO timestamp when the part was created
+     */
+    createdAt: string;
+
+    /**
+     * Canonical CSAT request payload for this thread event
+     */
+    csat: RatingRequested.Csat;
+
+    /**
+     * Object type identifier
+     */
+    object: 'conversation_part';
+
+    /**
+     * CSAT rating requested part type
+     */
+    partType: 'rating_requested';
+
+    /**
+     * ISO timestamp when the part was last updated
+     */
+    updatedAt: string;
+  }
+
+  export namespace RatingRequested {
+    /**
+     * Canonical CSAT request payload for this thread event
+     */
+    export interface Csat {
+      /**
+       * Channel used for the CSAT request
+       */
+      channel: 'desktop' | 'email';
+
+      /**
+       * ISO timestamp when the request was created
+       */
+      requestedAt: string;
+
+      /**
+       * Canonical CSAT request ID
+       */
+      requestId: string;
+
+      /**
+       * Source that created the CSAT request
+       */
+      requestSource: 'workflow';
+
+      /**
+       * Status of the CSAT request represented by this part
+       */
+      status: 'pending' | 'rated' | 'canceled' | 'expired';
+
+      /**
+       * ISO timestamp after which changing the rating is no longer allowed
+       */
+      changeLockWindowEndsAt?: string;
+
+      /**
+       * ISO timestamp when the request expired, when applicable
+       */
+      expiredAt?: string;
+
+      /**
+       * ISO timestamp after which late submission is no longer allowed
+       */
+      lateSubmitWindowEndsAt?: string;
+
+      ratedAgent?: ConversationsAPI.CsatRatedAgent;
+
+      workflow?: ConversationsAPI.CsatWorkflowLink;
+    }
+  }
+
+  /**
+   * Represents a persisted CSAT submission in the conversation thread
+   */
+  export interface RatingSubmitted {
+    /**
+     * Unique part identifier
+     */
+    id: string;
+
+    /**
+     * ISO timestamp when the part was created
+     */
+    createdAt: string;
+
+    /**
+     * Canonical CSAT submission payload for this thread event
+     */
+    csat: RatingSubmitted.Csat;
+
+    /**
+     * Object type identifier
+     */
+    object: 'conversation_part';
+
+    /**
+     * CSAT rating submitted part type
+     */
+    partType: 'rating_submitted';
+
+    /**
+     * ISO timestamp when the part was last updated
+     */
+    updatedAt: string;
+  }
+
+  export namespace RatingSubmitted {
+    /**
+     * Canonical CSAT submission payload for this thread event
+     */
+    export interface Csat {
+      /**
+       * Channel used for the CSAT request
+       */
+      channel: 'desktop' | 'email';
+
+      /**
+       * ISO timestamp when the customer submitted the rating
+       */
+      ratedAt: string;
+
+      /**
+       * Canonical CSAT request ID
+       */
+      requestId: string;
+
+      /**
+       * Source that created the CSAT request
+       */
+      requestSource: 'workflow';
+
+      /**
+       * CSAT score from 1 to 5
+       */
+      score: number;
+
+      /**
+       * Submitted ratings are always in the rated state
+       */
+      status: 'rated';
+
+      ratedAgent?: ConversationsAPI.CsatRatedAgent;
+
+      /**
+       * Optional remark left with the rating
+       */
+      remark?: string;
+
+      /**
+       * ISO timestamp when the request was created
+       */
+      requestedAt?: string;
+
+      workflow?: ConversationsAPI.CsatWorkflowLink;
+    }
+  }
+
+  /**
+   * Requests information from user via form
+   */
+  export interface AttributeCollectionPrompt {
+    /**
+     * Unique part identifier
+     */
+    id: string;
+
+    /**
+     * ISO timestamp when the part was created
+     */
+    createdAt: string;
+
+    /**
+     * Form configuration
+     */
+    form: AttributeCollectionPrompt.Form;
+
+    /**
+     * Object type identifier
+     */
+    object: 'conversation_part';
+
+    /**
+     * Attribute collection prompt type
+     */
+    partType: 'attr_prompt';
+
+    /**
+     * ISO timestamp when the part was last updated
+     */
+    updatedAt: string;
+
+    author?: ConversationsAPI.ConversationPartAuthor | null;
+
+    /**
+     * Whether this message has been redacted
+     */
+    redacted?: boolean;
+
+    /**
+     * Reply-level tag applications and provenance for this conversation part
+     */
+    tagApplications?: Array<ConversationsAPI.ConversationTagApplication>;
+  }
+
+  export namespace AttributeCollectionPrompt {
+    /**
+     * Form configuration
+     */
+    export interface Form {
+      /**
+       * Form ID
+       */
+      id: string;
+
+      /**
+       * Form fields
+       */
+      attributes: Array<Form.Attribute>;
+    }
+
+    export namespace Form {
+      export interface Attribute {
+        /**
+         * Field identifier
+         */
+        identifier: string;
+
+        /**
+         * Field display name
+         */
+        name: string;
+
+        /**
+         * Field type
+         */
+        type: string;
+      }
+    }
+  }
+
+  /**
+   * Indicates form was completed
+   */
+  export interface AttributeCollectionComplete {
+    /**
+     * Unique part identifier
+     */
+    id: string;
+
+    /**
+     * ISO timestamp when the part was created
+     */
+    createdAt: string;
+
+    /**
+     * Object type identifier
+     */
+    object: 'conversation_part';
+
+    /**
+     * Attribute collection complete type
+     */
+    partType: 'attr_complete';
+
+    /**
+     * ISO timestamp when the part was last updated
+     */
+    updatedAt: string;
+  }
+
+  /**
+   * Conversation assigned to admin or team
+   */
+  export interface Assignment {
+    /**
+     * Unique part identifier
+     */
+    id: string;
+
+    /**
+     * ISO timestamp when the part was created
+     */
+    createdAt: string;
+
+    /**
+     * Object type identifier
+     */
+    object: 'conversation_part';
+
+    /**
+     * Assignment type
+     */
+    partType: 'assign';
+
+    /**
+     * ISO timestamp when the part was last updated
+     */
+    updatedAt: string;
+
+    /**
+     * ID of the admin assigned to the conversation
+     */
+    adminAssigneeId?: string | null;
+
+    /**
+     * ID of the admin who made the assignment
+     */
+    adminAssignerId?: string | null;
+
+    /**
+     * ID of the team assigned to the conversation
+     */
+    teamAssigneeId?: string | null;
+  }
+
+  /**
+   * Conversation state changed (open/closed/snoozed)
+   */
+  export interface StatusChange {
+    /**
+     * Unique part identifier
+     */
+    id: string;
+
+    /**
+     * ISO timestamp when the part was created
+     */
+    createdAt: string;
+
+    /**
+     * Object type identifier
+     */
+    object: 'conversation_part';
+
+    /**
+     * Status change type
+     */
+    partType: 'status';
+
+    /**
+     * New conversation status
+     */
+    status: 'open' | 'closed' | 'snoozed';
+
+    /**
+     * ISO timestamp when the part was last updated
+     */
+    updatedAt: string;
+
+    /**
+     * ISO timestamp until conversation is snoozed (if snoozed)
+     */
+    snoozedUntil?: string | null;
+  }
+
+  /**
+   * A tag was added to or removed from a specific reply
+   */
+  export interface TagUpdate {
+    /**
+     * Unique part identifier
+     */
+    id: string;
+
+    /**
+     * Whether the tag was added or removed
+     */
+    action: 'added' | 'removed';
+
+    /**
+     * ISO timestamp when the part was created
+     */
+    createdAt: string;
+
+    /**
+     * Object type identifier
+     */
+    object: 'conversation_part';
+
+    /**
+     * ISO timestamp when the tag mutation occurred
+     */
+    occurredAt: string;
+
+    /**
+     * Tag update type
+     */
+    partType: 'tags';
+
+    /**
+     * Identifier of the affected tag
+     */
+    tagId: string;
+
+    /**
+     * ISO timestamp when the part was last updated
+     */
+    updatedAt: string;
+
+    /**
+     * Actor that applied the tag
+     */
+    actor?: ConversationsTagsAPI.ConversationTagMutationActor;
+
+    /**
+     * Tag name at the time of the event or the best available current display name
+     */
+    tagName?: string | null;
+
+    /**
+     * Conversation part that the tag mutation targeted
+     */
+    targetPartId?: string | null;
+  }
+
+  /**
+   * Represents a workflow wait start, finish, or interruption in the conversation
+   * thread
+   */
+  export interface WorkflowWaitEvent {
+    /**
+     * Unique part identifier
+     */
+    id: string;
+
+    /**
+     * ISO timestamp when the part was created
+     */
+    createdAt: string;
+
+    /**
+     * Object type identifier
+     */
+    object: 'conversation_part';
+
+    /**
+     * Workflow wait event part type
+     */
+    partType: 'workflow_wait';
+
+    /**
+     * ISO timestamp when the part was last updated
+     */
+    updatedAt: string;
+
+    /**
+     * Workflow wait event payload for this thread event
+     */
+    workflowWait: WorkflowWaitEvent.WorkflowWait;
+  }
+
+  export namespace WorkflowWaitEvent {
+    /**
+     * Workflow wait event payload for this thread event
+     */
+    export interface WorkflowWait {
+      /**
+       * Lifecycle stage of the workflow wait event
+       */
+      eventType: 'started' | 'finished' | 'interrupted';
+
+      /**
+       * ISO timestamp when the wait event occurred
+       */
+      occurredAt: string;
+
+      /**
+       * User type that interrupted the wait when applicable
+       */
+      interruptedByUserType?: 'admin' | 'customer' | 'lead';
+
+      /**
+       * Human-readable wait duration or preset label
+       */
+      waitLabel?: string;
+
+      /**
+       * Workflow ID associated with the wait event
+       */
+      workflowId?: string;
+
+      /**
+       * Workflow display name at the time of the wait event
+       */
+      workflowName?: string;
+    }
+  }
+
+  /**
+   * Conversation priority was updated
+   */
+  export interface PriorityChange {
+    /**
+     * Unique part identifier
+     */
+    id: string;
+
+    /**
+     * ISO timestamp when the part was created
+     */
+    createdAt: string;
+
+    /**
+     * Whether the conversation is now marked as priority
+     */
+    isPriority: boolean;
+
+    /**
+     * Object type identifier
+     */
+    object: 'conversation_part';
+
+    /**
+     * Priority change type
+     */
+    partType: 'priority';
+
+    /**
+     * ISO timestamp when the part was last updated
+     */
+    updatedAt: string;
+  }
+
+  /**
+   * New participant joined the conversation
+   */
+  export interface ParticipantAdded {
+    /**
+     * Unique part identifier
+     */
+    id: string;
+
+    /**
+     * ISO timestamp when the part was created
+     */
+    createdAt: string;
+
+    /**
+     * Object type identifier
+     */
+    object: 'conversation_part';
+
+    /**
+     * The added participant
+     */
+    participant: ParticipantAdded.Participant;
+
+    /**
+     * Participant added type
+     */
+    partType: 'part_add';
+
+    /**
+     * ISO timestamp when the part was last updated
+     */
+    updatedAt: string;
+  }
+
+  export namespace ParticipantAdded {
+    /**
+     * The added participant
+     */
+    export interface Participant {
+      /**
+       * Participant ID
+       */
+      id: string;
+
+      /**
+       * Participant type
+       */
+      type: 'customer' | 'lead' | 'admin';
+    }
+  }
+}
+
+export interface ConversationPartAuthor {
+  /**
+   * Author ID
+   */
+  id: string | null;
+
+  /**
+   * Type of author
+   */
+  type: 'customer' | 'lead' | 'admin' | 'bot' | 'guest' | 'integration';
+
+  /**
+   * Author email address
+   */
+  email?: string;
+
+  /**
+   * Author display name
+   */
+  name?: string;
+
+  /**
+   * Author profile picture URL
+   */
+  profilePicture?: string | null;
+}
+
+export interface ConversationParticipant {
+  /**
+   * Participant ID
+   */
+  id: string;
+
+  /**
+   * Type of participant
+   */
+  type: 'customer' | 'lead' | 'admin' | 'bot' | 'guest' | 'integration';
+}
+
+export interface ConversationTagApplication {
+  /**
+   * ISO timestamp when the tag was applied to this reply
+   */
+  appliedAt: string;
+
+  /**
+   * Identifier of the applied tag
+   */
+  tagId: string;
+
+  /**
+   * Actor that applied the tag
+   */
+  appliedBy?: ConversationsTagsAPI.ConversationTagMutationActor;
+
+  /**
+   * ISO timestamp when the tag was removed from this reply, if it was removed
+   */
+  removedAt?: string | null;
+
+  /**
+   * Actor that applied the tag
+   */
+  removedBy?: ConversationsTagsAPI.ConversationTagMutationActor;
+
+  /**
+   * Resolved tag object when the tag still exists in the shared workspace catalog
+   */
+  tag?: TagsAPI.ConversationTag;
+}
+
+export interface CsatEmailDelivery {
+  /**
+   * Email delivery status for the CSAT request when applicable
+   */
+  status: 'pending' | 'sent' | 'failed';
+
+  /**
+   * ISO timestamp when the CSAT email failed
+   */
+  failedAt?: string;
+
+  /**
+   * Operational failure reason for the CSAT email delivery
+   */
+  failureReason?: string;
+
+  /**
+   * Email message ID associated with delivery
+   */
+  messageId?: string;
+
+  /**
+   * ISO timestamp when the CSAT email was sent
+   */
+  sentAt?: string;
+}
+
+export interface CsatRatedAgent {
+  /**
+   * Type of agent the CSAT request is attributed to
+   */
+  type: 'teammate' | 'fibi' | 'chatbot';
+
+  /**
+   * Identifier of the rated agent when applicable
+   */
+  id?: string;
+}
+
+export interface CsatWorkflowLink {
+  /**
+   * Workflow action ID associated with the CSAT request
+   */
+  workflowActionId?: string;
+
+  /**
+   * Workflow ID associated with the CSAT request
+   */
+  workflowId?: string;
+
+  /**
+   * Workflow run ID associated with the CSAT request
+   */
+  workflowRunId?: string;
+
+  /**
+   * Workflow step ID associated with the CSAT request
+   */
+  workflowStepId?: string;
+}
+
+/**
+ * Primary recipients (To field)
+ */
+export interface EmailRecipients {
+  /**
+   * Array of email addresses
+   */
+  emails?: Array<string>;
+
+  /**
+   * Array of Featurebase contact IDs
+   */
+  ids?: Array<string>;
+}
+
+export interface ConversationListResponse {
+  /**
+   * Array of conversations
+   */
+  data: Array<Conversation>;
+
+  /**
+   * Cursor for fetching the next page
+   */
+  nextCursor: string | null;
+
+  /**
+   * Object type identifier
+   */
+  object: 'list';
+}
+
+export interface ConversationDeleteResponse {
+  /**
+   * Unique identifier of the deleted conversation
+   */
+  id: string;
+
+  /**
+   * Indicates the resource was deleted
+   */
+  deleted: true;
+
+  /**
+   * Object type identifier
+   */
+  object: 'conversation';
+}
+
+export interface ConversationCreateParams {
+  /**
+   * 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.
+   */
+  bodyMarkdown: string;
+
+  /**
+   * Body param: The author initiating the conversation. Use type "contact" for
+   * customer/lead or "admin" for outreach.
+   */
+  from: ConversationCreateParams.ContactFrom | ConversationCreateParams.AdminFrom;
+
+  /**
+   * Body param: The channel for the conversation. Defaults to "desktop"
+   * (SDK/widget).
+   */
+  channel?: 'desktop' | 'email';
+
+  /**
+   * 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.
+   */
+  createdAt?: string | null;
+
+  /**
+   * Body param: Recipients for admin-initiated outreach. Required when from.type is
+   * "admin". Specify at least one recipient in the "to" field.
+   */
+  recipients?: ConversationCreateParams.Recipients;
+
+  /**
+   * Body param: Subject line for the email. Required when channel is "email" and
+   * from.type is "admin".
+   */
+  subject?: string;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export namespace ConversationCreateParams {
+  /**
+   * Conversation initiated by a contact
+   */
+  export interface ContactFrom {
+    /**
+     * The Featurebase contact ID
+     */
+    id: string;
+
+    /**
+     * The type of author. Use "contact" for customer/lead initiated conversations.
+     */
+    type: 'contact';
+  }
+
+  /**
+   * Conversation initiated by an admin (outreach)
+   */
+  export interface AdminFrom {
+    /**
+     * The Featurebase admin ID
+     */
+    id: string;
+
+    /**
+     * The type of author. Use "admin" for admin initiated outreach conversations.
+     */
+    type: 'admin';
+  }
+
+  /**
+   * Recipients for admin-initiated outreach. Required when from.type is "admin".
+   * Specify at least one recipient in the "to" field.
+   */
+  export interface Recipients {
+    /**
+     * Primary recipients (To field)
+     */
+    to: ConversationsAPI.EmailRecipients;
+
+    /**
+     * Primary recipients (To field)
+     */
+    bcc?: ConversationsAPI.EmailRecipients;
+
+    /**
+     * Primary recipients (To field)
+     */
+    cc?: ConversationsAPI.EmailRecipients;
+  }
+}
+
+export interface ConversationRetrieveParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface ConversationUpdateParams {
+  /**
+   * 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.
+   */
+  actingAdminId?: string;
+
+  /**
+   * Body param: The admin ID to assign the conversation to, or null to unassign.
+   */
+  adminAssigneeId?: string | null;
+
+  /**
+   * Body param: Custom attributes to set on the conversation. Uses the same
+   * validation as v1 API.
+   */
+  customAttributes?: { [key: string]: unknown };
+
+  /**
+   * Body param: Mark the conversation as read for specific admins and/or contacts.
+   */
+  markAsRead?: ConversationUpdateParams.MarkAsRead;
+
+  /**
+   * Body param: ISO datetime when the conversation should be unsnoozed. Required
+   * when state is "snoozed". Must be a future date.
+   */
+  snoozedUntil?: string | null;
+
+  /**
+   * Body param: The state of the conversation. Use "snoozed" with snoozedUntil to
+   * snooze.
+   */
+  state?: 'open' | 'closed' | 'snoozed';
+
+  /**
+   * Body param: The team ID to assign the conversation to, or null to unassign.
+   */
+  teamAssigneeId?: string | null;
+
+  /**
+   * Body param: The title of the conversation.
+   */
+  title?: string;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export namespace ConversationUpdateParams {
+  /**
+   * Mark the conversation as read for specific admins and/or contacts.
+   */
+  export interface MarkAsRead {
+    /**
+     * Array of admin IDs to mark as read. Only admins with existing readReceipts will
+     * be updated.
+     */
+    adminIds?: Array<string>;
+
+    /**
+     * If true, marks all admins with existing readReceipts as read.
+     */
+    allAdmins?: boolean | null;
+
+    /**
+     * If true, marks all contacts (customers and leads) with existing readReceipts as
+     * read.
+     */
+    allContacts?: boolean | null;
+
+    /**
+     * Array of contact IDs to mark as read. Only contacts with existing readReceipts
+     * will be updated.
+     */
+    contactIds?: Array<string>;
+  }
+}
+
+export interface ConversationListParams {
+  /**
+   * Query param: An opaque cursor for pagination. Use the nextCursor value from a
+   * previous response to fetch the next page of results.
+   */
+  cursor?: string;
+
+  /**
+   * Query param: A limit on the number of objects to be returned, between 1 and 100.
+   */
+  limit?: number;
+
+  /**
+   * Query param: Filter conversations by one or more tag IDs using a comma-separated
+   * list. Conversations must contain all provided tags.
+   */
+  tagIds?: string | Array<string>;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface ConversationDeleteParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface ConversationRedactParams {
+  /**
+   * Body param: The conversation short ID that contains the part to redact
+   */
+  conversationId: string;
+
+  /**
+   * Body param: The conversation part short ID to redact
+   */
+  conversationPartId: string;
+
+  /**
+   * Body param: The type of item to redact. Currently only "conversation_part" is
+   * supported.
+   */
+  type: 'conversation_part';
+
+  /**
+   * Body param: The admin ID performing this action. If not provided, changes are
+   * attributed to the system bot user.
+   */
+  actingAdminId?: string;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export type ConversationReplyParams =
+  | ConversationReplyParams.ContactReplyBody
+  | ConversationReplyParams.AdminReplyBody;
+
+export declare namespace ConversationReplyParams {
+  export interface ContactReplyBody {
+    /**
+     * 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.
+     */
+    bodyMarkdown: string;
+
+    /**
+     * Body param: The type of message. Always "reply" for contact replies.
+     */
+    messageType: 'reply';
+
+    /**
+     * Body param: The type of author. Use "contact" for customer/lead replies.
+     */
+    type: 'contact';
+
+    /**
+     * Body param: The Featurebase contact ID
+     */
+    id?: string;
+
+    /**
+     * Body param: Skip sending notifications (default: false). Useful for bulk
+     * imports.
+     */
+    skipNotifications?: boolean;
+
+    /**
+     * Body param: The external user ID from your system
+     */
+    userId?: string;
+
+    /**
+     * Header param: API version for this request. Defaults to your organization's
+     * configured API version if not specified.
+     */
+    'Featurebase-Version'?: string;
+  }
+
+  export interface AdminReplyBody {
+    /**
+     * Body param: The Featurebase admin ID
+     */
+    id: 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.
+     */
+    bodyMarkdown: string;
+
+    /**
+     * Body param: The type of message. "reply" is visible to the customer, "note" is
+     * an internal note only visible to admins.
+     */
+    messageType: 'reply' | 'note';
+
+    /**
+     * Body param: The type of author. Use "admin" for admin replies.
+     */
+    type: 'admin';
+
+    /**
+     * Body param: Skip sending notifications (default: false). Useful for bulk
+     * imports.
+     */
+    skipNotifications?: boolean;
+
+    /**
+     * Header param: API version for this request. Defaults to your organization's
+     * configured API version if not specified.
+     */
+    'Featurebase-Version'?: string;
+  }
+}
+
+Conversations.Tags = Tags;
+Conversations.Participants = Participants;
+
+export declare namespace Conversations {
+  export {
+    type Conversation as Conversation,
+    type ConversationPart as ConversationPart,
+    type ConversationPartAuthor as ConversationPartAuthor,
+    type ConversationParticipant as ConversationParticipant,
+    type ConversationTagApplication as ConversationTagApplication,
+    type CsatEmailDelivery as CsatEmailDelivery,
+    type CsatRatedAgent as CsatRatedAgent,
+    type CsatWorkflowLink as CsatWorkflowLink,
+    type EmailRecipients as EmailRecipients,
+    type ConversationListResponse as ConversationListResponse,
+    type ConversationDeleteResponse as ConversationDeleteResponse,
+    type ConversationCreateParams as ConversationCreateParams,
+    type ConversationRetrieveParams as ConversationRetrieveParams,
+    type ConversationUpdateParams as ConversationUpdateParams,
+    type ConversationListParams as ConversationListParams,
+    type ConversationDeleteParams as ConversationDeleteParams,
+    type ConversationRedactParams as ConversationRedactParams,
+    type ConversationReplyParams as ConversationReplyParams,
+  };
+
+  export {
+    Tags as Tags,
+    type AttachedConversationTag as AttachedConversationTag,
+    type ConversationTagMutationActor as ConversationTagMutationActor,
+    type TagAttachParams as TagAttachParams,
+    type TagDetachParams as TagDetachParams,
+  };
+
+  export {
+    Participants as Participants,
+    type ParticipantAddParams as ParticipantAddParams,
+    type ParticipantRemoveParams as ParticipantRemoveParams,
+  };
+}