Collections

Collection Object

Collections are represented as a JSON object with the following properties

Name	Type	Description
id	integer	The ID of the collection.
name	string	The name of the collection.
created_by	string	ID of the user who created the collection.
config	object	Details about the object can be found here.
emoji_config	object	Details about the object can be found here.
ticketing_config	object	Details about the object can be found here.
csat_config	object	Details about the object can be found here.
created_at	string	The creation timestamp of the collection
updated_at	string	The update timestamp of the collection

Config Object

Config is represented as a JSON object with the following properties

Name	Type	Description
story_detection	boolean	Indicates if story detection is enabled
force_story_request	boolean	Indicates if forcing story request is enabled
auto_assign	object	Object containing auto assign information
responders	array	Array of responder objects. The following two types of objects are possible: { "responder_type": "users", "value": [ "U038DHU0J6A" ] } { "responder_type": "domains", "value": [ "clearfeed.ai" ] }

Emoji Config Object

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

Name	Type	Description
emoji_names	object	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. Each emoji_name object contains: action: Type of action (assign or solved) enabled: Indicates if the action is enabled action_config: Object with configuration settings "action_config": { "apply_on_request_channel": "boolean" }

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	Object containing method information. emoji: Name of the emoji used (if method is emoji) type: Type of method ("emoji" or "automatic")

CSAT Config Object

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

Name	Type	Description
enabled	boolean	Indicates if the feature is enabled
trigger_rules	array	Array of trigger rules. If there are no rules selected, then CSAT will be triggered for all REQUESTS. Current possible rules are : {"name" : "tickets_only"}
trigger_type	string	Type of trigger (automatic or manual)
survey_config	object	Object containing survey configuration information survey_type: Type of survey (e.g., five_point_rating)

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.

Name	Type	Description
id	string	ID of the monitored channel
owner	string	User ID of the primary individual responsible for the channel
name	string	Name of the channel
status	enum	Denotes the status of the channel in the collection. Possible values: active: Channel belongs to the collection and is being actively monitored. processing: Channel was added to the collection and last few messages of the channel are being processed. inactive: Channel belongs to the collection but is not being monitored.

Get Collections

GET https://api.clearfeed.app/v1/rest/collections

Get all collections in your account

Query Parameters

Name	Type	Description
include?	'channels'	Use the include query parameter to include more data for each collection.

200

{
  "collections": [
    {
      "id": 1,
      "name": "premium customers",
      "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"
        }
      ]
    }
  ]
}

403: Forbidden Permission denied

Add Channels to a Collection

POST https://api.clearfeed.app/v1/rest/collections/:id/channels

Start monitoring channels by adding them to a collection.

Path Parameters

Name	Type	Description
id*	Number	ID of the collection to which the channels should be added. Warning: This should be the ID returned by the Get Collections API - and not IDs referenced in ClearFeed Webapp URLs

Channel Object

Name	Type	Description
id*	string	Slack Channel ID of the channel that needs to be added to the collection. See the conversations.list Slack API
owner	string	Slack User ID of the primary individual responsible for the channel.

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 to determine which version you are using.

Name	Type	Description
id*	string	Slack Channel ID of the channel that needs to be added to the collection. See the conversations.list Slack API
customer	object	Customer association for the channel. See Customer Object 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.

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

Name	Type	Description
type*	string	Must be set to "existing"
id*	number	The ID of the existing customer (customer secondary_id). Must be a positive integer.

New Customer Object

Name	Type	Description
type*	string	Must be set to "new"
owner	string	Owner to assign to the new customer record. This will be used as the customer owner during creation. If this field is not provided, we'll set the user calling the API as the owner of the newly created customer object.
domains	array	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.

Sample Payload Format

For Standard (Channel-Based) Management accounts:

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

For Customer-Centric Inbox accounts:

Example 1: Link channel to existing customer

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

Example 2: Create new customer

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

Example 3: Create new customer without domains

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

Request Body

Name	Type	Description
channels*	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.

201: Created Channels successfully added to collections

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

406: Not Acceptable