Channels
ChatKitty organizes conversations into dedicated contexts called channels. Channels structure and order your application's chat experience. You can create a channel for any topic, project, or team.
After a user joins a channel, the user becomes a channel member. ChatKitty broadcasts messages created in channels to channel members with active chat sessions and sends push notifications to offline members. ChatKitty persists messages sent in a channel by default but this behaviour can be configured.
Schema
id required | integer <int64> 64-bit integer identifier associated with this resource |
type required | string Enum: "DIRECT" "PUBLIC" "PRIVATE" The type of this channel |
name | string The unique name of this channel used to reference the channel |
displayName | string Human readable name of this channel shown to users |
object (ChatUserProperties) | |
Array of objects (ChatUserProperties) [ items ] The members of this channel. Present if this is a direct channel. For other channel types, use get channel members | |
object (MessageProperties) The message last received associated with this channel | |
required | object Custom data associated with this channel |
createdTime required | string <date-time> The ISO date-time this channel was created |
object (Links) |
{- "id": 55913,
- "type": "PUBLIC",
- "name": "b0a0bd55-921a-4f72-8ee3-f26c6fda0bb7",
- "displayName": "Our public channel",
- "properties": { },
- "createdTime": "2021-09-28T01:35:40.967Z",
- "_links": {
- "participants": {
},
}
}
Channel types
There are three types of channels:
Direct Channels
Direct channels let users have private one-on-one conversations with other users. New users cannot be added to a direct channel and there can only exist one direct channel between a set of users.
note
A direct channel can have up to 10 members. Public and private channels are better suited for group chats; supporting up to hundreds-of-thousands of members.
Public Channels
Public channels let users discuss topics openly. By default, any user can view and join a public channel. Users can join public channels by themselves or via invites from an existing channel member.
Private Channels
Private channels are for topics that should not be open to all members. Users must be added to a private channel by someone who's already a member of the channel.
Additional Properties
Name | Type | Description | Required |
---|---|---|---|
members | User [ ] | An array of member users of this channel | ✔ |
Creating a channel
Create a new channel of channel type (DIRECT
, PUBLIC
, or PRIVATE
) with a unique name for public and private channels and member references for direct channels. A user is automatically a member of a channel they created.
Creating a direct channel
const result = await kitty.createChannel({
type: 'DIRECT',
members: [
{ username: 'jane@chatkitty.com' },
{ username: 'john@chatkitty.com' },
],
});
if (result.succeeded) {
const channel = result.channel; // Handle channel
}
if (result.failed) {
const error = result.error; // Handle error
}
Creating a public channel
const result = await kitty.createChannel({
type: 'PUBLIC',
name: 'my-first-public-channel',
});
if (result.succeeded) {
const channel = result.channel; // Handle channel
}
if (result.failed) {
const error = result.error; // Handle error
}
Creating a private channel
const result = await kitty.createChannel({
type: 'PRIVATE',
name: 'my-first-private-channel',
});
if (result.succeeded) {
const channel = result.channel; // Handle channel
}
if (result.failed) {
const error = result.error; // Handle error
}
Getting channels
Get all channels accessible to the current user regardless of current membership status.
const result = await kitty.getChannels();
if (result.succeeded) {
const channels = result.paginator.items; // Handle channels
}
if (result.failed) {
const error = result.error; // Handle error
}
Getting joined channels
Get channels the current user has joined (is already a member) and can start chat sessions in.
const result = await kitty.getChannels({ filter: { joined: true } });
if (result.succeeded) {
const channels = result.paginator.items; // Handle channels
}
if (result.failed) {
const error = result.error; // Handle error
}
Getting joinable channels
Get channels the current user can join, becoming a member.
const result = await kitty.getChannels({ filter: { joined: false } });
if (result.succeeded) {
const channels = result.paginator.items; // Handle channels
}
if (result.failed) {
const error = result.error; // Handle error
}
Getting a channel
Get a channel by searchable properties like channel ID
const result = await kitty.getChannel(channelId);
if (result.succeeded) {
const channel = result.channel; // Handle channel
}
if (result.failed) {
const error = result.error; // Handle error
}
Joining a public channel
const result = await kitty.joinChannel({ channel });
if (result.succeeded) {
const channel = result.channel; // Handle channel
}
if (result.failed) {
const error = result.error; // Handle error
}
Observing user joined channel
When the current user joins a channel or is added to a channel by another user or through the Platform REST API, registered channel observers are notified.
const unsubscribe = kitty.onChannelJoined((channel) => {
// handle channel
});
// call when you're no longer interested in updates
unsubscribe();
Reading a channel
Read a channel to automatically read all channel messages.
const result = await kitty.readChannel({ channel });
if (result.succeeded) {
const channel = result.channel; // Handle channel
}
if (result.failed) {
const error = result.error; // Handle error
}
Checking if a channel is unread
A channel is unread if it has any unread messages by the current user.
const result = await kitty.getChannelUnread({
channel: channel,
});
if (result.succeeded) {
const unread = result.unread; // Handle if unread
}
Deleting a channel
Delete a channel and all its related resources
const result = await kitty.deleteChannel({
channel: channel
});
if (result.succeeded) {
// Handle result
}
const result = await kitty.deleteChannel({
channel: channel
});
if (succeeded(result)) {
// Handle result
}
curl -X DELETE "https://api.chatkitty.com/v1/applications/APP-ID/channels/CHANNEL-ID" -H "Authorization: Bearer OAUTH-TOKEN"