Chat

Chat

new Chat(channelopt, isPrivateopt, autoConnectopt, metaopt, groupopt)

Source:

This is the root Chat class that represents a chat room

Parameters:
Name Type Attributes Default Description
channel String <optional>
 new Date().getTime()

A unique identifier for this chat Chat. Must be alphanumeric. The channel is the unique name of a Chat, and is usually something like "The Watercooler", "Support", or "Off Topic". See PubNub Channels.
isPrivate Boolean <optional>
 false

Attempt to authenticate ourselves before connecting to this Chat.
autoConnect Boolean <optional>
 true

Connect to this chat as soon as its initiated. If set to false, call the Chat#connect method to connect to this Chat.
meta Object <optional>
 {}

Chat metadata that will be persisted on the server and populated on creation.
group String <optional>
 'default'

Groups chat into a "type". This is the key which chats will be grouped into within Me.session object.
Fires:
  • $.ready
  • $.state
  • $.online.*
  • $.offline.*

Extends

Members

asleep :Boolean

Source:

If user manually disconnects via ChatEngine#disconnect, the chat is put to "sleep". If a connection is reestablished via ChatEngine#reconnect, sleeping chats reconnect automatically.

Type:
  • Boolean

(readonly) channel :String

Source:
See:

A string identifier for the Chat room. Any chat with an identical channel will be able to communicate with one another.

Type:
  • String

connected :Boolean

Source:

Boolean value that indicates of the Chat is connected to the network

Type:
  • Boolean

hasConnected :Boolean

Source:

Keep a record if we've every successfully connected to this chat before.

Type:
  • Boolean

(readonly) isPrivate :Boolean

Source:

Excludes all users from reading or writing to the chat unless they have been explicitly invited via Chat#invite;

Type:
  • Boolean

(readonly) meta :Object

Source:

Chat metadata persisted on the server. Useful for storing things like the name and description. Call Chat#update to update the remote information.

Type:
  • Object

(readonly) users :Object

Source:

A list of users in this Chat. Automatically kept in sync as users join and leave the chat. Use $.join and related events to get notified when this changes

Type:
  • Object

Methods

connect()

Source:

Establish authentication with the server, then subscribe with PubNub.

Example
// create a new chatroom, but don't connect to it automatically
let chat = new Chat('some-chat', false, false);

// connect to the chat when we feel like it
chat.connect();
Fires:
  • $.ready

emit(event, data)

Source:

Send events to other clients in this User. Events are trigger over the network and all events are made on behalf of Me

Example
chat.emit('custom-event', {value: true});
chat.on('custom-event', (payload) => {
    console.log(payload.sender.uuid, 'emitted the value', payload.data.value);
});
Parameters:
Name Type Description
event String

The event name
data Object

The event payload object

invite(user)

Source:

Invite a user to this Chat. Authorizes the invited user in the Chat and sends them an invite via User#direct.

Example
// one user running ChatEngine
let secretChat = new ChatEngine.Chat('secret-channel');
secretChat.invite(someoneElse);

// someoneElse in another instance of ChatEngine
me.direct.on('$.invite', (payload) => {
    let secretChat = new ChatEngine.Chat(payload.data.channel);
});
Parameters:
Name Type Description
user User

The User to invite to this chatroom.
Fires:

leave()

Source:

Leave from the Chat on behalf of Me. Disconnects from the Chat and will stop receiving events.

Example
chat.leave();
Fires:

objectify() → {Object}

Source:

Turns a Chat into a JSON representation.

Returns:
Type
Object

off(event)

Source:
Inherited From:

Stop a callback from listening to an event.

Example
let callback = function(payload;) {
   console.log('something happend!');
};
object.on('event', callback);
// ...
object.off('event', callback);
Parameters:
Name Type Description
event String

The event name

on(event, cb)

Source:
Overrides:

Listen for a specific event and fire a callback when it's emitted. Supports wildcard matching.

Example
// Get notified whenever someone joins the room
object.on('event', (payload) => {
    console.log('event was fired').
})

// Get notified of event.a and event.b
object.on('event.*', (payload) => {
    console.log('event.a or event.b was fired').;
})
Parameters:
Name Type Description
event String

The event name
cb function

The function to run when the event is emitted

onAny(callback)

Source:
Inherited From:

Listen for any event on this object and fire a callback when it's emitted

Example
object.onAny((event, payload) => {
    console.log('All events trigger this.');
});
Parameters:
Name Type Description
callback function

The function to run when any event is emitted. First parameter is the event name and second is the payload.

