Comments in Template

This feature is available with the Plugin for Business plan and higher.

If you're on the Plugin for Startup or Plugin Expansion plan, consider upgrading to access this feature. For more details, visit our pricing page or contact support.

We provide an option to use comments in the template. There is also an option to create comment threads on sections and blocks.

To enable the comments feature enable it inside Topol Options:

enableComments: true;

And enter current user information and templateId inside Topol Options:

currentUser: {
  userId: "current user user_id",
  name: "current user name",
  profilePhotoUrl:
    "link to the current user's profile picture",
};
templateId: "id";

You can also set your team users that cooperate with you in the templates. You can tag these users in the comments.

teamUsers: [
  {
    userId: "1",
    name: "Jane Doe",
    profilePhotoUrl: "...",
  },
  {
    userId: "2",
    name: "John Doe",
    profilePhotoUrl: "...",
  },
];

Before implementing the endpoints check how to work with API endpoints

List conversations

• URL: /{API.CONVERSATIONS}
• Method: GET
• Content-Type: application-json

Params:

key	value
key	authorization api key
hostname	hostname
template_id	id of the template
entity_id	entity_id corresponds to userId in Options
current_user_id	user id of current user
sort_by	"date" or "unread"
show_resolved	"true" or "false"

This endpoint is called when the editor is initially loaded, sorting is changed or display preference is changed or when you call refresh comments function on TopolPlugin instance. TopolPlugin.refreshComments("conversation_key");.

Response:

{
  "success": true,
  "data": [
    {
      "key": "conversation_key", //section or block uid on which the conversation is based
      "type": "block", // or section
      "resolved": false,
      "delete": false,
      "involved_users": [
        {
          "user_id": "user_id",
          "profile_photo_url": "link to the user's profile picture",
          "name": "user name"
        }
      ], // list of involved users, maximum of the first 7 users will be displayed
      "comments": [
        {
          "id": "comment_id",
          "created_by": {
            "user_id": "user_id",
            "profile_photo_url": "link to the user's profile picture",
            "name": "user name"
          },
          "created_at": "ISO 8601 time",
          "content": "text content of the comment",
          "read_by": ["user_id of the user who saw the comment"],
          "reactions": [
            {
              "created_by": {
                "user_id": "user_id",
                "profile_photo_url": "link to the user's profile picture",
                "name": "user name"
              },
              "type": "thumb-up" // or thumb-down
            }
          ]
        }
      ]
    }
  ]
}

Detail conversation

• URL: /{API.CONVERSATIONS}/{conversation_key}
• Method: GET
• Content-Type: application-json
• Params: key, hostname, template_id, entity_id, current_user_id

This endpoint is called in two situations:

• When user opens conversation
• When user currently has conversation opened and TopolPlugin.refreshComments(“conversation_key”); is called on TopolPlugin instance

Unread messages should be marked as read.

Response:

{
  "success": true,
  "data": {
    "key": "conversation_key", //section or block uid on which the conversation is based
    "type": "block", //or section
    "resolved": false,
    "delete": false,
    "involved_users": [
      {
        "user_id": "user_id",
        "profile_photo_url": "link to the user's profile picture",
        "name": "user name"
      }
    ], // list of involved users, maximum of the first 7 users will be displayed
    "comments": [
      {
        "id": "comment_id",
        "created_by": {
          "user_id": "user_id",
          "profile_photo_url": "link to the user's profile picture",
          "name": "user name"
        },
        "created_at": "ISO 8601 time",
        "content": "text content of the comment",
        "read_by": ["user_id of the user who saw the comment"],
        "reactions": [
          {
            "created_by": {
              "user_id": "user_id",
              "profile_photo_url": "link to the user's profile picture",
              "name": "user name"
            },
            "type": "thumb-up" // or thumb-down
          }
        ]
      }
    ]
  }
}

Resolve or unresolve conversation

• URL: /{API.CONVERSATIONS}/{conversation_key}
• Method: PATCH

This endpoint is called when you click to resolve button.

Request:

{
  "template_id": "id of the template",
  "entity_id": "entity user_id",
  "current_user_id": "current user user_id",
  "hostname": "origin",
  "key": "api key",
  "resolved": true // or false depending on whether we want resolved or unresolved
}

Expected Response: STATUS 200

Delete conversation

• URL: /{API.CONVERSATIONS}/{conversation_key}
• Method: DELETE
• Params: key, hostname, template_id, entity_id, current_user_id

This endpoint is called when user deletes a conversation.

Consider whether to delete the conversation or just soft delete.

Expected Response: STATUS 200

Add comment

• URL: /{API.CONVERSATIONS}/{conversation_key}
• Method: POST

This endpoint is called when new comment is entered.

Request:

{
  "template_id": "id of the template",
  "entity_id": "entity user_id",
  "current_user_id": "current user user_id",
  "hostname": "origin",
  "key": "api key",
  "type": "block", // or section, is for setting up a conversation
  "content": "text content of comment",
  "mentions": ["user_id of the user who is mentioned in the comment"]
}

Expected Response: STATUS 200

Edit, react, read or unread the comment

• URL: /{API.COMMENTS}/{comment_id}
• Method: POST

This endpoint is called when edit specific comment, react (add thumbs up or down) to specific comment or click to mark as read/unread conversation (will call for last comment of conversation).

Request:

{
  "template_id": "id of the template",
  "entity_id": "entity user_id",
  "current_user_id": "current user user_id",
  "hostname": "origin",
  "key": "api key",
  // if edit the comment
  "content": "new text content of comment",
  "mentions": ["user_id of the user who is mentioned in the comment"],
  // if react to the comment
  "react": "thumb-up", // or thumb-down
  // if click on mark as read/unread on the parent conversation
  "action": "mark_as_read" // or mark_as_unread
}

Expected Response: STATUS 200

Delete user's comment

• URL: /{API.COMMENTS}/{comment_id}
• Method: DELETE
• Params: key, hostname, template_id, entity_id, current_user_id

This endpoint is called when user deletes a comment.

Expected Response: STATUS 200

refreshComments

When a user adds or deletes a comment, you need to call refreshComments function on the TopolPlugin instance with the conversation-key of the conversation.

TopolPlugin.refreshComments("conversation_key");