Besides client side sdks, StraaS messaging service also provides server side api for higher privilege control actions. The server-to-server apis locate in an isolated cluster, which have hostname

All the public apis use app token authorization (how to get an app token?), which you have to provide bear token in request header.

And currently have following functions:

1. POST /public-chatrooms
2. POST /public-chatroom (legacy endpoint, to be deprecated)
3. GET /public-chatrooms
4. DELETE /public-chatrooms

1. PUT /manager
2. POST /chat-user
3. GET /chat-user

1. GET /sync-aggregated-data
2. [To be deprecated]POST /archive-msg
3. POST /app/messages
4. PUT /banned_words
5. GET /banned_words

1. POST /chat-meta
2. GET /chat-meta

Chatroom API could be used to create, update the data of chatrooms.

Create a chatroom without an owner. Note that the chat_id in the response doesn't have to be stored, you can still get the chat_id later by providing chatroom name to our sdk.

• Method: POST /public-chatrooms

• Rate Limit:

  10 requests per second

• Example:

    curl -H "Content-Type: application/json" -H "Authorization: Bearer <APP_TOKEN>" -X POST \
    -d '{"chatroom_name":"<CHATROOM_NAME>"}' \
    <host>/public-chatrooms

• Headers:

  Name	Mandatory	Meaning	Note
  Authorization	v	app token belongs to partner	JWT generated from CMS, contains account_id

• Parameters:

  Name	Mandatory	Meaning	Note

• Request Body: application/json

  Name	Mandatory	Meaning	Note
  chatroom_name	v		length range [2, 60]

  E.g.:

  {
    "chatroom_name": "straas-test"
  }

• Response:

  200

  Name	Meaning	Note
  chat_id	unique id of chat	mongo generated id. it's useless in our message sdk, do not need to store it.

  {
    "chat_id": "58104d56b1e769eb00e266fe"
  }

• Error Response:

  Code	Type	Description
  400	Bad Request	invalid parameter
  401	Unauthorized	wrong /expired token
  409	Conflict	chat existed
  429	Too Many Request	hit rate limit
  500	Internal Server Error

List all chatrooms under your account.

• Method: Get /public-chatrooms

• Rate Limit:

  10 requests per second

• Example:

  curl -X GET \
  '<host>/public-chatrooms?page=1&per_page=100' \
  -H 'Authorization: Bearer <APP_TOKEN>' \
  -H 'Content-Type: application/json' \

• Headers:

  Name	Mandatory	Meaning	Note
  Authorization	v	app token belongs to partner	JWT generated from CMS, contains account_id

• Parameters:

  Name	Mandatory	Meaning	Note
  page		Page of results to fetch.	default: 1
  per_page		Number of results to return per page.	default: 100, max: 100

• Request Body: application/json

  Name	Mandatory	Meaning	Note

• Response:

  • Headers

    • implement pagination with web linking RFC8288
    • example

    Link: <https://host_name/public_chatrooms?page=10&per_page=100>; rel="last",
    <https://host_name/public_chatrooms?page=2&per_page=100>; rel="next"
    Page: 1
    Per-Page: 100
    Total: 10
    

    200

    • array of json

    Name	Meaning	Note
    chatroom_name	custom self-defined
    created_at	timestamp in RFC3339 format

    [
      {
        "chatroom_name": "room1",
        "created_at": "2019-11-12T10:09:08.374Z"
      },
      {
        "chatroom_name": "room2",
        "created_at": "2019-12-10T09:13:11.653Z"
      }
    ]

• Error Response:

  Code	Type	Description
  400	Bad Request	invalid parameter
  401	Unauthorized	wrong /expired token
  429	Too Many Request	hit rate limit
  500	Internal Server Error

Delete chatroom.

• Method: DELETE /public-chatrooms

• Rate Limit:

  1 requests per second

• Example:

  curl -X DELETE \
  <host>/public-chatrooms \
  -H 'Authorization: Bearer <APP_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "chatroom_name":"room1"
  }
  '

