Class: Channel

Channel

A Channel represents a remote channel of communication between multiple Programmable Chat Clients

Properties:
Name Type Description
attributes Object The Channel's custom attributes
createdBy String The identity of the User that created this Channel
dateCreated Date The Date this Channel was created
dateUpdated Date The Date this Channel was last updated
friendlyName String The Channel's name
isPrivate Boolean Whether the channel is private (as opposed to public)
lastConsumedMessageIndex Number Index of the last Message the User has consumed in this Channel
lastMessage Channel#LastMessage Last Message sent to this Channel
notificationLevel Channel#NotificationLevel User Notification level for this Channel
sid String The Channel's unique system identifier
status Channel#Status The Channel's status
type Channel#Type The Channel's type
uniqueName String The Channel's unique name (tag)
Fires:

Methods


add(identity)

Add a participant to the Channel by its Identity.
Parameters:
Name Type Description
identity String Identity of the Client to add
Returns:
Type
Promise.<(void|Error|SessionError)>

advanceLastConsumedMessageIndex(index)

Advance last consumed Channel's Message index to current consumption horizon. Rejects if User is not Member of Channel. Last consumed Message index is updated only if new index value is higher than previous.
Parameters:
Name Type Description
index Number Message index to advance to as last read
Returns:
resulting unread messages count in the channel
Type
Promise.<(number|Error|SessionError)>

decline()

Decline an invitation to the Channel and unsubscribe from its events.
Returns:
Type
Promise.<(Channel|SessionError)>

delete()

Delete the Channel and unsubscribe from its events.
Returns:
Type
Promise.<(Channel|SessionError)>

getAttributes()

Get the custom attributes of this Channel.
NOTE: Channel's attributes property will be empty for public channels until this function is called.
Returns:
Type
Promise.<Object>

getMemberByIdentity(identity)

Get a Member by its identity.
Parameters:
Name Type Description
identity String Member identity
Returns:
Type
Promise.<Member>

getMemberBySid(memberSid)

Get a Member by its SID.
Parameters:
Name Type Description
memberSid String Member sid
Returns:
Type
Promise.<Member>

getMembers()

Get a list of all Members joined to this Channel.
Returns:
Type
Promise.<Array.<Member>>

getMembersCount()

Get channel members count.
This method is semi-realtime. This means that this data will be eventually correct, but will also possibly be incorrect for a few seconds. The Chat system does not provide real time events for counter values changes.
So this is quite useful for any UI badges, but is not recommended to build any core application logic based on these counters being accurate in real time.
Returns:
Type
Promise.<(number|Error)>

getMessages( [pageSize] [, anchor] [, direction])

Returns messages from channel using paginator interface.
Parameters:
Name Type Argument Default Description
pageSize Number <optional>
30 Number of messages to return in single chunk
anchor Number <optional>
Index of newest Message to fetch. From the end by default
direction String <optional>
backwards Query direction. By default it query backwards from newer to older. 'forward' will query in opposite direction
Returns:
page of messages
Type
Promise.<Paginator.<Message>>

getMessagesCount()

Get total message count in a channel.
This method is semi-realtime. This means that this data will be eventually correct, but will also possibly be incorrect for a few seconds. The Chat system does not provide real time events for counter values changes.
So this is quite useful for any UI badges, but is not recommended to build any core application logic based on these counters being accurate in real time.
Returns:
Type
Promise.<(number|Error)>

getUnconsumedMessagesCount()

Get unconsumed messages count for User if he is Member of this Channel. Rejects if User is not Member of Channel.
This method is semi-realtime. This means that this data will be eventually correct, but will also possibly be incorrect for a few seconds. The Chat system does not provide real time events for counter values changes.
So this is quite useful for any “unread messages count” badges, but is not recommended to build any core application logic based on these counters being accurate in real time.
Returns:
Type
Promise.<(number|Error)>

getUserDescriptors()

Gets User Descriptors for this channel.
Returns:
Type
Promise.<Paginator.<UserDescriptor>>

invite(identity)

Invite a user to the Channel by their Identity.
Parameters:
Name Type Description
identity String Identity of the user to invite
Returns:
Type
Promise.<(void|Error|SessionError)>

join()

Join the Channel and subscribe to its events.
Returns:
Type
Promise.<(Channel|SessionError)>

leave()

Leave the Channel.
Returns:
Type
Promise.<(Channel|SessionError)>

removeMember(member)

Remove a Member from the Channel.
Parameters:
Name Type Description
member String identity of member to remove
Returns:
Type
Promise.<(void|Error|SessionError)>

