Groups

Overview

Groups are the standard form of interacting within the Cotalker environment and are primarily accessed through the Main Menu Bar and Group Panel.

Group types:

• Standard groups contain channels used for communicating with other users.
• Workflow or Task groups, like standard groups, have communication channels but are associated with workflow tasks and their states.
• Link groups direct you to anywhere within or outside the Cotalker environment.
• Category groups bring together other groups to form sub-menus on the Main Menu Bar.

Get Groups

Returns all channels within the company.

GET /groups

Endpoint URL

https://www.cotalker.com/api/v2/groups

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN

Query Parameters

Parameter	Description	Type	Required	Notes
created	Returns groups with the indicated creation date in the createdAt field.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
created_gt	Returns groups created after the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
created_gte	Returns groups with a value in the createdAt field equal to or greater than the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
created_lt	Returns groups created before the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
created_lte	Returns groups with a value in the createdAt field equal to or less than the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
count	Adds the counter field with the total amount of groups within the company.	boolean	Optional
groupType	Returns groups specified by type.	string	Optional	Available values: link (link groups), task (workflow or task groups), and channel (standard groups)
hasCatergories	Filters category groups, i.e., groups displayed in sub-menus on the Main Menu Bar.	boolean	Optional	true displays categorized groups. false displays uncategorized groups.
isActive	Returns groups according to their isActive status.	string	Optional	Options are: all, true, false
isLink	Returns all link groups found in the company.	boolean	Optional
isTaskGroup	Returns all task groups found in the company.	boolean	Optional
debug	Adds the debug field with error notifications.	string	Optional	Option: true
limit	Limits the amount of groups returned in the response.	number	Optional	By default, the limit is set to 10.
modified	Returns groups with the indicated modification date in the modifiedAt field.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
modified_gt	Returns groups modified after the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
modified_gte	Returns groups with a value in the modifiedAt field equal to or greater than the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
orderBy	Orders the groups by ascendeing or descending order according to their modifiedAt field.	string	Optional	Options: asc, desc
page	Makes the response display data from the indicated page number.	number	Optional	Best used in combination with the "limit" parameter.
sortBy	Sorts groups in the response according to the modifiedAt field.	string	Optional	modifiedAt is the only value available.
search	Returns groups that match the keywords in the groups.search field array.	string	Optional

Request Samples

cURL (default)

This default request gets all the groups in the company.

curl --location --request GET 'https://www.cotalker.com/api/v2/groups' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

cURL (query)

This example uses the groupType query parameter to get all task groups within the company.

curl --location --request GET 'https://www.cotalker.com/api/v2/groups?groupType=task' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

Typescript (default)

This example gets all groups in the company.

// $ACCESS_TOKEN stored in .env file.
import { Configuration, GroupGetCollection, V2GroupsApi } from "@cotalker/cotalker-api";

const api = new V2GroupsApi(new Configuration({
    basePath: 'https://www.cotalker.com/api',
    accessToken: process.env.ACCESS_TOKEN,
}));

async function getGroups(): Promise<GroupGetCollection | undefined> {
    const response = await api.getV2Groups();
    return response.data?.data;
}

getGroups().then(groups => console.log(groups)).catch(e=>console.log(e))

Response Sample

Responses follow the COTGroup data model.

---

Get a Group by Id

Returns the group indicated by the Id.

GET /groups/{id}

Endpoint URL

https://www.cotalker.com/api/v2/groups/{id}

Path Parameters

Parameter	Description	Type	Required	Notes
id	The ObjectId of the group that is to be returned.	ObjectId<COTGroup>	Required

Headers

Header	Description	Required	Values
Admin	Grants access to request the endpoint.	Required	true
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN

Query Parameters

Parameter	Description	Type	Required	Notes
debug	Adds the debug field with error notifications.	string	Optional	Option: true

Request Sample

curl --location --request GET 'https://www.cotalker.com/api/v2/groups/618a9a1c881d93046349c820' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

Response Sample

The response follows the COTGroup data model.

---

Create a New Group

Creates a new group within the company.

POST /groups

Endpoint URL

https://www.cotalker.com/api/v2/groups

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
Admin	Grants administrative access to create a group.	Required	true
Content-Type	Indicates the body's format.	Required	application/json

Query Parameters

Parameter	Description	Type	Required	Notes
debug	Adds the debug field with error notifications.	string	Optional	Option: true

