featurebase-node 0.14.2 → 0.15.0

package/resources/support/conversations/conversations.js

@@ -17,91 +17,6 @@ class Conversations extends resource_1.APIResource {
         super(...arguments);
         this.participants = new ParticipantsAPI.Participants(this._client);
     }
-    /**
-     * 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
-     * // Automatically fetches more pages as needed.
-     * for await (const conversation of client.support.conversations.list()) {
-     *   // ...
-     * }
-     * ```
-     */
-    list(params = {}, options) {
-        const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
-        return this._client.getAPIList('/v2/conversations', (pagination_1.CursorPage), {
-            query,
-            ...options,
-            headers: (0, headers_1.buildHeaders)([
-                {
-                    ...(featurebaseVersion?.toString() != null ?
-                        { 'Featurebase-Version': featurebaseVersion?.toString() }
-                        : undefined),
-                },
-                options?.headers,
-            ]),
-        });
-    }
     /**
      * Creates a new conversation. Supports both contact-initiated (customer/lead) and
      * admin-initiated (outreach) conversations.
@@ -369,54 +284,6 @@ class Conversations extends resource_1.APIResource {
             ]),
         });
     }
-    /**
-     * 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.support.conversations.delete('12345');
-     * ```
-     */
-    delete(id, params = {}, options) {
-        const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
-        return this._client.delete((0, path_1.path) `/v2/conversations/${id}`, {
-            ...options,
-            headers: (0, headers_1.buildHeaders)([
-                {
-                    ...(featurebaseVersion?.toString() != null ?
-                        { 'Featurebase-Version': featurebaseVersion?.toString() }
-                        : undefined),
-                },
-                options?.headers,
-            ]),
-        });
-    }
     /**
      * Updates a conversation's properties. Supports partial updates - only provided
      * fields will be updated.
@@ -560,97 +427,236 @@ class Conversations extends resource_1.APIResource {
         });
     }
     /**
-     * Adds a reply to an existing conversation. Supports both contact (customer/lead)
-     * and admin replies.
+     * Returns a list of conversations in your organization using cursor-based
+     * pagination.
      *
-     * ### Path Parameters
+     * ### Query Parameters
      *
-     * - `id` - The conversation ID (short ID)
+     * - `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.
      *
-     * ### Request Body
+     * ### Response Format
      *
-     * The request body varies based on who is sending the reply:
+     * Returns a list object with:
      *
-     * #### Contact Reply (customer/lead)
+     * - `object` - Always "list"
+     * - `data` - Array of conversation objects
+     * - `nextCursor` - Cursor for the next page, or null if no more results
      *
-     * | 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.                                                              |
+     * ### Conversation Object
      *
-     * \*At least one of `userId` or `id` is required.
+     * Each conversation includes:
      *
-     * #### Admin Reply
+     * - `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
      *
-     * | 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.                                                              |
+     * ### Example
      *
-     * ### Response
+     * ```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="
+     * }
+     * ```
      *
-     * Returns the created conversation part object with a **201 Created** status. The
-     * response includes both `bodyHtml` (with signed image URLs) and `bodyMarkdown`
-     * fields.
+     * ### Version Availability
      *
-     * ### Example Contact Reply
+     * This endpoint is only available in API version 2026-01-01.nova and newer.
      *
-     * ```json
-     * {
-     *   "type": "contact",
-     *   "userId": "user_123",
-     *   "bodyMarkdown": "Thank you for your help!",
-     *   "messageType": "reply"
+     * @example
+     * ```ts
+     * // Automatically fetches more pages as needed.
+     * for await (const conversation of client.support.conversations.list()) {
+     *   // ...
      * }
      * ```
+     */
+    list(params = {}, options) {
+        const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
+        return this._client.getAPIList('/v2/conversations', (pagination_1.CursorPage), {
+            query,
+            ...options,
+            headers: (0, headers_1.buildHeaders)([
+                {
+                    ...(featurebaseVersion?.toString() != null ?
+                        { 'Featurebase-Version': featurebaseVersion?.toString() }
+                        : undefined),
+                },
+                options?.headers,
+            ]),
+        });
+    }
+    /**
+     * Permanently deletes a conversation by its short ID.
      *
-     * ### Example Admin Reply
+     * ### Path Parameters
+     *
+     * - `id` - The conversation short ID (numeric)
+     *
+     * ### Response
+     *
+     * Returns a deletion confirmation object:
      *
      * ```json
      * {
-     *   "type": "admin",
-     *   "id": "507f1f77bcf86cd799439011",
-     *   "bodyMarkdown": "I'm happy to help! Here's what you need to do...",
-     *   "messageType": "reply"
+     *   "id": "12345",
+     *   "object": "conversation",
+     *   "deleted": true
      * }
      * ```
      *
-     * ### Example Admin Note (Internal)
+     * ### 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.support.conversations.delete('12345');
+     * ```
+     */
+    delete(id, params = {}, options) {
+        const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+        return this._client.delete((0, path_1.path) `/v2/conversations/${id}`, {
+            ...options,
+            headers: (0, headers_1.buildHeaders)([
+                {
+                    ...(featurebaseVersion?.toString() != null ?
+                        { 'Featurebase-Version': featurebaseVersion?.toString() }
+                        : undefined),
+                },
+                options?.headers,
+            ]),
+        });
+    }
+    /**
+     * 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
      * {
-     *   "type": "admin",
-     *   "id": "507f1f77bcf86cd799439011",
-     *   "bodyMarkdown": "Customer seems frustrated, escalating to tier 2.",
-     *   "messageType": "note"
+     *   "tagId": "67ec1234abcd5678ef901234",
+     *   "actingAdminId": "507f1f77bcf86cd799439011"
      * }
      * ```
      *
-     * ### Example Response
+     * ### Version Availability
+     *
+     * This endpoint is only available in API version 2026-01-01.nova and newer.
+     *
+     * @example
+     * ```ts
+     * const attachedConversationTag =
+     *   await client.support.conversations.attachTag('12345', {
+     *     actingAdminId: '507f1f77bcf86cd799439011',
+     *     tagId: '67ec1234abcd5678ef901234',
+     *   });
+     * ```
+     */
+    attachTag(id, params, options) {
+        const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+        return this._client.post((0, path_1.path) `/v2/conversations/${id}/tags`, {
+            body,
+            ...options,
+            headers: (0, headers_1.buildHeaders)([
+                {
+                    ...(featurebaseVersion?.toString() != null ?
+                        { 'Featurebase-Version': featurebaseVersion?.toString() }
+                        : undefined),
+                },
+                options?.headers,
+            ]),
+        });
+    }
+    /**
+     * 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
      * {
-     *   "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"
+     *   "actingAdminId": "507f1f77bcf86cd799439011"
      * }
      * ```
      *
@@ -660,17 +666,19 @@ class Conversations extends resource_1.APIResource {
      *
      * @example
      * ```ts
-     * const conversationPart =
-     *   await client.support.conversations.reply('12345', {
-     *     bodyMarkdown: 'Thank you for your help!',
-     *     messageType: 'reply',
-     *     type: 'contact',
-     *   });
+     * const attachedConversationTag =
+     *   await client.support.conversations.detachTag(
+     *     '67ec1234abcd5678ef901234',
+     *     {
+     *       id: '12345',
+     *       actingAdminId: '507f1f77bcf86cd799439011',
+     *     },
+     *   );
      * ```
      */