sendMessage(message, messageAttributes)

Send a Message in the Channel.
Parameters:
Name Type Description
message String | FormData | Channel#SendMediaOptions The message body for text message, FormData or MediaOptions for media content
messageAttributes Object attributes for the message
Returns:
new Message's index in the Channel's messages list
Type
Promise.<(number|Error|SessionError)>

setAllMessagesConsumed()

Set last consumed Channel's Message index to last known Message's index in this Channel.
Returns:
resulting unread messages count in the channel
Type
Promise.<(number|SessionError)>

setNoMessagesConsumed()

Set all messages in the channel unread.
Returns:
resulting unread messages count in the channel
Type
Promise.<(number|SessionError)>

setUserNotificationLevel(notificationLevel)

Set User Notification level for this channel.
Parameters:
Name Type Description
notificationLevel Channel#NotificationLevel The new user notification level
Returns:
Type
Promise.<(void|Error|SessionError)>

typing()

Send a notification to the server indicating that this Client is currently typing in this Channel. Typing ended notification is sent after a while automatically, but by calling again this method you ensure typing ended is not received.
Returns:
Type
Promise.<(void|SessionError)>

updateAttributes(attributes)

Update the Channel's attributes.
Parameters:
Name Type Description
attributes Object The new attributes object
Returns:
Type
Promise.<(Channel|Error|SessionError)>

updateFriendlyName(name)

Update the Channel's friendlyName.
Parameters:
Name Type Description
name String The new Channel friendlyName
Returns:
Type
Promise.<(Channel|SessionError)>

updateLastConsumedMessageIndex(index)

Set last consumed Channel's Message index to current consumption horizon.
Parameters:
Name Type Description
index Number | null Message index to set as last read. If null provided, then the behavior is identical to Channel#setNoMessagesConsumed
Returns:
resulting unread messages count in the channel
Type
Promise.<(number|Error|SessionError)>

updateUniqueName(uniqueName)

Update the Channel's unique name.
Parameters:
Name Type Description
uniqueName String The new Channel uniqueName
Returns:
Type
Promise.<(Channel|SessionError)>

Type Definitions


LastMessage

The Channel's last message's information.
Type:
  • Object
Properties:
Name Type Description
index Number Message's index
timestamp Date Message's creation timestamp

NotificationLevel

The User's Notification level for Channel, determines whether the currently logged-in User will receive pushes for events in this Channel. Can be either muted or default, where default defers to global Service push configuration.
Type:
  • 'default' | 'muted'

SendMediaOptions

These options can be passed to Channel#sendMessage.
Type:
  • Object
Properties:
Name Type Description
contentType String content type of media
media String | Buffer content to post

Status

The status of the Channel, relative to the Client: whether the Channel is known to local Client, Client is invited to or is joined to this Channel
Type:
  • 'unknown' | 'known' | 'invited' | 'joined'

Type

The type of Channel (public or private).
Type:
  • 'public' | 'private'

UpdateReason

The update reason for updated event emitted on Channel
Type:
  • 'attributes' | 'createdBy' | 'dateCreated' | 'dateUpdated' | 'friendlyName' | 'lastConsumedMessageIndex' | 'status' | 'uniqueName' | 'lastMessage' | 'notificationLevel'

Events


memberJoined

Fired when a Member has joined the Channel.
Type: Member

memberLeft

Fired when a Member has left the Channel.
Type: Member

memberUpdated

Fired when a Member's fields has been updated.
Type: Object
Properties:
Name Type Description
member Member Updated Member
updateReasons Array.<Member#UpdateReason> Array of Member's updated event reasons

messageAdded

Fired when a new Message has been added to the Channel.
Type: Message

messageRemoved

Fired when Message is removed from Channel's message list.
Type: Message

messageUpdated

Fired when an existing Message's fields are updated with new values.
Type: Object
Properties:
Name Type Description
message Message Updated Message
updateReasons Array.<Message#UpdateReason> Array of Message's updated event reasons

removed

Fired when the Channel was destroyed or currently logged in User has left private Channel
Type: Channel

typingEnded

Fired when a Member has stopped typing.
Type: Member

typingStarted

Fired when a Member has started typing.
Type: Member

updated

Fired when a Channel's attributes or metadata have been updated. During Channel's creation and initialization this event might be fired multiple times for same joined or created Channel as new data is arriving from different sources.
Type: Object
Properties:
Name Type Description
channel Channel Updated Channel
updateReasons Array.<Channel#UpdateReason> Array of Channel's updated event reasons