Appearance

Return to top
On this page

Talkee Websocket Protocol

Authentication

Talkee need client to send credentials (access token) as the first message in the WebSocket connection.

The JavaScript code below shows how to authenticate with Talkee WebSocket connection:

js
const socket = new WebSocket(
  `${talkeeWsBase}?site_id=${site_id}&slug=${slug}`
);
socket.addEventListener("open", (event) => {
  // send the auth message
  socket.send(
    JSON.stringify({
      type: "auth",
      token: talkeeToken,
    })
  );
});

// Listen for incoming messages
socket.addEventListener("message", (event) => {
  console.log("receive a message", event.data);
});

Note that the talkeeToken is the access_token returned by Talkee /auth/login API, which we mentioned in the previous section section.

Message types

Talkee uses a simple message format to communicate with clients, which is a JSON object with the following fields:

FieldTypeDescription
categorystringThe type of the message.
dataobjectThe data of the message. Should be base64 encoded.
message_iduuidAn uuid of message.

At present, Talkee only supports one type of message: text. So, to send a text message, you can do it like this:

js
const url = `${talkeeWsApiBase}/messages?site_id=${site_id}&slug=${slug}`;
const resp = await fetch(url, {
  method: "POST",
  mode: "cors",
  cahce: "no-cache",
  headers: {
    Authorization: "Bearer " + talkeeToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message_id: uuidv4(),
    category: "text",
    data: btoa("Hello!"),
  }),
});

const data = await resp.json();
console.log(data);

Get latest messages

AUTHORIZATION REQUIRED
GET /messages?site_id=:site_id&slug=:slug&filter=latest

This API is used to get latest 100 messages of specific site and slug.

Params
NameTypeInRequiredDescription
site_idnumberurltruesite's id
slugstringurltruethe slug of site
filterstringurltruethe filter name of messages, can only be "latest"

Response

json
[
  {
    "category":"text",
    "data":"SGVsbG8h",
    "created_at":"2023-02-06T17:26:17.800860098+09:00",
    "user":{
      "id": 1,
      "mixin_user_id": "36158804-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "mixin_identity_number": "1234456",
      "full_name": "John Wick",
      "avatar_url": "https://mixin-images.zeromesh.net/...",
      "created_at": "2022-02-05T16:11:16.420872+09:00"
    }
  }
  // ...
]

Create a new message

AUTHORIZATION REQUIRED
POST /messages?site_id=:site_id&slug=:slug

This API is used to create a new message.

Params
NameTypeInRequiredDescription
site_idnumberurltruesite's id
slugstringurltruethe slug of site
categorystringjsontruethe category of message, can only be "text"
datastringjsontruethe data of message, should be base64 encoded
message_iduuidjsontrueAn uuid of message

Response

json
{
  "category":"text",
  "data":"SGVsbG8h",
  "created_at":"2023-02-06T17:26:17.800860098+09:00",
  "user":{
    "id": 1,
    "mixin_user_id": "36158804-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "mixin_identity_number": "1234456",
    "full_name": "John Wick",
    "avatar_url": "https://mixin-images.zeromesh.net/...",
    "created_at": "2022-02-05T16:11:16.420872+09:00"
  }
}