channels
introduction
using cyxth you can creat simple one to one channels,many to many group channels, few to many broadcast channels and everything
in between. cyxth gives you options to manage and limit channel features and users. cyxth does not offer channel discovery
but there is an option to make channels public so they can be fetched using channels.list()
with listPublicOnly
option set to true.
all operations here are in the channels
namespace i.e channels.create()
;
create
to create a channel use
channels.create(channel: NewChannel): Status
for example to create a channel hello one could use this.
cyxth.channels
.create({
id: 'hello',
name: 'hello',
metadata: {
logo: 'channel_avatar.png'
},
users: ['id1', 'id2', 'id3', '...']
})
.then((status) => {
console.log(status);
})
.catch((err) => {
// handle error
});
join or leave
To join a given channel use the channels.join()
function providing the channel id. this may fail if user
is blocked or users are not allowed to join the channel.
channels.join(channelId: string): Promise<{id:string}>
Similary to leave a channel.
channels.leave(channelId: string): Promise<{id:string}>
listing
To get channels for the active user use the channels.list()
method. for simple channel discovery add the listPublicOnly
option alongside
pagination.
channels.list(pagination?: Pagination, listPublicOnly = false): Promise<{ channels: Channel[] }>
for example
cyxth.channels
.list()
.then((channels) => {
console.log(channels);
})
.catch((err) => {
//handle error
});
To get more channel information such as metadata,avatar,name and more use channels.get()
channels.get(channelId: string): Promise<Channel | undefined>
members management
to get all members in a channel use channels.getMembers()
.
channels.getMembers(channelId: string): Promise<ChannelUser[]>
to add members use channel.addMembers()
. this will fail if any of the members in a list provided does not exist, this
method requires admin privilages in channel.
channels.addMembers(channelId: string, userIds: string | string[]): Status
similary to remove members use channel.removeMembers()
. this
method requires admin privilages in channel.
channels.removeMembers(channelId: string, userIds: string | string[]): Status
moderation
Channel moderation requires admin privilages in given channels.
to moderate users use channels.moderate()
channels.moderate(channelId: string, moderation: Moderation): Status
for example to block 3 users
cyxth.channels.moderate('channel_id', {
mode: 'block',
users: ['alice', 'bob', 'cyx']
});
message history
to get activity and messages in a channel use channels.getMessages()
function
getMessages(
start: Date | string,
limit: number = 50,
channels: undefined | string | string[] = undefined,
direction: 'reverse' | 'forward' = 'forward'
): Promise<{ [key: string]: Message[] }>
examples
// using an id only
cyxth.channnels
.getMessages('7085164563653595136')
.then((messages) => {
console.log(messages);
})
.catch((err) => console.error(err));
// using id and limit, 150 is max at once
cyxth.channnels
.getMessages('7085164563653595136', 150)
.then((messages) => {
console.log(messages);
})
.catch((err) => console.error(err));
// use date instead
let date = new Date();
cyxth.channnels
.getMessages(date)
.then((messages) => {
console.log(messages);
})
.catch((err) => console.error(err));
This is particulary useful when combined with offline mode. where users can get updates of messages when they were offline or disconnected.
update and delete
you can also update and delete channels using channels.update()
and channels.delete()
functions respectively.
these operations can only be carried out by channel creator or admin in channel.
update
.update(channel: Channel): Status
delete
.delete(channelId: string): Status
events
all activities carried out in any given channel are reported by listening on the activity
event
these notifies users when they’ve been added to a channel, blocked, made admins … etc.
activity can be configured for a given channel or instance wide
cyxth.on('activity', (activity: Activity) => {
// do sth
});
to get messages in a channel
cyxth.on('message', (message: Message) => {
// do sth
});
types
auto generated types related to channels
export declare class Channels {
create(channel: NewChannel): Status;
get(channelId: string): Promise<Channel | undefined>;
delete(channelId: string): Status;
update(channel: Channel): Status;
join(channelId: string): Promise<{
id: string;
}>;
leave(channelId: string): Promise<{
id: string;
}>;
getMembers(channelId: string): Promise<ChannelUser[]>;
addMembers(channelId: string, userIds: string | string[]): Status;
removeMembers(channelId: string, userIds: string | string[]): Status;
moderate(channelId: string, moderation: Moderation): Status;
getMessages(
start: Date | string,
limit?: number,
channels?: undefined | string | string[],
direction?: 'reverse' | 'forward'
): Promise<{
[key: string]: Message[];
}>;
list(
pagination?: Pagination,
listPublicOnly?: boolean
): Promise<{
channels: Channel[];
}>;
}
type ModerationType = 'block' | 'unblock' | 'make_admin' | 'revoke_admin';
interface Moderation {
mode: ModerationType;
users: string | string[];
}
interface Channel {
id: string;
name: string;
metadata: {
logo?: string;
about?: string;
};
}
interface NewChannel extends Channel {
users?: string[];
}
interface Pagination {
starting_after: string;
limit: number;
}
interface ChannelUser {
id: string;
name: string;
mode: number;
}
type Status = Promise<{
status: number;
}>;
interface Message {
userId: string;
channelId: string;
messageId: string;
content: MessageContent;
timestamp: Date;
type: 'activity' | 'message' | 'private';
activity?: ChannelActivity;
}
interface ChannelActivity {
event: 'join' | 'leave' | 'create' | string;
scope: 'channel' | string;
sender: string;
data?: any;
}
interface MessageContent {
text?: string;
media?: any;
meta?: string;
}