Entry comments

Users can add comments to an entry. This allows for teams to collaborate and have conversations.

Availability

Comments are globally available for all customers.

Mentions in comments

Mentions in comments allow you to tag collaborators in the comments tab of an entry. By including the ”@” followed by an individual’s or team’s name, you can directly engage in conversations regarding feedback, workflow statuses, or general comments.

Only when creating a comment that includes a mention of a collaborator, the mentioned recipient will receive an email notification. The following comments that do not include a mention of a user or team, such as replies or updates, will not be subject to notifications.

To mention users, you must provide a body in Contenful’s rich-text format. There, include a node of type mention where you indicate the user ID, using the following code:

1
{
2
        "nodeType": "document",
3
        "data": {},
4
        "content": [
5
          {
6
            "nodeType": "paragraph",
7
            "data": {},
8
            "content": [
9
              {
10
                "nodeType": "text",
11
                "value": "Text ab with ",
12
                "marks": [],
13
                "data": {}
14
              },
15
              {
16
                "nodeType": "mention", // new node type
17
                "data": {
18
                  "target": {
19
                    "sys": {
20
                      "id": "userId",
21
                      "type": "Link",
22
                      "linkType": "User"
23
                    }
24
                  }
25
                },
26
                "content": []
27
              },
28
            ]
29
          }
30
        ]
31
      }

To mention teams, instead of indicating the ‘user ID’ and a ‘linkType: User’, include the ‘team ID’ and use ‘Team’ as the ‘linkType’. For example:

1
{
2
        "nodeType": "document",
3
        "data": {},
4
        "content": [
5
          {
6
            "nodeType": "paragraph",
7
            "data": {},
8
            "content": [
9
              {
10
                "nodeType": "text",
11
                "value": "Text ab with ",
12
                "marks": [],
13
                "data": {}
14
              },
15
              {
16
                "nodeType": "mention", // new node type
17
                "data": {
18
                  "target": {
19
                    "sys": {
20
                      "id": "teamId",
21
                      "type": "Link",
22
                      "linkType": "Team"
23
                    }
24
                  }
25
                },
26
                "content": []
27
              },
28
            ]
29
          }
30
        ]
31
      }

To submit comments with rich-text, provide the following header: x-contentful-comment-body-format to mention a user in the comment with the value: rich-text. You can request a comment using either format plain-text or rich-text by passing either value in this header.

The request for the header will return the following:

1
{
2
  "sys": {
3
    "version": 0,
4
    "parent": {
5
      "sys": {
6
        "id": "string",
7
        "linkType": "Comment",
8
        "type": "Link"
9
      }
10
    },
11
    "updatedAt": "string",
12
    "updatedBy": {
13
      "sys": {
14
        "id": "string",
15
        "linkType": "User",
16
        "type": "Link"
17
      }
18
    },
19
    "createdAt": "string",
20
    "createdBy": {
21
      "sys": {
22
        "id": "string",
23
        "linkType": "User",
24
        "type": "Link"
25
      }
26
    },
27
    "parentEntity": {
28
      "sys": {
29
        "id": "string",
30
        "linkType": "Entry",
31
        "type": "Link"
32
      }
33
    },
34
    "environment": {
35
      "sys": {
36
        "id": "string",
37
        "linkType": "Environment",
38
        "type": "Link"
39
      }
40
    },
41
    "space": {
42
      "sys": {
43
        "id": "string",
44
        "linkType": "Space",
45
        "type": "Link"
46
      }
47
    },
48
    "type": "Comment",
49
    "id": "string"
50
  },
51
  "body": Object
52
}

If you request a comment that was previously created as rich-text and request without a header or plain-text header specification, the comment will be returned in plain-text. In the plain-text representations, mentions will have the following format: User(id=1xGZIRXr2WPnsLkKfREo0z). You can also fetch the rich-text representation of a plain-text comment by passing rich-text as the value in the above header.

Comment schema

A comment has two top level properties: body and sys. These are described in detail below.

In addition to the common sys properties comments have the following extra sys properties

The property resolvedBy is only defined if the comment is resolved. Reopening a comment will remove the field from the sys property.

Entry comments collection

Get all comments of an entry

Use this endpoint to get all the comments of an entry. This API does not offer pagination, calls to it will return all the existing comments.

It is possible to filter comments by optionally providing the status query parameter, if no value is provided comments with any status will be returned.

Permissions

Any user with read access to an entry can read all the comments in the entry. Space admins can read all the comments in any entry.

Create a comment

Use this endpoint to create a new comment. When using this endpoint, an ID will be automatically generated for the created comment and returned in the response. If you want to create a reply to a specific comment, you need to set the header X-Contentful-Parent-Id with the comment ID you want to reply to.

To reference a specific field and locale with your comment, you can set the header X-Contentful-Parent-Entity-Reference. Only values specifying a path to a field and locale of the entry are considered valid, therefore the value must match the pattern fields.<field_id>.<locale_code>.

There’s a limit of 100 comments per entry. An attempt to create more than 100 comments will result in an error.

Permissions

Any user with read access to an entry can create comments in the entry. Space admins can create comments on any entry.

Errors

• A 400 - BadRequest error is returned if there’s an attempt to create more than 100 comments in one entry.
• A 422 - ValidationFailed error is returned if the body field has a value bigger than 512 bytes.

Comment

Get a comment

Use this endpoint to fetch a comment with a specified ID.

Permissions

Any user with read access to an entry can read a comment in the entry. Space admins can read any comment in any entry.

Delete a comment

Use this method to delete a comment.

Permissions

Comment creators can delete their own comments. Admins can delete any comment on any entry.

Update a comment

Use this method to modify the body of the comment.

Permissions

The creator or an admin can update the comment.

Errors

• An 403 - AccessDenied error is returned if a user different from the comment creator or an admin changed the comment body.
• A 422 - ValidationFailed error is returned if the body field has a value bigger than 512 bytes.