# Conversation Attributes

## List conversation custom attributes

`client.conversationAttributes.list(ConversationAttributeListParamsparams?, RequestOptionsoptions?): ConversationAttributeListResponse`

**get** `/v2/conversation_attributes`

Returns conversation custom attribute definitions configured in your organization.

Conversation payloads expose `customAttributes` keyed by stable attribute IDs. Use this endpoint to map those IDs to display names, identifiers, data types, field subtypes, and select options.

By default, archived definitions are excluded. Set `includeArchived=true` to include archived definitions.

### Parameters

- `params: ConversationAttributeListParams`

  - `includeArchived?: boolean | "true" | "false"`

    Query param: Include archived conversation custom attributes in the response.

    - `boolean`

    - `"true" | "false"`

      - `"true"`

      - `"false"`

  - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"`

    Header param: API version for this request. Defaults to your organization's configured API version if not specified.

    - `"2026-01-01.nova"`

    - `"2025-12-12.clover"`

### Returns

- `ConversationAttributeListResponse`

  - `data: Array<ConversationAttribute>`

    Array of conversation custom attribute definitions.

    - `id: string`

      Stable machine identifier used as the key in conversation.customAttributes.

    - `archived: boolean`

      Whether this definition has been archived.

    - `dataType: "string" | "number" | "boolean" | 3 more`

      Storage-level data type used for validation and search.

      - `"string"`

      - `"number"`

      - `"boolean"`

      - `"date"`

      - `"array"`

      - `"object"`

    - `fieldSubType: "text" | "number" | "select" | 3 more`

      Conversation field subtype that controls the expected value shape.

      - `"text"`

      - `"number"`

      - `"select"`

      - `"multi-select"`

      - `"checkbox"`

      - `"date"`

    - `identifier: string`

      Stable internal identifier for the attribute definition.

    - `name: string`

      Human-readable attribute name shown in Featurebase.

    - `object: "conversation_attribute"`

      Object type identifier

      - `"conversation_attribute"`

    - `createdAt?: string`

      ISO timestamp when the attribute was created.

    - `options?: Array<ConversationAttributeOption>`

      Allowed values for select and multi-select attributes.

      - `label: string`

        Option display label

      - `id?: string`

        Option unique identifier when stored for this option.

    - `updatedAt?: string`

      ISO timestamp when the attribute was last updated.

  - `nextCursor: string | null`

    Cursor for fetching the next page. Always null; all definitions are returned at once.

  - `object: "list"`

    Object type identifier

    - `"list"`

### Example

```typescript
import Featurebase from 'featurebase-node';

const client = new Featurebase({
  apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted
});

const conversationAttributes = await client.conversationAttributes.list();

console.log(conversationAttributes.data);
```

#### Response

```json
{
  "data": [
    {
      "id": "65d26304b2e65b1e1278170c",
      "archived": false,
      "dataType": "number",
      "fieldSubType": "number",
      "identifier": "conversations.customFields.Minutes_to_Resolve",
      "name": "Minutes to Resolve",
      "object": "conversation_attribute",
      "createdAt": "2026-06-09T16:00:19.000Z",
      "options": [
        {
          "label": "Enterprise",
          "id": "65d26304b2e65b1e1278170d"
        }
      ],
      "updatedAt": "2026-06-09T16:00:19.000Z"
    }
  ],
  "nextCursor": null,
  "object": "list"
}
```

## Get a conversation custom attribute by ID

`client.conversationAttributes.retrieve(stringid, ConversationAttributeRetrieveParamsparams?, RequestOptionsoptions?): ConversationAttribute`

**get** `/v2/conversation_attributes/{id}`

Retrieves a single conversation custom attribute definition by its stable ID.

Use this when a conversation response contains a `customAttributes` key and you need the corresponding display name, identifier, data type, field subtype, or options.

### Parameters

- `id: string`

  Conversation custom attribute unique identifier

- `params: ConversationAttributeRetrieveParams`

  - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"`

    API version for this request. Defaults to your organization's configured API version if not specified.

    - `"2026-01-01.nova"`

    - `"2025-12-12.clover"`

### Returns