• Headers:

  Name	Mandatory	Meaning	Note
  Authorization	v	app token belongs to partner	JWT generated from CMS, contains account_id

• Parameters:

  Name	Mandatory	Meaning	Note

• Request Body: application/json

  Name	Mandatory	Meaning	Note
  chatroom_name	v		length range [2, 60]

  E.g.:

  {
    "chatroom_name": "room1"
  }

• Response:

  200

  Name	Meaning	Note

  {}

• Error Response:

  Code	Type	Description
  400	Bad Request	invalid parameter
  401	Unauthorized	wrong /expired token
  404	Not Found	chatroom doesn't exist
  429	Too Many Request	hit rate limit
  500	Internal Server Error

User API could let you operate with your user data.

Change a member's role to be LOCAL_MANAGER or MODERATOR or NORMAL. (Detail about the role is in here) Note that, the member must existed under your account, or you would get an 404 error. (more details about creating new member)

• Method: PUT /manager

• Example:

    curl -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>" -X PUT \
    -d '{"member_id":"<MEMBER_ID>","chatroom_name":"<CHATROOM_NAME>","role":"<ROLE>"}' \
    <host>/manager

• Headers:

  Name	Mandatory	Meaning	Note
  Authorization	v	app token belongs to partner	JWT generated from CMS, contains account_id

• Parameters:

  Name	Mandatory	Meaning	Note

• Request Body: application/json

  Name	Mandatory	Meaning	Note
  member_id	v
  chatroom_name	v		length range [2, 60]
  role	v		enum: LOCAL_MANAGER, MODERATOR, NORMAL

  E.g.:

  {
    "member_id": "[email protected]",
    "chatroom_name": "straas-test",
    "role": "LOCAL_MANAGER"
  }

• Response:

  200

  Name	Meaning	Note
  ok

  {}

• Error Response:

  Code	Type	Description
  400	Bad Request	invalid parameter
  401	Unauthorized	wrong /expired token
  404	Not Found	chat/member not found
  429	Too Many Request	hit rate limit
  500	Internal Server Error

• Rate Limit:

  10 requests per second

Add an existed member to a chatroom. Please note that adding a member into a chatroom is systematically creating the relationship between a member ID and a chatroom for further account manipulation, e.g. promoting as a chatroom manager while the member himself might actually stay out of the chatroom. The only way that a member can literally join in a chatroom and be able to chat with the others is through another API method connect(chatroomName, options), please see here for more details.

• Method: POST /chat-user

• Example:

    curl -H "Content-Type: application/json" -H "Authorization: Bearer <APP_TOKEN>" -X POST \
    -d '{
      "chatroom_name":"<CHATROOM_NAME>",
      "member_id":"<MEMBER_ID>",
      "role":"NORMAL"
    }' \
    <host>/chat-user

• Headers:

  Name	Mandatory	Meaning	Note
  Authorization	v	app token belongs to partner	JWT generated from CMS, contains account_id

• Request Body: application/json

  Name	Mandatory	Meaning	Note
  chatroom_name	v		length range [2, 60]
  member_id	v		the member must be created by CMS create member API
  role	v	role of the member in the chatroom	(MODERATOR|LOCAL_MANAGER|NORMAL), Please refer https://github.com/StraaS/StraaS-web-document/wiki/Messaging-Service-Concept#roles-of-messaging-service

• Response:

  200

• Error Response:

  Code	Type	Description
  400	Bad Request	invalid parameter
  401	Unauthorized	wrong /expired token
  404	Not Found	chatroom not found or member not found
  409	Conflict	member already existed in chatroom
  429	Too Many Request	hit rate limit
  500	Internal Server Error

• Rate Limit:

  10 requests per second

