Mirror of https://github.com/roostorg/coop
github.com/roostorg/coop
1# Appeals
2
3When a user on your platform is unsatisfied with your decision and submits an appeal request, asking you to re-review your original decision, you should send that appeal request to Coop through this API.
4
5## Implementation
6
7> [!NOTE]
8> Before you implement the Appeal API integration, please first review the [Basic Concepts](CONCEPTS.html) and set up your [Item Types](CONCEPTS.html#item-type) and [Actions](CONCEPTS.html#actions)
9
10To populate Appeals in your Review Queues, send Coop appealed decisions and create a routing rule.
11
12
13
14
15When a user submits an appeal request, make a POST request to /api/v1/report/appeal. You'll have to [authenticate](ARCHITECTURE.md#authentication) the request and add the relevant parameters to the body of the request, as shown in our code examples below.
16
17## REST API Examples
18
19Below are some code snippets that you can paste directly into your code. You'll notice we're [authenticating the request](ARCHITECTURE.md#authentication) using your organization's API key in the HTTP headers.
20
21### Example Request
22
23```typescript
24const body = {
25 "appealId": "3cc76649-f99b-4ce2-b45f-4f40e7115e2a",
26 "appealedBy": {
27 "id": "abc123",
28 "typeId": "def456"
29 },
30 "appealedAt": "2022-10-16 17:47:55.781-05",
31 "actionedItem": {
32 "id": "ghi789",
33 "typeId": "jkl234",
34 "data": {
35 "text": "some text commented by a user",
36 // ... all other fields in your Item Type
37 }
38 },
39 "actionsTaken": [
40 "mno654"
41 ],
42 "appealReason": "I dont believe this violates any site policies, but was taken down anyway",
43 "additionalItems": [
44 {
45 "id": "hij123",
46 "typeId": "jkl234",
47 "data": {
48 "text": "some post",
49 // ... all other fields in your Item Type
50 }
51 },
52 {
53 "id": "rst567",
54 "typeId": "jkl234",
55 "data": {
56 "text": "another post",
57 // ... all other fields in your Item Type
58 }
59 },
60 ],
61 "violatingPolicies": [
62 {
63 id: "ghi789",
64 },
65 {
66 id: "jkl321",
67 }
68 ],
69};
70
71const response = await fetch(
72 "/api/v1/report/appeal",
73 {
74 method: 'post',
75 body: JSON.stringify(body),
76 headers: {
77 "x-api-key": "<<apiKey>>",
78 "Content-Type": "application/json"
79 },
80 }
81);
82console.log(response.status);
83```
84
85These are the fields that Coop expects in the body of the request:
86
87| Property | Type | Required? | Description |
88| :---- | :---- | :---- | :---- |
89| appealId | String | Required | The internal ID that represents this appeal submission in your system. This will be propagated back to you when a moderator reviews the Appeal. |
90| appealedBy | ItemIdentifier | Required | The user that reported the Item you're sending. See the ItemIdentifier schema below for details. This should include your internal user id, as well as the typeIdof the user item in Coop’s system. |
91| appealedAt | Datetime | Required | The datetime indicating the exact time at which the appeal was submitted. Datetimes should be formatted as [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) strings. |
92| actionedItem | Item | Required | The Item that was actioned. See the ActionedItem schema below for details. |
93| appealReason | string | Optional | If you allow users to write additional free form text associated with the appeal to indicate why they're submitting the appeal, you can add that here. |
94| actionsTaken | Array\<String> | Required | If the moderation action that led to this appeal came from Coop IDs of any actions that were taken and sent to your Action callback. |
95| violatingPolicies | Array\<Policy> | Optional | If you received a list of Policies from the Action API when the initial moderation action was taken, you can include these here |
96| additionalItems | Array\<Item> | Optional | If you want to render other pieces of content along with your report (e.g. the previous five posts made by the author of the reported content) for additional context, you can include those here in your report. |
97
98Item schema:
99
100| Property | Type | Required? | Description |
101| :---- | :---- | :---- | :---- |
102| id | String | Required | Your unique identifier for the Item that was actioned. |
103| typeId | String | Required | The ID of the [Item Type](CONCEPTS.md#item-type) that corresponds to the Item being appealed. This should exactly match the ID of one of the [Item Types](CONCEPTS.md#item-type) that you defined in the Item Types page. |
104| data | JSON | Required | This is a JSON containing the Item itself. In the Item Types page, you defined a schema for each Item Type. This data JSON must contain the fields you defined in the schema of the Item Type that corresponds to the reported Item. We'll return an error if any of the required fields are missing, if any of the types mismatch, or if any additional fields are included. Note: This is the same data JSON that you send Coop in the Item API. |
105
106ItemIdentifier schema:
107
108| Property | Type | Required? | Description |
109| :---- | :---- | :---- | :---- |
110| id | String | Required | Your unique identifier for the Item that is being reported. |
111| typeId | String | Required | The ID of the [Item Type](CONCEPTS.md#item-type) that corresponds to the Item being reported. This should exactly match the ID of one of the Item Types that you defined in the Item Types page. |
112
113Policy Schema
114
115| Property | Type | Description |
116| :---- | :---- | :---- |
117| id | String | This is Coop’s unique identifier for this [Policy](CONCEPTS.md#policy). You can create, update, and view your company's Policies in the Policies page. If you click the "Edit" button on a particular Policy, you'll be able to see its id. |
118
119### Example Response
120
121Coop will respond with an HTTP response status code, which indicates whether the request was successful.
122
123```json
124{
125 status: 204,
126}
127```
128
129Successful requests will have a 204 status code.
130
131# Appeal Decision Callback API
132
133For every Appeal you moderate in Coop, you will receive the decision information through a public-facing API endpoint. Whenever a moderator accepts or rejects a user's appeal submission, Coop will send a POST request to your Appeal API endpoint. When your server receives that POST request, you may process that appeal decision internally and communicate the decision to the user.
134
135Here's an example of a request Coop would send your Appeal API when an Appeal is accepted by a moderator on Coop
136
137```json
138{
139 "appealId": "3cc76649-f99b-4ce2-b45f-4f40e7115e2a",
140 "item": {
141 "id": "ghi789",
142 "typeId": "jkl234",
143 },
144 "appealedBy": {
145 "id": "abc123",
146 "typeId": "def456"
147 },
148 "appealDecision": "ACCEPT"
149 "custom": {
150 // ... any custom parameters that you configured in the Appeals Dashboard
151 }
152}
153```
154
155The Body of the Request will include the following:
156
157| Property | Type | Always Present? | Description |
158| :---- | :---- | :---- | :---- |
159| item | Item | Always Present | The Item that originally received a moderation action, which was appealed by a user. |
160| appealId | String | Always Present | The internal ID that you use to track this appeal, will correspond to an appeal ID sent to Coop via the Appeal API |
161| appealedBy | ItemIdentifier | Always Present | The user that submitted this appeal, corresponding to the information send to Coop via the Appeal API. |
162| appealDecision | ACCEPT/REJECT | Always present | The decision made by your moderator on this Appeal. "ACCEPT" meaning the original moderation action was incorrect, and the user appeal should be processed and accepted. "REJECT" meaning the original moderation action was correct, and does not need to be undone. |
163| custom | Object | Not Always Present | If you would like Coop to include any custom parameters in the request Coop sends to your Appeal endpoint, you can add those custom parameters in the Appeal Configuration Form. These can be configured in the "Body" section of the form. |
164
165#### Item Schema
166
167| Property | Type | Description |
168| :---- | :---- | :---- |
169| id | String | Your unique identifier for this Item. You can use this ID to determine on which Item was originally moderated, leading to the user appeal. |
170| typeId | String | The ID of the [Item Type](CONCEPTS.md#item-type) that corresponds to the Item which received a moderation action. This will exactly match the ID of one of the Item Types that you defined in the Item page. The IDs of each Item Type can be found in that dashboard |
171
172#### ActionSchema
173
174| Property | Type | Description |
175| :---- | :---- | :---- |
176| id | String | This is Coop’s unique identifier for this [Action](CONCEPTS.md#actions). You can create, update, and view your company's Actions in the Actions page. If you click the "Edit" button on a particular Action, you'll be able to see its id at the end of the URL. |