once(event, callback)

Source:
Inherited From:

Listen for an event and only fire the callback a single time

Example
object.once('message', => (event, payload) {
    console.log('This is only fired once!');
});
Parameters:
Name Type Description
event String

The event name
callback function

The function to run once

plugin(module)

Source:
Inherited From:
Tutorials:
  • Tutorial: using

Binds a plugin to this object

Parameters:
Name Type Description
module Object

The plugin module
Source:

Search through previously emitted events. Parameters act as AND operators. Returns an instance of the emitter based History. Will which will emit all old events unless config.event is supplied.

Example
chat.search({
        event: 'my-custom-event',
        sender: ChatEngine.me,
        limit: 20
    }).on('my-custom-event', (event) => {
        console.log('this is an old event!', event);
    }).on('$.search.finish', () => {
        console.log('we have all our results!')
    });
Parameters:
Name Type Attributes Description
config Object <optional>

Our configuration for the PubNub history request. See the PubNub History docs for more information on these parameters.

Properties
Name Type Attributes Default Description
event Event <optional>

The Event to search for.
sender User <optional>

The User who sent the message.
pages Number <optional>
 10

The maximum number of history requests which ChatEngine will do automatically to fulfill limit requirement.
limit Number <optional>
 20

The maximum number of results to return that match search criteria. Search will continue operating until it returns this number of results or it reached the end of history. Limit will be ignored in case if both 'start' and 'end' timetokens has been passed in search configuration.
count Number <optional>
 100

The maximum number of messages which can be fetched with single history request.
start Number <optional>
 0

The timetoken to begin searching between.
end Number <optional>
 0

The timetoken to end searching between.
reverse Boolean <optional>
 false

Search oldest messages first.
Returns:
Type
Search

update(data)

Source:

Update the Chat metadata on the server.

Parameters:
Name Type Description
data object

JSON object representing chat metadta.

Events

$.connected

Source:

Broadcast that the Chat is connected to the network.

Example
chat.on('$.connected', () => {
    console.log('chat is ready to go!');
});

$.error.chatLeave

Source:
Properties:
Name Type Description
ceError String

The specific error thrown by ChatEngine

There was a problem leaving the chat.

$.error.chatMeta

Source:
Properties:
Name Type Description
ceError String

The specific error thrown by ChatEngine

Something went wrong updating the chat metadata.

$.error.getState

Source:
Properties:
Name Type Description
ceError String

The specific error thrown by ChatEngine

There was a problem restoring the state for this user

$.error.invite

Source:
Properties:
Name Type Description
ceError String

The specific error thrown by ChatEngine

Something went wrong with the server request to invite the user.

$.error.notConnected

Source:
Properties:
Name Type Description
ceError String

The specific error thrown by ChatEngine

There was a problem searching the chat.

$.error.presence

Source:
Properties:
Name Type Description
ceError String

The specific error thrown by ChatEngine
status Number

The PubNub service that surfaced this error
error String
message String

The PubNub supplied error
payload Object

There was a problem fetching the presence of this chat

$.error.publish

Source:

There was a problem publishing over the PubNub network.

$.error.search

Source:
Properties:
Name Type Description
ceError String

The specific error thrown by ChatEngine

There was a problem fetching the history of this chat

$.error.sync

Source:
Properties:
Name Type Description
ceError String

The specific error thrown by ChatEngine

There was a problem restoring the session

$.offline.disconnect

Source:
Properties:
Name Type Description
user Object

The User that disconnected

Fired specifically when a User looses network connection to the Chat involuntarily.

Example
chat.on('$.offline.disconnect', (data) => {
    console.log('User disconnected from the network:', data.user);
});

$.offline.leave

Source:
Properties:
Name Type Description
user User

The User that has left the room

Fired when a User intentionally leaves a Chat.

Example
chat.on('$.offline.leave', (data) => {
    console.log('User left the room manually:', data.user);
});

$.online.here

Source:
Properties:
Name Type Description
user User

The User that came online

Broadcast that a User has come online. This is when the framework firsts learn of a user. This can be triggered by, $.join, or other network events that notify the framework of a new user.

Example
chat.on('$.online.here', (data) => {
    console.log('User has come online:', data.user);
});

$.online.join

Source:
Properties:
Name Type Description
data Object

The payload returned by the event

Properties
Name Type Description
user User

The User that came online

Fired when a User has joined the room.

Example
chat.on('$.join', (data) => {
    console.log('User has joined the room!', data.user);
});