Query Historical Chat Messages

Updated: 2022-05-23 19:02:59

Interface URL

http://api.polyv.net/live/v2/chat/{channelId}/getHistory

Interface Description

1. Purpose: Query chat records within a specified time period. The time format is yyyy-MM-dd or yyyy-MM-dd HH:mm:ss.
If only a date is provided without a specific time, the start time defaults to 00:00:00 of that day, and the end time defaults to 23:59:59 of that day.
2. The interface supports the HTTPS protocol.
3. {channelId} in the interface URL represents the Channel ID.

Supported Format

JSON

Request Method

GET, POST

Request Limit

TRUE

Request Parameters

Parameter Name	Required	Type	Description
startDay	Yes	String	Start time for chat records. Format must be yyyy-MM-dd (e.g., 2017-08-01) or yyyy-MM-dd HH:mm:ss (e.g., 2017-08-01 16:30:12)
endDay	Yes	string	End time for chat records. Same format requirements as above.
appId	Yes	string	Obtained from API settings, the appId registered in the live streaming system.
page	No	int	Page number of chat records to retrieve. Default is 1.
limit	No	int	Number of records per page. Default is 1000.
timestamp	Yes	string	Current 13-digit millisecond timestamp. Valid for 3 minutes.
sign	Yes	string	Signature, 32-character uppercase MD5 value.
userType	No	string	User type. Multiple types can be selected, separated by commas. Optional values include: slice: Cloud Classroom Student teacher: Instructor guest: Guest manager: Administrator assistant: Teaching Assistant viewer: Special Guest Viewer monitor: Event Monitor attendee: Seminar Participant student: General Live Stream Viewer
status	No	string	Chat record status. Default: pass (approved). Review status: pass (approved), censor (under review and deleted).
source	No	string	Type. Default is public chat if not specified. extend: Administrator private chat.
roomId	No	string	If a room ID exists, it needs to be passed. Default is not passed.

Successful Response JSON Example

{
    "code": 200,
    "status": "success",
    "message": "",
    "data": [
        {
            "accountId": "ee7fe7fbda",
            "clientIP": "",
            "content": "123",
            "event": "",
            "id": "9b7b0d20-12b7-11eb-8860-43fdec7e6710",
            "image": "",
            "msgType": "",
            "quote": "",
            "roomId": "157468202",
            "sessionId": "",
            "time": 1603186536120,
            "user": {
                "actor": "管理员",
                "banned": false,
                "channelId": "1574682",
                "clientIp": "",
                "nick": "管理员",
                "pic": "//s1.videocc.net/face.png",
                "roomId": "157468201",
                "sessionId": "fnnjgog6vi",
                "uid": "46a6KWLWMdxQwBShAAAC",
                "userId": "ee7fe7fbda",
                "userType": "manager"
            },
            "userType": "manager",
            "status": "pass",
            "sourceType": "public"
        },
        {
            "accountId": "ee7fe7fbda",
            "clientIP": "",
            "content": "3231",
            "event": "",
            "id": "9ee931d0-12b7-11eb-b668-b35576b339fa",
            "image": "",
            "msgType": "",
            "quote": "",
            "roomId": "157468202",
            "sessionId": "",
            "time": 1603186541876,
            "user": {
                "actor": "管理员",
                "banned": false,
                "channelId": "1574682",
                "clientIp": "",
                "nick": "管理员",
                "pic": "//s1.videocc.net/face.png",
                "roomId": "157468202",
                "sessionId": "fnnjgog6vi",
                "uid": "VQUMlI2l7wcHjiJaAAAC",
                "userId": "ee7fe7fbda",
                "userType": "manager"
            },
            "userType": "manager",
            "status": "pass",
            "sourceType": "public"
        }
    ]
}

Failed Response JSON Examples:

appId not provided

{
    "code": 400,
    "status": "error",
    "message": "appId not found.",
    "data": ""
}

Incorrect appId

{
    "code": 400,
    "status": "error",
    "message": "application not found.",
    "data": ""
}

Timestamp error

{
    "code": 400,
    "status": "error",
    "message": "invalid timestamp.",
    "data": ""
}

Signature error

{
    "code": 403,
    "status": "error",
    "message": "invalid signature.",
    "data": ""
}

