Home Reference Source
import {SkygearChatContainer} from 'skygear-chat/lib/container.js'
public class | source

SkygearChatContainer

You can directly use an instance of this class. chatContainer

SkygearChatContainer provide API access to the chat plugin.

Member Summary

Public Members
public get

pubsub: *

Private Members
private

_pubsub: *

Method Summary

Public Methods
public

async addAdmins(conversation: Conversation, admins: []User): Promise<Conversation>

addAdmins allow adding admins to a conversation.

public

async addParticipants(conversation: Conversation, participants: []User): Promise<Conversation>

addParticipants allow adding participants to a conversation.

public

async createConversation(participants: []User, title: string, meta: object, options: object): Promise<Conversation>

createConversation create an conversation with provided participants and title.

public

async createDirectConversation(user: User, title: string, meta: object, options: object): Promise<Conversation>

createDirectConversation is a helper function will create conversation with distinctByParticipants set to true

public

async createMessage(conversation: Conversation, body: string, metadata: object, asset: File | skygear.Asset): Promise<Message>

createMessage create a message in a conversation.

public

async deleteConversation(conversation: Conversation): Promise<boolean>

Delete a conversation.

public

async deleteMessage(message: Message): Promise<Message>

deleteMessage delete an existing message

public

async editMessage(message: Message, body: string, metadata: object, asset: File): Promise<Mesage>

editMessage edit the body, meta and asset of an existing message

public

async getConversation(conversationID: string, includeLastMessage: boolean): Promise<Conversation>

getConversation query a Conversation Record from Skygear

public

async getConversations(page: number, pageSize: number, includeLastMessage: boolean): Promise<[]Conversation>

getConversations query a list of Conversation Records from Skygear which are readable to the current user

public

async getMessageReceipts(message: Message): Promise<[]Receipt>

getMessageReceipts returns an array of receipts of a message.

public

async getMessages(conversation: Conversation, limit: number, beforeTime: Date, order: string): Promise<[]Message>

getMessages returns an array of message in a conversation.

public

getUnreadCount return following unread count;

public

getUnreadMessageCount(conversation: Conversation): Promise<number>

this method was deprecated. Use conversation.unread_count instead

getUnreadMessageCount query a unread count of a conversation

public

async leaveConversation(conversation: Conversation): Promise<boolean>

Leave a conversation.

public

async markAsDelivered(messages: []Message): Promise<boolean>

markAsDelivered mark all messages as delivered

public

async markAsLastMessageRead(conversation: Conversation, message: Message): Promise<number>

markAsLastMessageRead mark the message as last read message.

public

async markAsRead(messages: []Message): Promise<boolean>

markAsRead mark all messages as read

public

async removeAdmins(conversation: Conversation, admins: []User): Promise<Conversation>

removeAdmins allow removal of admins from a conversation.

public

async removeParticipants(conversation: Conversation, participants: []User): Promise<COnversation>

removeParticipants allow removal of participants from a conversation.

public

sendTypingIndicator(conversation: Conversation, event: string): Promise<number>

sendTypingIndicaton send typing indicator to the specified conversation.

public

subscribe(handler: function)

subscribe all message changes event from the system.

public

Subscribe to typing indicator events in all conversation.

public

subscribeTypingIndicator(conversation: Conversation, callback: function)

Subscribe to typing indicator events in a conversation.

public

unsubscribe(handler: function)

Unsubscribe one or all typing message handler(s)

public

unsubscribeTypingIndicator(conversation: Conversation, handler: function)

unsubscribe one or all typing indicator handler(s) from a conversation.

public

async updateConversation(conversation: Conversation, title: string, meta: object): Promise<Conversation>

updateConversation is a helper method for updating a conversation with the provied title and meta.

Private Methods
private

async _getUserConversation(conversation: Conversation): Promise<UserConversation>

_getUserConversation query a UserConversation record of current logged in user by conversation.id

Public Members

public get pubsub: * source

Private Members

private _pubsub: * source

Public Methods

public async addAdmins(conversation: Conversation, admins: []User): Promise<Conversation> source

addAdmins allow adding admins to a conversation.

The use will also add as participants of the conversation if he is not already a participants of the conversation.

Params:

NameTypeAttributeDescription
conversation Conversation

Conversation to update

admins []User

array of Skygear User

Return:

Promise<Conversation>

A promise to save result

