About the Votes API

The Votes API lets visitors and members express feedback on comments by casting upvotes and downvotes.

With the Votes API, you can:

• Build voting controls that let people cast, change, and remove their votes.
• Restore each visitor's or member's voting selections when a page loads.
• Retrieve votes for multiple comments in one query.

Use the Comments API to retrieve the comments displayed alongside your voting controls.

Vote lifecycle

A vote belongs to the identity that cast it. Casting the opposite vote changes the existing vote's type. Repeating the same vote doesn't undo it; the request can still update the record and emit a vote event. Use Remove Vote to clear a vote.

Keep the vote ID returned in vote.voteId separately from the comment ID. Removing a vote requires the vote ID. A visitor and a signed-in member are distinct identities; don't assume votes transfer on sign-in.

Before you begin

It's important to note the following points before starting to code:

• Authenticate each request for the site and the identity performing the operation. Visitor requests also require authentication.
• Voting must be enabled for the comment's context, including when removing an existing vote. Support for comments or reactions doesn't imply support for upvotes and downvotes.
• Specify contextData.appDefId and contextData.contextId for the comment's app and context. Include contextData.contextType when the integration uses a context type. Use the same context across vote operations.
• For comment votes, resourceId is the comment ID, and resourceFqdn is wix.comments.v2.comment. Don't substitute the containing post ID for the comment ID.
• App authentication cannot cast or remove votes. Use visitor or member authentication for these operations; granting an app a permission scope does not enable voting on behalf of a visitor or member.
• Visitor votes use createdBy.identityType: ANONYMOUS in responses. This describes a visitor identity, not an unauthenticated request.
• Visitor and member queries return the caller's own votes. Authorized application queries can return votes from multiple identities; don't use them as personal vote state.

Use cases

• Show and change a comment vote.
• Restore vote controls after a page reload.

Terminology

• Vote: An upvote or downvote associated with one identity and one resource.
• Resource: The item receiving a vote, such as a comment.
• Context: The app-specific container that determines where a vote belongs, such as a comments category.