-    reply(id, params, options) {
-        const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
-        return this._client.post((0, path_1.path) `/v2/conversations/${id}/reply`, {
+    detachTag(tagID, params, options) {
+        const { id, 'Featurebase-Version': featurebaseVersion, ...body } = params;
+        return this._client.delete((0, path_1.path) `/v2/conversations/${id}/tags/${tagID}`, {
             body,
             ...options,
             headers: (0, headers_1.buildHeaders)([
@@ -777,10 +785,8 @@ class Conversations extends resource_1.APIResource {
         });
     }
     /**
-     * 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.
+     * Adds a reply to an existing conversation. Supports both contact (customer/lead)
+     * and admin replies.
      *
      * ### Path Parameters
      *
@@ -788,92 +794,88 @@ class Conversations extends resource_1.APIResource {
      *
      * ### 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. |
+     * The request body varies based on who is sending the reply:
      *
-     * ### Behavior
+     * #### Contact Reply (customer/lead)
      *
-     * Featurebase resolves the latest taggable reply/message in the conversation and
-     * records the tag attachment against that part so audit metadata remains
-     * deterministic.
+     * | 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 affected tag plus attachment metadata such as `targetPartId`,
-     * `appliedAt`, and `appliedBy`.
+     * Returns the created conversation part object with a **201 Created** status. The
+     * response includes both `bodyHtml` (with signed image URLs) and `bodyMarkdown`
+     * fields.
      *
-     * ### Example Request
+     * ### Example Contact Reply
      *
      * ```json
      * {
-     *   "tagId": "67ec1234abcd5678ef901234",
-     *   "actingAdminId": "507f1f77bcf86cd799439011"
+     *   "type": "contact",
+     *   "userId": "user_123",
+     *   "bodyMarkdown": "Thank you for your help!",
+     *   "messageType": "reply"
      * }
      * ```
      *
-     * ### Version Availability
-     *
-     * This endpoint is only available in API version 2026-01-01.nova and newer.
+     * ### Example Admin Reply
      *
-     * @example
-     * ```ts
-     * const attachedConversationTag =
-     *   await client.support.conversations.attachTag('12345', {
-     *     actingAdminId: '507f1f77bcf86cd799439011',
-     *     tagId: '67ec1234abcd5678ef901234',
-     *   });
+     * ```json
+     * {
+     *   "type": "admin",
+     *   "id": "507f1f77bcf86cd799439011",
+     *   "bodyMarkdown": "I'm happy to help! Here's what you need to do...",
+     *   "messageType": "reply"
+     * }
      * ```
-     */
-    attachTag(id, params, options) {
-        const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
-        return this._client.post((0, path_1.path) `/v2/conversations/${id}/tags`, {
-            body,
-            ...options,
-            headers: (0, headers_1.buildHeaders)([
-                {
-                    ...(featurebaseVersion?.toString() != null ?
-                        { 'Featurebase-Version': featurebaseVersion?.toString() }
-                        : undefined),
-                },
-                options?.headers,
-            ]),
-        });
-    }
-    /**
-     * 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
+     * ### Example Admin Note (Internal)
      *
-     * Returns the affected tag payload with the most relevant attachment metadata
-     * available for that relationship.
+     * ```json
+     * {
+     *   "type": "admin",
+     *   "id": "507f1f77bcf86cd799439011",
+     *   "bodyMarkdown": "Customer seems frustrated, escalating to tier 2.",
+     *   "messageType": "note"
+     * }
+     * ```
      *
-     * ### Example Request
+     * ### Example Response
      *
      * ```json
      * {
-     *   "actingAdminId": "507f1f77bcf86cd799439011"
+     *   "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"
      * }
      * ```
      *
@@ -883,19 +885,17 @@ class Conversations extends resource_1.APIResource {
      *
      * @example
      * ```ts
-     * const attachedConversationTag =
-     *   await client.support.conversations.detachTag(
-     *     '67ec1234abcd5678ef901234',
-     *     {
-     *       id: '12345',
-     *       actingAdminId: '507f1f77bcf86cd799439011',
-     *     },
-     *   );
+     * const conversationPart =
+     *   await client.support.conversations.reply('12345', {
+     *     bodyMarkdown: 'Thank you for your help!',
+     *     messageType: 'reply',
+     *     type: 'contact',
+     *   });
      * ```
      */
-    detachTag(tagID, params, options) {
-        const { id, 'Featurebase-Version': featurebaseVersion, ...body } = params;
-        return this._client.delete((0, path_1.path) `/v2/conversations/${id}/tags/${tagID}`, {
+    reply(id, params, options) {
+        const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+        return this._client.post((0, path_1.path) `/v2/conversations/${id}/reply`, {
             body,
             ...options,
             headers: (0, headers_1.buildHeaders)([
@@ -954,18 +954,53 @@ class Conversations extends resource_1.APIResource {
      * `participant_id`, `company_id`, `created_at`) are still accepted for back-compat
      * but are deprecated — please migrate to camelCase in new code.
      *
-     * | Field                      | Type                                                                        | Operators              |
-     * | -------------------------- | --------------------------------------------------------------------------- | ---------------------- |
-     * | `state`                    | enum (`open` / `closed` / `snoozed`)                                        | `=`, `!=`, `IN`, `NIN` |
-     * | `priority`                 | boolean                                                                     | `=`, `!=`              |
-     * | `adminAssigneeId`          | id or null (unassigned)                                                     | `=`, `!=`, `IN`, `NIN` |
-     * | `teamAssigneeId`           | id or null (unassigned)                                                     | `=`, `!=`, `IN`, `NIN` |
-     * | `brandId`                  | id or null                                                                  | `=`, `!=`, `IN`, `NIN` |
-     * | `tagIds`                   | id (matches any conversation containing this tag)                           | `=`, `!=`, `IN`, `NIN` |
-     * | `userId` / `participantId` | id of a conversation participant                                            | `=`, `!=`, `IN`, `NIN` |
-     * | `companyId`                | company id (matches conversations whose participants belong to the company) | `=`, `!=`, `IN`, `NIN` |
-     * | `mentionedAdminIds`        | admin id                                                                    | `=`, `!=`, `IN`, `NIN` |
-     * | `createdAt`                | unix seconds                                                                | `=`, `>`, `<`          |
+     * | Field                            | Type                                                                        | Operators                                                               |
+     * | -------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+     * | `state`                          | enum (`open` / `closed` / `snoozed`)                                        | `=`, `!=`, `IN`, `NIN`                                                  |
+     * | `priority`                       | boolean                                                                     | `=`, `!=`                                                               |
+     * | `adminAssigneeId`                | id or null (unassigned)                                                     | `=`, `!=`, `IN`, `NIN`                                                  |
+     * | `teamAssigneeId`                 | id or null (unassigned)                                                     | `=`, `!=`, `IN`, `NIN`                                                  |
+     * | `brandId`                        | id or null                                                                  | `=`, `!=`, `IN`, `NIN`                                                  |
+     * | `tagIds`                         | id (matches any conversation containing this tag)                           | `=`, `!=`, `IN`, `NIN`                                                  |
+     * | `userId` / `participantId`       | id of a conversation participant                                            | `=`, `!=`, `IN`, `NIN`                                                  |
+     * | `companyId`                      | company id (matches conversations whose participants belong to the company) | `=`, `!=`, `IN`, `NIN`                                                  |
+     * | `mentionedAdminIds`              | admin id                                                                    | `=`, `!=`, `IN`, `NIN`                                                  |
+     * | `createdAt`                      | unix seconds                                                                | `=`, `>`, `<`                                                           |
+     * | `customAttributes.<attributeId>` | conversation custom attribute (see below)                                   | `=`, `!=`, `IN`, `NIN`; plus `>`, `<`, `>=`, `<=` for `number` / `date` |
+     *
+     * ### Filtering by custom attributes
+     *
+     * Any non-archived conversation custom attribute can be used as a filter field via
+     * `customAttributes.<attributeId>`, where `<attributeId>` is the attribute's `id`
+     * from `GET /v2/conversation_attributes`. The accepted value shape follows the
+     * attribute's `fieldSubType`:
+     *
+     * - `select` / `multi-select` — pass an option **label** (e.g.
+     *   `"Product question"`) or an option **id**; both are matched interchangeably,
+     *   and id-based filters keep working after options are renamed
+     * - `text` — string
+     * - `number` — number; range operators (`>`, `<`, `>=`, `<=`) are supported
+     * - `date` — ISO 8601 string or unix seconds; range operators are supported
+     * - `checkbox` — boolean
+     *
+     * Example — all conversations where the "Issue type" select attribute is "Product
+     * question":
+     *
+     * ```json
+     * {
+     *   "query": {
+     *     "field": "customAttributes.6863d3fca1234b0d5e15c86c",
+     *     "operator": "=",
+     *     "value": "Product question"
+     *   },
+     *   "include": ["customAttributeDefinitions"]
+     * }
+     * ```
+     *
+     * Referencing an attribute id that does not exist (or has been archived) returns a
+     * `field_unknown` error. Set `include` to `["customAttributeDefinitions"]` to get
+     * each returned conversation's attribute values resolved with names and types
+     * alongside the ID-keyed `customAttributes` map.
      *
      * For unbounded fields a query consisting only of `!=` or `NIN` clauses is
      * rejected with `query_too_broad` to prevent full-org scans. Combine the negation
@@ -973,6 +1008,16 @@ class Conversations extends resource_1.APIResource {
      * fields (`state`, `priority`) are exempt because their negation is naturally
      * bounded.
      *
+     * ### Inbox visibility
+     *
+     * An open-state filter uses the same visibility rule as the Featurebase dashboard
+     * inbox. Workflow and outbound-message shells are excluded until a customer or
+     * lead interacts with them. As a result, `state = "open"` (or an `IN`/`NIN` filter
+     * that resolves exclusively to open) returns the conversations shown in the
+     * dashboard's open inbox rather than unreplied campaign or automation shells.
+     * Searches without an open-only state filter keep their existing organization-wide
+     * semantics.
+     *
      * ### Pagination
      *
      * Cursor-based, `limit` between 1 and 100 (default 10). Pagination cursors are