Skygear Plugin - Chat SDK
Clone or download

Build Status

Chat Plugin for Skygear

Related SDK

You can find the SDK code in following repos on github. You can also directly install at the package manager.

Get the demo running at Skygear cloud


Assumed you go registered at


git submodule to import the source code.

git submodule add chat

In your cloud code, import the chat plugin. Skygear will load and lambda and database hook will be ready for use.

from skygear.settings import settings

from .chat import includeme



Tell Skygear cloud to serve the asset from chat-SDK-JS demo folder

git submodule to import the JS SDK source code.

git submodule add chat-SDK-JS
from skygear import static_assets
from skygear.utils.assets import relative_assets

def chat_demo():
    return relative_assets('chat-SDK-JS/demo')


Quick Start

We provide Quick Start tutorial in different language.

We also have basic guide go through feature by feature.

Understanding the model

In this chat plugin, we have various model represent different data in application. Understanding the model relation make you able to use the plugin efficiently. It also enable developer to store application specific data in the correct model.

Following is the model relation diagram.

Entity Relation

Overview of models responsibility are as follow.

  • Conversation - represent a conversation, it store conversation information like title, last message, no. of participant.
  • Message - actual message display on screen, it store message text, related asset and metadata.
  • UserConversation - represent a user is participating a conversation. It stores user specific information to a conversation, like last read time and unread count.
  • Receipt - Store the user receipt on a message.

Details attributes on models

Following is the table of attributes ensured by this plugin.

Note that User is Skygear provided User profile model.


Attributes Type Description
name String


Attributes Type Description
title String
admin_ids JSON Array
participant_ids JSON Array
participant_count Number
distinct_by_participants Boolean
metadata JSON Object
last_message Reference


Attributes Type Description
body String
conversation_status String Summary of receipt status
attachment Asset
metadata JSON Object
conversation_id Reference


Attributes Type Description
unread_count Number
last_read_message Reference
user Reference
conversation Reference


Attributes Type Description
read_at Datetime
delivered_at Datetime
user_id Reference
message_id Reference

Detail API

For API detail, please visit the platform specific API filie:

Some sample code

Sending push notification

Push notification can be implemented by the following code. Please ensure APNS certificate and private key are properly setup, if you are using [], you can configure it at the setting panel.

import skygear
from skygear.container import SkygearContainer
from skygear.options import options as skyoptions
from skygear.action import push_user

# Import the chat plugin module.
# If you not using pip for the plugin, you will have modify the following lines
# to use relative import.
# For example if you have the `chat` folder located at the root of the project,
# you should use `from .chat import ...` instead of `from chat import ...`
from chat.user_conversation import total_unread
from chat.conversation import Conversation
from chat.message import Message

# Create a container so we can talk to skygear server
container = SkygearContainer(api_key=skyoptions.masterkey)

# Register a handler after message is saved
def push_message_after_save_handler(record, original_record, conn):
    message = Message.from_record(record)
    conversation = Conversation(message.fetchConversationRecord())

    # Fetch the owner of the message
    resp = container.send_action('record:query', {
            'record_type': 'user',
            'predicate': [
                {'$type': 'keypath', '$val': '_id'},
    user_record = resp['result'][0]

    # Construct the message for push notification
    if conversation['title'] is None:
        push_message = '{0}: {1}'.format(user_record['name'], record['body'])
        push_message = '{0}@{1}: {2}'.format(user_record['name'], conversation['title'], record['body'])

    # Send push notification to each participant
    for participant_id in conversation.participant_set:
        # Except the message author
        if record._owner_id == participant_id:

        # Get the total unread message count
        total_unread_count = total_unread(participant_id)['message']

        # Finally send the notification
                'apns': {
                    'aps': {
                        'alert': push_message,
                        'sound': 'default',
                        'badge': total_unread_count,
                    'from': 'skygear-chat',
                    'operation': 'notification'


For implementation related questions or technical support, please find us on the official forum or community chat; For bug reports or feature requests, feel free to open an issue in this repo