# Collections

## Collection Object

Collections are represented as a JSON object with the following properties

<table data-full-width="true"><thead><tr><th width="200">Name</th><th width="96.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>integer</td><td>The ID of the collection.</td></tr><tr><td>name</td><td>string</td><td>The name of the collection.</td></tr><tr><td>owner</td><td>string</td><td>ID of the user who is set as the owner of the collection.</td></tr><tr><td>created_by</td><td>string</td><td>ID of the user who created the collection.</td></tr><tr><td>config</td><td>object</td><td>Details about the object can be found <a href="#config-object">here</a>.</td></tr><tr><td>emoji_config</td><td>object</td><td>Details about the object can be found <a href="#emoji-config-object">here</a>.</td></tr><tr><td>ticketing_config</td><td>object</td><td>Details about the object can be found <a href="#ticketing-config-object">here</a>.</td></tr><tr><td>csat_config</td><td>object</td><td>Details about the object can be found <a href="#csat-config-object">here</a>.</td></tr><tr><td>created_at</td><td>string</td><td>The creation timestamp of the collection</td></tr><tr><td>updated_at</td><td>string</td><td>The update timestamp of the collection</td></tr></tbody></table>

## Config Object

Config is represented as a JSON object with the following properties

<table data-full-width="true"><thead><tr><th width="199.33333333333331">Name</th><th width="99">Type</th><th>Description</th></tr></thead><tbody><tr><td>story_detection</td><td>boolean</td><td>Indicates if story detection is enabled</td></tr><tr><td>force_story_request</td><td>boolean</td><td>Indicates if forcing story request is enabled</td></tr><tr><td>auto_assign</td><td>object</td><td>Object containing auto assign information</td></tr><tr><td>responders</td><td>array</td><td><p>Array of responder objects. The following two types of objects are possible:</p><pre class="language-json"><code class="lang-json">{
  "responder_type": "users",
  "value": [
    "U038DHU0J6A"
  ]
}
{
  "responder_type": "domains",
  "value": [
    "clearfeed.ai"
  ]
}
</code></pre></td></tr></tbody></table>

## Emoji Config Object

Emoji Config is represented as a JSON object with the following properties

<table data-full-width="true"><thead><tr><th width="148.33333333333331">Name</th><th width="92">Type</th><th>Description</th></tr></thead><tbody><tr><td>emoji_names</td><td>object</td><td><p>Object containing configuration for all emojis that are set up at the collection level. It has the following properties. For all emojis set up, there will be a key with the same emoji_name, and the value will be the config object for that emoji.</p><p><strong>Each emoji_name object contains:</strong></p><ul><li><strong>action:</strong> Type of action (<code>assign</code> or <code>solved</code>)</li><li><strong>enabled:</strong> Indicates if the action is enabled</li><li><strong>action_config:</strong> Object with configuration settings</li></ul><pre class="language-json"><code class="lang-json">"action_config": {
  "apply_on_request_channel": "boolean"
}
</code></pre></td></tr></tbody></table>

## Ticketing Config Object

Ticket Config is represented as a JSON object with the following properties

| Name        | Type    | Description                                                                                                                                         |
| ----------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| enabled     | boolean | Indicates if the feature is enabled                                                                                                                 |
| integration | string  | The integration being used                                                                                                                          |
| method      | object  | <p>Object containing method information.<br>emoji: Name of the emoji used (if method is emoji)<br>type: Type of method ("emoji" or "automatic")</p> |

## CSAT Config Object

CSAT Config is represented as a JSON object with the following properties

<table data-full-width="true"><thead><tr><th width="164">Name</th><th width="137.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>enabled</td><td>boolean</td><td>Indicates if the feature is enabled</td></tr><tr><td>trigger_rules</td><td>array</td><td>Array of trigger rules. If there are no rules selected, then CSAT will be triggered for all REQUESTS. Current possible rules are :<br><code>{"name" : "tickets_only"}</code></td></tr><tr><td>trigger_type</td><td>string</td><td>Type of trigger (<code>automatic</code> or <code>manual</code>)</td></tr><tr><td>survey_config</td><td>object</td><td>Object containing survey configuration information<br>survey_type: Type of survey (e.g., <code>five_point_rating</code>)</td></tr></tbody></table>