This API gets the member's data of some chatroom. A member might have different roles in different chats. Note that, this API only gets member's data (guest doesn't have member_id, and its role could only be NORMAL or BLOCKED)

• Method: GET /chat-user

• Example:

    curl -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>" \
      -XGET <host>/chat-user?chatroom_name=<CHATROOM_NAME>&member_id=<MEMBER_ID>

• Headers:

  Name	Mandatory	Meaning	Note
  Authorization	v	app token belongs to partner	JWT generated from CMS, contains account_id

• Query Parameters:

  Name	Mandatory	Meaning	Note
  member_id	v
  chatroom_name	v		length range [2, 60]

• Request Body: application/json

  Name	Mandatory	Meaning	Note

• Response:

  200

  Name	Meaning	Note
  member_id
  chatroom_name
  name		if member doesn't have a name, it would be member_id
  avatar_url
  personal_url
  role		more about role

  {
    "member_id": "[email protected]",
    "chatroom_name": "some_chat",
    "name": "some_name",
    "avatar_url": "https://some.picture/ooo.jpg",
    "peronsal_url": "some url",
    "role": "NORMAL"
  }

• Error Response:

  Code	Type	Description
  400	Bad Request	invalid parameter
  401	Unauthorized	wrong /expired token
  404	Not Found	chat/member not found
  429	Too Many Request	hit rate limit
  500	Internal Server Error

• Rate Limit:

  100 requests per second

Message APIs could let you sync and control related messages.

Get recently(within two months) changed aggregated data of some chats that belong to some account

• Method: GET /sync-aggregated-data

• Example:

    curl -H "Content-Type: application/json" -H "Authorization: Bearer <APP_TOKEN>" \
    <host>/sync-aggregated-data?index=0&page_size=100

• Headers:

  Name	Mandatory	Meaning	Note
  Authorization	v	app token belongs to partner	JWT generated from CMS, contains account_id

• Parameters:

  Name	Mandatory	Meaning	Note
  index	v	index for syncing
  page_size		Number of results to return (1 ~ 1000), default is 100

• Request Body:

  Name	Mandatory	Meaning	Note

• Response:

  200

  Name	Meaning	Note
  next_index	index for next sync	get same value as input, means there doesn't have any new data
  data[]	array contains aggregated data of chat	empty if there doesn't have any new data

  {
    "next_index": "1487080435000",
    "data":
    [{
      "chat_id": "58104d56b1e769eb00e266fe",
      "chatroom_name": "chat1",
      "aggregated": [{ "key": "key1", "n": 11 }, { "key": "key2", "n": 22 }]
    }, {
      "chat_id": "58104d56b1e769eb00e777fe",
      "chatroom_name": "chat2",
      "aggregated": [{ "key": "key3", "n": 33 }]
    }]
  }

• Error Response:

  Code	Type	Description
  400	Bad Request	invalid parameter
  401	Unauthorized	wrong /expired token
  429	Too Many Request	hit rate limit
  500	Internal Server Error

Note that, this api is going to be deprecatd.

Since get-messages-by-chat API only allow users to retrieve recent messages, for the requirement to retrieve old messages, archive-msg API archives messages with user generated id and given date range. Although API only allows to archive recent messages too, archived messages will be kept for a long time. End user could retrieve archived messages via our SDK with the archive id.

• Method: POST /archive-msg

• Example:

    curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer <APP_TOKEN>" \
    -d '{
      "archiveId": "a123412341234123412341",
      "chatroomName": "testChatRoomName",
      "msgType": "text",
      "oldestDate": 1494801537000,
      "latestDate": 1494809537000
    }`

• Headers:

  Name	Mandatory	Meaning	Note
  Authorization	v	app token belongs to partner	JWT generated from CMS, contains account_id

• Request Body:

  Name	Mandatory	Meaning	Note
  archiveId	v	user generated ID bind to the archive message	id should match the regular expression pattern ^[A-Za-z0-9_-]{10,32}$
  chatroomName	v	the name of chatroom to archive
  msgType	v	indicate the type of sending msg	"text" or "raw"
  oldestDate	v		unix timestamp in millisecond, oldestDate not older than (2 weeks)
  latestDate	v		unix timestamp in millisecond, latestDate - oldestDate <= 1 day

• Response:

  200

• Error Response:

  Code	Type	Description
  400	Bad Request	invalid parameter
  401	Unauthorized	wrong /expired token
  404	Not Found	chat room not found
  429	Too Many Request	hit rate limit
  500	Internal Server Error

Create a message from server side of some partners, then it would be broadcasted by socket event

• Method: POST /app/messages

• Example:

    curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer <TOKEN>" -X POST \
    -d '{
      "chatroom_name": "<CHATROOM_NAME>",
      "msg_type": "text",
      "text": "some text"
    }' \
    <host>/app/messages

• Headers:

  Name	Mandatory	Meaning	Note
  Authorization	v	app token belongs to partner	JWT generated from CMS, contains account_id

• Request Body: application/json

  Name	Mandatory	Meaning	Note
  chatroom_name	v		length range [2, 60]
  msg_type		text(default) or raw
  value		json type, used in raw message	max length of JSON.stringify(value) is 2048
  text		string type, used in text message	max length is 300. text would be cropped if it exceeds max length

• for text message, new line would be replace by space

    text.replace(/\r?\n|\r/gm, " ")

  E.g.:

  {
    "chatroom_name": "straas-test",
    "msg_type": "text",
    "text": "this is a text message"
  }

  {
    "chatroom_name": "straas-test",
    "msg_type": "raw",
    "value": {
      "custom-defined-field": "this is a raw message"
    }
  }

• Response:

  200

  Name	Meaning	Note
  message_id	unique id of message

  {
    "message_id": "58104d56b1e769eb00e266fe"
  }

• Error Response:

  Code	Type	Description
  400	Bad Request	invalid parameter
  401	Unauthorized	wrong /expired token
  404	Not Found	chat not exist
  429	Too Many Request	reach rate limit
  500	Internal Server Error

• Socket Event:

  • event message for text message

  socket.emit("message", {
    "id":"5628563d989b73094eb6da25",
    "category": "SYSTEM",
    "text": "some text",
    "createdDate":"2015-10-22T03:21:33.459Z",
    "creator":{
      "name": "system",
      "label": -1
    }
  })

  • event raw_data for raw message

  socket.emit("raw_data", {
    "id":"5628563d989b73094eb6da25",
    "category": "SYSTEM",
    "value": {
      "aaa": "bbb"
    },
    "createdDate":"2015-10-22T03:21:33.459Z",
    "creator":{
      "name": "system",
      "label": -1
    }
  })

• Set banned words which would be blocked in the chatroom

• Method: PUT /banned-words

• Example:

    curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer <TOKEN>" -X PUT \
    -d '{
      "banned_words": ["只有", "支援", "中文"]
    }' \
    <host>/banned-words

• Headers:

  Name	Mandatory	Meaning	Note
  Authorization	v	app token belongs to partner	JWT generated from CMS, contains account_id

• Request Body: application/json

  Name	Mandatory	Meaning	Note
  banned_words	v		maximum number of banned word is 500

  • only support Chinese character
  • it would update all banned words in database, if you want to keep old banned words, remember to put those old banned words in api body
    • e.g. have ["a"], set ["b"], get only ["b"]; set ["a", "b"] to get both
  • set an empty array to clear all banned words

• Response:

  200

  Name	Meaning	Note

  {}

• Error Response:

  Code	Type	Description
  400	Bad Request	invalid parameter
  401	Unauthorized	wrong / expired token
  429	Too Many Request	reach rate limit
  500	Internal Server Error

• Rate Limit:

  10 requests per second

• Method: GET /banned-words

• Example:

    curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer <TOKEN>" -X GET \
    <host>/banned-words

• Headers:

  Name	Mandatory	Meaning	Note
  Authorization	v	app token belongs to partner	JWT generated from CMS, contains account_id

• Query Parameters: application/json

  Name	Mandatory	Meaning	Note

• Response:

  200

  Name	Meaning	Note
  banned_words		array of string

  {
    "banned_words": ["只有", "支援", "中文"]
  }

• Error Response:

  Code	Type	Description
  400	Bad Request	invalid parameter
  401	Unauthorized	wrong / expired token
  429	Too Many Request	reach rate limit
  500	Internal Server Error

• Rate Limit:

  10 requests per second

Chat Metadata API could be used to get and set chat metadata of chatrooms.

Set a metadata key-value pair to a chatroom

• Method: POST /chat-meta

• Example:

    curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <APP_TOKEN>" \
    https://mgp.straas.net/chat-meta \
    -d '{
      "chatroom_name": "testChatRoomName",
      "key": "some_key",
      "value": {"aaa": 10, "bbb": 5},
      "broadcast": true
    }`
  

