Euphoria Packet Format

Packets

The heim API is transmitted via websocket in units called packets. Each packet is serialized to JSON with UTF-8 encoding for transmission.

Packets originating from the client will always receive a packet from the server in response. If a client sends packets A and B, then the server will always send the response to A before it sends the response to B.

The server may also send packets to the client asynchronously. For example, when a user says something in a room, a packet is broadcast to each other session connected to that room. An asynchronous packet could be transmitted before the response to a client packet is transmitted.

Every packet shares a common top-level structure. Here is a sample ping, sent from the the server to the client on connect.

{
  type: "ping-event",
  data: {
    time:1428979816,
    next:1428979846
  }
}

The type, and data fields are common to all packets. The type field specifies the command or event being communicated, and this determines the expected structure of the data field. This packet is an example of an asynchronous packet.

Non-asynchronous packets use an id field:

{
  id: "1",
  type: "send",
  data: {
    content: "hello ezzie!"
  }
}

The id should be given in any packet sent by the client, and its value should be unique in the lifetime of the connection. The server must include the same id when it sends the corresponding response packet, if an id was given.

Client Commands

The following commands are available to the client:

Type	Purpose	Example
nick	Modify the user's display name for this session.
who	Receive a listing of live users in the room.
log	Receive the most recent chat history.
send	Send a message to the room's chat.

nick

Use the nick command to change the user's display name, for subsequent messages sent from the user and for subsequent listings of the room. The user will not be allowed to send messages to a room before sending a nick packet.

Request: {id: "1", type: "nick", data: {name: "Ezzie"}}

Response:

{
  id: "1", 
  type: "nick-reply", 
  data: {
    id: "agent:61ea7b275e1248f5", 
    name: "Ezzie", 
    server_id:"heim.3", 
    server_era:"00g5femcgk0lc", 
    session_id:"373f7e9af9f00b71-00000236"
  }
}

The response will also be broadcast to all other users in the room.

Broadcast:

{
  type: "nick-event",
  data: {
    id: "agent:61ea7b275e1248f5", 
    to: "Ezzie", 
    from: "Logan", 
    server_id:"heim.3", 
    server_era:"00g5femcgk0lc", 
    session_id:"373f7e9af9f00b71-00000236"}
}

who

Use the who command to fetch the current list of live users in the room.

Request: {id: "2", type: "who"}

Response: ``` { id: "2", type: "who-reply", data: [ { id: "agent:61ea7b275e1248f5", name: "Logan", server_id:"heim.3", server_era:"00g5femcgk0lc", session_id:"61ea7b275e1248f5-00000236" }, { id: "agent:8ed8e41c4771ca4f", name: "Max", server_id:"heim.4", server_era:"00g5fg7f12ww0", session_id:"8ed8e41c4771ca4f-00000210" } ] }

<h4>log</h4>

Use the log command to fetch the latest *n* messages from the room's chat. 

Request: `{id: "1", type: "log", data: {n: 50, before:"00c97lmxzgq9s"}}`

Response:

{ id: "1", type: "log-reply", data: [ { time: 1418585692, sender: { id: "agent:8ed8e41c4771ca4f", name: "Max", server_id:"heim.4", server_era:"00g5fg7f12ww0", session_id:"8ed8e41c4771ca4f-00000210" }, content: "hi!", edited:null, deleted:null }, { time: 1418585697, sender: { id: "agent:8a55576975ce6e47", name: "Logan", server_id:"heim.3", server_era:"00g5femcgk0lc", session_id:"61ea7b275e1248f5-00000236" }, content: "j0!", edited:null, deleted:null } ] }

<h4>send</h4>

Use the send command to send a message to the room's chat.

Request: `{id: "1", type: "send", data: {content: "hello ezzie"}}`

Response:

{ id: "1", type: "send-reply", data: { time: 1418585715, id:"00gd6yy9hvksg", parent:"" sender: { id: "agent:4da8fa7375215589", name: "Ezzie", server_id:"heim.1", server_era:"00g5fdwjzl91c", session_id:"4da8fa7375215589-00000246"}, content: "hello ezzie", edited:null, deleted:null } }

The response will also be broadcast to all other users in the room.

Broadcast:

{ type: "send-event", data: { time: 1418585715, id:"00gd6yy9hvksg", parent:"" sender: { id: "agent:4da8fa7375215589", name: "Ezzie", server_id:"heim.1", server_era:"00g5fdwjzl91c", session_id:"4da8fa7375215589-00000246"}, content: "hello ezzie", edited:null, deleted:null } }