Select your Platform:
Querying Channels
Confused about "Querying Channels"?
Let us know how we can improve our documentation:
If you’re building a similar application to Facebook Messenger or Intercom, you’ll want to show a list of Channels. The Chat API supports MongoDB style queries to make this easy to implement.
You can query channels based on built-in fields as well as any custom field you add to channels. You can find the complete list of supported operators in the query syntax section of the docs.
Multiple filters can be combined, but more complex filters can increase the latency of this API, particularly with custom fields. Reach out to support if you have any doubts about your query filter or logic.
As an example, let's say that you want to query the last conversations I participated in sorted by last_message_at.
Here’s an example of how you can query the list of channels:
Query Parameters
Copied!Confused about "Query Parameters"?
Let us know how we can improve our documentation:
| name | type | description | default | optional |
|---|---|---|---|---|
| filters | object | The query filters to use. You can query on any of the custom fields you've defined on the Channel. You can also filter other built-in channel fields, see next section for reference. | {} | |
| sort | object or array of objects | The sorting used for the channels matching the filters. Sorting is based on field and direction, multiple sorting options can be provided. You can sort based on last_updated, last_message_at, updated_at, created_at, member_count, unread_count or has_unread(unread status). Direction can be ascending (1) or descending (-1) | [{last_updated: -1}] | |
| options | object | Query options. See below. | {} |
filter should include members: { $in: [userID] } . The query channels endpoint will only return channels that the user can read, you should make sure that the query uses a filter that includes such logic. For example: messaging channels are readable only to their members, such requirement can be included in the query filter (see below).
Common filters by use-case
Copied!Confused about "Common filters by use-case"?
Let us know how we can improve our documentation:
Messaging and Team
Copied!On messaging and team applications you normally have users added to channels as a member. A good starting point is to use this filter to show the channels the user is participating.
Support
Copied!On a support chat, you probably want to attach additional information to channels such as the support agent handling the case and other information regarding the status of the support case (ie. open, pending, solved).
Channel Queryable Built-In Fields
Copied!Confused about "Channel Queryable Built-In Fields"?
Let us know how we can improve our documentation:
The following channel fields can be used to filter your query results.
Name | Type | Description | Supported Operators | EXAMPLE |
|---|---|---|---|---|
frozen | boolean | channel frozen status | $eq | false |
type | string or list of string | the type of channel | $in, $eq | messaging |
id | string or list of string | the ID of the channel | $in, $eq | general |
cid | string or list of string | the full channel ID | $in, $eq | messaging:general |
members | string or list of string | the list of user IDs of the channel members | $in, $eq | marcelo or [thierry, marcelo] |
invite | string, must be one of these values: (pending, accepted, rejected) | the status of the invite | $eq | pending |
joined | boolean | whether current user is joined the channel or not (through invite or directly) | $eq | true |
muted | boolean | whether the current user has muted the channel | $eq | true |
member.user.name | string | the 'name' property of a user who is a member of the channel | $autocomplete, $eq | marc |
created_by_id | string | the id of the user that created the channel | $eq | marcelo |
hidden | boolean | whether the current user has hidden the channel | $eq | false |
last_message_at | string, must be formatted as an RFC3339 timestamp | the time of the last message in the channel | $eq, $gt, $lt, $gte, $lte, $exists | 2021-01-15T09:30:20.45Z |
member_count | integer | the number of members in the channel | $eq, $gt, $lt, $gte, $lte | 5 |
created_at | string, must be formatted as an RFC3339 timestamp | the time the channel was created | $eq, $gt, $lt, $gte, $lte $exists | 2021-01-15T09:30:20.45Z |
updated_at | string, must be formatted as an RFC3339 timestamp | the time the channel was updated | $eq, $gt, $lt, $gte, $lte | 2021-01-15T09:30:20.45Z |
team | string | the team associated with the channel | $eq | stream |
last_updated | string, must be formatted as an RFC3339 timestamp | the time of the last message in the channel. If the channel has no messages, then the time the channel was created | $eq, $gt, $lt, $gte, $lte | 2021-01-15T09:30:20.45Z |
Disabled | boolean | Whether the channel is disabled or not. | $eq | false |
has_unread | boolean | Retrieve channels where the user has an unread message. Only "true" is supported, up to 100 channels | true | true |
cid field as far as possible to optimize API performance. As the full channel ID, cidis indexed everywhere in Stream database where id is not.Query Options
Copied!Confused about "Query Options"?
Let us know how we can improve our documentation:
| name | type | description | default | optional |
|---|---|---|---|---|
| state | boolean | if true returns the Channel state | true | ✓ |
| watch | boolean | if true listen to changes to this Channel in real time. | true | ✓ |
| limit | integer | The number of channels to return (max is 30) | 10 | ✓ |
| offset | integer | The offset (max is 1000) | 0 | ✓ |
| message_limit | integer | How many messages should be included to each channel (Max 300) | 25 | ✓ |
| member_limit | integer | How many members should be included for each channel (Max 100) | 100 | ✓ |
Query channels allows you to retrieve channels and start watching them at same time using the watch parameter set to true.
Response
Copied!Confused about "Response"?
Let us know how we can improve our documentation:
The result of querying a channel is a list of ChannelState objects which include all the required information to render them without any additional API call.
ChannelState Response
Copied!Field Name | Description |
|---|---|
channel | The data for this channel |
messages | The most recent messages for this channel (see message_limit option) |
watcher_count | How many users are currently watching the channel |
read | The read state for all members of the channel |
members | The list of members, up to 100 ordered by the most recent added |
pinned_messages | Up to 10 most recent pinned messages |
Pagination
Copied!Confused about "Pagination"?
Let us know how we can improve our documentation:
Query channel requests can be paginated similar to how you paginate on other calls. Here's a short example:
filter should include, at the very least {members: {$in: [userID]} or pagination could break.