public async addParticipants(conversation: Conversation, participants: []User): Promise<Conversation> source

addParticipants allow adding participants to a conversation.

Params:

NameTypeAttributeDescription
conversation Conversation

Conversation to update

participants []User

array of Skygear User

Return:

Promise<Conversation>

A promise to save result

public async createConversation(participants: []User, title: string, meta: object, options: object): Promise<Conversation> source

createConversation create an conversation with provided participants and title.

Duplicate call of createConversation with same list of participants will return the different conversation, unless distinctByParticipants in options is set to true. By default distinctByParticipants is false.

Adding or removing participants from a distinct conversation (see below) makes it non-distinct.

For application specific attributes, you are suggested to put them as meta.

All participant will be admin unless specific in options.admins

Params:

NameTypeAttributeDescription
participants []User

array of Skygear Users

title string

string for describing the conversation topic

meta object

attributes for application specific purpose

options object
  • optional

options for the conversation, avaliable options distinctByParticipants and admins

options.distinctByParticipants boolean
  • optional

create conversation distinct by participants

options.admins []string | []User
  • optional

admin IDs of the conversation

Return:

Promise<Conversation>

Promise of the new Conversation Record

Example:

const skygearChat = require('skygear-chat');

skygearChat.createConversation([userBen], 'Greeting')
  .then(function (conversation) {
    console.log('Conversation created!', conversation);
  }, function (err) {
    console.log('Conversation created fails');
  });

public async createDirectConversation(user: User, title: string, meta: object, options: object): Promise<Conversation> source

createDirectConversation is a helper function will create conversation with distinctByParticipants set to true

Params:

NameTypeAttributeDescription
user User

Skygear Users

title string

string for describing the conversation topic

meta object

attributes for application specific purpose

options object
  • optional

options for the conversation, avaliable options admins

options.admins []string | []User
  • optional

admin IDs of the conversation

Return:

Promise<Conversation>

Promise of the new Conversation Record

Example:

const skygearChat = require('skygear-chat');

skygearChat.createDirectConversation(userBen, 'Greeting')
  .then(function (conversation) {
    console.log('Conversation created!', conversation);
  }, function (err) {
    console.log('Conversation created fails');
  });

public async createMessage(conversation: Conversation, body: string, metadata: object, asset: File | skygear.Asset): Promise<Message> source

createMessage create a message in a conversation.

A message can be just a text message, or a message with image, audio or video attachment. Application developer can also save metadata to a message, so the message can be display as important notice. The metadata provide flexibility to application to control how to display the message, like font and color.

Params:

NameTypeAttributeDescription
conversation Conversation

create the message in this conversation

body string

body text of the message

metadata object

application specific meta data for display purpose

asset File | skygear.Asset

Browser file object to be saves as attachment of this message, also accept skygear.Asset instance

Return:

Promise<Message>

A promise to save result

Example:

const skygearChat = require('skygear-chat');

skygearChat.createMessage(
  conversation,
  'Red in color, with attachment',
  {'color': 'red', },
  $('message-asset').files[0],
).then(function (result) {
  console.log('Save success', result);
});

public async deleteConversation(conversation: Conversation): Promise<boolean> source

Delete a conversation.

Params:

NameTypeAttributeDescription
conversation Conversation

Conversation to be deleted

Return:

Promise<boolean>

Promise of result

public async deleteMessage(message: Message): Promise<Message> source

deleteMessage delete an existing message

Params:

NameTypeAttributeDescription
message Message

The message object to be deleted

Return:

Promise<Message>

A promise to deleted message

Example:

const skygearChat = require('skygear-chat');
skygearChat.deleteMessage(
   message
).then(function(result) {
   console.log('Deletion success', result);
});

public async editMessage(message: Message, body: string, metadata: object, asset: File): Promise<Mesage> source

editMessage edit the body, meta and asset of an existing message

Params:

NameTypeAttributeDescription
message Message

The message object to be edited

body string

New message body

metadata object

New application specific meta data for display purpose, omitting thie parameter will keep the old meta

asset File

New file object to be saves as attachment of this message, omitting thie parameter will keep the old asset

Return:

Promise<Mesage>

A promise to save result

Example:

const skygearChat = require('skygear-chat');
skygearChat.editMessage(
  message,
   'new message Body',
).then(function(result) {
  console.log('Save success', result);
});