## Channel Object

A channel monitored in a collection is represented as a JSON object with the following properties. It is included in the API when the `include` query parameter is passed with the value `channels`.

<table data-full-width="true"><thead><tr><th width="164">Name</th><th width="156.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>ID of the monitored channel</td></tr><tr><td>owner</td><td>string</td><td>User ID of the primary individual responsible for the channel</td></tr><tr><td>name</td><td>string</td><td>Name of the channel</td></tr><tr><td>status</td><td>enum</td><td><p>Denotes the status of the channel in the collection. Possible values:</p><ul><li><strong>active:</strong> Channel belongs to the collection and is being actively monitored.</li><li><strong>processing:</strong> Channel was added to the collection and last few messages of the channel are being processed.</li><li><strong>inactive:</strong> Channel belongs to the collection but is not being monitored.</li></ul></td></tr><tr><td>customer_id</td><td>number</td><td>ID of the associated customer. Only present for Customer Inbox enabled accounts.</td></tr></tbody></table>

## Get Collections

<mark style="color:blue;">`GET`</mark> `https://api.clearfeed.app/v1/rest/collections`

Get all collections in your account

Query Parameters

<table><thead><tr><th width="118">Name</th><th width="320">Type</th><th>Description</th></tr></thead><tbody><tr><td>include?</td><td><pre class="language-typescript"><code class="lang-typescript">'channels'
</code></pre></td><td>Use the include query parameter to include more data for each collection.</td></tr></tbody></table>

{% tabs %}
{% tab title="200 " %}

```json
{
  "collections": [
    {
      "id": 1,
      "name": "premium customers",
      "owner": "U038DHU0J6A",
      "created_by": "U05HGPBRZJN",
      "created_at": "2023-01-01T00:00:00.000Z",
      "updated_at": "2023-01-01T00:00:00.000Z",
      "config": {
        "story_detection": false,
        "force_story_request": true,
        "auto_assign": {
          "enabled": false
        },
        "responders": [
          {
            "responder_type": "users",
            "value": ["U038DHU0J6A"]
          }
        ]
      },
      "emoji_config": {
        "emoji_names": {
          "eyes": {
            "action": "assign",
            "enabled": true,
            "action_config": {
              "apply_on_request_channel": true
            }
          },
          "white_check_mark": {
            "action": "solved",
            "enabled": true,
            "action_config": {
              "apply_on_request_channel": true
            }
          }
        }
      },
      "csat_config": {
        "enabled": true,
        "trigger_rules": [],
        "trigger_type": "automatic",
        "survey_config": {
          "survey_type": "five_point_rating"
        }
      },
      "ticketing_config": {
        "enabled": true,
        "integration": "zendesk",
        "method": {
          "emoji": "ticket",
          "type": "emoji"
        }
      },
      "channels": [
        {
          "id": "C06ASRDC6R0",
          "owner": "U038DHU0J6A",
          "name": "clearfeed-google",
          "status": "active",
          "customer_id": 123 // Only returned for customer inbox enabled accounts
        }
      ]
    }
  ]
}
```

{% endtab %}

{% tab title="403: Forbidden Permission denied" %}

{% endtab %}
{% endtabs %}

## Add Channels to a Collection

<mark style="color:green;">`POST`</mark> `https://api.clearfeed.app/v1/rest/collections/:id/channels`

Start monitoring channels by adding them to a collection.

#### Path Parameters

<table data-full-width="true"><thead><tr><th width="100">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>id<mark style="color:red;">*</mark></td><td>Number</td><td>ID of the collection to which the channels should be added. <strong>Warning:</strong> This should be the ID returned by the <a data-mention href="#get-collections">#get-collections</a> API - and not IDs referenced in ClearFeed Webapp URLs</td></tr></tbody></table>

#### Channel Object

<table data-full-width="true"><thead><tr><th width="100">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>id<mark style="color:red;">*</mark></td><td>string</td><td>Slack Channel ID of the channel that needs to be added to the collection. See the <a href="https://docs.slack.dev/reference/methods/conversations.list/">conversations.list</a> Slack API</td></tr><tr><td>owner</td><td>string</td><td>Slack User ID of the primary individual responsible for the channel.</td></tr></tbody></table>