Channel ID error

{
    "code": 400,
    "status": "error",
    "message": "channel not found.",
    "data": ""
}

Start time is empty

{
    "code": 400,
    "status": "error",
    "message": "startDay can not be empty.",
    "data": ""
}

End time is empty

{
    "code": 400,
    "status": "error",
    "message": "endDay can not be empty.",
    "data": ""
}

Incorrect start time format (correct format is yyyy-MM-dd)

{
    "code": 400,
    "status": "error",
    "message": "the startDay is no right.",
    "data": ""
}

Incorrect end time format (correct format is yyyy-MM-dd)

{
    "code": 400,
    "status": "error",
    "message": "the endDay is no right.",
    "data": ""
}

End time is earlier than start time

{
    "code": 400,
    "status": "error",
    "message": "the endDay can not be earlier than the startDay.",
    "data": ""
}

Other errors

{
    "code": 400,
    "status": "error",
    "message": "Unable to access chat room data",
    "data": ""
}

Field Description

Parameter Name	Type	Description
code	int	Request status response code
status	string	Request status
message	string	Error message
data	array	Data list
data[0].accountId	string	Account ID
data[0].clientIP	string	User IP
data[0].content	string	Chat content
data[0].id	string	Chat message ID
data[0].image	string	Image URL for image messages
data[0].msgType	string	Current values: redpaper: Red envelope message; chatImg: Image message; custom: Custom message (sent via socket); reward: Tip message; customerMessage: Custom message (sent via HTTP interface) Empty (msgType="") indicates a regular chat message;
data[0].quote		string
data[0].roomId	string	Channel ID
data[0].sessionId	string	Session ID
data[0].time	string	Timestamp when the message was sent
data[0].status	string	Review status: pass (approved), censor (under review), delete (deleted)
data[0].userType	string	User type. Possible values: slice: Cloud Classroom Student teacher: Instructor guest: Guest manager: Administrator assistant: Teaching Assistant viewer: Special Guest Viewer monitor: Event Monitor attendee: Seminar Participant student: General Live Stream Viewer
data[0].sourceType	string	Message source. Currently: public (group chat), extend (administrator private chat)
data[0].user.clientIp	string	User IP
data[0].user.nick	string	Viewer nickname
data[0].user.pic	string	Viewer avatar
data[0].user.roomId	string	Room ID
data[0].user.userId	string	Unique user identifier
data[0].user.uid	string	socketId
data[0].user.sessionId	string	Session ID
data[0].user.channelId	int	Channel ID
data[0].user.banned	boolean	Whether muted
data[0].user.actor	string	Role
data[0].user.userType	string	User type. Possible values: slice: Cloud Classroom Student teacher: Instructor guest: Guest manager: Administrator assistant: Teaching Assistant viewer: Special Guest Viewer monitor: Event Monitor attendee: Seminar Participant student: General Live Stream Viewer

content Type Description

content The field type is affected by the msgType field. If msgType is empty, it indicates a regular message, and content is a string type. If msgType is another type, then content is an object.

msgType is redpaper

Indicates a red envelope. The content object is:

Parameter Name	Type	Description
content	string	Red envelope description
msgSource	string	String "redpaper"
number	number	Number of red envelopes
redCacheId	string	Red envelope cache ID
redpackId	string	Red envelope ID
totalAmount	number	Total amount of red envelopes
type	string	Red envelope type: normal for regular red envelope, rain for red envelope rain

msgType is chatImg

Sending an image. The content object is:

Parameter Name	Type	Description
id	string	Image ID
msgSource	string	String "chatImg"
size	object	Image size information, where width indicates width and height indicates height
status	string	Image success status
type	string	String "chatImg"
uploadImgUrl	string	Image link URL

msgType is custom

Sending a custom message. The content object is:

Parameter Name	Type	Description
msgSource	string	String "custom"
EVENT	string	Custom message event name
version	number	Custom message version
emitMode	number	Custom message broadcast type: 0 broadcasts to everyone in the room including self; 1 broadcasts to the room excluding self; 2 broadcasts to a specific socketID.
tip	string	Custom message prompt
data	object	Custom message content, defined by the caller

POLYV Help Center