Differences between channel.create, channel.watch, and channel.query - Chat

This article covers the differences between three common channel methods: channel.create, channel.watch, and channel.query. 

These methods share some similarities, but their differences are important to be aware of so you can know the best method for your use case. 

channel.create()

channel.create() is used for server-side channel creation.

It does not subscribe to channel updates, like channel.watch() does.

If the channel already exists, it will not throw an error, it will return a simplified version of the channel instance. 

const channel = chatClient.channel('messaging', 'my-new-channel', {
  members: [chatClient.user.id, 'Suki', 'Stephen']
})

await channel.create()

Note the use of await in channel.create() but not in serverClient.channel() this is because serverClient.channel() is not an API request but channel.create() is.

channel.watch()

channel.watch() is intended for client-side use.

This method creates a channel if it does not already exist - and if the channel already exists, it will return a more detailed version of the channel instance (including messages, watchers, and 'read').

In addition, running this method will 'watch' the channel, that is, the currently connected user will be subscribed to event updates (new message, new member, etc...)

More info on events here

channel.query()

channel.query() is also suited for client-side use and its main intention is to return certain parameters of the channel (watcher count, member count, etc).

A common use case for this method would be to return a paginated list of members, which would look something like this...

const result = await channel.query({members: { limit:2, offset:0 }})

console.log(result.members)

[
  {
    user_id: 'Cody',
    user: {
      id: 'Cody',
      role: 'user',
      created_at: '2021-03-25T17:31:36.528874Z',
      updated_at: '2021-04-28T20:34:58.612221Z',
      last_active: '2021-06-02T19:38:43.117752565Z',
      banned: false,
      online: true,
      extraData: [Object]
    },
    role: 'owner',
    created_at: '2021-06-02T19:43:30.349954Z',
    updated_at: '2021-06-02T19:43:30.349954Z',
    banned: false,
    shadow_banned: false
  },
  {
    user_id: 'Suki',
    user: {
      id: 'Suki',
      role: 'user',
      created_at: '2021-04-28T20:34:58.601915Z',
      updated_at: '2021-04-28T20:34:58.601916Z',
      banned: false,
      online: false
    },
    role: 'member',
    created_at: '2021-06-02T19:43:30.349954Z',
    updated_at: '2021-06-02T19:43:30.349954Z',
    banned: false,
    shadow_banned: false
  }
]