Message Protocol

This protocol is intended as a generic data format to store and transmit chat messages coming from different platforms through our socket system.

Namespace

At own3d we follow the <client_id>.<platform>.<platform_id>[.<extension>] namespace format.

Example for own3d chatbot: chatbot.<shard>
Example for own3d user: 90a951d1-ea50-4fda-8c4d-275b81f7d219.own3d.1.chat

The .chat extension is a public room for all users to read.

Socket Connection

// Select a random server
const server: AxiosResponse<string[]> = await axios.get('https://socket-hel1-1.own3d.dev/server-ids')
const serverId: string = server.data[0]
// Connect to the socket
const socket = io('https://socket-hel1-1.own3d.dev', {
    withCredentials: true, // Required for cookies
    extraHeaders: {
        Cookie: 'serverid=' + serverId, // Set the serverid cookie
    },
})

socket.on('connect', () => {
    // login as chatbot or user
})

socket.on("message", (data: TBD) => {
    // TODO handle chat message
});

socket.on("clear-chat", (data: TBD) => {
    // TODO handle delete message
});

socket.on("delete-message", (data: TBD) => {
    // TODO handle clear chat
});

socket.on("ingress-event", (e: {type: string, data: any}) => {
  // TODO handle ingress event
  
  // example event: "heartbeat"
  if (e.type === "heartbeat") {
    console.log("Received heartbeat event", e.data)
  }
});

Message Reference

{
  "id": "9b1aef5e-b16a-4c7a-916e-309b7d581e67",
  "type": "message", // message oder announcement
  "timestamp": 1705400139136, // Y2K38 acknowledged
  "platform": "twitch", // twitch, youtube, etc.
  "user": {
    "platform_id": "12354",
    "username": "Sender",
    "avatar_url": "https://api.own3d.pro/v1/resolvers/avatars/{platform}/{platform_id}",
    "color": "#000000", // nullable
    "badges": [
      { "type": "moderator", "text": "Moderator", "id": "1234" }, // or broadcaster / vip
      { "type": "subscriber", "text": "Subscriber", "id": "1234", "count": 1 },
      { "type": "custom", "text": "TwitchCon 2022", "id": "1234" }
    ]
  },
  "channel": {
    "id": "1", // own3d id
    "platform_id": "4321",
    "username": "OWN3D",
    "avatar_url": "https://api.own3d.pro/v1/resolvers/avatars/{platform}/{platform_id}"
  },
  "message": "Hello @World! KEKW! Kappa Cheer17",
  "fragments": [
    { "type": "text", "text": "Hello " },
    { "type": "mention", "text": "@World" },
    { "type": "text", "text": "! KEKW! " },
    { "type": "emote", "text": "ExtraLife", "data": { "platform": "twitch", "platform_id": "302426269", "emote_set_id": "0" } },
    { "type": "cheermote", "text": "Cheer17", "data": { "platform": "twitch", "platform_id": "cheer", "bits": 17, "tier": 1 } }
  ],
  "parent": {
    "id": "9b1aef5e-b16a-4c7a-916e-309b7d581e67",
    "message": "Hello World!" // nullable
  }, // nullable
  "platform_data": {
    "video_id": "foo",
    "live_chat_id": "bar"
  }, // may be undefined see below
  "attributes": {
    "edited": false,
    "accent": "#ffffff",
    "action": false,
    "highlight": false
  }
}

Message Attributes

`id`

The id attribute is a unique identifier for the message. The id attribute is a string that is generated by the platform.

The type attribute is a string that describes the type of the message. The type attribute may be message or announcement. The announcement uses the accent attribute to highlight the message in a given color. Twitch for example provides different colors for different colors.

`timestamp`

The timestamp attribute is a UNIX timestamp in milliseconds that represents the time when the message was received by our system.

`platform`

The platform attribute is a string that represents the platform where the message was sent. The platform attribute may be twitch, youtube, etc.

`user`

The user attribute is an object that contains information about the user who sent the message.

`channel`

The channel attribute is an object that contains information about the channel where the message was sent.

`message`

The message attribute is a raw string that contains the text of the message.

`fragments`

The fragments attribute is an array of objects that represent the different parts of the message. Each fragment has a type attribute that describes the type of the fragment and a text attribute that contains the text of the fragment.

Text Fragment

The text fragment represents a plain text fragment.

{
  "type": "text",
  "text": "Hello "
}

Mention Fragment

The mention fragment represents a mention of another user in the message. The mention fragment may contain an id attribute that represents the user platform ID of the mentioned user.

{
  "type": "mention",
  "text": "@World"
}

Emote Fragment

The emote fragment represents an emote in the message. The emote fragment may contain an emote_set_id attribute that represents the emote set ID of the emote.

Each emote has a platform and platform_id attribute that represents the platform and the platform ID of the emote.

In the future, we may resolve 7TV, BTTV, FFZ emotes on our server-side to provide a unified experience.

{
  "type": "emote",
  "text": "ExtraLife",
  "data": {
    "platform": "twitch",
    "platform_id": "302426269",
    "emote_set_id": "0"
  }
}

Cheermote Fragment

The cheermote fragment represents a cheermote in the message. The cheermote fragment contains a bits attribute that represents the number of bits used for the cheermote and a tier attribute that represents the tier of the cheermote.

{
  "type": "cheermote",
  "text": "Cheer17",
  "data": {
    "platform": "twitch",
    "platform_id": "cheer",
    "bits": 17,
    "tier": 1
  }
}

The cheermote fragment may or may not keep the bits and tier attributes. This is due to the fact that the bits and tier attributes are not available for all platforms.
The emote fragment may or may not keep the emote_set_id attribute. This is due to the fact that the emote_set_id attribute is not available for all platforms.
The mention fragment may or may not contain the id attribute.