COVERITLIVE API - COMMENT/LIST (V. 2.0)

The Request

This method provides a list of comments submitted to a CoveritLive event. This includes all comments, including those that weren't published. It also includes comments from all sources, including those submitted by email or through the API (using the comment/create method)

URL:
https://api.coveritlive.com/remote/2/comment/list
Response Format:
JSON
HTTP Method(s):
GET
API Rate Limited:
false
In addition to the parameters listed in the Request Parameters section, the comment/create method also includes the following parameters:

Parameter Description Required
event_code The event code for the event for which comments are being retreived. Each CiL event that is created is assigned a unique event code that identifies it in the database - The event owner can find this value after creating a new event, by selecting the "altcast_code" which is found in their Viewer Window embed code (e.g. the event code is "46e6cd22b5" in "altcast_code=46e6cd22b5"). This value is also returned by the event/list API method. yes
comment_id The comment ID at which you want to start receiving comments. The comment ID is unique and is provided in the data for any comment returned. If it's not included, it will default to the earliest possible comment item (up to the default comment_count limit). no
comment_count Controls the number of comments that are returned. If the comment_id parameter is also included in the request, the comment_count comments directly after the comment with comment_id will be returned. Set comment_count to a negative value to return the comment_count items directly before the comment with comment_id. If no value is provided, the last 500 matching comments will be returned. Set this to an integer less than 500 to limit the number of comments returned. If this value is set to an integer greater than 500, only the last 500 matching comments will be returned. no
source Where a comment originated. If parameter not included or left blank, comments from all sources will be returned. Possible values:

native - typed by a person viewing the event

api - Comment supplied by comment/create API method

email - Comment submitted through email
no
status Controls the status of the returned items. Possible values:

deleted - returns all comments that have been deleted.

Omit this parameter to return only active comments (comments that have not been deleted).
no

Example #1 - Retrieve the last 25 comments after a particular item


https://api.coveritlive.com/remote/2/comment/list?
event_code=000000000
&token=05c413a1242b409fa91f574cea05072b
&comment_id=11649181 
&comment_count=25

This request would retrieve:

  • comments for the event with event_code 000000000 which is accessible to the user identified by token 05c413a1242b409fa91f574cea05072b
  • retrieving 25 comments that are directly subsequent to the comment with an comment_id of 11649181

Example #2 - Retrieve the last 25 comments before a particular item


https://api.coveritlive.com/remote/2/comment/list?
event_code=000000000
&token=05c413a1242b409fa91f574cea05072b
&comment_id=11649181 
&comment_count=-25

This request would retrieve:

  • comments for the event with event_code 000000000 which is accessible to the user identified by token 05c413a1242b409fa91f574cea05072b
  • retrieving 25 comments that are directly before the comment with an comment_id of 11649181

Example #3 - How to retrieve Reader Comment API inserted comments in an event


https://api.coveritlive.com/remote/2/comment/list?
event_code=000000000
&token=05c413a1242b409fa91f574cea05072b
&source=api

This request would retrieve:

  • comments for the event with event_code 000000000 which is accessible to the user identified by token 05c413a1242b409fa91f574cea05072b
  • comments where the source of the comment was from the API rather than native to the event or through email.

The Response

The comment data is returned in the data field of a general response. The data returned consists of the following fields:

Field Name Field Value(s) Explanation
code {string} Event Code - a unique code that identifies the event.
title {string} Event Title - the title of the event.
status upcoming
live
finished
Status of the event.
comment_count {int} Count of event stream items.
scheduled_starttime {int} Date and time event was scheduled to start. Value is integer representing seconds since Unix Epoch (January 1 1970 00:00:00) GMT timezone.
start_timestamp {int} Date and time event started - empty if status is upcoming. Value is integer representing seconds since Unix Epoch (January 1 1970 00:00:00) GMT timezone.
end_timestamp {int} Date and time event ended - empty if status is upcoming or live. Value is integer representing seconds since Unix Epoch (January 1 1970 00:00:00) GMT timezone
event_comments {Array} An array of comment objects

comment objects have the following fields:


Field Name Field Value(s) Explanation
commentID {string} ID of this comment
timestamp {int} Date and time comment was submitted - format UNIX timestamp.
author_name {string} Display name of the author of the comment.
author_avatar {string} URL of thumbnail image associated with author_name. Empty if none provided. (NOTE: Image size is not guaranteed and may vary depending on image source and type. It is recommended that consumers of the comment/list data adjust image size appropriately for the destination environment.)
moderation moderated
unmoderated
unpublished
When a comment is initially submitted, it's moderation status is unpublished. If it is subsequently published, it's moderation status changes to moderated. If a user has been given the ability to publish without moderation (aka "Always Allow"), their comments are automatically published and the comment moderation status is unmoderated
source {string} The source of the comment. If blank, the comment was submitted through the viewer window. Possible values include:

API - Comment supplied by the comment/create API method

email - Comment submitted through email
status {string} The status of the comment. Possible values include:

deleted - The comment has been deleted in the EventStudio

active - The comment is visible in the EventStudio
api_tag {string} Comments sent to the event through the Reader Comment API have an optional field (tag) which if provided will be shown here.
comment {string} Comment text
time {string} Time comment was submitted using format: HH:MM

Example response to a successful comment/list request:


{
    "result":"success",
    "message":"true",
    "type":"comment",
    "action":"list",
    "version":2,
    "data":{
        "code":"7f577dcef3",
        "title":"Test API Event",
        "status":"live",
        "comment_count":5,
        "scheduled_starttime":"1315576800",
        "start_timestamp":"1315576573",
        "end_timestamp":"-62169962400",
        "event_comments":[
            {
                "commentID":"13630089",
                "timestamp":1315576630,
                "author_name":"Viewer Commenter",
                "author_avatar":"",
                "moderation":"moderated",
                "status" : "active",
                "source":"",
                "api_tag":"",
                "comment":"Test comment from a guest. ",
                "time":"10:05"
            },
            {
                "commentID":"13630088",
                "timestamp":1315576620,
                "author_name":"API Commenter",
                "author_avatar":"",
                "moderation":"moderated",
                "status" : "active",
                "source":"API",
                "api_tag":"",
                "comment":"Test comment from an api user. ",
                "time":"10:00"
            },
            {
                "commentID":"13630087",
                "timestamp":1315576610,
                "author_name":"jordanb",
                "author_avatar":"",
                "moderation":"moderated",
                "status" : "active",
                "source":"email",
                "api_tag":"",
                "comment":"Test comment from an email user. ",
                "time":"09:57"
            },
        ]
    }
}

comment/list Error Responses

A variety of error responses (in addition to the common error responses) to comment/list requests, and instructions on how to rectify them:

result response message response solution
invalid_comment_id The comment_id request parameter did not contain a valid comment id. When populating the comment_id request parameter, ensure it contains a valid comment_id. The comment_id must correspond to an comment that exists in the event for which you are retrieving comments.
invalid_status_param Status parameter contains an invalid value. When populating the status request parameter, ensure it contains a valid value. Value values include: deleted.