public async getConversation(conversationID: string, includeLastMessage: boolean): Promise<Conversation> source

getConversation query a Conversation Record from Skygear

Params:

NameTypeAttributeDescription
conversationID string

ConversationID

includeLastMessage boolean
  • optional
  • default: true

message is fetched and assigned to each conversation object.

Return:

Promise<Conversation>

A promise to array of Conversation

public async getConversations(page: number, pageSize: number, includeLastMessage: boolean): Promise<[]Conversation> source

getConversations query a list of Conversation Records from Skygear which are readable to the current user

Params:

NameTypeAttributeDescription
page number
  • optional
  • default: 1

Which page to display, default to the 1. The first page

pageSize number
  • optional
  • default: 50

How many item pre page, default to 50.

includeLastMessage boolean
  • optional
  • default: true

message is fetched and assigned to each conversation object.

Return:

Promise<[]Conversation>

A promise to array of Conversation.

public async getMessageReceipts(message: Message): Promise<[]Receipt> source

getMessageReceipts returns an array of receipts of a message.

Params:

NameTypeAttributeDescription
message Message

the message

Return:

Promise<[]Receipt>

array of Receipt records

public async getMessages(conversation: Conversation, limit: number, beforeTime: Date, order: string): Promise<[]Message> source

getMessages returns an array of message in a conversation. The way of query is to provide limit and beforeTime. The expected way is to query from the latest message first. And use the message createdAt to query the next pages via setting beforeTime when user scroll.

Once you query specific messages, the SDK will automatically mark the message as delivery on the server.

Params:

NameTypeAttributeDescription
conversation Conversation

conversation to query

limit number
  • optional
  • default: 50

limit the result set, if it is set to too large, may result in timeout.

beforeTime Date

specific from which time

order string

order of the message, 'edited_at' or '_created_at'

Return:

Promise<[]Message>

array of Message records

Example:

const skygearChat = require('skygear-chat');¬

const ulNode = document.createElement('UL');
const currentTime = new Date();
skygearChat.getMessages(conversation, 10, currentTime)
  .then(function (messages) {
    let lastMsgTime;
    message.forEach(function (m) {
      const liNode = document.createElement('LI');
      liNode.appendChild(document.createTextNode(m.content));
      ulNode.appendChild(liNode);
      lastMsgTime = m.createAt;
    });
    // Querying next page
    skygearChat.getMessages(conversation, 10, lastMsgTime).then(...);
  }, function (err) {
    console.log('Error: ', err);
  });

public async getUnreadCount(): Promise<object> source

getUnreadCount return following unread count;

  1. The total unread message count of current user.
  2. The total number of conversation have one or more unread message.

Format is as follow:

{
  'conversation': 3,
  'message': 23
}

Return:

Promise<object>

A promise to total count object

Example:

const skygearChat = require('skygear-chat');¬

skygearChat.getUnreadCount().then(function (count) {
  console.log('Total message unread count: ', count.message);
  console.log(
    'Total converation have unread message: ',
    count.conversation);
}, function (err) {
  console.log('Error: ', err);
});

public getUnreadMessageCount(conversation: Conversation): Promise<number> source

this method was deprecated. Use conversation.unread_count instead

getUnreadMessageCount query a unread count of a conversation

Params:

NameTypeAttributeDescription
conversation Conversation

conversation to be query

Return:

Promise<number>

A promise to result

public async leaveConversation(conversation: Conversation): Promise<boolean> source

Leave a conversation.

Params:

NameTypeAttributeDescription
conversation Conversation

Conversation to leave

Return:

Promise<boolean>

Promise of result

public async markAsDelivered(messages: []Message): Promise<boolean> source

markAsDelivered mark all messages as delivered

Params:

NameTypeAttributeDescription
messages []Message

an array of message to mark as delivery

Return:

Promise<boolean>

A promise to result

public async markAsLastMessageRead(conversation: Conversation, message: Message): Promise<number> source

markAsLastMessageRead mark the message as last read message. Once you mark a message as last read, the system will update the unread count at UserConversation.

Params:

NameTypeAttributeDescription
conversation Conversation

conversation the message belong to

message Message

message to be mark as last read

Return:

Promise<number>

A promise to result

public async markAsRead(messages: []Message): Promise<boolean> source

markAsRead mark all messages as read

Params:

NameTypeAttributeDescription
messages []Message

