Messaging Service Public API

Introduction

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

Hostname: `https://mgp.straas.net`

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:

Chatroom API

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

[POST] Create chatroom

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

[GET] List chatrooms

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] Delete chatroom

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

User API could let you operate with your user data.

[PUT] Create or update a member's role in a chatroom

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": "test@straas.io",
  "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

[POST] Add a member into chatroom

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

[GET] Get a member's data of a chatroom

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": "some_member@ikala.tv",
  "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 API

Message APIs could let you sync and control related messages.

[GET] Sync Aggregated Data

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

[POST] Archive Messages

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

[POST] Create Message

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
  }
})

[PUT] Set banned word

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

[GET] Get banned word

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

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

[POST] Chat Metadata

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

[GET] Chat Metadata

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

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

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

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

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

Messaging Service Public API

Introduction

Hostname: https://mgp.straas.net

Chatroom api

User api

Message api

Chat Metadata api

Chatroom API

[POST] Create chatroom

[GET] List chatrooms

[DELETE] Delete chatroom

User API

[PUT] Create or update a member's role in a chatroom

[POST] Add a member into chatroom

[GET] Get a member's data of a chatroom

Message API

[GET] Sync Aggregated Data

[POST] Archive Messages

[POST] Create Message

[PUT] Set banned word

[GET] Get banned word

Chat Metadata API

[POST] Chat Metadata

[GET] Chat Metadata

Straas API Overview

Authentication

Register a member avatar in Straas

Video uploading

Sell your content

How to play a stream

Common Concept

Broadcasting

Messaging Service

Concept

SDK

Messaging Server-side APIs

Sample Code

API Document

Clone this wiki locally

Hostname: `https://mgp.straas.net`