For **Customer-Centric Inbox** accounts the channel object looks like the following:

> **How to check if you are on Customer-Centric Inbox:** See [this guide](https://docs.clearfeed.ai/clearfeed-help-center/clearfeed-helpdesk/customers#which-version-am-i-using) to determine which version you are using.

<table data-full-width="true"><thead><tr><th width="100">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>id<mark style="color:red;">*</mark></td><td>string</td><td>Slack Channel ID of the channel that needs to be added to the collection. See the <a href="https://docs.slack.dev/reference/methods/conversations.list/">conversations.list</a> Slack API</td></tr><tr><td>customer</td><td>object</td><td>Customer association for the channel. See <a href="#customer-object">Customer Object</a> below for details. This is optional in this API. When it's not provided, ClearFeed tries to automatically link the newly monitored channel to an existing customer object based on the domains of the users present in the channel. If no existing customer exists with those domains, ClearFeed will create a new customer object and link it to the channel.</td></tr></tbody></table>

#### Customer Object

The customer object that can be passed with the channel object for Customer-Centric Inbox accounts can be one of two types:

**Existing Customer Object**

<table data-full-width="true"><thead><tr><th width="100">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>type<mark style="color:red;">*</mark></td><td>string</td><td>Must be set to <code>"existing"</code></td></tr><tr><td>id<mark style="color:red;">*</mark></td><td>number</td><td>The ID of the existing customer (customer secondary_id). Must be a positive integer.</td></tr></tbody></table>

**New Customer Object**

<table data-full-width="true"><thead><tr><th width="100">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>type<mark style="color:red;">*</mark></td><td>string</td><td>Must be set to <code>"new"</code></td></tr><tr><td>owner</td><td>string | null</td><td>Owner to assign to the new customer record. This will be used as the customer owner during creation. Can be null. If null or not provided, the system will use the owner of the collection that this customer belongs to.</td></tr><tr><td>domains</td><td>array</td><td>List of email domains associated with this customer. Must be valid FQDN (Fully Qualified Domain Names). Free domains (e.g., gmail.com, yahoo.com) are not allowed. Defaults to an empty array if not provided.</td></tr></tbody></table>

#### Sample Payload Format

**For Standard (Channel-Based) Management accounts:**

```json
{
  "channels": [
    {
      "id": "C01AB2CD1T",
      "owner": "U038DHU0J6A"
    },
    {
      "id": "C02EF3GH2X"
    }
  ]
}
```

**For Customer-Centric Inbox accounts:**

**Example 1: Link channel to existing customer**

```json
{
  "channels": [
    {
      "id": "C01AB2CD1T",
      "customer": {
        "type": "existing",
        "id": 123
      }
    }
  ]
}
```

**Example 2: Create new customer**

```json
{
  "channels": [
    {
      "id": "C02EF3GH2X",
      "customer": {
        "type": "new",
        "domains": ["acme.com", "acmecorp.com"]
      }
    }
  ]
}
```

**Example 3: Create new customer without domains**

```json
{
  "channels": [
    {
      "id": "C03HI4JKL5Y",
      "customer": {
        "type": "new"
      }
    }
  ]
}
```

#### Request Body

| Name                                       | Type  | Description                                                                                                                                                                                                                    |
| ------------------------------------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| channels<mark style="color:red;">\*</mark> | Array | This will be an array of channel objects. For Standard accounts, each object contains a Channel ID `id` and optional `owner`. For Customer-Centric Inbox accounts, each object must also include a required `customer` object. |

{% tabs %}
{% tab title="201: Created Channels successfully added to collections " %}

```json
{
  "channels": [
    {
      "id": "C0A9T968PGT",
      "owner": "U0924MZ1QBZ", // Only returned in case of Standard (Channel-Based) Management accounts
      "name": "abcdef",
      "status": "processing",
      "customer_id": 123
    }
  ]
}
```

{% endtab %}

{% tab title="406: Not Acceptable" %}
Returned if channels cannot be added. This can happen if:

* A channel does not exist in the workspace
* A channel exists but is private and not visible to ClearFeed

If any channel in the request cannot be added (e.g., doesn't exist or isn't accessible), the entire request will fail with a 406 error and no channels will be added.
{% endtab %}
{% endtabs %}