# Conversation Attributes

## List conversation custom attributes

**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.

### Query Parameters

- `includeArchived: optional boolean or "true" or "false"`

  Include archived conversation custom attributes in the response.

  - `boolean`

  - `"true" or "false"`

    - `"true"`

    - `"false"`

### Header Parameters

- `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"`

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

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

### Returns

- `data: array of 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" or "number" or "boolean" or 3 more`

    Storage-level data type used for validation and search.

    - `"string"`

    - `"number"`

    - `"boolean"`

    - `"date"`

    - `"array"`

    - `"object"`

  - `fieldSubType: "text" or "number" or "select" or 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: optional string`

    ISO timestamp when the attribute was created.

  - `options: optional array of ConversationAttributeOption`

    Allowed values for select and multi-select attributes.

    - `label: string`

      Option display label

    - `id: optional string`

      Option unique identifier when stored for this option.

  - `updatedAt: optional string`

    ISO timestamp when the attribute was last updated.

- `nextCursor: string`

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

- `object: "list"`

  Object type identifier

  - `"list"`

### Example

```http
curl https://do.featurebase.app/v2/conversation_attributes \
    -H "Authorization: Bearer $FEATUREBASE_API_KEY"
```

#### 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

**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.

### Path Parameters

- `id: string`

  Conversation custom attribute unique identifier

### Header Parameters

- `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"`

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

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

### Returns

- `ConversationAttribute object { id, archived, dataType, 7 more }`

  - `id: string`

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

  - `archived: boolean`

    Whether this definition has been archived.

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

    Storage-level data type used for validation and search.

    - `"string"`

    - `"number"`

    - `"boolean"`

    - `"date"`

    - `"array"`

    - `"object"`

  - `fieldSubType: "text" or "number" or "select" or 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: optional string`

    ISO timestamp when the attribute was created.

  - `options: optional array of ConversationAttributeOption`

    Allowed values for select and multi-select attributes.

    - `label: string`

      Option display label

    - `id: optional string`

      Option unique identifier when stored for this option.

  - `updatedAt: optional string`

    ISO timestamp when the attribute was last updated.

### Example

```http
curl https://do.featurebase.app/v2/conversation_attributes/$ID \
    -H "Authorization: Bearer $FEATUREBASE_API_KEY"
```

#### 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 object { id, archived, dataType, 7 more }`

  - `id: string`

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

  - `archived: boolean`

    Whether this definition has been archived.

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

    Storage-level data type used for validation and search.

    - `"string"`

    - `"number"`

    - `"boolean"`

    - `"date"`

    - `"array"`

    - `"object"`

  - `fieldSubType: "text" or "number" or "select" or 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: optional string`

    ISO timestamp when the attribute was created.

  - `options: optional array of ConversationAttributeOption`

    Allowed values for select and multi-select attributes.

    - `label: string`

      Option display label

    - `id: optional string`

      Option unique identifier when stored for this option.

  - `updatedAt: optional string`

    ISO timestamp when the attribute was last updated.

### Conversation Attribute Option

- `ConversationAttributeOption object { label, id }`

  - `label: string`

    Option display label

  - `id: optional string`

    Option unique identifier when stored for this option.

### Conversation Attribute List Response

- `ConversationAttributeListResponse object { data, nextCursor, object }`

  - `data: array of 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" or "number" or "boolean" or 3 more`

      Storage-level data type used for validation and search.

      - `"string"`

      - `"number"`

      - `"boolean"`

      - `"date"`

      - `"array"`

      - `"object"`

    - `fieldSubType: "text" or "number" or "select" or 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: optional string`

      ISO timestamp when the attribute was created.

    - `options: optional array of ConversationAttributeOption`

      Allowed values for select and multi-select attributes.

      - `label: string`

        Option display label

      - `id: optional string`

        Option unique identifier when stored for this option.

    - `updatedAt: optional string`

      ISO timestamp when the attribute was last updated.

  - `nextCursor: string`

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

  - `object: "list"`

    Object type identifier

    - `"list"`