an array of message to mark as read

Return:

Promise<boolean>

A promise to result

public async removeAdmins(conversation: Conversation, admins: []User): Promise<Conversation> source

removeAdmins allow removal of admins from a conversation.

The removed user will still as the participants of the conversation.

Params:

NameTypeAttributeDescription
conversation Conversation

Conversation to update

admins []User

array of Skygear User

Return:

Promise<Conversation>

A promise to save result

public async removeParticipants(conversation: Conversation, participants: []User): Promise<COnversation> source

removeParticipants allow removal of participants from a conversation.

Remove an user from participants of a conversation will also remove it from admins.

Params:

NameTypeAttributeDescription
conversation Conversation

Conversation to update

participants []User

array of Skygear User

Return:

Promise<COnversation>

A promise to save result

public sendTypingIndicator(conversation: Conversation, event: string): Promise<number> source

sendTypingIndicaton send typing indicator to the specified conversation. The event can be begin, pause and finished.

Params:

NameTypeAttributeDescription
conversation Conversation

conversation to be query

event string

the event to send

Return:

Promise<number>

A promise to result

public subscribe(handler: function) source

subscribe all message changes event from the system.

The server will push all messsage change events via UserChannel that concerning the current user. i.e. all message belongs to a conversation that the current user have access to.

The handler will receive following object as parameters

{
  "record_type": "message",
  "event_type": "create",
  "record": recordObj,
  "original_record": nulll
}
  • event_type can be update, create and delete.
  • recordObj is skygear.Record instance.

Common use-case on the event_type: create - other user send a message to the conversation and insert it in the conversation view. updated - when a message is received by other, the message delivery status is changed. For example, from delivered to some_read. You can check the message_status fields to see the new delivery status.

Params:

NameTypeAttributeDescription
handler function

function to be invoke when a notification arrive

public subscribeAllTypingIndicator(callback: function) source

Subscribe to typing indicator events in all conversation.

If you application want to dispatch the typing other than per-conversation manner. You can use this method in stead of subscribeTypingIndicator.

The format of payload is similiar with conversation id as key to separate users' typing event. To get typing indicator event, call this method with a handler that accepts following parameters.

{
  "conversation/id1": {
    "user/id": {
      "event": "begin",
      "at": "20161116T78:44:00Z"
    },
    "user/id2": {
      "event": "begin",
      "at": "20161116T78:44:00Z"
    }
  }
}

Params:

NameTypeAttributeDescription
callback function

function be be invoke when there is someone typing in conversation you have access to.

public subscribeTypingIndicator(conversation: Conversation, callback: function) source

Subscribe to typing indicator events in a conversation.

You are required to specify a conversation where typing indicator events apply. You may subscribe to multiple conversation at the same time. To get typing indicator event, call this method with a handler that accepts following parameters.

{
  "user/id": {
    "event": "begin",
    "at": "20161116T78:44:00Z"
  },
  "user/id2": {
    "event": "begin",
    "at": "20161116T78:44:00Z"
  }
}

Params:

NameTypeAttributeDescription
conversation Conversation

conversation to be query

callback function

function be be invoke when there is someone typing in the specificed conversation

public unsubscribe(handler: function) source

Unsubscribe one or all typing message handler(s)

Params:

NameTypeAttributeDescription
handler function

Which handler to remove, if absent, all handlers are removed.

public unsubscribeTypingIndicator(conversation: Conversation, handler: function) source

unsubscribe one or all typing indicator handler(s) from a conversation.

Params:

NameTypeAttributeDescription
conversation Conversation

conversation to be unsubscribe

handler function

Which handler to remove, if absent, all handlers are removed.

public async updateConversation(conversation: Conversation, title: string, meta: object): Promise<Conversation> source

updateConversation is a helper method for updating a conversation with the provied title and meta.

Params:

NameTypeAttributeDescription
conversation Conversation

Conversation to update

title string

new title for describing the conversation topic

meta object

new attributes for application specific purpose

Return:

Promise<Conversation>

A promise to save result

Private Methods

private async _getUserConversation(conversation: Conversation): Promise<UserConversation> source

_getUserConversation query a UserConversation record of current logged in user by conversation.id

Params:

NameTypeAttributeDescription
conversation Conversation

Conversation

Return:

Promise<UserConversation>

A promise to UserConversation Recrod