Developer's Guide to Messages

bkad edited this page Jan 11, 2013 · 15 revisions
Clone this wiki locally

There are two kinds of messages that clients subscribe to: Channel and Self events.

Channel Events

These messages prefixed by channel id when sent out over the wire. A channel id is generated by taking the base64 of the channel's name. A user subscribes to all messages happening on channels he belongs to. These messages are also typically sent and received in some form on the websocket.

Messages of this type tend to be user chats and notifications when users join/leave a channel.

Channel Events and their payloads

publish_message: Occurs when a user sends a chat message to a channel.

{
  "action": "publish_message",
  "data": {
    "user": {
      "username": "nickname",
      "name": "FirstName LastName",
      "email": "nickname@example.com",
      "gravatar": "http://link.to/avatar.jpg"
    },
    "channel": "Channel name",
    "datetime": 123, #seconds-since-the-epoch,
    "message": "Hello World",
    "rendered_message": "<p>Hello World</p>"
  }
}

join_channel: Occurs when a user joins a channel.

{
  "action": "join_channel",
  "data": {
    "channel": "Channel name",
    "user": {
      "email": "nickname@example.com",
      "gravatar": "http://gravatar.com/userimage.jpg",
      "name": "Full name",
      "username": "nickname",
      "status": "active"
    }
  }
}

leave_channel: Occurs when a user leaves a channel.

{
  "action": "leave_channel",
  "data": {
    "channel": "Channel name",
    "user": {
      "email": "nickname@example.com",
      "gravatar": "http://gravatar.com/userimage.jpg",
      "name": "Full name",
      "username": "nickname",
      "status": "active"
    }
  }
}

user_active: Occurs when a user logs on.

{
  "action": "user_active",
  "data": {
    "channel": "Foo",
    "user": {
      "email": "nickname@example.com",
      "gravatar": "http://gravatar.com/userimage.jpg",
      "name": "Full name",
      "username": "nickname",
      "status": "active"
    }
  }
}

user_offline: Occurs when a user logs off.

{
  "action": "user_offline",
  "data": {
    "channel": "Foo",
    "user": {
      "email": "nickname@example.com",
      "gravatar": "http://gravatar.com/userimage.jpg",
      "name": "Full name",
      "username": "nickname",
      "status": "active"
    }
  }
}

Self Events

These messages are prefixed by the email address. All of a user's open clients listen to eachother.

Messages of this type occur when one of a user's open clients wants to communicate to the user's other open clients (ex. the user has joined/reordered/deleted a channel and wants the other open clients to update their UI).

self_join_channel: User signals to his other clients that they should join a channel

{
  "action": "self_join_channel",
  "data": {
    "client_id": "1234-abcd-5678-efgh",
    "channel_id": "abcDEFG==",
    "channel_name": "Joined channel name"
  }
}

self_leave_channel: User signals to his other clients that they should leave a channel

{
  "action": "self_leave_channel",
  "data": {
    "client_id": "1234-abcd-5678-efgh",
    "channel_id": "abcDEFG==",
    "channel_name": "Left channel name"
  }
}

Miscellaneous Events

Pong!: Server acknowledges heartbeat.

{
  "action": "pong",
  "data": {
    "message": "PONG"
  }
}

Sending messages back to the server

Sending chat messages: Sending a message to a channel

{
  "action": "publish_message",
  "data": {
    "message": "Hello world!",
    "channel": "general"
  }
}

Join a channel: Once you join a channel, you will start to receive events that happen on the channel.

{
  "action": "join_channel",
  "data": {
    "channel": "New channel"
  }
}

Leave a channel: Once you leave a channel, you will no longer receive events that happen on the channel.

{
  "action": "leave_channel",
  "data": {
    "channel": "New channel"
  }
}

Heartbeat: Clients should send this keep-alive every 30 seconds to the server.

{
  "action": "ping",
  "data": {
    "message": "PING"
  }
}