Request Body

Only required fields are listed below. For a complete schema description, please go to the COTGroup data model. Unrequired fields that are not submitted are either filled in automatically or left blank.

Element	Description	Type	Required	Notes
nameDisplay	The Group name users will see on the platform.	string	Required
nameCode	The group's unique identification name.	string	Required	Maximum 60 characters; only lowercase letters, numbers, and underscores allowed; must be unique.

Request Sample

Channel created with the minimum required fields:

curl --location --request POST 'https://www.cotalker.com/api/v2/groups' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "nameDisplay": "The Best Group Ever!",
    "nameCode": "best_group"
}'

Response Sample

Go to COTGroup for a complete description of the response.

{
    "apperance": {
        "textColor": "#ffffff"
    },
    "image": {
        "icon": "https://placeholdit.imgix.net/~text?txtsize=50&bg=ffeeeetxtclr=bbcccc&txt=i%20CoTalker&w=20&h=20"
    },
    "createChannels": {
        "requiredPermission": [],
        "requiredPermissionsV2": [],
    },
    "link": {
        "requiredPermission": [],
        "requiredPermissionsV2": []
    },
    "isActive": true,
    "color": "#000000",
    "search": [
        "the",
        "best",
        "group",
        "ever"
    ],
    "hideChannelsByProperties": [],
    "channelsWithoutCategoryLocation": "top",
    "groupSort": "a-z",
    "groupSortDirection": "asc",
    "innerSort": "lastMessage",
    "innerSortDirection": "desc",
    "_id": "619e51fee8b60a63b678aa94",
    "nameDisplay": "The Best Group Ever!",
    "nameCode": "best_group",
    "company": "619e51f3e7e198f18fe56a01",
    "createdAt": "2021-11-24T14:11:26.195Z",
    "actions": [],
    "modifiedAt": "2021-11-24T14:11:26.199Z",
    "weight": 135,
    "__v": 0
}

---

Update a Group

Updates or edits an existing channel's information.

PATCH /groups/{id}

Endpoint URL

https://www.cotalker.com/api/v2/groups/{id}

Path Parameters

Parameter	Description	Type	Required	Notes
id	The ObjectId of the group that is to be modified.	ObjectId<COTGroup>	Required

Headers

Header	Description	Required	Values
Admin	Grants administrative access to modify a group.	Required	true
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
Content-Type	Sets the body's format.	Required	application/json

Query Parameters

Parameter	Description	Type	Required	Notes
debug	Adds the debug field with error notifications.	string	Optional	Option: true

Request Body

Only the fields that are being updated or added are required to be put into the body. For a complete schema description, please go to the COTGroup data model.

Request Sample

Updating a group's channel creation settings:

curl --location --request PATCH 'https://www.cotalker.com/api/v2/groups/619e51fee8b60a63b678aa94' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "createChannels": {
        "active": true,
        "requiredPermissionsV2": [
            "admin-groups-write"
        ]
    }
}'

Response Sample

Go to COTGroup for a complete description of the response.

{
    "apperance": {
        "textColor": "#ffffff"
    },
    "image": {
        "icon": "https://placeholdit.imgix.net/~text?txtsize=50&bg=ffeeeetxtclr=bbcccc&txt=i%20CoTalker&w=20&h=20"
    },
    "createChannels": {
        "requiredPermission": [],
        "requiredPermissionsV2": [
            "admin-groups-write"
        ],
        "active": true
    },
    "link": {
        "requiredPermission": [],
        "requiredPermissionsV2": []
    },
    "isActive": true,
    "color": "#000000",
    "search": [
        "the",
        "best",
        "group",
        "ever"
    ],
    "hideChannelsByProperties": [],
    "channelsWithoutCategoryLocation": "top",
    "groupSort": "a-z",
    "groupSortDirection": "asc",
    "innerSort": "lastMessage",
    "innerSortDirection": "desc",
    "_id": "619e51fee8b60a63b678aa94",
    "nameDisplay": "The Best Group Ever!",
    "nameCode": "best_group",
    "company": "619e51f3e7e198f18fe56a01",
    "createdAt": "2021-11-24T14:11:26.195Z",
    "actions": [],
    "modifiedAt": "2021-11-24T14:11:26.199Z",
    "weight": 135,
    "__v": 0
}

---