Channel Users

Overview

Using the Team Channel Users endpoint you are able to add and remove individual users from a channel. If you wish to set the entire list of users for a channel use the Team Channels endpoint.

Get Channel Users

Get all users that belong to a specified channel

GET /channels/{channel_id}/users

Pagination

The maximum number of users that will be returned in a single request is 100. If there are more than 100 users you can specify a page parameter great than 1 to get more data. The response will contain information about how many pages of data are available.

Query Parameters

Parameter	Default	Description
page	1	Specifies which page of results to return
per_page	100	Specifies maximum number of channels to return in a given request. The maximum you can specify is 100.

Success Response

A successful response will have an HTTP status of 200

Response Properties

Property	Description
page	Current page number of data returned
per_page	Maximum number of users returned per page
total_pages	Number of pages of data available
response_count	The number of users that were returned from the given request
total_count	Total number of users that are available
channel	Information about the specified channel
users	Collection of users

Example response

The sample response below indicates that you have received the second page of results. There are 2 pages available. The current page contains 21 of the total 121 channels.

{
    "page": 2,
    "per_page": 100,
    "total_pages": 2,
    "response_count": 21,
    "total_count": 121,
    "channel": {
        "id": "chat.team.e3a07dfc-d8a3-40b9-ab1e-530aa3791396",
        "name": "Parking Security"
    },
    "users": [
      {...},
      {...}
    ]
}

Add a Channel User

PUT /channels/{channel_id}/users

Path Parameters

Parameter	Description
channel_id	Id of the channel you are adding a user to.

Body Parameters

Parameter	Required	Description
id	Yes	Id of the user you are adding to the channel

Example Request Body

{
   "id": "d4fa7488-7a58-4bd0-956a-9f8c5b0a87f1"
}

Success Response

A successful channel user add response will have an HTTP status of 200. The payload of the response is the same as you will see when requesting information about a specific user.

Error Response

If there was a problem creating the channel user you will receive a response that contains status and message properties.

Example error response:

{
    "status": 422,
    "message": {
        "error": "Invalid Users",
        "invalid_user_ids": [
            "my-bogus-id"
        ]
    }
}

Remove a Channel User

Remove a specified user from a specified channel

DELETE /channels/{channel_id}/users/{user_id}

Path Parameters

Parameter	Description
channel_id	Id of the channel you are removing a user to.
user_id	Id of the user you wish to remove from the channel.

Success Response

A successful channel creation response will have an HTTP status of 200. The payload of the response is the same as you will see when requesting information about a specific user.

Replace Channel Users

Use this endpoint to set a channel to include a specific set of users. Any current channel users that are not specified in your request body will be removed from the channel.

PUT /channels/{channel_id}/users/replace

Path Parameters

Parameter	Description
channel_id	Id of the channel in which you are replacing users on.

Body Parameters

Parameter	Required	Description
users	Yes	Array of user objects. Each user object must contain and id. Example: [{id:123456}, {id: 98765}]

Example Request Body

{
   "users": [
        {"id": "d4fa7488-7a58-4bd0-956a-9f8c5b0a87f1"}, 
        {"id": "d13535e5-7ebf-4433-9fd1-90f3de9b6e2d"}, 
        {"id": "fdd21692-7d52-46b5-a01c-6d660a247a31"}
    ]
}

Success Response

A successful channel user replace response will have an HTTP status of 200. The payload of the response is the same as you will see when requesting information about a specific channel.

Error Response

If there was a problem replacing the channel users you will receive a response that contains status and message properties.

Example error response:

{
    "status": 422,
    "message": {
        "error": "Invalid Users",
        "invalid_user_ids": [
            "my-bogus-id"
        ]
    }
}