- `ConversationAttribute`

  - `id: string`

    Stable machine identifier used as the key in conversation.customAttributes.

  - `archived: boolean`

    Whether this definition has been archived.

  - `dataType: "string" | "number" | "boolean" | 3 more`

    Storage-level data type used for validation and search.

    - `"string"`

    - `"number"`

    - `"boolean"`

    - `"date"`

    - `"array"`

    - `"object"`

  - `fieldSubType: "text" | "number" | "select" | 3 more`

    Conversation field subtype that controls the expected value shape.

    - `"text"`

    - `"number"`

    - `"select"`

    - `"multi-select"`

    - `"checkbox"`

    - `"date"`

  - `identifier: string`

    Stable internal identifier for the attribute definition.

  - `name: string`

    Human-readable attribute name shown in Featurebase.

  - `object: "conversation_attribute"`

    Object type identifier

    - `"conversation_attribute"`

  - `createdAt?: string`

    ISO timestamp when the attribute was created.

  - `options?: Array<ConversationAttributeOption>`

    Allowed values for select and multi-select attributes.

    - `label: string`

      Option display label

    - `id?: string`

      Option unique identifier when stored for this option.

  - `updatedAt?: string`

    ISO timestamp when the attribute was last updated.

### Example

```typescript
import Featurebase from 'featurebase-node';

const client = new Featurebase({
  apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted
});

const conversationAttribute = await client.conversationAttributes.retrieve(
  '65d26304b2e65b1e1278170c',
);

console.log(conversationAttribute.id);
```

#### Response

```json
{
  "id": "65d26304b2e65b1e1278170c",
  "archived": false,
  "dataType": "number",
  "fieldSubType": "number",
  "identifier": "conversations.customFields.Minutes_to_Resolve",
  "name": "Minutes to Resolve",
  "object": "conversation_attribute",
  "createdAt": "2026-06-09T16:00:19.000Z",
  "options": [
    {
      "label": "Enterprise",
      "id": "65d26304b2e65b1e1278170d"
    }
  ],
  "updatedAt": "2026-06-09T16:00:19.000Z"
}
```

## Domain Types

### Conversation Attribute

- `ConversationAttribute`

  - `id: string`

    Stable machine identifier used as the key in conversation.customAttributes.

  - `archived: boolean`

    Whether this definition has been archived.

  - `dataType: "string" | "number" | "boolean" | 3 more`

    Storage-level data type used for validation and search.

    - `"string"`

    - `"number"`

    - `"boolean"`

    - `"date"`

    - `"array"`

    - `"object"`

  - `fieldSubType: "text" | "number" | "select" | 3 more`

    Conversation field subtype that controls the expected value shape.

    - `"text"`

    - `"number"`

    - `"select"`

    - `"multi-select"`

    - `"checkbox"`

    - `"date"`

  - `identifier: string`

    Stable internal identifier for the attribute definition.

  - `name: string`

    Human-readable attribute name shown in Featurebase.

  - `object: "conversation_attribute"`

    Object type identifier

    - `"conversation_attribute"`

  - `createdAt?: string`

    ISO timestamp when the attribute was created.

  - `options?: Array<ConversationAttributeOption>`

    Allowed values for select and multi-select attributes.

    - `label: string`

      Option display label

    - `id?: string`

      Option unique identifier when stored for this option.

  - `updatedAt?: string`

    ISO timestamp when the attribute was last updated.

### Conversation Attribute Option

- `ConversationAttributeOption`

  - `label: string`

    Option display label

  - `id?: string`

    Option unique identifier when stored for this option.

### Conversation Attribute List Response

- `ConversationAttributeListResponse`

  - `data: Array<ConversationAttribute>`

    Array of conversation custom attribute definitions.

    - `id: string`

      Stable machine identifier used as the key in conversation.customAttributes.

    - `archived: boolean`

      Whether this definition has been archived.

    - `dataType: "string" | "number" | "boolean" | 3 more`

      Storage-level data type used for validation and search.

      - `"string"`

      - `"number"`

      - `"boolean"`

      - `"date"`

      - `"array"`

      - `"object"`

    - `fieldSubType: "text" | "number" | "select" | 3 more`

      Conversation field subtype that controls the expected value shape.

      - `"text"`

      - `"number"`

      - `"select"`

      - `"multi-select"`

      - `"checkbox"`

      - `"date"`

    - `identifier: string`

      Stable internal identifier for the attribute definition.

    - `name: string`

      Human-readable attribute name shown in Featurebase.

    - `object: "conversation_attribute"`

      Object type identifier

      - `"conversation_attribute"`

    - `createdAt?: string`

      ISO timestamp when the attribute was created.

    - `options?: Array<ConversationAttributeOption>`

      Allowed values for select and multi-select attributes.

      - `label: string`

        Option display label

      - `id?: string`

        Option unique identifier when stored for this option.

    - `updatedAt?: string`

      ISO timestamp when the attribute was last updated.

  - `nextCursor: string | null`

    Cursor for fetching the next page. Always null; all definitions are returned at once.

  - `object: "list"`

    Object type identifier

    - `"list"`