• Headers:

  Name	Mandatory	Meaning	Note
  Authorization	v	app token belongs to partner	JWT generated from CMS, contains account_id

• Parameters:

  Name	Mandatory	Meaning	Note

• Request Body: application/json

  Name	Mandatory	Meaning	Note
  chatroom_name	v		length range [2, 60]
  key	v	key of a metadatda pair	key must match regular expression ^[A-Za-z0-9][A-Za-z0-9_-@#]{0,29}$
  value	v	value of metadata pair	value must be a valid JSON, the max size of broadcasting metadata is 1k and none-broadcasting is 4k
  broadcast	v	indicate metadata is broadcasting or not

• Response:

  200

  {}

• Error Response:

  Code	Type	Description
  400	Bad Request	invalid parameter
  401	Unauthorized	wrong /expired token
  403	Forbidden	operation is not allowed
  404	Not Found	chat room not found
  429	Too Many Request	hit rate limit
  500	Internal Server Error

• Socket Event:

  • if input broadcast is true, server would emit meta event

    socket.emit("meta", [{
      key: "some_key",
      scope: "chat",
      value: {"aaa": 10, "bbb": 5},
      version: 1
    }])

• Rate Limit:

  Type	Limit
  Broadcast	1 request per second per chatroom
  None-broadcast	30 request per second per chatroom

• Remark:

  Each chatroom is allowed to store 100 different metadata keys, setting more than 100 keys will lead to Forbidden(403) response

Query metadata key-value pairs of a chatroom

• Method: GET /chat-meta

• Example:

    curl \
    -H "Authorization: Bearer <APP_TOKEN>" \
    "https://mgp.straas.net/chat-meta?chatroom_name=testChatRoomName&keys[]=aaa&keys[]=bbb"

• Headers:

  Name	Mandatory	Meaning	Note
  Authorization	v	app token belongs to partner	JWT generated from CMS, contains account_id

• Parameters:

  Name	Mandatory	Meaning	Note
  chatroom_name	v		length range [2, 60]
  keys		array contains keys to query	query all keys associated to the chatroom if not specified

• Response:

  Name	Meaning	Note
  meta	array of Model Meta

  Name	Meaning
  scope	scope of metadata
  key	key of a metadata pair
  value	value of a metadata pair
  broadcast	broadcasting or not

  {
    "meta": [
      {
        "scope": "chat",
        "key": "aaa",
        "value": {"a":10},
        "broadcast": true
      },
      {
        "scope": "chat",
        "key": "aaa",
        "value": [4, 5, 6, 7],
        "broadcast": false
      },
      {
        "scope": "chat",
        "key": "bbb",
        "value": null,
        "broadcast": true
      }
    ]
  }

• Error Response:

  Code	Type	Description
  400	Bad Request	invalid parameter
  401	Unauthorized	wrong /expired token
  404	Not Found	chat room not found
  429	Too Many Request	hit rate limit
  500	Internal Server Error

• Rate Limit:

  10 requests per second per chatroom

• Remark:

  When keys are given, API only responses with existed keys, even no keys were found at all