{ "openapi": "3.0.1", "info": { "title": "TalkLabs / SportsTalk 24/7 API", "version": "v3", "description": "Audience engagement APIs for chat, comments, polls, users, moderation, webhooks, and live telemetry. TalkLabs assigns resource IDs; customid, userid, and telemetry contextid values are defined by the customer." }, "paths": { "/api/v3/{appid}/chat/rooms": { "get": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 200 }, "description": "The maximum number of records to return." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The cursor returned by the previous page." }, { "name": "filterByName", "in": "query", "schema": { "type": "string", "default": "" } }, { "name": "filterById", "in": "query", "schema": { "type": "string", "default": "" } }, { "name": "filterByCustomId", "in": "query", "schema": { "type": "string", "default": "" }, "x-identifier-source": "customer-defined" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "list.chatrooms", "cursor": "5ec3c1945617e21bd8c5567b", "more": false, "itemcount": 1, "rooms": [ { "kind": "chat.room", "id": "5ec3c1945617e21bd8c5567b", "appid": "5ebbe03d5617e00de4b044c2", "ownerid": "userid_abe", "name": "ROOM HAS NEW NAME", "description": "Live from the top of the Empire State Building", "customtype": "", "customid": "new-york-city-club", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "enableactions": true, "enableenterandexit": true, "open": true, "inroom": 0, "added": "2020-05-19T11:23:00.3049587Z", "whenmodified": "2020-05-20T03:54:04.4814629Z", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "delaymessageseconds": 0 } ] } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Rooms", "description": "_This method requires authentication._\n\nRooms can be public or private. This method lists all public rooms that everyone can see.\n\n- **cursor** : (optional) The first time you call list rooms, omit this property to start from the beginning. Call the method again passing in the value returned in the cursor field of the response to get the next page of results. If there are more results available, more will be true.\n \n- **limit** : (optional) Specify the number of items to return. Default is 200.", "security": [ { "ApiToken": [] } ] }, "post": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateRoomFormModel" } ] }, "example": { "name": "New York City Chat (Post-Moderated)", "description": "Live from the top of the Empire State Building", "moderation": "post" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "chat.room", "id": "5ec3c1945617e21bd8c5567b", "appid": "5ebbe03d5617e00de4b044c2", "ownerid": "userid_abe", "name": "New York City Chat (Post-Moderated)", "description": "Live from the top of the Empire State Building", "customtype": "", "customid": "new-york-city-club", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "enableactions": true, "enableenterandexit": true, "open": true, "inroom": 0, "added": "2020-05-19T11:23:00.3049587Z", "whenmodified": "2020-05-20T03:52:34.5114855Z", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "delaymessageseconds": 0 } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Create Room", "description": "_This method requires authentication._\n\n\\* **name**: (required) The name of the room \n\\* **description**: (optional) The description of the room \n\\* **pictureurl**: (optional) The URL for a picture for the room \n\\* **moderation**: (optional) \\[\"pre\"/\"post\"\\] Defaults to post-moderation. \n\\* **enableactions**: (optional) \\[true/false\\] Turns action commands on or off \n\\* **enableenterandexit**: (optional) \\[true/false\\] Turn enter and exit events on or off. Disable for large rooms to reduce noise. \n\\* **enableprofanityfilter**: (optional) \\[default=true / false\\] Enables profanity filtering. \n\\* **enableautoexpiresessions**: (optional) \\[defaulttrue / false\\] Enables automatically expiring idle sessions, which removes inactive users from the room. \n\\* **delaymessageseconds**: (optional) \\[default=0\\] Puts a delay on messages from when they are submitted until they show up in the chat. Used for throttling. \n\\* **roomisopen**: (optional) \\[true/false\\] If false, users cannot perform any commands in the room, chat is suspended. \n\\* **maxreports**: (optional) Default is 3. This is the maximum amount of user reported flags that can be applied to a message before it is sent to the moderation queue. \n\\* **customid**: (optional) A customid for the room. Can be unused, or a unique key. \n\\* **customtype** : (optional) Custom type string. \n\\* **custompayload** : (optional) Custom payload string. \n\\* **customfield1** : (optional) User custom field 1. Store any string value you want here, limit 1024 bytes. \n\\* **customfield2** : (optional) User custom field 2. Store any string value you want here, limit 1024 bytes. \n\\* **customtags** : (optional) A comma delimited list of tags \n\\* **private:** (false | optional) If set to true a user cannot join this room unless explicitly granted with a call to the Set User Permission API.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}": { "post": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateRoomFormModel" } ] }, "example": { "name": "ROOM HAS NEW NAME", "description": "Live from the top of the Empire State Building", "moderation": "post" } } } }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiResult" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "chat.room", "id": "5ec3c1945617e21bd8c5567b", "appid": "5ebbe03d5617e00de4b044c2", "ownerid": "userid_abe", "name": "ROOM HAS NEW NAME", "description": "Live from the top of the Empire State Building", "customtype": "", "customid": "new-york-city-club", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "enableactions": true, "enableenterandexit": true, "open": true, "inroom": 0, "added": "2020-05-19T11:23:00.3049587Z", "whenmodified": "2020-05-20T03:53:22.4959941Z", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "delaymessageseconds": 0 } } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiResult" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiResult" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiResult" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiResult" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Update Room", "description": "*This method requires authentication.* \n\n* __userid__: (optional) The owner of the room\n* __name__: (optional) The name of the room\n* __description__: (optional) The description of the room\n* __moderation__: (optional) [premoderation/postmoderation] Defaults to post-moderation. \n* __enableactions__: (optional) [true/false] Turns action commands on or off\n* __enableenterandexit__: (optional) [true/false] Turn enter and exit events on or off. Disable for large rooms to reduce noise.\n* __enableprofanityfilter__: (optional) [default=true / false] Enables profanity filtering.\n* **enableautoexpiresessions**: (optional) [defaulttrue / false] Enables automatically expiring idle sessions, which removes inactive users from the room.\n* __delaymessageseconds__: (optional) [default=0] Puts a delay on messages from when they are submitted until they show up in the chat. Used for throttling.\n* __roomisopen__: (optional) [true/false] If false, users cannot perform any commands in the room, chat is suspended.\n* __throttle__: (optional) Defaults to 0. This is the number of seconds to delay new incomming messags so that the chat room doesn't scroll messages too fast.\n# Creates a new chat room\n\n*This method requires authentication.*\n\n* **name**: (required) The name of the room\n* **description**: (optional) The description of the room\n* **pictureurl**: (optional) The URL for a picture for the room\n* **moderation**: (optional) [\"pre\"/\"post\"] Defaults to post-moderation. \n* **enableactions**: (optional) [true/false] Turns action commands on or off\n* **enableenterandexit**: (optional) [true/false] Turn enter and exit events on or off. Disable for large rooms to reduce noise.\n* **enableprofanityfilter**: (optional) [default=true / false] Enables profanity filtering.\n* **delaymessageseconds**: (optional) [default=0] Puts a delay on messages from when they are submitted until they show up in the chat. Used for throttling.\n* **roomisopen**: (optional) [true/false] If false, users cannot perform any commands in the room, chat is suspended.\n* **maxreports**: (optional) Default is 3. This is the maximum amount of user reported flags that can be applied to a message before it is sent to the moderation queue.\n* **customid**: (optional) A customid for the room. Can be unused, or a unique key.\n* **customtype** : (optional) Custom type string.\n* **custompayload** : (optional) Custom payload string.\n* **customfield1** : (optional) User custom field 1. Store any string value you want here, limit 1024 bytes.\n* **customfield2** : (optional) User custom field 2. Store any string value you want here, limit 1024 bytes.\n* **customtags** : (optional) A comma delimited list of tags", "security": [ { "ApiToken": [] } ] }, "get": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "chat.room", "id": "600d78d45617e20e34c39dd5", "appid": "600d78305617e20e34c39bb2", "ownerid": null, "name": "New York City Chat (Post-Moderated)", "description": "Live from the top of the Empire State Building", "pictureurl": "", "customtype": "", "customid": "new-york-city-club", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "enableactions": true, "enableenterandexit": true, "open": true, "inroom": 5, "added": "2021-01-24T13:40:36.5938847Z", "whenmodified": "2021-02-10T21:56:01.7549454Z", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "delaymessageseconds": 0, "bouncedusers": [], "flaggedusers": [ "u-8842" ], "shadowbannedusers": [], "reportedusers": [ { "userid": "u-8842", "reportedbyuserid": "userid_abelincoln", "reason": "abuse", "added": "2021-02-05T16:19:04.2278254Z" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Get Room Details", "description": "_This method requires authentication._\n\nThis will return all the settings for the room and the participant count but not the participant list.", "security": [ { "ApiToken": [] } ] }, "delete": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Room deleted successfully.", "errors": {}, "data": { "kind": "deleted.room", "deletedEventsCount": 0, "room": { "kind": "chat.room", "id": "5fe33c045617e2126867c5f6", "appid": "5edbd0fb5617e609c00ff168", "ownerid": null, "name": "Test Room to be Deleted (Post-Moderated)", "description": "We have but one life to live", "pictureurl": "", "customtype": "", "customid": "Test_Room_Delete_Me", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "enableactions": true, "enableenterandexit": true, "open": true, "inroom": 0, "added": "2020-12-23T12:45:56.4938555Z", "whenmodified": "2020-12-23T12:45:56.4938555Z", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "delaymessageseconds": 0, "bouncedusers": [], "shadowbannedusers": [] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Delete Room", "description": "This cannot be reversed. This command permanently deletes the chat room and all events in it.\n\n## URL Parameters\n* **roomid** : (required) The room to be deleted.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/roomsbycustomid/{customid}": { "get": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "customid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A customer-defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID.", "x-identifier-source": "customer-defined" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "chat.room", "id": "5ec3c1945617e21bd8c5567b", "appid": "5ebbe03d5617e00de4b044c2", "ownerid": "userid_abe", "name": "New York City Chat (Post-Moderated)", "description": "Live from the top of the Empire State Building", "customtype": "", "customid": "new-york-city-club", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "enableactions": true, "enableenterandexit": true, "open": true, "inroom": 0, "added": "2020-05-19T11:23:00.3049587Z", "whenmodified": "2020-05-20T03:52:34.5114855Z", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "delaymessageseconds": 0 } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Get a room by custom ID", "description": "_This method requires authentication._\n\nThis will return all the settings for the room and the participant count but not the participant list.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/messagesbyuser/{userid}": { "get": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" }, { "name": "cursor", "in": "query", "schema": { "type": "string", "default": "" }, "description": "The cursor returned by the previous page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 200 }, "description": "The maximum number of records to return." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "list.chatevents", "cursor": "5ec4aa385617e40ed4e82aaf", "events": [ { "kind": "chat.event", "id": "5ec4aa2b5617e40ed4e82aad", "roomid": "5ec3c1945617e21bd8c5567b", "body": "Hello, Dev World!", "added": "2020-05-20T03:55:22.9999147Z", "ts": 637255437229999100, "eventtype": "speech", "userid": "userid_abe", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "banned": false }, "customtype": "", "customid": "", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": null, "parentid": "", "hierarchy": [], "edited": false, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 0, "reactions": [], "moderation": "na", "reports": [] }, { "kind": "chat.event", "id": "5ec4aa385617e40ed4e82aaf", "roomid": "5ec3c1945617e21bd8c5567b", "body": "Hello a second time!", "added": "2020-05-20T03:55:36.9845354Z", "ts": 637255437369845400, "eventtype": "speech", "userid": "userid_abe", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "banned": false }, "customtype": "", "customid": "", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": null, "parentid": "", "hierarchy": [], "edited": false, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 0, "reactions": [], "moderation": "na", "reports": [] } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Messages By User", "description": "_This method requires authentication._\n\nThe purpose of this method is to get a list of messages or comments by a user, with count of replies and reaction data. This way, you can easily make a screen in your application that shows the user a list of their comment contributions and how people reacted to it.\n\n### URL PARAMETERS\n\n* **roomid** : (required) The ID of the chatroom to retreive the messages by this user from\n* **userid** : (required) The ID of the user to fetch messages by\n* **cursorid** : (optional) If null / \"\", starts at the first messsage, and if not null, resumes cursoring", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/listpreviousevents": { "get": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100 }, "description": "The maximum number of records to return." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "default": "" }, "description": "The cursor returned by the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "list.chatevents", "cursor": "637275092820138536", "more": false, "itemcount": 4, "events": [ { "kind": "chat.event", "id": "5ee2a8225617e01b9cae081c", "roomid": "5ee2a81f5617e01b9cae0816", "body": "Mind if I quote you?", "originalbody": "", "added": "2020-06-11T21:54:42.9770073Z", "modified": "2020-06-11T21:54:42.9770073Z", "ts": 637275092829770100, "eventtype": "quote", "userid": "userid_abe", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "banned": false }, "customtype": "", "customid": "", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": { "kind": "chat.event", "id": "5ee2a8225617e01b9cae0819", "roomid": "5ee2a81f5617e01b9cae0816", "body": "No, you're misunderstaning me, Prince Valiant. I'm saying if you were a sheep, would you **** a sheep, if you were another sheep? We can't tolerate that in Scunthorpe.", "originalbody": "No, you're misunderstaning me, Prince Valiant. I'm saying if you were a sheep, would you fuck a sheep, if you were another sheep? We can't tolerate that in Scunthorpe.", "added": "2020-06-11T21:54:42.239921Z", "modified": "2020-06-11T21:54:42.239921Z", "ts": 637275092822399200, "eventtype": "speech", "userid": "userid_abe", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "banned": false }, "customtype": "", "customid": null, "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": null, "parentid": "", "hierarchy": [], "depth": 0, "edited": false, "editedbymoderator": true, "censored": true, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 1, "reactions": [], "moderation": "na", "reports": [] }, "parentid": "5ee2a8225617e01b9cae0819", "hierarchy": [], "depth": 0, "edited": false, "editedbymoderator": false, "censored": false, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 0, "reactions": [], "moderation": "na", "reports": [] }, { "kind": "chat.event", "id": "5ee2a8225617e01b9cae081b", "roomid": "5ee2a81f5617e01b9cae0816", "body": "I spy with my little eye an opportunity to post a reply!", "originalbody": "", "added": "2020-06-11T21:54:42.7482416Z", "modified": "2020-06-11T21:54:42.7482416Z", "ts": 637275092827482400, "eventtype": "reply", "userid": "userid_abe", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "banned": false }, "customtype": "", "customid": "", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": { "kind": "chat.event", "id": "5ee2a8225617e01b9cae0819", "roomid": "5ee2a81f5617e01b9cae0816", "body": "No, you're misunderstaning me, Prince Valiant. I'm saying if you were a sheep, would you **** a sheep, if you were another sheep? We can't tolerate that in Scunthorpe.", "originalbody": "No, you're misunderstaning me, Prince Valiant. I'm saying if you were a sheep, would you fuck a sheep, if you were another sheep? We can't tolerate that in Scunthorpe.", "added": "2020-06-11T21:54:42.239921Z", "modified": "2020-06-11T21:54:42.239921Z", "ts": 637275092822399200, "eventtype": "speech", "userid": "userid_abe", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "banned": false }, "customtype": "", "customid": null, "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": null, "parentid": "", "hierarchy": [], "depth": 0, "edited": false, "editedbymoderator": true, "censored": true, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 0, "reactions": [], "moderation": "na", "reports": [] }, "parentid": "5ee2a8225617e01b9cae0819", "hierarchy": [ "5ee2a8225617e01b9cae0819" ], "depth": 1, "edited": false, "editedbymoderator": false, "censored": false, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 0, "reactions": [], "moderation": "na", "reports": [] }, { "kind": "chat.event", "id": "5ee2a8225617e01b9cae081a", "roomid": "5ee2a81f5617e01b9cae0816", "body": "Abraham Lincoln gave Dave M. a high 5!", "originalbody": "", "added": "2020-06-11T21:54:42.5294899Z", "modified": "2020-06-11T21:54:42.5294899Z", "ts": 637275092825294800, "eventtype": "action", "userid": "userid_abe", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "banned": false }, "customtype": "", "customid": "", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": null, "parentid": "", "hierarchy": [], "depth": 0, "edited": false, "editedbymoderator": false, "censored": false, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 0, "reactions": [], "moderation": "na", "reports": [] }, { "kind": "chat.event", "id": "5ee2a8225617e01b9cae0818", "roomid": "5ee2a81f5617e01b9cae0816", "body": "Hello, Dev World!", "originalbody": "", "added": "2020-06-11T21:54:42.0138536Z", "modified": "2020-06-11T21:54:42.0138536Z", "ts": 637275092820138500, "eventtype": "speech", "userid": "userid_abe", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "banned": false }, "customtype": "", "customid": "", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": null, "parentid": "", "hierarchy": [], "depth": 0, "edited": false, "editedbymoderator": false, "censored": false, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 0, "reactions": [], "moderation": "na", "reports": [] } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Previous Events", "description": "* This method allows you to go back in time to \"scroll\" in reverse through past messages. The typical use case for this method is to power the scroll-back feature of a chat window allowing the user to look at recent messages that have scrolled out of view. It's intended use is to retrieve small batches of historical events as the user is scrolling up.\n* This method returns a list of events sorted from newest to oldest.\n* This method excludes events that are not in the active state (for example if they are removed by a moderator)\n* This method excludes non-displayable events (reaction, replace, remove, purge)\n* This method will not return events that were emitted and then deleted before this method was called\n\n## URL PARAMETERS\n* **limit** : (Optional) Defaults to 100, maximum 500.\n* **cursor**: (Optional) If not provided, the most recent events will be returned. To get older events, call this method again using the cursor string returned from the previous call.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/listeventsbytype": { "get": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "EventType", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/ChatEventTypes" } ] } }, { "name": "CustomType", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100 }, "description": "The maximum number of records to return." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "default": "" }, "description": "The cursor returned by the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "list.chatevents", "cursor": "637477362782873373", "more": false, "itemcount": 1, "events": [ { "kind": "chat.event", "id": "60174bd65617e6176c7aaf1a", "roomid": "600d78d45617e20e34c39dd5", "body": "this is an announcement by the admin.", "originalbody": "", "added": "2021-02-01T00:31:18.2873373Z", "modified": "2021-02-01T00:31:18.2873373Z", "ts": 637477362782873300, "eventtype": "announcement", "userid": "bobsmith4|600d78305617e20e34c39bb2", "user": { "kind": "app.user", "userid": "bobsmith4", "handle": "dave_m75962", "handlelowercase": "georgew75962", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "role": "admin", "customtags": [], "banned": false, "shadowbanned": false, "shadowbanexpires": "0001-01-01T00:00:00Z", "muted": false, "moderation": "approved", "reports": [] }, "mentions": [], "customtype": "", "customid": "", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": null, "parentid": "", "hierarchy": [], "depth": 0, "edited": false, "editedbymoderator": false, "censored": false, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 0, "reactions": [], "moderation": "na", "reports": [] } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Events By Type", "description": "* This method enables you to retrieve a small list of recent events by type. This is useful for things like fetching a list of recent announcements or custom event types without the need to scroll through the entire chat history.\n* This method returns a list of events sorted from newest to oldest.\n* This method returns only active events.\n* If you specify eventtype = customtype, you must pass the customtype value, a string of your choosing for your custom type.\n\n## URL PARAMETERS\n* **limit** : (Optional) Defaults to 10, maximum 100.\n* **cursor**: (Optional) If not provided, the most recent events will be returned. To get older events, call this method again using the cursor string returned from the previous call.\n* **eventtype** : (Optional) Specify the chat event type you are filtering for. If you want to filter for a custom event type, specify 'custom' and then provide a value for the **customtype* parameter\n* **customtype** : (Optional) If you want to filter by custom type you must first specify 'custom' for the eventtype field. This will enable you to filter to find events of a custom type.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/searchevents": { "post": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ChatSearchEventsFormModel" } ] }, "example": { "types": [ "speech", "quote", "reply" ], "limit": 10 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Search Event History", "description": "This method is still operational but its use should be replaced with Search Events. This will be discontinued March 31, 2021.\n\nThis returns displayable messages (for example speech, quote, threadedreply) that are in the active state (not flagged by moderator or logically deleted).\n\n# BODY PROPERTIES\n* **fromuserid** : (optional) Return ony events from the specified user.\n* **fromhandle** : (optional) Return only events from a user with the specified handle. Exact match, case insensitive.\n* **roomid** : (optional) Return only events in the specified room.\n* **body** : (optional) Returns only messages which contain the specified body substring.\n* **limit** : (optional) Default is 50, maximum is 200. Limits how many items are returned.\n* **cursor** : (optional) Leave blank to start from the beginning of the result set; provide the value from the previous returned cursor to resume cursoring through the next page of results\n* **direction** : (optional) Defaults to Backward. Pass **forward** or **backward**. Backward is newest to oldest order, forward is oldest to newest order.\n* **types** : (optional) Default = all. Use this to filter for specific event types.\n * speech\n * quote\n * reply\n * announcement\n * custom\n * reaction\n * action\n * enter\n * exit\n * ad\n * roomopened\n * roomclosed\n * purge\n * remove\n * replace\n * bounce", "security": [ { "ApiToken": [] } ] }, "get": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "FromUserId", "in": "query", "description": "If specified, filters the search to only include messages where the user posting the event has this userid as an exact match", "schema": { "type": "string" }, "x-identifier-source": "customer-defined" }, { "name": "FromHandle", "in": "query", "description": "If specified, filters the search to only include messages where the user posting the event has this handle as an exact match", "schema": { "type": "string" } }, { "name": "Types", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChatEventTypes" } } }, { "name": "RoomId", "in": "query", "description": "If specified, filters the search to only include events from the specified room", "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "Body", "in": "query", "description": "If specified, performs a substring match (case insensitive of the body)", "schema": { "type": "string" } }, { "name": "Limit", "in": "query", "schema": { "type": "integer", "format": "int32" }, "description": "The maximum number of records to return." }, { "name": "Cursor", "in": "query", "schema": { "type": "string" }, "description": "The cursor returned by the previous page." }, { "name": "Direction", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/CursoringDirections" } ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Search event history with query parameters", "description": "Create rooms, publish messages, subscribe users, and read live activity.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/listeventshistory": { "get": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100 }, "description": "The maximum number of records to return." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "default": "" }, "description": "The cursor returned by the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Event History", "description": "* This method enables you to download all of the events from a room in large batches. It should only be used if doing a data export. \n* This method returns a list of events sorted from oldest to newest.\n* This method returns all events, even those in the inactive state.\n\n## URL PARAMETERS\n* **limit** : (Optional) Defaults to 100, maximum 2000.\n* **cursor**: (Optional) If not provided, the most recent events will be returned. To get older events, call this method again using the cursor string returned from the previous call.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/join": { "post": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/JoinRoomFormModel" } ] }, "example": { "handle": "dave_m", "role": "admin" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Successfully joined as anonymous user", "errors": {}, "data": { "kind": "chat.joinroom", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "banned": false }, "room": { "kind": "chat.room", "id": "5ec2047286c2921ad07edd39", "appid": "5ec2038a86c2921ad07edd35", "ownerid": "u-8842", "name": "New York City Chat (Post-Moderated)", "description": "Live from the top of the Empire State Building", "customtype": "", "customid": "5th-stand", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "enableactions": true, "enableenterandexit": true, "open": true, "inroom": 1, "added": "2020-05-18T03:43:46.3198116Z", "whenmodified": "2020-05-18T03:43:46.3198116Z", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "delaymessageseconds": 0 }, "eventscursor": { "kind": "list.chatevents", "cursor": "", "more": false, "itemcount": 0, "room": null, "events": [] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Join Room", "description": "_Requires Authentication._\n\nYou want your chat experience to open fast. The steps to opening a chat experience are:\n\n1. Create Room\n2. Create User\n3. Join Room (user gets permission to access events data from the room)\n4. Get Recent Events to display in your app\n \n\nIf you have already created the room (step 1) then you can perform steps 2 - 4 using join room. \nWhen you attempt to join the room, if the userid you provide does not exist then a user will be created for you automatically. \nYou may optionally provide a handle. If the handle is in use, a random number will be appended to the end, or you may get an error code if after 20 tries the system cannot find an available handle. \nJoin may be used to create a new user. Join may not be used to update an existing user.\n\n## BODY PARAMETERS\n\n- Provide a unique _user ID_ string and _chat handle_ string. If this is the first time the user ID has been used a new user record will be created for the user. Whenever the user creates an event in the room by doing an action like saying something, the user information will be returned.\n- You can optionally also provide a URL to an image and a URL to a profile.\n- If you provide user information and the user already exists in the database, the user will be updated with the new information.\n- The user will be added to the list of participants in the room and the room participant count will increase.\n- The user will be removed from the room automatically after some time if the user doesn't perform any operations.\n- Users can only execute commands in the room if they have joined the room.\n- When a logged in user joins a room an entrance event is generated in the room.\n- When a logged in user leaves a room, an exit event is generated in the room.\n- **limit** : (optional) Defaults to 50. This limits the number of previous messages returned when joining the room.\n \n\n**Creating A New User**: \nYou have the option to create or update an existing user during join.\n\n- **userid**: _Required_. If the userid is new then the user will be created. If the userid is already in use in the database then the user will be updated.\n- **handle**: (Optional) A unique string representing the user that is easy for other users to type.\n - Example @GeorgeWashington could be the handle but Display Name could be \"Wooden Teef For The Win\".\n - If you are creating a user and you don't specify a handle, the system will generate one for you (using Display Name as basis if you provide that).\n - If you request a handle and it's already in use a new handle will be generated for you by adding a number from 1-99 and returned.\n - If the handle can't be generated because all the options 1-99 on the end of it are taken then the request will be rejected with BadRequest status code.\n - Only these characters may be used: \"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890_\"\n- **displayname**: _Optional_. This is the desired name to display, typically the real name of the person.\n- **pictureurl**: _Optional_. The URL to the picture for this user.\n- **profileurl**: _Optional_. The profileurl for this user.\n- **role**: _Optional_. Valid roles are \"user\" (default), \"moderator\" and \"admin\".\n- **usercustomtags**: _Optional_. A list of strings to attach to the user object.\n \n\n## RESPONSE CODES\n\n- **200 | OK** : Sweet, sweet success.\n- **400 | BadRequest** : Something is wrong with your request. View response message and errors list for details.\n- **403 | Forbidden** : Request is not authorized with a valid token.\n- **405 | MethodNotAllowed** : See the error message, a rule blocked this from completing, such as profanity in the user Display Name (if filtering is enabled), or invalid characters in the handle.\n- **409 | Conflict** : The handle for this user is already in use. System will try up to 20 times to find a variant of your handle with 5 random numbers on the end, for example, \"Harald\" becomes \"Harald12345\".", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/roomsbycustomid/{customid}/join": { "post": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "customid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A customer-defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID.", "x-identifier-source": "customer-defined" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/JoinRoomFormModel" } ] }, "example": { "limit": 50 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Successfully joined as identified user", "errors": {}, "data": { "kind": "chat.joinroom", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "role": "user", "customtags": [], "banned": false, "shadowbanned": false, "shadowbanexpires": "0001-01-01T00:00:00Z", "muted": false, "moderation": "na", "reports": [] }, "room": { "kind": "chat.room", "id": "5ffdaefc86c29a175c6c46fe", "appid": "5ff89dfb86c2941010796f93", "ownerid": null, "name": "New York City Chat (Post-Moderated)", "description": "Live from the top of the Empire State Building", "pictureurl": "", "customtype": "", "customid": "new-york-city-club", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "enableactions": true, "enableenterandexit": true, "open": true, "inroom": 1, "added": "2021-01-12T14:15:24.8535603Z", "whenmodified": "2021-01-12T14:15:24.8535603Z", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "delaymessageseconds": 0, "bouncedusers": [], "shadowbannedusers": [] }, "eventscursor": { "kind": "list.chatevents", "cursor": "637460577330724021", "more": false, "itemcount": 1, "events": [ { "kind": "chat.event", "id": "5ffdaf0586c29a175c6c4702", "roomid": "5ffdaefc86c29a175c6c46fe", "body": "Message has been modified", "originalbody": "", "added": "2021-01-12T14:15:33.0724021Z", "modified": "2021-01-20T12:53:06.8107428Z", "ts": 637460577330724000, "eventtype": "speech", "userid": "userid_abe", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "role": "user", "customtags": [], "banned": false, "shadowbanned": false, "shadowbanexpires": "0001-01-01T00:00:00Z", "muted": false, "moderation": "na", "reports": [] }, "mentions": [], "customtype": "", "customid": "", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": null, "parentid": "", "hierarchy": [], "depth": 0, "edited": true, "editedbymoderator": false, "censored": false, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 0, "reactions": [], "moderation": "na", "reports": [] } ] }, "previouseventscursor": "637460577330724021" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Join a room by custom ID", "description": "## This method is the same as Join Room, except you can use your customid\nThe benefit of this method is you don't need to query to get the roomid using customid, and then make another call to join the room. This eliminates a request and enables you to bring your chat experience to your user faster.\n\nYou want your chat experience to open fast. The steps to opening a chat experience are:\n1. Create Room\n2. Create User\n3. Join Room (user gets permission to access events data from the room)\n4. Get Recent Events to display in your app\n\nIf you have already created the room (step 1) then you can perform steps 2 - 4 using join room. \n\nWhen you attempt to join the room, if the userid you provide does not exist then a user will be created for you automatically.\nYou may optionally provide a handle. If the handle is in use, a random number will be appended to the end, or you may get an error code if after 20 tries the system cannot find an available handle.\nJoin may be used to create a new user. Join may not be used to update an existing user.\n\n## DATA PARAMETERS\n- Provide a unique _user ID_ string and _chat handle_ string. If this is the first time the user ID has been used a new user record will be created for the user. Whenever the user creates an event in the room by doing an action like saying something, the user information will be returned.\n- You can optionally also provide a URL to an image and a URL to a profile.\n- If you provide user information and the user already exists in the database, the user will not be updated.\n- The user will be added to the list of participants in the room and the room participant count will increase.\n- The user will be removed from the room automatically after some time if the user doesn't perform any operations.\n- Users can only execute commands in the room if they have joined the room.\n- When a logged in user joins a room an entrance event is generated in the room.\n- When a logged in user leaves a room, an exit event is generated in the room.\n\n**Creating A New User**:\nYou have the option to create or update an existing user during join.\n* **limit** : (optional) Defaults to 50. This limits the number of previous messages returned when joining the room.\n* **userid**: _Required_. If the userid is new then the user will be created. If the userid is already in use in the database then the user will be updated.\n* **handle**: (Optional) A unique string representing the user that is easy for other users to type.\n\t* Example @GeorgeWashington could be the handle but Display Name could be \"Wooden Teef For The Win\".\n\t* If you are creating a user and you don't specify a handle, the system will generate one for you (using Display Name as basis if you provide that).\n\t* If you request a handle and it's already in use a new handle will be generated for you by adding a number from 1-99 and returned. \n\t* If the handle can't be generated because all the options 1-99 on the end of it are taken then the request will be rejected with BadRequest status code.\n\t* Only these characters may be used: \"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890_\"\n* **displayname**: _Optional_. This is the desired name to display, typically the real name of the person.\n* **pictureurl**: _Optional_. The URL to the picture for this user.\n* **profileurl**: _Optional_. The profileurl for this user.\n* **role**: _Optional_. Valid roles are \"user\" (default), \"moderator\" and \"admin\".\n* **customtags**: _Optional_. A list of strings to attach to the user object.\n\n\n## RESPONSE CODES\n* **200 | OK** : Sweet, sweet success.\n* **400 | BadRequest** : Something is wrong with your request. View response message and errors list for details.\n* **403 | Forbidden** : Request is not authorized with a valid token.\n* **405 | MethodNotAllowed** : See the error message, a rule blocked this from completing, such as profanity in the user Display Name (if filtering is enabled), or invalid characters in the handle.\n* **409 | Conflict** : The handle for this user is already in use. System will try up to 20 times to find a variant of your handle with 5 random numbers on the end, for example, \"Harald\" becomes \"Harald12345\".", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/participants": { "get": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "Cursor", "in": "query", "schema": { "type": "string" }, "description": "The cursor returned by the previous page." }, { "name": "Limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 50 }, "description": "The maximum number of records to return." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "list.chatparticipants", "cursor": "5ec4aa045617e40ed4e82aac", "participants": [ { "kind": "chat.participant", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "banned": false } } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Room Participants", "description": "_This method requires authentication._\n\nUse this method to cursor through the people who have subscribe to the room.\n\nTo cursor through the results if there are many participants, invoke this function many times. Each result will return a cursor value and you can pass that value to the next invokation to get the next page of results. The result set will also include a *next* field with the full URL to get the next page, so you can just keep reading that and requesting that URL until you reach the end. When you reach the end, no more results will be returned or the result set will be less than maxresults and the next field will be empty.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/user/{userid}/subscriptions": { "get": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" }, { "name": "Cursor", "in": "query", "schema": { "type": "string" }, "description": "The cursor returned by the previous page." }, { "name": "Limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 50 }, "description": "The maximum number of records to return." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "list.userroomsubscriptions", "cursor": "6391e369b524fb507cc278e7|63968e70664b8d01949058ba|userid_abe", "more": false, "itemcount": 1, "subscriptions": [ { "kind": "chat.subscription", "id": "6391e369b524fb507cc278e7|63968e70664b8d01949058ba|userid_abe", "roomid": "63968e70664b8d01949058ba", "roomcustomid": "new-york-city-club", "userid": "userid_abe", "updated": "2022-12-12T02:14:17.975Z", "added": "2022-12-12T02:14:17.975Z", "roomname": "New York City Chat (Post-Moderated)", "roomcustomtags": [], "persist": false } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List User Subscribed Rooms", "description": "_This method requires authentication._\n\nUse this method to cursor through all the rooms the user is subscribed to. This will include all rooms. If you want to build a private messaging experience, you can put custom tags on the rooms to separate out which are for private messenger and which are public group rooms.\n\nTo cursor through the results if there are many participants, invoke this function many times. Each result will return a cursor value and you can pass that value to the next invokation to get the next page of results. The result set will also include a _next_ field with the full URL to get the next page, so you can just keep reading that and requesting that URL until you reach the end. When you reach the end, no more results will be returned or the result set will be less than maxresults and the next field will be empty.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/exit": { "post": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UserIdFormModel" } ] }, "example": { "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Exit a Room", "description": "_Requires Authentication._\n\nThis method should be called to remove a user from a room. This will cause an EXIT event to be broadcast in the room and this user will no longer show up in the list of attendees in the room.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/bounce": { "post": { "tags": [ "ChatApi" ], "summary": "Bounce User (ban user from room)", "parameters": [ { "name": "appid", "in": "path", "description": "The TalkLabs application ID assigned to your account.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "description": "The TalkLabs-assigned room ID returned when the room was created.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ChatBounceUserFormModel" } ] }, "example": { "bounce": "true", "announcement": "The bouncer shows dave_m the way out.", "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "description": "## Optionally display a message to people in the room indicating this person was bounced.\n\nWhen you bounce a user from the room, the user is removed from the room and blocked from reentering. Past events generated by that user are not modified (past messages from the user are not removed).\n\n* **userid**: (required) The ID of the user to bounce from the room.\n* **bounce**: (required, true / false) True if the user is being bounced from the room. False if user is debounced, allowing the user to reenter the room.\n* **announcement**: (optional) If provided, this announcement is displayed to the people who are in the room, as the body of a BOUNCE event.\n\n## URL Parameters\n* **roomid** : The ID of the chat room from which to bounce this user.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/shadowban": { "post": { "tags": [ "ChatApi" ], "summary": "Shadow Ban User (In Room Only)", "parameters": [ { "name": "appid", "in": "path", "description": "The TalkLabs application ID assigned to your account.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "description": "The TalkLabs-assigned room ID returned when the room was created.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ChatUserEffectFormModel" } ] }, "example": { "applyEffect": true, "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "description": "There is a user level shadow ban (global) and local room level shadow ban. \n\nA Shadow Banned user can send messages into a chat room, however those messages are flagged as shadow banned. This enables the application to show those messags only to the shadow banned user, so that that person may not know they were shadow banned. This method shadow bans the user on the global level (or you can use this method to lift the ban). You can optionally specify an expiration time. If the expiration time is specified, then each time the shadow banned user tries to send a message the API will check if the shadow ban has expired and will lift the ban.\n\n* **userid**: (required) The applicaiton provided userid of the user to ban\n* **applyeffect**: (required) true or false. If true, user will be set to banned state. If false, will be set to non-banned state.\n* **expireseconds**: (optional) Duration of shadowban value in seconds. If specified, the shadow ban will be lifted when this time is reached. If not specified, shadowban remains until explicitly lifted. Maximum seconds is a double byte value.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/mute": { "post": { "tags": [ "ChatApi" ], "summary": "Mute User (In Room Only)", "parameters": [ { "name": "appid", "in": "path", "description": "The TalkLabs application ID assigned to your account.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "description": "The TalkLabs-assigned room ID returned when the room was created.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ChatUserEffectFormModel" } ] }, "example": { "applyEffect": true, "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "description": "There is a user level shadow ban (global) and local room level shadow ban. \n\nA Shadow Banned user can send messages into a chat room, however those messages are flagged as shadow banned. This enables the application to show those messags only to the shadow banned user, so that that person may not know they were shadow banned. This method shadow bans the user on the global level (or you can use this method to lift the ban). You can optionally specify an expiration time. If the expiration time is specified, then each time the shadow banned user tries to send a message the API will check if the shadow ban has expired and will lift the ban.\n\n* **userid**: (required) The applicaiton provided userid of the user to ban\n* **mute**: (required) true or false. If true, will have the mute affect applied. If false, mute will not be applied.\n* **expireseconds**: (optional) Duration of the effect,in seconds. If specified, the shadow ban will be lifted when this time is reached. If not specified, effect remains until explicitly lifted. Maximum seconds is a double byte value.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/sessions/{userid}/touch": { "post": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Touch Session (\"keep alive\")", "description": "Users who are not active will automatically exit the room. This method lets the room know that the user is still active so the user doesn't need to rejoin. The SDKs will do this for you automatically.\n\nYou can configure a room to not auto-expire sessions in the settings for that room.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/events/{eventid}/setdeleted": { "put": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "eventid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned chat event ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "Deleted", "in": "query", "required": true, "schema": { "type": "boolean" } }, { "name": "UserId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" }, { "name": "PermanentIfNoReplies", "in": "query", "required": true, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "chat.executecommand", "op": "speech", "room": { "kind": "chat.room", "id": "5ec2047286c2921ad07edd39", "appid": "5ec2038a86c2921ad07edd35", "ownerid": "u-8842", "name": "New York City Chat (Post-Moderated)", "description": "Live from the top of the Empire State Building", "customtype": "", "customid": "5th-stand", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "enableactions": true, "enableenterandexit": true, "open": true, "inroom": 1, "added": "2020-05-18T03:43:46.3198116Z", "whenmodified": "2020-05-18T03:43:46.3198116Z", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "delaymessageseconds": 0 }, "speech": { "kind": "chat.event", "id": "5ec204d986c2921ad07edd3d", "roomid": "5ec2047286c2921ad07edd39", "body": "Hello, SportsTalk247.com World!↵", "added": "2020-05-18T03:45:29.3561662Z", "ts": 637253703293561600, "eventtype": "speech", "userid": "userid_abe", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "banned": false }, "customtype": "", "customid": null, "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": null, "parentid": "", "hierarchy": [], "edited": false, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 0, "reactions": [], "moderation": "na", "reports": [] }, "action": null } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Event Set Deleted (Logical Delete)", "description": "Use this when you want to delete the contents of an event but still have the event, for example to display that the message was withdrawn, or to keep a reply history if using threaded replies. This will logically delete an event, updating it to set deleted flag = true. It will also cause a REPLACE event to be sent so you can update the event you are currently displaying.\n\n## BODY PARAMETERS\n\n- **deleted**: (required) true to delete the event, false to undelete the event.\n- **userid**: (required) The userid of user who is executing the command. The user must have joined the room first. The user must own the event or have elevated permissions.for future analysis or audit trail purposes.\n- permanentifnoreplies: (required) If this is set to true, the command is converted from logical delete to permanent delete automatically if the event has no replies. This is for when you want to permanently delete the event but only if it has no children.\n \n\n## RESPONSE CODES\n\n- **200 | OK** : Sweet, sweet success.\n- **400 | BadRequest** : Something is wrong with your request. View response message and errors list for details.\n- **403 | Forbidden** : The userid issuing the request is banned from chatting in this room (or is banned globally).\n- **405 | MethodBlocked** : The method was blocked because it contained profanity and filtermode was set to 'block'.\n- **409 | Conflict** : The customid of your event is already in use.\n- **412 | PreconditionFailed** : User must JOIN the room before executing a chat command.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/events/{eventid}": { "delete": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "eventid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned chat event ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "query", "schema": { "type": "string" }, "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Delete Event", "description": "This will parmenently delete an event from the room and it will trigger a \"remove\" event to be sent as an update, so you can remove it from your display.\n\n## URL Parameters\n\n- **userid** : (Optional) If provded, a check will be made to enforce this userid (the one deleting the event) is the owner of the event or has elevated permissions. If null, it assumes your business service made the determination to delete the event. If it is not provided this authorization check is bypassed.", "security": [ { "ApiToken": [] } ] }, "get": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "eventid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned chat event ID.", "x-identifier-source": "TalkLabs ID" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Get Event by ID", "description": "The comment time stamp is stored in UTC time.\n\n### URL Arguments\n* **chat_room_id** : (required) The ID of the comment conversation, URL ENCODED.\n* **chat_event_id** : (required) The unique ID of the comment, URL ENCODED.", "security": [ { "ApiToken": [] } ] }, "put": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "eventid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned chat event ID.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ChatUpdateEventFormModel" } ] }, "example": { "body": "Message has been modified", "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "updated", "errors": {}, "data": { "kind": "chat.event", "id": "5ffdaf0586c29a175c6c4702", "roomid": "5ffdaefc86c29a175c6c46fe", "body": "Message has been modified", "originalbody": "", "added": "2021-01-12T14:15:33.0724021Z", "modified": "2021-01-20T12:53:06.8107428Z", "ts": 637460577330724000, "eventtype": "speech", "userid": "userid_abe", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "banned": false, "shadowbanned": false, "shadowbanexpires": "0001-01-01T00:00:00Z", "muted": false, "moderation": "na", "reports": [] }, "mentions": [], "customtype": "", "customid": null, "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": null, "parentid": "", "hierarchy": [], "depth": 0, "edited": true, "editedbymoderator": false, "censored": false, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 0, "reactions": [], "moderation": "na", "reports": [] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Update Chat Message Content", "description": "This API may be used to update the body of an existing Chat Event. It is used to enable the user to edit the message after it is published. This may only be used with MESSAGE event types (speech, quote, reply). When the chat event is updated another event of type \"replace\" will be emitted with the updated event contents, and the original event will be replaced in future calls to List Event History, Join and List Previous Events. The event will also be flagged as edited by user.\n\n### URL Arguments\n* **roomid** : (required) The ID of the chat room conversation\n* **eventid** : (required) The unique ID of the chat event to be edited. This must be a messsage type event (speech, quote or reply).\n\n### BODY Properties\n* **userid** : (required) The application specific user ID updating the chat event. This must be the owner of the comment or moderator / admin.\n* **body** : (required) The new body contents of the event. \n* **customid** : (optional) Optionally replace the customid.\n* **custompayload** : (optional) Optionally replace the payload of the event.\n* **customfield1** : (optional) Optionally replace the customfield1 value.\n* **customfield2** : (optional) Optionally replace the customfield2 value.\n* **customtags** : (optional) Optionaly replace the custom tags.\n\nThe comment will be flagged to indicate that it has been modified.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/events": { "delete": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Delete all events in a room", "description": "Create rooms, publish messages, subscribe users, and read live activity.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/eventsbytimestamp/list/{ts}": { "get": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "ts", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "An ISO 8601 timestamp." }, { "name": "limitolder", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "limitnewer", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "list.chateventsbytimestamp", "cursorolder": "637477180206230222", "cursornewer": "637477362782873373", "timestampolder": 637477180206230300, "timestampnewer": 637477362782873300, "hasmoreolder": true, "hasmorenewer": false, "itemcount": 2, "events": [ { "kind": "chat.event", "id": "601704845617e4176c05e5c7", "roomid": "600d78d45617e20e34c39dd5", "body": "That's another pickle you've gotten us into Ollie!", "originalbody": "", "added": "2021-01-31T19:27:00.6230222Z", "modified": "2021-01-31T19:27:00.6230222Z", "ts": 637477180206230300, "eventtype": "custom", "userid": "bobsmith4", "user": { "kind": "app.user", "userid": "bobsmith4", "handle": "dave_m75962", "handlelowercase": "georgew75962", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "role": "admin", "customtags": [], "banned": false, "shadowbanned": false, "shadowbanexpires": "0001-01-01T00:00:00Z", "muted": false, "moderation": "approved", "reports": [] }, "mentions": [], "customtype": "pickles", "customid": "", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": null, "parentid": "", "hierarchy": [], "depth": 0, "edited": false, "editedbymoderator": false, "censored": false, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 0, "reactions": [], "moderation": "na", "reports": [] }, { "kind": "chat.event", "id": "60174bd65617e6176c7aaf1a", "roomid": "600d78d45617e20e34c39dd5", "body": "this is an announcement by the admin.", "originalbody": "", "added": "2021-02-01T00:31:18.2873373Z", "modified": "2021-02-01T00:31:18.2873373Z", "ts": 637477362782873300, "eventtype": "announcement", "userid": "bobsmith4|600d78305617e20e34c39bb2", "user": { "kind": "app.user", "userid": "bobsmith4", "handle": "dave_m75962", "handlelowercase": "georgew75962", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "role": "admin", "customtags": [], "banned": false, "shadowbanned": false, "shadowbanexpires": "0001-01-01T00:00:00Z", "muted": false, "moderation": "approved", "reports": [] }, "mentions": [], "customtype": "", "customid": "", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": null, "parentid": "", "hierarchy": [], "depth": 0, "edited": false, "editedbymoderator": false, "censored": false, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 0, "reactions": [], "moderation": "na", "reports": [] } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Events By Timestamp", "description": "* This method enables you to retrieve an event using a timestamp.\n* You can optionally retrieve a small number of displayable events before and after the message at the requested timestamp.\n* This method returns a list of events sorted from oldest to newest.\n* This method returns only active events.\n* The timestamp is a high resolution timestamp accurate to the thousanth of a second. It is possible, but very unlikely, for two messages to have the same timestamp.\n* The method returns \"timestampolder\". This can be passed as the timestamp value when calling functions like this which accept a timestamp to retrieve data.\n* The method returns \"timestampnewer\". This can be passed as the timestamp value when calling this function again.\n* The method returns \"cursorpolder\". This can be passed as the cursor to ethods that accept an events-sorted-by-time cursor.\n* The method returns \"cursornewer\". This can be passed as the cursor to methods that accept an events-sorted-by-time cursor.\n\n## LIMITATIONS\nIf you pass in 0 for limitolder you won't get any older events than your timestamp and hasmoreolder will always be false because the API will not query for older events.\nIf you pass in 0 for limitnewer you won't get any newer events than your timestamp and hasmorenewer will always be false because the API will not query for newer events.\n\n## URL PARAMETERS\n* **ts**: (Required) If not provided, the most recent events will be returned. To get older events, call this method again using the cursor string returned from the previous call.\n* **limitolder** : (Optional) Defaults to 0, maximum 100.\n* **limitnewer** : (Optional) Defaults to 0, maximum 100.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/eventsbycustomid/{customid}": { "get": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "customid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A customer-defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID.", "x-identifier-source": "customer-defined" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Get an event by custom ID", "description": "Create rooms, publish messages, subscribe users, and read live activity.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/updates/{cursor}": { "get": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The cursor returned by the previous page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100 }, "description": "The maximum number of records to return." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Get room updates", "description": "Create rooms, publish messages, subscribe users, and read live activity.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/events/{eventid}/quote": { "post": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "eventid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned chat event ID.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ChatQuotedReplyFormModel" } ] }, "example": { "body": "Mind if I quote you?", "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "chat.executecommand", "op": "speech", "room": { "kind": "chat.room", "id": "5ec3c1945617e21bd8c5567b", "appid": "5ebbe03d5617e00de4b044c2", "ownerid": "userid_abe", "name": "ROOM HAS NEW NAME", "description": "Live from the top of the Empire State Building", "customtype": "", "customid": "new-york-city-club", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "enableactions": true, "enableenterandexit": true, "open": true, "inroom": 1, "added": "2020-05-19T11:23:00.3049587Z", "whenmodified": "2020-05-20T03:54:04.4814629Z", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "delaymessageseconds": 0 }, "speech": { "kind": "chat.event", "id": "5ec4aa755617e40ed4e82ab2", "roomid": "5ec3c1945617e21bd8c5567b", "body": "This is my reply↵", "added": "2020-05-20T03:56:37.4495882Z", "ts": 637255437974495900, "eventtype": "reply", "userid": "userid_abe", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "banned": false }, "customtype": "", "customid": null, "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": { "kind": "chat.event", "id": "5ec4aa385617e40ed4e82aaf", "roomid": "5ec3c1945617e21bd8c5567b", "body": "Hello a second time!", "added": "2020-05-20T03:55:36.9845354Z", "ts": 637255437369845400, "eventtype": "speech", "userid": "userid_abe", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "banned": false }, "customtype": "", "customid": null, "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": null, "parentid": "", "hierarchy": [], "edited": false, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 0, "reactions": [ { "type": "like", "count": 1, "users": [ { "userid": "userid_abe", "handle": "HonestAbe", "displayname": "Abraham Lincoln" } ] } ], "moderation": "na", "reports": [] }, "parentid": "", "hierarchy": [], "edited": false, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 0, "reactions": [], "moderation": "na", "reports": [] }, "action": null } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Quote a Message", "description": "This method is provided to support a chat experience where a person wants to reply to another person, and the reply is inline with the rest of chat, but contains a copy of all or part of the original message you are replying to. You can see this behavior in WhatsApp and iMessage. This way, when viewing the reply, the user doesn't need to scroll up searching conversation history for the context (the parent the reply is addresssing).\n\n## URL PARAMETERS\n* **appid** : (required) The ID of your application\n* **chatroomid** : (required) The ID of your chat room\n* **eventid** : (required) The ID of the event you are quoting\n\n## BODY PARAMETERS\n* **userid** : (Required) The userid of the user who is publishing the quoted reply\n* **body** : (Required) The contents of the reply for the quoted reply. Cannot be empty.\n* **customid**: (Optional) Assigns a custom ID to the quoted reply event.\n* **custompayload**: (Optional) Attach a custom payload string to the quoted reply such as JSON or XML.\n* **customfield1**: (Optional) Use this field however you wish\n* **customfield2**: (Optional) Use this field however you wish\n* **customtags**: (Optional) An array of strings, use this field however you wish.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/events/{eventid}/reply": { "post": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "eventid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned chat event ID.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ChatThreadedReplyFormModel" } ] }, "example": { "body": "I spy with my little eye an opportunity to post a reply!", "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "chat.executecommand", "op": "speech", "room": { "kind": "chat.room", "id": "5ec3c1945617e21bd8c5567b", "appid": "5ebbe03d5617e00de4b044c2", "ownerid": "userid_abe", "name": "ROOM HAS NEW NAME", "description": "Live from the top of the Empire State Building", "customtype": "", "customid": "new-york-city-club", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "enableactions": true, "enableenterandexit": true, "open": true, "inroom": 1, "added": "2020-05-19T11:23:00.3049587Z", "whenmodified": "2020-05-20T03:54:04.4814629Z", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "delaymessageseconds": 0 }, "speech": { "kind": "chat.event", "id": "5ec4aa755617e40ed4e82ab2", "roomid": "5ec3c1945617e21bd8c5567b", "body": "This is my reply↵", "added": "2020-05-20T03:56:37.4495882Z", "ts": 637255437974495900, "eventtype": "reply", "userid": "userid_abe", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "banned": false }, "customtype": "", "customid": null, "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": { "kind": "chat.event", "id": "5ec4aa385617e40ed4e82aaf", "roomid": "5ec3c1945617e21bd8c5567b", "body": "Hello a second time!", "added": "2020-05-20T03:55:36.9845354Z", "ts": 637255437369845400, "eventtype": "speech", "userid": "userid_abe", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "banned": false }, "customtype": "", "customid": null, "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": null, "parentid": "", "hierarchy": [], "edited": false, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 0, "reactions": [ { "type": "like", "count": 1, "users": [ { "userid": "userid_abe", "handle": "HonestAbe", "displayname": "Abraham Lincoln" } ] } ], "moderation": "na", "reports": [] }, "parentid": "", "hierarchy": [], "edited": false, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 0, "reactions": [], "moderation": "na", "reports": [] }, "action": null } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Reply to a Message (Threaded)", "description": "The purpose of this method is to enable support of a sub-chat within the chat room. You can use it to split off the conversation into a nested conversation. You can build a tree structure of chat messages and replies, but it is recommended not to build experiences deeper than parent and child conversation level or it becomes complex for the users to follow.\n\n* Replies do not support admin or action commands\n\n## URL PARAMETERS\n* **appid** : (required) The ID of your application\n* **chatroomid** : (required) The ID of your chat room\n* **eventid** : (required) The ID of the event you are quoting\n\n## BODY PARAMETERS\n* **userid** : (Required) The userid of the user who is publishing the quoted reply\n* **body** : (Required) The contents of the reply for the quoted reply. Cannot be empty.\n* **customid**: (Optional) Assigns a custom ID to the quoted reply event.\n* **custompayload**: (Optional) Attach a custom payload string to the quoted reply such as JSON or XML.\n* **customfield1**: (Optional) Use this field however you wish\n* **customfield2**: (Optional) Use this field however you wish\n* **customtags**: (Optional) An array of strings, use this field however you wish.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/events/{eventid}/react": { "post": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "eventid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned chat event ID.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ReactionFormModel" } ] }, "example": { "reaction": "like", "reacted": "true", "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "chat.event", "id": "5ec4aa615617e40ed4e82ab0", "roomid": "5ec3c1945617e21bd8c5567b", "body": "", "added": "2020-05-20T03:56:17.7773748Z", "ts": 637255437777773700, "eventtype": "reaction", "userid": "userid_abe", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "banned": false }, "customtype": "", "customid": "", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": { "kind": "chat.event", "id": "5ec4aa385617e40ed4e82aaf", "roomid": "5ec3c1945617e21bd8c5567b", "body": "Hello a second time!", "added": "2020-05-20T03:55:36.9845354Z", "ts": 637255437369845400, "eventtype": "speech", "userid": "userid_abe", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "banned": false }, "customtype": "", "customid": null, "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": null, "parentid": "", "hierarchy": [], "edited": false, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 0, "reactions": [ { "type": "like", "count": 1, "users": [ { "userid": "userid_abe", "handle": "HonestAbe", "displayname": "Abraham Lincoln" } ] } ], "moderation": "na", "reports": [] }, "parentid": "", "hierarchy": [], "edited": false, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 0, "reactions": [], "moderation": "na", "reports": [] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "React To A Message (\"Like\")", "description": "After this completes, a new event appears in the stream representing the reaction. The new event will have an updated version of the event in the replyto field, which you can use to update your UI.\n\n### POST PARAMETERS\n\n- **userid**: (required) The ID of the user who is reacting.\n- **reaction**: (required) A string for the reaction such as \"like\", or \"emoji:{emojid}\" which accepts a standard unicode value for an emoji.\n- **reacted**: (required) true to add reaction or false to remove the reaction.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/events/{eventid}/report": { "post": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "eventid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned chat event ID.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ReportFormModel" } ] }, "example": { "reportType": {}, "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Report Message", "description": "A reported message is temporarily removed from the chat event stream until it is evaluated by a moderator.\n\n## POST PARAMETERS\n\n- **userid** : (optional) The application provided userid of the user who reported the abuse.\n \n- **reporttype:** (required) This is the classification of the reported post. It must be one of the below values (note that 'false' represents information considered false by the reporter:\n \n - abuse\n \n - spam\n \n - selfharm\n \n - hate\n \n - violence\n \n - harassment\n \n - nudity\n \n - illegal\n \n - false\n \n - other\n \n\n## RESPONSE CODES\n\n- **200 | OK** : Sweet, sweet success.\n \n- **400 | BadRequest** : Something is wrong with your request. View response message and errors list for details.\n \n- **403 | Forbidden** : The userid issuing the request is banned from chatting in this room (or is banned globally), or, attempted to report an event that was published by a moderator or admin.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/users/{userid}/report": { "post": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ReportFormModel" } ] }, "example": { "reportType": {}, "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "chat.room", "id": "5fda771e91dfe04208da0295", "appid": "5fd60d0191dfe07304adde1a", "ownerid": null, "name": "New York City Chat (Post-Moderated)", "description": "Live from the top of the Empire State Building", "pictureurl": "", "customtype": "", "customid": "new-york-city-club", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "enableactions": true, "enableenterandexit": true, "open": true, "inroom": 8, "added": "2020-12-16T21:07:42.4358144Z", "whenmodified": "2021-02-11T13:59:43.2118834Z", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "delaymessageseconds": 0, "bouncedusers": [], "flaggedusers": [ "u-8842" ], "shadowbannedusers": [], "reportedusers": [ { "userid": "u-8842", "reportedbyuserid": "userid_abelincoln", "reason": "abuse", "added": "2021-02-11T13:59:43.1969243Z" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Report User In Room", "description": "- This API enables users to report other users who exhibit abusive behaviors. It enables users to silence another user when a moderator is not present. If the user receives too many reports in a trailing 24 hour period, the user will become flagged at the room level.\n \n- This API moderates users on the ROOM LEVEL. If a There is an API method that enable reporting users at the global user level which impacts all rooms. This API impacts only the experience for the specified userid within the specified room.\n \n- This API will return an error (see responses below) if user reporting is not enabled for your application in the application settings by setting User Reports limit to a value > 0.\n \n- A user who is flagged will have the _shadowban_ effect applied.\n \n\n### URL Arguments\n\n- **userid** : (required) The ID of the user who is being reported, URL ENCODED.\n \n\n### BODY Parameters\n\n- **reporttype** : (required) Possible values: \"abuse\", \"spam\". SPAM is unsolicited commercial messages and abuse is hate speach or other unacceptable behavior, 'false' represents information considered false by the reporter:\n \n - abuse\n \n - spam\n \n - selfharm\n \n - hate\n \n - violence\n \n - harassment\n \n - nudity\n \n - illegal\n \n - false\n \n - other\n \n\n### RESPONSES:\n\n| Code | Meaning | Description |\n| --- | --- | --- |\n| 200 | OK | Request completed successfully (or duplicate report ignored) |\n| 404 | Not Found | The specified user or application or room could not be found |\n| 412 | Precondition Failed | The request was rejected because user reporting is not enabled for the application. |", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/commands/purge": { "post": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ChatCommandPurgeUserMessagesFormModel" } ] }, "example": { "userid": "u-8842", "byuserid": "admin" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Purge User Messages", "description": "- **command**: The command to execute. In this case, \"\\*purge \"\n \n\n### POST ARGUMENTS\n\n- **userid**: (required) The userid of the user owning the messages to be purged\n \n- **byuserid:** (optional) The userid of the user executing the purge command. If provided, this validates that the user executing the command has the rights to do it", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/reset": { "post": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "RoomId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ChatResetRoomFormModel" } ] }, "example": {} } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "The specified conversation and all comments were permanently deleted.", "errors": {}, "data": { "kind": "delete.conversation", "conversationid": "api-conversation-demo1", "userid": null, "deletedconversations": 1, "deletedcomments": 17 } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Reset Room", "description": "## This removes all events from the room and resets any counters. The purpose of this function is to reset the room back to a clean state after using it for testing purposes\n\n### URL Arguments\n\n- **roomid** : (required) The ID of the room\n \n\n### POST BODY Arguments\n\n- **removeusereffects** : (optional | false) If true, all effects applied to users in this room are removed from this room only", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/batch/details": { "get": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "customid", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "A customer-defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID.", "x-identifier-source": "customer-defined" }, { "name": "entity", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RoomEntityTypes" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "chat.room.list.extendeddetails", "details": [ { "room": { "kind": "chat.room", "id": "601b44620dc9ec1af01775ff", "appid": "600a193386c292217434a82c", "ownerid": null, "name": "New York City Chat (Post-Moderated)", "description": "Live from the top of the Empire State Building", "pictureurl": "", "customtype": "", "customid": "new-york-city-club", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "enableactions": true, "enableenterandexit": true, "open": true, "inroom": 2386, "added": "2021-02-04T00:48:34.7165009Z", "whenmodified": "2021-02-16T10:41:52.9094331Z", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "delaymessageseconds": 0, "bouncedusers": [], "reportedusers": [] }, "mostrecentmessagetime": null, "inroom": 0 } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Get Room Extended Details Batch", "description": "This method lets you specify a list of entity types to return. You can use it to get room details as well as statistics and other data associated with a room that is not part of the room entity.\n\nYou must specify one or more roomid values or customid values. \nYou may optionally provide both roomid and customid values.\nYou may not request more than 20 rooms at once total.\nYou must specify at least one entity type.\n\nIn the future, each entity requested will count towards your API usage quota, so don't request data you will not be using.\n\nThe response will be a list of RoomExtendedDetails objects. They contain properties such as room, mostrecentmessagetime, and inroom. These properties will be null if their entity type is not specified.\n\n### URL Parameters\n* **roomid** : (optional) A list of room IDs.\n* **customid** : (optional) A list of room customIDs.\n* **entity** : (required) Specify one or more ENTITY TYPES to include in the response. Use one or more of the types below.\n * *room* : This returns the room entity.\n * *numparticipants* : This returns number of active participants / room subscribers.\n * *lastmessagetime* : This returns the time stamp for the most recent event that is a visible displayable message (speech, quote, threaded reply or announcement).", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/moderation/queues/events": { "get": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" }, "description": "The maximum number of records to return." }, { "name": "roomId", "in": "query", "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The cursor returned by the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Messages Needing Moderation", "description": "_This method requires authentication._\n\n* *limit*: (optional) Defaults to 200. This limits how many messages to return from the queue\n* *roomId*: (optional) Provide the ID for a room to filter for only the queued events for a specific room\n* *cursor*: (optional) Provide cursor value to get the next page of results.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/moderation/queues/events/{eventid}/applydecision": { "post": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "eventid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned chat event ID.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ModerateEventFormModel" } ] }, "example": { "approve": "true" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Moderator Approve / Reject Message", "description": "If PRE-MODERATION is enabled for a room, then all messages go to the queue before they can appear in the event stream. For each incomming message, a webhook will be fired, if one is configured. \n\nIf the room is set to use POST-MODERATION, messages will only be sent to the moderation queue if they are reported.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/moderation/queues/roomflaggedusers": { "get": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" }, "description": "The maximum number of records to return." }, { "name": "roomId", "in": "query", "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The cursor returned by the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Flagged Users Needing Moderation", "description": "When users report other users, if the reported user gets reported too many times the user becomes flagged. Once the user is flagged, the user will appear in the results of this query.\n\n* *limit*: (optional) Defaults to 50. This limits how many items are returned\n* *roomId*: (optional) Provide the ID for a room to filter for only the queued events for a specific room\n* *cursor*: (optional) Provide cursor value to get the next page of results.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/moderation/flaggedusers/{userid}/applydecision": { "post": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ModerateUserFormModel" } ] }, "example": { "approve": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Moderator Apply Decision to Flagged User", "description": "If a user is reported by other users as being abusive, the user will be sent to the moderation queue and is flagged while in the queue.\n* Invoke this method to either approve or reject the user\n* In either case the user is no longer flagged\n* In either case the reports are erased\n* If apply is true, user gets shadowban effect with no expiration\n* If apply is false, flag is remove\n\n# BODY PROPERTIES\n* **approve** : (required) Pass **true** to approve the user (indicate the user is not abusive) or **false** to reject the user.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/usereffects": { "get": { "tags": [ "ChatApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Room User Effects", "description": "Users can have effects applied such as mute, ban, and so on. This method returns a list of all users in the room that have one or more effect on them (that has not expired).\n\nIt is possible for the user to appear more than once in the list if there is more than one effect on the user.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/comment/conversations": { "post": { "tags": [ "CommentApi" ], "summary": "Create / Update Conversation", "parameters": [ { "name": "appid", "in": "path", "description": "The appid of your app", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "description": "The post body (JSON)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateConversationFormModel" } ] }, "example": { "property": "", "moderation": "post", "title": "Sample Conversation", "open": true, "conversationId": "conversation-id" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Inserted", "errors": {}, "data": { "kind": "comment.conversation", "appid": "5ededa7086c2920e6ccc06f8", "owneruserid": "", "conversationid": "demo-conversation-id", "property": "sportstalk247.com/apidemo", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "title": "Sample Conversation", "maxcommentlen": 512, "commentcount": 0, "open": true, "added": "2020-06-09T19:32:28.6308249Z", "whenmodified": "2020-06-09T19:32:28.6308249Z", "customtype": "", "customid": "/articles/2020-03-01/article1/something-very-important-happened", "customtags": [ "taga", "tagb" ], "custompayload": "{ num : 0 }", "customfield1": "/sample/userdefined1/emojis/😂🤣❤😍😒", "customfield2": "/sample/userdefined2/intl/characters/äöüÄÖÜß" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "description": "If a conversation with the specified ID already exists, this will update it.\n\nCustom fields can be set, and can be overwritten. However, once a custom field is used it can not be set to no value (empty string).\n\n### BODY Properties\n\n- **owneruserid** : (optional) The application's userid representing the user who created the converation. If provided, this user is considered the \"owner\" and has full rights over the conversation space.\n \n- **conversationid** : (required) The conversation ID. This must be a URL friendly string (cannot contain / ? or other URL delimiters). Maximum length is 250 characters.\n \n- **replaceconversationid**: (optional) If you are updating an existing conversation, this will replace the ID of the conversation with the new URL friendly string and will update all comments having the old ID with the new conversation ID. For good performance, use this sparingly to avoid waiting while all affected comments are updated.\n \n- **property** : (required) The property this conversation is associated with. It is any string value you want. Typically this is the domain of your website for which you want to use commenting, if you have more than one. Examples:\n \n - _dev_, _uat_, _stage_, _prod_\n \n - _website_, _mobile_\n \n - _site1.com_, _site2.com_\n \n- **moderation** : (required) Specify if _pre_ or _post_ moderation is to be used\n \n- **maxreports** : (optional, default = 3) If this number of users flags a content item in this conversation, the item is disabled and sent to moderator queue for review\n \n- **title** : (optional) The title of the conversation\n \n- **maxcommentlen**: (optional) The maximum allowed length of a comment. Default is 256 characters. Maximum value is 10485760 (10 MB)\n \n- **open**: (optional, defaults to _true_) If the conversation is open people can add comments.\n \n- **enableprofanityfilter**: (optional, defaults to true) Filters comments for known profanities and replaces them with \\* chars.\n \n- **added**: (optional) If this timestamp is provided then the whenadded field will be overridden. You should only use this when migrating data; data is timestamped automatically. Example value: \"2020-05-02T08:51:53.8140055Z\"\n \n- **customid** : (optional) 250 characters for a custom ID for your app. This field is indexed for high performance object retrieval.\n \n- **customtype** : (optional) Custom type string.\n \n- **custompayload** : (optional) Custom payload string.\n \n- **customfield1** : (optional) User custom field 1. Store any string value you want here, limit 1024 bytes.\n \n- **customfield2** : (optional) User custom field 2. Store any string value you want here, limit 1024 bytes.\n \n- **customtags** : (optional) A comma delimited list of tags", "security": [ { "ApiToken": [] } ] }, "get": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "propertyid", "in": "query", "schema": { "type": "string", "default": "" } }, { "name": "title", "in": "query", "schema": { "type": "string", "default": "" } }, { "name": "conversationid", "in": "query", "schema": { "type": "string", "default": "" }, "description": "The TalkLabs-assigned conversation ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "customid", "in": "query", "schema": { "type": "string", "default": "" }, "description": "A customer-defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID.", "x-identifier-source": "customer-defined" }, { "name": "cursor", "in": "query", "schema": { "type": "string", "default": "" }, "description": "The cursor returned by the previous page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 200 }, "description": "The maximum number of records to return." }, { "name": "sort", "in": "query", "schema": { "type": "string", "default": "oldest" } }, { "name": "filterStartTime", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "filterEndTime", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "list.commentconversations", "cursor": "5e9e654338a2851934963163", "more": false, "conversations": [ { "kind": "comment.conversation", "appid": "5e9389ed38a2b10794e271ee", "owneruserid": "", "conversationid": "conversationabcd", "property": "chelseafc.com", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "title": "Champions League Final Victory", "maxcommentlen": 512, "commentcount": 0, "open": true, "added": 1587481667, "whenmodified": 1587481667, "customtype": "", "customid": "media./content/chelseafc/en/news-mobile/2020/03/18/watch-our-2012-champions-league-final-victory-in-full-from-8pm", "customtags": [ "taga", "tagb" ], "custompayload": "{ num : 0 }", "customfield1": "/sample/userdefined1/emojis/😂🤣❤😍😒", "customfield2": "/sample/userdefined2/intl/characters/äöüÄÖÜß" }, { "kind": "comment.conversation", "appid": "5e9389ed38a2b10794e271ee", "owneruserid": "", "conversationid": "my_conversation_id", "property": "sportstalk247.com/apidemo", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "title": "Sample Conversation", "maxcommentlen": 512, "commentcount": 5, "open": true, "added": 1587438915, "whenmodified": 1587438915, "customtype": "", "customid": "/articles/2020-03-01/article1/something-very-important-happened", "customtags": [ "taga", "tagb" ], "custompayload": "{ num : 0 }", "customfield1": "/sample/userdefined1/emojis/😂🤣❤😍😒", "customfield2": "/sample/userdefined2/intl/characters/äöüÄÖÜß" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Conversations", "description": "### Cursoring\n\n- API Method returns a cursor\n- Cursor includes a \"more\" field indicating if there are more results that can be read at the time this call is made\n- Cursor includes \"cursor\" field, which can be passed into subsequent calls to this method to get additional results\n- Cursor includes \"itemcount\" field, which is the number of items returned by the cursor not the total number of items in the database\n- All LIST methods in the API return cursors and they all work the same way\n \n\n### Optional Parameters\n\n- **propertyid** : Filters list of conversations by property. Exact match only, case sensitive.\n- **cursor** : (Optional, default = \"\"). For cusoring, pass in cursor output from previous call to continue where you left off.\n- **limit** : (Optional, default = 200). For cursoring, limit the number of responses for this request.\n- **sort** : (Optional, default = \"oldest\").\n - **newest** : Default. Sorts from newest created conversation to the oldest.\n - **oldest** : Starts from oldest conversation and cursors towards the newest.\n - **reactioncount**: Sorts conversations based on how many reactions there were on the conversation, from highest to lowest. Secondary sort order is WhenAdded desc (when the conversation was created).\n- **filterStartTime** : (Optional, default=\"\"). ISO8601 datetime. When provided, only conversations created on or after this time are returned. Example: \"2024-01-26T20:25:37.667Z\"\n \n- **filterEndTime** : (Optional, default=\"\"). ISO8601 datetime. When provided, only conversations created bn or before this time are returned.\n \n\nRetrieves metadata about all conversations for a property. Whenever you create a conversation, you provide a property to associate it with. This returns the metadata for all conversations associated with a property.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/comment/conversations/{conversationid}": { "delete": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "conversationid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned conversation ID.", "x-identifier-source": "TalkLabs ID" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "The specified conversation and all comments were permanently deleted.", "errors": {}, "data": { "kind": "delete.conversation", "conversationid": "api-conversation-demo1", "userid": null, "deletedconversations": 1, "deletedcomments": 17 } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Delete Conversation", "description": "## CANNOT BE UNDONE. This deletes all history of a conversation including all comments and replies within it.\n\n\n### URL Arguments\n* **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED.", "security": [ { "ApiToken": [] } ] }, "get": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "conversationid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned conversation ID.", "x-identifier-source": "TalkLabs ID" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "comment.conversation", "appid": "5e9389ed38a2b10794e271ee", "owneruserid": null, "conversationid": "my_conversation_id", "property": "sportstalk247.com/apidemo", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "title": "Sample Conversation", "maxcommentlen": 512, "commentcount": 1, "open": true, "added": 1587437568, "whenmodified": 1587438787, "customtype": "", "customid": "/articles/2020-03-01/article1/something-very-important-happened", "customtags": [ "taga", "tagb" ], "custompayload": "{ num : 0 }", "customfield1": "/sample/userdefined1/emojis/😂🤣❤😍😒", "customfield2": "/sample/userdefined2/intl/characters/äöüÄÖÜß" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Get Conversation by ID", "description": "Retrieves metadata about a conversation. \n\n### URL Arguments\n* **comment_conversation_id** : (required) The ID of the conversation which is a context for comments. The ID must be URL ENCODED.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/comment/conversations/details/batch": { "get": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "propertyid", "in": "query", "schema": { "type": "string", "default": "" } }, { "name": "ids", "in": "query", "schema": { "type": "string" } }, { "name": "cid", "in": "query", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "Entities", "in": "query", "schema": { "type": "string", "default": "" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "list.commentconversations", "conversations": [ { "kind": "comment.conversation", "appid": "67ce162f5b142e45a0ea5ff7", "owneruserid": "", "conversationid": "api-conversation-demo1", "property": "sportstalk247.com/demo", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "title": "Sample Conversation", "maxcommentlen": 512, "commentcount": 5, "replycount": -1, "reactions": [], "reactioncount": 0, "likecount": 0, "open": true, "added": "2025-03-09T23:38:02.724963Z", "whenmodified": "2025-03-09T23:38:02.7250116Z", "customtype": "", "customid": "/articles/2020-03-01/article1/something-very-important-happened", "customtags": [ "taga", "tagb" ], "custompayload": "{ num : 0 }", "customfield1": "/sample/userdefined1/emojis/😂🤣❤😍😒", "customfield2": "/sample/userdefined2/intl/characters/äöüÄÖÜß" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Batch Get Conversation Details", "description": "The purpose of this method is to support a use case where you start with a list of conversations and you want metadata about only those conversations so you can display things like like count or comment count making minimal requests.\n\nYou can choose to either retrieve articles using the SportsTalk Conversation ID or by using your custom IDs you associated with the conversation using our create/update conversation API.\n\nThe API will return a JSON document containing a list of child objects each containing the requested metadata (see entities property).\n\n### URL PARAMETERS\n\n- ids: (optional): Include one or more comma delimited Sportstalk conversation IDs.\n \n- cid: (optional): Include one or more cid arguments. Each is a _**URL ENCODED**_ string containing the customid. You can specify up to 200 at a time.\n \n- entities (optional): By default only the conversation object data is returned. For more data (and deeper queries) provide any of these entities:\n \n - **reactions**: Includes user reactions and microprofiles in the response\n \n - **likecount**: Includes number of likes on the conversation in the response, otherwise returns -1 for like count.\n \n - **commentcount**: Includes the number of comments in the response, otherwise returns -1 for comment count.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/comment/conversations/{conversationid}/comments": { "post": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "conversationid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned conversation ID.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateCommentFormModel" } ] }, "example": { "body": "Hello, World!", "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "comment.comment", "id": "5edfe37586c2921148f128fc", "appid": "5ededa7086c2920e6ccc06f8", "conversationid": "demo-conversation-id", "commenttype": "comment", "added": "2020-06-09T19:31:01.5810693Z", "modified": "2020-06-09T19:31:01.5810693Z", "userid": "u-8842", "user": { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "banned": false }, "body": "Hello, World! This is a comment with international characters and emojis. Intl: äöüÄÖÜß | Emojis: 😂🤣❤😍😒", "originalbody": "", "hashtags": [], "customtype": "my-custom-type", "customid": "", "custompayload": "{ num : 0 }", "customtags": [ "taga", "tagb" ], "customfield1": "/sample/userdefined1/emojis/😂🤣❤😍😒", "customfield2": "/sample/userdefined2/intl/characters/äöüÄÖÜß", "edited": false, "censored": false, "deleted": false, "parentid": "", "hierarchy": [], "mentions": [], "reactions": [], "likecount": 0, "replycount": 0, "votecount": 0, "votescore": 0, "votes": [], "moderation": "na", "active": true, "reports": [] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Create and Publish Comment", "description": "You can optionally make this comment into a reply by passing in the optional replyto field. \nCustom fields can be set, and can be overwritten. However, once a custom field is used it can not be set to no value (empty string).\n\n### URL Arguments\n\n- **comment_conversation_id** : (required) The ID of the comment stream to publish the comment to. See the Create / Update Conversation method for rules around conversationid.\n \n\n### BODY Properties\n\n- **userid** : (required) The application's userid representing the user who submitted the comment\n \n- **body** : (required) The body of the comment (the message). Supports unicode characters including EMOJIs and international characters.\n \n- **replyto** : (optional) The ID of the comment that this is a reply to.\n \n- **added**: (optional) If this timestamp is provided then the whenadded field will be overridden. You should only use this when migrating data; data is timestamped automatically. Example value: \"2020-05-02T08:51:53.8140055Z\"\n \n\n### OPTIONAL BODY Properties to Create or Update a User\n\nIf the user with matching userid does not exist, the user will be created. If the user does exist, that user will be updated with whatever values you provide from this list\n\n- **userid**: _Required_. If the userid is new then the user will be created. If the userid is already in use in the database then the user will be updated.\n \n- **handle**: (Optional) If you are creating a user and you don't specify a handle, the system will generate one for you (using Display Name as basis if you provide that). If you request a handle and it's already in use a new handle will be generated for you and returned. Handle is an easy to type unique identifier for a user, for example @GeorgeWashington could be the handle but Display Name could be \"da prez numero uno\".\n \n- **displayname**: _Optional_. This is the desired name to display, typically the real name of the person.\n \n- **pictureurl**: _Optional_. The URL to the picture for this user.\n \n- **profileurl**: _Optional_. The profileurl for this user.\n \n- **displayname** : (required if creating a new user, otherwise optional) The non-unique name to display when showing the user's name\n \n- **pictureurl** : (optional) A URL to the user's photo\n \n- **profileurl** : (optional) A URL to the user's profile\n \n- **role**: _Optional_. Valid roles are \"user\" (default), \"moderator\" and \"admin\".\n \n- **usercustomtags**: _Optional_. A list of strings to attach to the user object.\n \n- **customid** : (optional) 250 characters for a custom ID for your app. This field is indexed for high performance object retrieval. If used, it must be unique to the scope of your application.\n \n- **customtype** : (optional) Custom type string.\n \n- **custompayload** : (optional) Custom payload string.\n \n- **customfield1** : (optional) User custom field 1. Store any string value you want here, limit 1024 bytes.\n \n- **customfield2** : (optional) User custom field 2. Store any string value you want here, limit 1024 bytes.\n \n- **customtags** : (optional) A comma delimited list of tags\n \n\n### RESPONSE CODES\n\n- **200 | OK** : Sweet, sweet success.\n \n- **204 | NoContent** : The content was blocked because it contained profanity and filtermode was set to 'block'.\n \n- **400 | BadRequest** : Something is wrong with your request. View response message and errors list for details.\n \n- **403 | Forbidden** : The userid issuing the request is banned from commenting.\n \n- **409 | Conflict** : The customid of your event is already in use.", "security": [ { "ApiToken": [] } ] }, "get": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "conversationid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned conversation ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "sort", "in": "query", "schema": { "type": "string", "default": "oldest" } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "default": "" }, "description": "The cursor returned by the previous page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 200 }, "description": "The maximum number of records to return." }, { "name": "direction", "in": "query", "schema": { "type": "string", "default": "forward" } }, { "name": "includechildren", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "includeinactive", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "filterPostedByUserId", "in": "query", "schema": { "type": "string", "default": "" }, "x-identifier-source": "customer-defined" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "list.comments", "cursor": "", "more": false, "conversation": { "kind": "comment.conversation", "appid": "5e9389ed38a2b10794e271ee", "owneruserid": "", "conversationid": "my_conversation_id", "property": "sportstalk247.com/apidemo", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "title": "Sample Conversation", "maxcommentlen": 512, "commentcount": 5, "open": true, "added": 1587438915, "whenmodified": 1587438915, "customtype": "", "customid": "/articles/2020-03-01/article1/something-very-important-happened", "customtags": [ "taga", "tagb" ], "custompayload": "{ num : 0 }", "customfield1": "/sample/userdefined1/emojis/😂🤣❤😍😒", "customfield2": "/sample/userdefined2/intl/characters/äöüÄÖÜß" }, "comments": [] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Comments", "description": "## GETTING THE RIGHT COMMENTS\n\n- If you use ListComments you will get the top level comments.\n \n- If you use List Replies you will get comments that are children of another comment.\n \n- If you want all replies lower in the tree of comments than the current level use the includechildren property.\n \n\n## READ THIS: Cursoring Limitations for Offset Cursors\n\nIf you use a cursoring method that is offset based (likes/votescore/mostreplies) rather than time based (oldest/newest) you are not guaranteed to see all of the comments. This is because the original query runs, and returs the comments ordered by your query. But, if you then send another request with a cursor value to get the next bunch, the cursor skips over the first set of results equal to the limit size in the query and returns the next set. So if you change your limit size or the underlying data changes because people react, vote, and like things, then you may not get a perfect results set. It is recommended that you request the top N records in one shot, as long as the request isn't too large. Otherwise, use cursoring with oldest sort method to download the entire list of comments and sort it yourself.\n\n### Cursoring\n\n- API Method returns a cursor\n \n- Cursor includes a \"more\" field indicating if there are more results that can be read at the time this call is made\n \n- Cursor includes \"cursor\" field, which can be passed into subsequent calls to this method to get additionaal results\n \n- Cursor includes \"itemcount\" field, which is the number of items returned by the cursor not the total number of items in the database\n \n- All LIST methods in the API return cursors and they all work the same way\n \n\n### URL Arguments\n\n- **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED.\n \n\n### URL Parameters\n\n- **cursor** : (optional) If provided, will get the next bundle of comments in the conversation resuming from where the cursor left off.\n \n- **limit** : (Optional, default = 200). For cursoring, limit the number of responses for this request.\n \n- **direction**: (optional) Default is forward. Must be **forward** or **backward**\n \n- **sort** : (optional, defaults to \"oldest\") Specifies that sort should be done by...\n \n - **oldest** : Sort by when added ascending (oldest on top)\n \n - **newest** : Sort by when added ascending (newest on top)\n \n - **likes** : Sort by number of likes, descending (most liked on top)\n \n - **votescore** : Sort by net of adding upvotes and subtracting downvotes, descending\n \n - **mostreplies** : Sort by number of replies,descending\n \n- **includechildren** : (optional, default is false) If false, this returns all reply nodes that are immediate children of the provided parent id. If true, it includes all replies under the parent id and all the children of those replies and so on.\n \n- includeinactive: (optional, default is false) If false, this returns all reply nodes that are immediate children of the provided parent id. If true, it includes all replies under the parent id and all the children of those replies and so on.\n \n- **filterpostedbyuserid**: (optional) If provided, the list returned will be filtered to only include comments published by the specified userid.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/comment/conversations/{conversationid}/comments/{commentid}": { "put": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "conversationid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned conversation ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "commentid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned comment ID.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateCommentFormModel" } ] }, "example": { "body": "Comment has been modified", "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "comment.comment", "id": "5e95afc238a2831340816195", "appid": "5e9389ed38a2b10794e271ee", "conversationid": "my_conversation_id", "commenttype": "comment", "added": 1586868162, "modified": 1586868474, "userid": "u-8842", "user": { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "banned": false }, "body": "Comment has been modified", "customtype": null, "customid": null, "custompayload": null, "tags": [ "taga", "tagb" ], "edited": true, "deleted": false, "parentid": "", "replyto": null, "hierarchy": [], "mentions": [], "reactions": [ { "type": "like", "count": 1, "users": [ { "userid": "u-8842", "handle": "dave_m", "displayname": "Dave M." } ] } ], "replycount": 0, "votecount": 1, "votescore": 1, "votes": [ { "type": "up", "count": 1, "users": [ { "userid": "u-8842", "handle": "dave_m", "displayname": "Dave M." } ] } ], "moderation": "na", "active": true, "reports": [] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Update Comment", "description": "### URL Arguments\n* **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED.\n* **comment_comment_id** : (required) The unique ID of the comment, URL ENCODED.\n\n### BODY Properties\n* **userid** : (required) The application specific user ID of the comment to be updated. This must be the owner of the comment or moderator / admin.\n* **body** : (required) The new body contents of the comment. \n\nThe comment will be flagged to indicate that it has been modified.", "security": [ { "ApiToken": [] } ] }, "get": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "conversationid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned conversation ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "commentid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned comment ID.", "x-identifier-source": "TalkLabs ID" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Get Comment by ID", "description": "The comment time stamp is stored in UTC time.\n\n### URL Arguments\n* **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED.\n* **comment_comment_id** : (required) The unique ID of the comment, URL ENCODED.*", "security": [ { "ApiToken": [] } ] }, "post": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "conversationid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned conversation ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "commentid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned comment ID.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateCommentFormModel" } ] }, "example": { "body": "This is a reply.", "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "comment.comment", "id": "5edfe3e686c2921148f12902", "appid": "5ededa7086c2920e6ccc06f8", "conversationid": "demo-conversation-id", "commenttype": "comment", "added": "2020-06-09T19:32:54.9919172Z", "modified": "2020-06-09T19:32:54.9919172Z", "userid": "u-8842", "user": { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "banned": false }, "body": "This is a reply.", "originalbody": "", "hashtags": [], "customtype": "", "customid": "", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "edited": false, "censored": false, "deleted": false, "parentid": "5edfe3da86c2921148f12901", "hierarchy": [ "5edfe3da86c2921148f12901" ], "mentions": [], "reactions": [], "likecount": 0, "replycount": 0, "votecount": 0, "votescore": 0, "votes": [], "moderation": "na", "active": true, "reports": [] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Reply to Comment", "description": "The reply to comment method is the same as the create comment method, except you pass in the ID of the parent comment using the **replyto** field. \nSee **WEBHOOKS SERVICE API** for information on receiving a notification when someone replies to a comment. \nSee documentation on **Create and Publish Comment**\n\n### URL Arguments\n\n- **comment_conversation_id** : (required) The ID of the comment conversation.\n \n- **comment_comment_id** : (required) The unique ID of the comment we will reply to.\n \n\n### BODY Parameters\n\n- **userid** : (required) The application's userid representing the user who submitted the comment\n \n- **body** : (required) The body of the reply (what the user is saying). Supports unicode characters including EMOJIs and international characters.\n \n- **added**: (optional) If this timestamp is provided (in Unix time format, for example 1588106064 (Tue Apr 28 2020 16:34:24 GMT-0400)) then the created timestamp of the conversation is overriden. Use this only to import data.\n \n\n### OPTIONAL BODY Properties to Create or Update a User\n\nIf the user with matching userid does not exist, the user will be created. If the user does exist, that user will be updated with whatever values you provide from this list\n\n- **userid**: _Required_. If the userid is new then the user will be created. If the userid is already in use in the database then the user will be updated.\n \n- **handle**: (Optional) If you are creating a user and you don't specify a handle, the system will generate one for you (using Display Name as basis if you provide that). If you request a handle and it's already in use a new handle will be generated for you and returned. Handle is an easy to type unique identifier for a user, for example @GeorgeWashington could be the handle but Display Name could be \"da prez numero uno\".\n \n- **displayname**: _Optional_. This is the desired name to display, typically the real name of the person.\n \n- **pictureurl**: _Optional_. The URL to the picture for this user.\n \n- **profileurl**: _Optional_. The profileurl for this user.\n \n- **displayname** : (required if creating a new user, otherwise optional) The non-unique name to display when showing the user's name\n \n- **pictureurl** : (optional) A URL to the user's photo\n \n- **profileurl** : (optional) A URL to the user's profile\n \n- **customid** : (optional) 250 characters for a custom ID for your app. This field is indexed for high performance object retrieval.\n \n- **customtype** : (optional) Custom type string.\n \n- **custompayload** : (optional) Custom payload string.\n \n- **customfield1** : (optional) User custom field 1. Store any string value you want here, limit 1024 bytes.\n \n- **customfield2** : (optional) User custom field 2. Store any string value you want here, limit 1024 bytes.\n \n- **customtags** : (optional) A comma delimited list of tags\n \n\n### RESPONSE CODES\n\n- **200 | OK** : Sweet, sweet success.\n \n- **204 | NoContent** : The content was blocked because it contained profanity and filtermode was set to 'block'. Can also be returned if content is too short.\n \n- **400 | BadRequest** : Something is wrong with your request. View response message and errors list for details.\n \n- **403 | Forbidden** : The userid issuing the request is banned from commenting.\n \n- **409 | Conflict** : The customid of your event is already in use.", "security": [ { "ApiToken": [] } ] }, "delete": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "conversationid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned conversation ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "commentid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned comment ID.", "x-identifier-source": "TalkLabs ID" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "The specified comment was permanently deleted.", "errors": {}, "data": { "kind": "delete.comment", "permanentdelete": true, "comment": { "kind": "comment.comment", "id": "5edfe37586c2921148f128fc", "appid": "5ededa7086c2920e6ccc06f8", "conversationid": "demo-conversation-id", "commenttype": "comment", "added": "2020-06-09T19:31:01.5810693Z", "modified": "2020-06-09T19:31:01.5810693Z", "userid": "u-8842", "user": { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "banned": false }, "body": "Hello, World! This is a comment with international characters and emojis. Intl: äöüÄÖÜß | Emojis: 😂🤣❤😍😒", "originalbody": "", "hashtags": [], "customtype": "my-custom-type", "customid": "", "custompayload": "{ num : 0 }", "customtags": [ "taga", "tagb" ], "customfield1": "/sample/userdefined1/emojis/😂🤣❤😍😒", "customfield2": "/sample/userdefined2/intl/characters/äöüÄÖÜß", "edited": false, "censored": false, "deleted": false, "parentid": "", "hierarchy": [], "mentions": [], "reactions": [], "likecount": 0, "replycount": 0, "votecount": 0, "votescore": 0, "votes": [], "moderation": "na", "active": true, "reports": [] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Delete Comment (permanent)", "description": "### URL Arguments\n* **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED.\n* **comment_comment_id** : (required) The unique ID of the comment, URL ENCODED.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/comment/conversations/{conversationid}/comments/{commentid}/setdeleted": { "put": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "conversationid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned conversation ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "commentid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned comment ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "query", "schema": { "type": "string" }, "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" }, { "name": "deleted", "in": "query", "schema": { "type": "boolean" } }, { "name": "permanentifnoreplies", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "The specified comment deleted flag was updated.", "errors": {}, "data": { "kind": "delete.comment", "permanentdelete": false, "comment": { "kind": "comment.comment", "id": "5edfe3e686c2921148f12902", "appid": "5ededa7086c2920e6ccc06f8", "conversationid": "demo-conversation-id", "commenttype": "comment", "added": "2020-06-09T19:32:54.9919172Z", "modified": "2020-06-09T19:35:14.4812684Z", "userid": "u-8842", "user": { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "banned": false }, "body": "(comment deleted)", "originalbody": "", "hashtags": [], "customtype": "", "customid": "", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "edited": false, "censored": false, "deleted": true, "parentid": "5edfe3da86c2921148f12901", "hierarchy": [ "5edfe3da86c2921148f12901" ], "mentions": [], "reactions": [ { "type": "like", "count": 1, "users": [ { "userid": "u-8842", "handle": "dave_m", "displayname": "Dave M." } ] } ], "likecount": 1, "replycount": 0, "votecount": 1, "votescore": 1, "votes": [ { "type": "up", "count": 1, "users": [ { "userid": "u-8842", "handle": "dave_m", "displayname": "Dave M." } ] } ], "moderation": "flagged", "active": false, "reports": [ { "userid": "u-8842", "reason": "abuse" } ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Set Comment Logically Deleted", "description": "* The comment is not actually deleted. The comment is flagged as deleted, and can no longer be read, but replies are not deleted.\n* If flag \"permanentifnoreplies\" is true, then it will be a permanent delete instead of logical delete for this comment if it has no children.\n* If you use \"permanentifnoreplies\" = true, and this comment has a parent that has been logically deleted, and this is the only child, then the parent will also be permanently deleted.\n\n\n### URL Arguments\n* **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED.\n* **comment_comment_id** : (required) The unique ID of the comment, URL ENCODED.\n\n\n### URL Parameters\n* **userid** : (required) This is the application specific user ID of the user deleting the comment. Must be the owner of the comment or authorized moderator.\n* **deleted** : (required) Set to **true** or **false** to flag the comment as deleted. If a comment is deleted, then it will have the deleted field set to true, in which case the contents of the comment should not be shown and the body of the comment will not be returned by the API by default. If a previously deleted comment is undeleted, the flag for deleted is set to false and the original comment body is returned.\n* **permanentifnoreplies**: (optional) If this optional parameter is set to \"true\", then if this comment has no replies it will be permanently deleted instead of logically deleted. If a permanent delete is performed, the result will include the field \"permanentdelete=true\".\n\n\nIf you want to mark a comment as deleted, and replies are still visible, use \"true\" for the logical delete value. If you want to permanently delete the comment and all of its replies, pass false.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/comment/conversations/{conversationid}/comments/{commentid}/react": { "post": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "conversationid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned conversation ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "commentid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned comment ID.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ReactionFormModel" } ] }, "example": { "reaction": "like", "reacted": true, "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "comment.comment", "id": "5edfe3e686c2921148f12902", "appid": "5ededa7086c2920e6ccc06f8", "conversationid": "demo-conversation-id", "commenttype": "comment", "added": "2020-06-09T19:32:54.9919172Z", "modified": "2020-06-09T19:32:54.9919172Z", "userid": "u-8842", "user": { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "banned": false }, "body": "This is a reply.", "originalbody": "", "hashtags": [], "customtype": "", "customid": null, "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "edited": false, "censored": false, "deleted": false, "parentid": "5edfe3da86c2921148f12901", "hierarchy": [ "5edfe3da86c2921148f12901" ], "mentions": [], "reactions": [ { "type": "like", "count": 1, "users": [ { "userid": "u-8842", "handle": "dave_m", "displayname": "Dave M." } ] } ], "likecount": 1, "replycount": 0, "votecount": 0, "votescore": 0, "votes": [], "moderation": "na", "active": true, "reports": [] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "React To Comment", "description": "A reaction can be added using any reaction string that you wish.\n\n### BODY Properties\n\n- **userid** : (required) The ID of the user reacting to the comment. Anonymous reactions are not supported.\n- **reaction** : (required) A string indicating the reaction you wish to capture, for example \"like\", or \"emoji:{id}\" where you can use the standard character code for your emoji.\n- **reacted** : (required) true or false, to toggle the reaction on or off for this user.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/comment/conversations/{conversationid}/react": { "post": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "conversationid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned conversation ID.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ReactionFormModel" } ] }, "example": { "reaction": "like", "reacted": true, "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "comment.comment", "id": "5edfe3e686c2921148f12902", "appid": "5ededa7086c2920e6ccc06f8", "conversationid": "demo-conversation-id", "commenttype": "comment", "added": "2020-06-09T19:32:54.9919172Z", "modified": "2020-06-09T19:32:54.9919172Z", "userid": "u-8842", "user": { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "banned": false }, "body": "This is a reply.", "originalbody": "", "hashtags": [], "customtype": "", "customid": null, "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "edited": false, "censored": false, "deleted": false, "parentid": "5edfe3da86c2921148f12901", "hierarchy": [ "5edfe3da86c2921148f12901" ], "mentions": [], "reactions": [ { "type": "like", "count": 1, "users": [ { "userid": "u-8842", "handle": "dave_m", "displayname": "Dave M." } ] } ], "likecount": 1, "replycount": 0, "votecount": 0, "votescore": 0, "votes": [], "moderation": "na", "active": true, "reports": [] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "React to a conversation", "description": "A conversation context is mapped to your topic by using either the conversationid or the customid. You can either react to the content itself (for example to LIKE an article/video/poll) or you can use the comment react api to react to an individual comment. This method is for commenting on the conversation topic level.\n\n### BODY Properties\n\n- **userid** : (required) The ID of the user reacting to the comment. Anonymous reactions are not supported.\n- **reaction** : (required) A string indicating the reaction you wish to capture, for example \"like\", or \"emoji:{id}\" where you can use the standard character code for your emoji.\n- **reacted** : (required) true or false, to toggle the reaction on or off for this user.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/comment/conversations/{conversationid}/comments/{commentid}/vote": { "post": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "conversationid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned conversation ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "commentid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned comment ID.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/VoteFormModel" } ] }, "example": { "vote": "up", "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "comment.comment", "id": "5edfe3e686c2921148f12902", "appid": "5ededa7086c2920e6ccc06f8", "conversationid": "demo-conversation-id", "commenttype": "comment", "added": "2020-06-09T19:32:54.9919172Z", "modified": "2020-06-09T19:32:54.9919172Z", "userid": "u-8842", "user": { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "banned": false }, "body": "This is a reply.", "originalbody": "", "hashtags": [], "customtype": "", "customid": null, "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "edited": false, "censored": false, "deleted": false, "parentid": "5edfe3da86c2921148f12901", "hierarchy": [ "5edfe3da86c2921148f12901" ], "mentions": [], "reactions": [ { "type": "like", "count": 1, "users": [ { "userid": "u-8842", "handle": "dave_m", "displayname": "Dave M." } ] } ], "likecount": 1, "replycount": 0, "votecount": 1, "votescore": 1, "votes": [ { "type": "up", "count": 1, "users": [ { "userid": "u-8842", "handle": "dave_m", "displayname": "Dave M." } ] } ], "moderation": "na", "active": true, "reports": [] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Vote on Comment", "description": "### URL Arguments\n* **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED.\n* **comment_comment_id** : (required) The unique ID of the comment, URL ENCODED.\n \n### BODY Properties\n* **vote** : (required) Must be one of \"*up*\", \"*down*\", or \"none\" (empty value). If up, the comment receives an upvote. If down, the comment receives a down vote. If empty, the vote is removed.\n* **userid** : (required) The application specific user id performing the action.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/comment/conversations/{conversationid}/comments/{commentid}/report": { "post": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned conversation ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned comment ID.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ReportFormModel" } ] }, "example": { "reportType": {}, "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "comment.comment", "id": "5edfe3e686c2921148f12902", "appid": "5ededa7086c2920e6ccc06f8", "conversationid": "demo-conversation-id", "commenttype": "comment", "added": "2020-06-09T19:32:54.9919172Z", "modified": "2020-06-09T19:32:54.9919172Z", "userid": "u-8842", "user": { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "banned": false }, "body": "This is a reply.", "originalbody": "", "hashtags": [], "customtype": "", "customid": null, "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "edited": false, "censored": false, "deleted": false, "parentid": "5edfe3da86c2921148f12901", "hierarchy": [ "5edfe3da86c2921148f12901" ], "mentions": [], "reactions": [ { "type": "like", "count": 1, "users": [ { "userid": "u-8842", "handle": "dave_m", "displayname": "Dave M." } ] } ], "likecount": 1, "replycount": 0, "votecount": 1, "votescore": 1, "votes": [ { "type": "up", "count": 1, "users": [ { "userid": "u-8842", "handle": "dave_m", "displayname": "Dave M." } ] } ], "moderation": "flagged", "active": false, "reports": [ { "userid": "u-8842", "reason": "abuse" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Report Comment", "description": "### URL Arguments\n\n- **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED.\n \n- **comment_comment_id** : (required) The unique ID of the comment, URL ENCODED.\n \n\n### BODY Parameters\n\n- **userid** : (required) This is the application specific user ID of the user reporting the comment.\n \n- **reporttype:** (required) This is the classification of the reported post. It must be one of the below values (note that 'false' represents information considered false by the reporter:\n \n - abuse\n \n - spam\n \n - selfharm\n \n - hate\n \n - violence\n \n - harassment\n \n - nudity\n \n - illegal\n \n - false\n \n - other", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/comment/conversations/{conversationid}/comments/{commentid}/flag": { "post": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned conversation ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned comment ID.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ReportFormModel" } ] }, "example": { "reportType": {}, "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "comment.comment", "id": "666ee62cae246d237ad3f1d1", "appid": "662bb49bf10e9a26a7e8ed92", "conversationid": "api-conversation-demo1", "commenttype": "comment", "added": "2024-06-16T13:18:36.2221886Z", "modified": "2024-06-16T13:18:36.2216101Z", "tsunix": 1718543916, "userid": "u-8842", "user": { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Thomas Jefferson", "pictureurl": "", "profileurl": "", "role": "admin", "customtags": [ "taga", "tagb" ], "banned": false, "banexpires": "0001-01-01T00:00:00Z", "shadowbanned": false, "shadowbanexpires": "0001-01-01T00:00:00Z", "muted": false, "muteexpires": "0001-01-01T00:00:00Z", "moderation": "na", "reports": [] }, "body": "Hello, World! This is a comment with international characters and emojis. Intl: äöüÄÖÜß | Emojis: 😂🤣❤😍😒", "originalbody": "", "hashtags": [], "shadowban": false, "customtype": "my-custom-type", "customid": null, "custompayload": "{ num : 0 }", "customtags": [ "taga", "tagb" ], "customfield1": "/sample/userdefined1/emojis/😂🤣❤😍😒", "customfield2": "/sample/userdefined2/intl/characters/äöüÄÖÜß", "edited": false, "censored": false, "deleted": false, "parentid": "", "hierarchy": [], "mentions": [], "reactions": [], "likecount": 0, "replycount": 0, "votecount": 0, "votescore": 0, "votes": [], "moderation": "flagged", "active": false, "reports": [] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Flag Comment", "description": "This operation immediately sets a comment to the flagged state. It is intended for use by moderators who are human or AI. This API doesn't take into consideration the report limit of the conversation, or the history of the comment, it immediately sets it to flagged.\n\n### URL Arguments\n\n- **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED.\n \n- **comment_comment_id** : (required) The unique ID of the comment, URL ENCODED.\n \n\n### BODY Parameters\n\n- **reporttype:** (\"abuse\" or \"spam\")\n \n- **userid** : (optional) This is the application specific user ID of the user reporting the comment.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/comment/conversations/{conversationid}/reset": { "post": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned conversation ID.", "x-identifier-source": "TalkLabs ID" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "The specified conversation and all comments were permanently deleted.", "errors": {}, "data": { "kind": "delete.conversation", "conversationid": "api-conversation-demo1", "userid": null, "deletedconversations": 1, "deletedcomments": 17 } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Reset Conversation", "description": "## CANNOT BE UNDONE. This deletes all history of a conversation including all comments and replies within it.\n\n### URL Arguments\n\n- **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/comment/conversations/{conversationid}/comments/{commentid}/replies": { "get": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "conversationid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned conversation ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "commentid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned comment ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "sort", "in": "query", "schema": { "type": "string", "default": "oldest" } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "default": "" }, "description": "The cursor returned by the previous page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 200 }, "description": "The maximum number of records to return." }, { "name": "direction", "in": "query", "schema": { "type": "string", "default": "forward" } }, { "name": "includechildren", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "includeinactive", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "filterpostedbyuserid", "in": "query", "schema": { "type": "string", "default": "" }, "x-identifier-source": "customer-defined" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "list.comments", "cursor": "637273279749919172", "more": false, "itemcount": 1, "conversation": { "kind": "comment.conversation", "appid": "5ededa7086c2920e6ccc06f8", "owneruserid": "", "conversationid": "demo-conversation-id", "property": "sportstalk247.com/apidemo", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "title": "Sample Conversation", "maxcommentlen": 512, "commentcount": 2, "open": true, "added": "2020-06-09T19:32:28.6308249Z", "whenmodified": "2020-06-09T19:32:28.6308249Z", "customtype": "", "customid": "/articles/2020-03-01/article1/something-very-important-happened", "customtags": [ "taga", "tagb" ], "custompayload": "{ num : 0 }", "customfield1": "/sample/userdefined1/emojis/😂🤣❤😍😒", "customfield2": "/sample/userdefined2/intl/characters/äöüÄÖÜß" }, "comments": [ { "kind": "comment.comment", "id": "5edfe3e686c2921148f12902", "appid": "5ededa7086c2920e6ccc06f8", "conversationid": "demo-conversation-id", "commenttype": "comment", "added": "2020-06-09T19:32:54.9919172Z", "modified": "2020-06-09T19:32:54.9919172Z", "userid": "u-8842", "user": { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "banned": false }, "body": "This is a reply.", "originalbody": "", "hashtags": [], "customtype": "", "customid": "", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "edited": false, "censored": false, "deleted": false, "parentid": "5edfe3da86c2921148f12901", "hierarchy": [ "5edfe3da86c2921148f12901" ], "mentions": [], "reactions": [], "likecount": 0, "replycount": 0, "votecount": 0, "votescore": 0, "votes": [], "moderation": "na", "active": true, "reports": [] } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Replies", "description": "This method works the same way as the **List Comments** method, so view the documentation on that method. The difference is that this method will filter to only include comments that have a parent.\n\n## GETTING THE RIGHT COMMENTS\n\n- If you use ListComments you will get the top level comments.\n \n- If you use List Replies you will get comments that are children of another comment.\n \n- If you want all replies lower in the tree of comments than the current level use the includechildren property.\n \n\n## READ THIS - ABOUT CURSORING WITH OFFSET CURSORS\n\n- The maximum limit value for the request depends on your account. In general, its best to use a lower limit and make multiple calls as users scroll through your application for fastest performance. However for exporting data or reporting purposes, a larger number with fewer requests is better.\n \n- If you use a cursoring method that is offset based (likes/votescore/mostreplies) rather than time based (oldest/newest) you are not guaranteed to see all of the comments. This is because the original query runs, and returs the comments ordered by your query. But, if you then send another request with a cursor value to get the next bunch, the cursor skips over the first set of results equal to the limit size in the query and returns the next set. So if you change your limit size or the underlying data changes because people react, vote, and like things, then you may not get a perfect results set. It is recommended that you request the top N records in one shot, as long as the request isn't too large. Otherwise, use cursoring with oldest sort method to download the entire list of comments and sort it yourself.\n \n\n### ABOUT CURSORING\n\n- API Method returns a cursor\n \n- Cursor includes a \"more\" field indicating if there are more results that can be read at the time this call is made\n \n- Cursor includes \"cursor\" field, which can be passed into subsequent calls to this method to get additionaal results\n \n- Cursor includes \"itemcount\" field, which is the number of items returned by the cursor not the total number of items in the database\n \n- All LIST methods in the API return cursors and they all work the same way\n \n\n### URL Arguments\n\n- **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED.\n \n\n### URL Parameters\n\n- **cursor** : (optional) If provided, will get the next bundle of comments in the conversation resuming from where the cursor left off.\n \n- **limit** : (Optional, default = 200). For cursoring, limit the number of responses for this request.\n \n- **direction**: (optional) Default is forward. Must be **forward** or **backward**\n \n- **sort** : (optional, defaults to \"oldest\") Specifies that sort should be done by...\n - **oldest** : Sort by when added ascending (oldest on top)\n \n - **newest** : Sort by when added ascending (newest on top)\n \n - **likes** : Sort by number of likes, descending (most liked on top)\n \n - **votescore** : Sort by net of adding upvotes and subtracting downvotes, descending\n \n - **mostreplies** : Sort by number of replies,descending\n \n- **includechildren** : (optional, default is false) If false, this returns all reply nodes that are immediate children of the provided parent id. If true, it includes all replies under the parent id and all the children of those replies and so on.\n \n- **includeinactive** : (optional, default is false) If true, return comments that are inactive (for example, disabled by moderation)\n \n- **filterpostedbyuserid**: (optional) If provided, the list returned will be filtered to only include comments published by the specified userid.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/comment/conversations/{conversationid}/repliesbyparentidbatch": { "get": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "conversationid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned conversation ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "childlimit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 20 } }, { "name": "parentids", "in": "query", "schema": { "type": "string" } }, { "name": "includeinactive", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "list.repliesbyparentid", "repliesgroupedbyparentid": [ { "kind": "list.commentreplygroup", "parentid": "5edee591f20111684c4be050", "comments": [ { "kind": "comment.comment", "id": "5edee626f20111684c4be051", "appid": "5ecdcfeff201110974822623", "conversationid": "some-random-convo-id", "commenttype": "comment", "added": "2020-06-09T01:30:14.8220404Z", "modified": "2020-06-09T01:30:14.8220404Z", "userid": "u-8842", "user": { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "banned": false }, "body": "This is a reply.", "originalbody": "", "hashtags": [], "customtype": "", "customid": "", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "edited": false, "censored": false, "deleted": false, "parentid": "5edee591f20111684c4be050", "hierarchy": [ "5edee591f20111684c4be050" ], "mentions": [], "reactions": [], "likecount": 0, "replycount": 0, "votecount": 0, "votescore": 0, "votes": [], "moderation": "na", "active": true, "reports": [] }, { "kind": "comment.comment", "id": "5edfbf0ef201112b68be197d", "appid": "5ecdcfeff201110974822623", "conversationid": "some-random-convo-id", "commenttype": "comment", "added": "2020-06-09T16:55:42.1891024Z", "modified": "2020-06-09T16:55:42.1891024Z", "userid": "u-8842", "user": { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "banned": false }, "body": "This is a reply.", "originalbody": "", "hashtags": [], "customtype": "", "customid": "", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "edited": false, "censored": false, "deleted": false, "parentid": "5edee591f20111684c4be050", "hierarchy": [ "5edee591f20111684c4be050" ], "mentions": [], "reactions": [], "likecount": 0, "replycount": 0, "votecount": 0, "votescore": 0, "votes": [], "moderation": "na", "active": true, "reports": [] } ] } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Replies Batch", "description": "The purpose of this method is to support a use case where you open an app or website widget and you have just displayed up to N top level comments and you want to retrieve the replies to those comments quickly, in 1 request.\nYou could call GetReplies for each top level parent, but if you want to get them in just one request use this method, which has more speed but some limitations:\n* This method does not support cursoring.\n* This method allows you to specify the maximum number of children to return per top level parent, but it does not apply a limit across the total number of replies across all of the top level comments.\n* This method will always return replies sorted by when originally published timestamp ascending (oldest to newest), with replies grouped by each parent comment in the result set.\n* This method will return the children that are direct immediate child replies to the parent only, not an entire tree under a parent.\n* If the parentid list contains a parentid that does not exist or has no child replies it will be skipped, you will not receive 404 unless none of the parentids were found.\n\n### URL Arguments\n* **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED.\n\n### URL Parameters\n* **childlimit** : (Optional, default = 50). \n* **parentids** : (Required). A comma delimited list of parentids, up to 30.\n* **includeinactive** : (Optional, default = false) If true, replies that are flagged or rejected by a moderator are excluded from results. Set it to false to receive rejected and flagged replies.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/comment/find/conversation/bycustomid": { "get": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "CustomId", "in": "query", "schema": { "type": "string" }, "description": "A customer-defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID.", "x-identifier-source": "customer-defined" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "comment.conversation", "appid": "5e9389ed38a2b10794e271ee", "owneruserid": null, "conversationid": "my_conversation_id", "property": "sportstalk247.com/apidemo", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "title": "Sample Conversation", "maxcommentlen": 512, "commentcount": 1, "open": true, "added": 1587437568, "whenmodified": 1587438787, "customtype": "", "customid": "/articles/2020-03-01/article1/something-very-important-happened", "customtags": [ "taga", "tagb" ], "custompayload": "{ num : 0 }", "customfield1": "/sample/userdefined1/emojis/😂🤣❤😍😒", "customfield2": "/sample/userdefined2/intl/characters/äöüÄÖÜß" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Find a conversation by custom ID", "description": "Uses the CustomID for the conversation supplied by the app to retrieve the conversation object. It returns exactly one object or 404 if not found. This query is covered by an index and is performant.\n\n### URL Parameters\n* **customid** : (Required) Locates a conversation using the custom ID.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/comment/moderation/queues/comments": { "get": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" }, "description": "The maximum number of records to return." }, { "name": "conversationId", "in": "query", "schema": { "type": "string" }, "description": "The TalkLabs-assigned conversation ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The cursor returned by the previous page." }, { "name": "filterModerationState", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/ModerationStates" } ] } }, { "name": "filterKeyword", "in": "query", "schema": { "type": "string", "default": "" } }, { "name": "filterUserid", "in": "query", "schema": { "type": "string", "default": "" }, "x-identifier-source": "customer-defined" }, { "name": "filterHandle", "in": "query", "schema": { "type": "string", "default": "" } }, { "name": "filterTag", "in": "query", "schema": { "type": "string", "default": "" } }, { "name": "filterHashtag", "in": "query", "schema": { "type": "string", "default": "" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "list.comments", "cursor": "5e9e65f138a285193496316b", "more": false, "conversation": null, "comments": [ { "kind": "comment.comment", "id": "5e9e65f138a285193496316b", "appid": "5e9389ed38a2b10794e271ee", "conversationid": "my_conversation_id", "commenttype": "comment", "added": 1587439089, "modified": 1587439089, "userid": "u-8842", "user": { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "banned": false }, "body": "Hello, World! This is a comment with international characters and emojis. Intl: äöüÄÖÜß | Emojis: 😂🤣❤😍😒", "hashtags": [], "customtype": "my-custom-type", "customid": "/articles/2020-03-01/article1/something-very-important-happened", "custompayload": "{ num : 0 }", "customtags": [ "taga", "tagb" ], "customfield1": "/sample/userdefined1/emojis/😂🤣❤😍😒", "customfield2": "/sample/userdefined2/intl/characters/äöüÄÖÜß", "edited": false, "deleted": false, "parentid": "", "hierarchy": [], "mentions": [], "reactions": [ { "type": "like", "count": 0, "users": [] } ], "likecount": 0, "replycount": 0, "votecount": 0, "votescore": 0, "votes": [], "moderation": "flagged", "active": false, "reports": [ { "userid": "u-8842", "reason": "abuse" } ] } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Comments in Moderation Queue", "description": "_This method requires authentication._\n\n* *limit*: (optional) Defaults to 200. This limits how many messages to return from the queue\n* *conversationid*: (optional) Provide the ConversationID for a room to filter for only the queued events for a specific room\n* *cursor*: (optional) Provide cursor value to get the next page of results.\n* *filterHandle*: (optional) Filters using exact match for a handle of a user\n* *filterKeyword*: (optional) Filters using substring search for your string\n* *filterModerationState*: (optional) Filters for comments in the specified moderation state.\n * approved: Moderator approved the comment\n * rejected: Moderator rejected the comment\n * pending: A new comment was posted to a premoderation room, and is pending review, but was never reported as abuse\n * flagged: Enough users reported the comment that it is in the flagged state and sent to moderation queue", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/comment/moderation/queues/comments/{commentid}/applydecision": { "post": { "tags": [ "CommentApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "commentid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned comment ID.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ModerateEventFormModel" } ] }, "example": { "approve": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Apply a comment moderation decision", "description": "If PRE-MODERATION is enabled for a conversation, then all messages go to the queue before they can appear in the conversation. For each incomming message, a webhook will be fired, if one is configured. \n\nIf the conversation is set to use POST-MODERATION, messages will only be sent to the moderation queue if they are reported.\n\n# BODY PROPERTIES\n* **approve** : (required) Pass **true** to approve the comment or **false** to reject the comment.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/monitor": { "get": { "tags": [ "MonitorApi" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Check API availability", "description": "When this function is invoked it checks that the API is in a healthy state. Do not invoke more than once every 5 minutes as a best practice because it causes API to do database checks.", "security": [] } }, "/api/v3/version": { "get": { "tags": [ "MonitorApi" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Get the API version", "description": "When this function is invoked it checks that the API is in a healthy state. Do not invoke more than once every 5 minutes as a best practice because it causes API to do database checks.", "security": [] } }, "/api/v3/{appid}/poll/poll/create": { "post": { "tags": [ "PollApi" ], "summary": "Create or Update Poll", "description": "Use this method to create a new poll. If you create a poll with a customID, you can call this method again to update the poll, passing in the same customID. However, if you provide a customID and that is in use already by another poll, you will get an error response.\n\nWhen creating a poll, provide the desired values. When updating an existing poll, only provide the values to overwrite. To delete a value, pass an empty string.\n\n#### METADATA\n\n- **ownerid**: (required) The userid of the owner of the poll\n \n\n#### DISPLAY PROPERTIES\n\n- **title**: (required) The title of the poll. Required on create. Optional on update.\n \n- **description**: (optional) The description of the poll\n \n- **pictureurl**: (optional) The URL for a picture for the room\n \n- **embedcontenttop**: (optional) Content to be displayed at the top of the poll\n \n- **embedcontentbottom**: (optional) Content to be displayed at the bottom of the poll\n \n- **displayresults**: (optional) \\[default=\"aftervote\"/always/pollclosed\\] Use \"aftervote\" to display results after a vote is over. Set to \"always\" to return current standings. Set to \"pollclosed\" to only allow poll results to be disclosed when the poll is closed.\n \n- **sortchoices**: (optional, \"random\" or \"asconfigured\", default = \"asconfigured\") When retrieving the list of response choices they can be displayed in the order you specified or in random order.\n \n\n#### BEHAVIOR SETTINGS\n\n- **allowanonymouspolling:** (optional, default=false), if true, allows users to submit responses without a userid value.\n \n- **allowmultiplechoicesperuser**: (\"true\" or default = \"false\") If true, the user may submit answers for more than one choice.\n \n- **maxtotalresponsesperuser**: (default = 1). This is the number of times that a user can respond to the poll, the total of all responses regardless of which choice was selected.\n \n- **maxresponsesperchoiceperuser**: (default = 1). The maximum time a user may submit a response per choice. For example you can make it so the user can respond 3 times but must select a different choice with each response, or you could allow the user to vote as many times as desired per choice with all their available responses.\n \n\n#### AUTO PUBLISH SETTINGS\n\n- **whenpollpublish**: (optional) \\[default=now\\] An ISO-8601 date time. Now by default. If specified, poll is hidden until the specified date and time.\n \n- **whenpollexpires**: (optional) \\[default=null\\] An ISO-8601 date time. If specified, the poll transitions to the expired state at this time and is no longer returned by the API (It only exists as archived data).\n \n- **whenpollopens**: (optional) \\[default=now\\] An ISO-8601 date time. Now by default. If specified, poll is not open until this time and no one can respond until then.\n \n- **whenpollcloses**: (optional) \\[default=null\\] An ISO-8601 date time. Null by default. If specified, poll transitions to closed state at this time and doesn't accept responses.\n \n\n#### LEAD CAPTURE\n\n- **leadcaptureenabled**: (optional, default=false) If true, enables lead capture for the poll.\n \n- **leadcapturerequired**: (optional, default=false) If true, makes lead capture required for the poll.\n \n- **leadcapturename**: (optional) If true, captures the name of the lead.\n \n- **leadcapturetitle**: (optional) The title for the lead capture form.\n \n- **leadcapturedescription**: (optional) The description for the lead capture form.\n \n- **leadcaptureprompt**: (optional) The prompt for the lead capture form.\n \n\n#### SOCIAL SHARE\n\n- **socialshareenable**: (optional, default=false) If true, enables social sharing for the poll.\n \n- **socialhandlefacebook**: (optional) The Facebook handle for social sharing.\n \n- **socialhandlex**: (optional) The X (formerly Twitter) handle for social sharing.\n \n- **socialhandletiktok**: (optional) The TikTok handle for social sharing.\n \n- **socialhandlewhatsapp**: (optional) The WhatsApp handle for social sharing.\n \n- **socialcardtitle**: (optional) The title for the social card.\n \n- **socialcardimageurl**: (optional) The image URL for the social card.\n \n- **socialcardurl**: (optional) The URL for the social card.\n \n\n#### CUSTOM FIELDS\n\n- **customid**: (optional) A customid for the room. Can be unused, or a unique key. If provided, and a poll with that customid is already created this call will update the existing poll.\n \n- **customtype** : (optional) Custom type string.\n \n- **custompayload** : (optional) Custom payload string.\n \n- **customfield1** : (optional) User custom field 1. Store any string value you want here, limit 1024 bytes.\n \n- **customfield2** : (optional) User custom field 2. Store any string value you want here, limit 1024 bytes.\n \n- **customtags** : (optional) A comma delimited list of tags", "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PollCreateOrUpdateFormModel" } ] }, "example": { "title": "What is your favorite color?", "description": "Vote for your favorite color" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "poll.poll", "id": "662da20fe45ad80a7f2bd950", "appid": "662bb49bf10e9a26a7e8ed92", "ownerid": "u-8842", "title": "Sample Poll 1: Vote for your favorite color", "description": "Vote for your favorite color", "posterurl": "", "embedcontenttop": "", "embedcontentbotton": "", "whenpollpublish": "2024-04-28T01:10:39.5358368Z", "whenpollopens": "2024-04-27T21:10:39.5358872-04:00", "whenpollcloses": null, "whenpollexpires": null, "displayresults": 1, "sortanswers": 0, "customtype": "", "customid": "sample-poll-1-vote", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/poll/poll/{pollid}/update": { "put": { "tags": [ "PollApi" ], "summary": "Update Poll", "description": "_This method requires authentication._\n\nWhen creating a poll, provide the desired values. When updating an existing poll, only provide the values to overwrite. To delete a value, pass an empty string.\n\n#### METADATA\n\n\\* **ownerid**: (required) The userid of the owner of the poll\n\n#### DISPLAY PROPERTIES\n\n\\* **title**: (required) The title of the poll. Required on create. Optional on update. \n\\* **description**: (optional) The description of the poll \n\\* **pictureurl**: (optional) The URL for a picture for the room \n\\* **embedcontenttop**: (optional) Content to be displayed at the top of the poll \n\\* **embedcontentbottom**: (optional) Content to be displayed at the bottom of the poll \n\\* **displayresults**: (optional) \\[default=\"aftervote\"/always/pollclosed\\] Use \"aftervote\" to display results after a vote is over. Set to \"always\" to return current standings. Set to \"pollclosed\" to only allow poll results to be disclosed when the poll is closed. \n\\* **sortchoices**: (optional, \"random\" or \"asconfigured\", default = \"asconfigured\") When retrieving the list of response choices they can be displayed in the order you specified or in random order.\n\n#### BEHAVIOR SETTINGS\n\n\\* **allowmultiplechoicesperuser**: (\"true\" or default = \"false\") If true, the user may submit answers for more than one choice. \n\\* **maxtotalresponsesperuser**: (default = 1). This is the number of times that a user can respond to the poll, the total of all responses regardless of which choice was selected. \n\\* **maxresponsesperchoiceperuser**: (default = 1). The maximum time a user may submit a response per choice. For example you can make it so the user can respond 3 times but must select a different choice with each response, o ryou could allow the user to vote as many times as desired per choice with all their available responses.\n\n#### AUTO PUBLISH SETTINGS\n\n\\* **whenpollpublish**: (optional) \\[default=now\\] An ISO-8601 date time. Now by default. If specified, poll is hidden until the specified date and time. \n\\* **whenpollexpires**: (optional) \\[default=null\\] An ISO-8601 date time. If specified, the poll transitions to the expired state at this time and is no longer returned by the API (It only exists as archived data). \n\\* **whenpollopens**: (optional) \\[default=now\\] An ISO-8601 date time. Now by default. If specified, poll is not open until this time and no one can respond until then. \n\\* **whenpollcloses**: (optional) \\[default=null\\] An ISO-8601 date time. Null by default. If specified, poll transitions to closed state at this time and doesn't accept responses.\n\n#### CUSTOM FIELDS\n\n\\* **customid**: (optional) A customid for the room. Can be unused, or a unique key. If provided, and a poll with that customid is already created this call will update the existing poll. \n\\* **customtype** : (optional) Custom type string. \n\\* **custompayload** : (optional) Custom payload string. \n\\* **customfield1** : (optional) User custom field 1. Store any string value you want here, limit 1024 bytes. \n\\* **customfield2** : (optional) User custom field 2. Store any string value you want here, limit 1024 bytes. \n\\* **customtags** : (optional) A comma delimited list of tags", "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "pollid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned poll ID.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PollCreateOrUpdateFormModel" } ] }, "example": { "title": "What is your favorite color?", "description": "Vote for your favorite color" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "poll.poll", "id": "662da20fe45ad80a7f2bd950", "appid": "662bb49bf10e9a26a7e8ed92", "ownerid": "u-8842", "title": "Sample Poll 1: Vote for your favorite color", "description": "Vote for your favorite color", "posterurl": "", "embedcontenttop": "", "embedcontentbotton": "", "whenpollpublish": "2024-04-28T01:10:39.5358368Z", "whenpollopens": "2024-04-27T21:10:39.5358872-04:00", "whenpollcloses": null, "whenpollexpires": null, "displayresults": 1, "sortanswers": 0, "customtype": "", "customid": "sample-poll-1-vote", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/poll/poll/{pollid}/choice": { "post": { "tags": [ "PollApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "pollid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned poll ID.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PollChoiceCreateOrUpdateFormModel" } ] }, "example": { "position": -1, "title": "Red" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": [ { "kind": "poll.choice", "id": "662da22ee45ad80a7f2bd951", "appid": "662bb49bf10e9a26a7e8ed92", "pollid": "662da20fe45ad80a7f2bd950", "position": 0, "title": "Red", "imageurl": "", "videoid": "", "embedcode": "", "customtype": "", "customid": "", "custompayload": "", "customtags": null, "customfield1": "", "customfield2": "" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Create or Update Choice", "description": "_This method requires authentication._\n\nUse this method to create or update a poll choice. This method will return all choices with their positions updated so that they can be displayed correctly in an editor. When utilizing random sort order, that will be applied when requesting the poll details\n\n\\* **id**: (optional) If specified, the poll choice with this ID will be updated \n\\* **position**: (optional, default = -1) The position of the choice in the list of choices. By default a new choice is added to the end of the list of choices. If you specify a position, the choice is moved to that position and any other choices there or after that position are moved up one position index. \n\\* **title**: (optional) This is the text displayed with the choice. \n\\* **imageurl**: (optional) You can use this field to set the URL for an image \n\\* **videoid**: (optional) A field to store the ID of a video \n\\* **embedcode**: (optional) Store content that can be used to display the choice. \n\\* **vidoeurl**: (optional) This field may be used to store the URL for a video \n\\* **customid**: (optional) A customid for the room. Can be unused, or a unique key. \n\\* **customtype** : (optional) Custom type string. \n\\* **custompayload** : (optional) Custom payload string. \n\\* **customfield1** : (optional) User custom field 1. Store any string value you want here, limit 1024 bytes. \n\\* **customfield2** : (optional) User custom field 2. Store any string value you want here, limit 1024 bytes. \n\\* **customtags** : (optional) A comma delimited list of tags \n\\* **private:** (false | optional) If set to true a user cannot join this room unless explicitly granted with a call to the Set User Permission API.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/poll/poll": { "get": { "tags": [ "PollApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "IncludeUnpublished", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 200 }, "description": "The maximum number of records to return." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The cursor returned by the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "list.poll.responses", "cursor": "", "more": false, "itemcount": 1, "choices": [ { "kind": "poll.poll", "id": "663fae9abe2ce30d3d6c428c", "appid": "662bb49bf10e9a26a7e8ed92", "ownerid": "u-8842", "title": "Which is the best model of the show?", "description": "Vote for your favorite model", "posterurl": "", "embedcontenttop": "", "embedcontentbotton": "", "whenpollpublish": "2024-05-11T17:44:58.705Z", "whenpollopens": "2024-05-11T17:44:58.705Z", "whenpollcloses": "9999-12-31T23:59:59.9999999Z", "whenpollexpires": "9999-12-31T23:59:59.9999999Z", "displayresults": 1, "sortchoices": 0, "maxtotalresponsesperuser": 10, "allowmultiplechoicesperuser": true, "maxvotesperchoiceperuser": 5, "customtype": "", "customid": "miamitape-atlsw-2024", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Polls", "description": "_This method requires authentication._\n\nRooms can be public or private. This method lists all public rooms that everyone can see.\n\n- **cursor** : (optional) The first time you call list rooms, omit this property to start from the beginning. Call the method again passing in the value returned in the cursor field of the response to get the next page of results. If there are more results available, more will be true.\n \n- **limit** : (optional) Specify the number of items to return. Default is 200.\n \n- **includeUnpublished**: (optional: false). If set to true, the function will include polls that are not yet published. Requires createpoll permission.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/poll/poll/{pollid}/choices": { "get": { "tags": [ "PollApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "pollid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned poll ID.", "x-identifier-source": "TalkLabs ID" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": [ { "kind": "poll.choice", "id": "662da22ee45ad80a7f2bd951", "appid": "662bb49bf10e9a26a7e8ed92", "pollid": "662da20fe45ad80a7f2bd950", "position": 0, "title": "Red", "imageurl": "", "videoid": "", "embedcode": "", "customtype": "", "customid": "", "custompayload": "", "customtags": null, "customfield1": "", "customfield2": "" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Choices for Poll", "description": "_This method requires authentication._\n\nRooms can be public or private. This method lists all public rooms that everyone can see.\n* **cursor** : (optional) The first time you call list rooms, omit this property to start from the beginning. Call the method again passing in the value returned in the cursor field of the response to get the next page of results. If there are more results available, more will be true.\n* **limit** : (optional) Specify the number of items to return. Default is 200.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/poll/poll/{pollid}": { "get": { "tags": [ "PollApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "pollid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned poll ID.", "x-identifier-source": "TalkLabs ID" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "poll.details", "poll": { "kind": "poll.poll", "id": "662da6fbe37d2e9ac76a562b", "appid": "662bb49bf10e9a26a7e8ed92", "ownerid": "u-8842", "title": "Sample Poll 1: Vote for your favorite color", "description": "Vote for your favorite color", "posterurl": "", "embedcontenttop": "", "embedcontentbotton": "", "whenpollpublish": "2024-04-28T01:31:39.262Z", "whenpollopens": "2024-04-28T01:31:39.262Z", "whenpollcloses": null, "whenpollexpires": null, "displayresults": 1, "sortanswers": 0, "customtype": "", "customid": "sample-poll-1-vote", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "" }, "choices": [] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Get Poll Details", "description": "_This method requires authentication._\n\nFetches the poll, choices and optionally can return standing / results depending on state of the poll.\n\n- **id**: (required) The ID of the poll to fetch.\n \n- **entities:** (optional = \"poll\"). Provide \"poll\", \"choices\", or \"results\" to get the desired data.", "security": [ { "ApiToken": [] } ] }, "delete": { "tags": [ "PollApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "pollid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned poll ID.", "x-identifier-source": "TalkLabs ID" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "poll.poll", "id": "662da20fe45ad80a7f2bd950", "appid": "662bb49bf10e9a26a7e8ed92", "ownerid": "u-8842", "title": "Sample Poll 1: Vote for your favorite color", "description": "Vote for your favorite color", "posterurl": "", "embedcontenttop": "", "embedcontentbotton": "", "whenpollpublish": "2024-04-28T01:10:39.5358368Z", "whenpollopens": "2024-04-27T21:10:39.5358872-04:00", "whenpollcloses": null, "whenpollexpires": null, "displayresults": 1, "sortanswers": 0, "customtype": "", "customid": "sample-poll-1-vote", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Delete Poll", "description": "_This method requires authentication._\n\nWhen creating a poll, provide the desired values. When updating an existing poll, only provide the values to overwrite. To delete a value, pass an empty string.\n\n#### URL PARAMETERS\n\n\\* **pollid**: (required) The ID of the poll to delete", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/poll/pollbycustomid/{customid}": { "get": { "tags": [ "PollApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "customid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A customer-defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID.", "x-identifier-source": "customer-defined" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "poll.details", "poll": { "kind": "poll.poll", "id": "662da6fbe37d2e9ac76a562b", "appid": "662bb49bf10e9a26a7e8ed92", "ownerid": "u-8842", "title": "Sample Poll 1: Vote for your favorite color", "description": "Vote for your favorite color", "posterurl": "", "embedcontenttop": "", "embedcontentbotton": "", "whenpollpublish": "2024-04-28T01:31:39.262Z", "whenpollopens": "2024-04-28T01:31:39.262Z", "whenpollcloses": null, "whenpollexpires": null, "displayresults": 1, "sortanswers": 0, "customtype": "", "customid": "sample-poll-1-vote", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "" }, "choices": [] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Get a poll by custom ID", "description": "_This method requires authentication._\n\nFetches the poll, choices and optionally can return standing / results depending on state of the poll.\n\n- **customid**: (required) The customid of the poll to fetch.\n \n- **entities:** (optional = \"poll\"). Provide \"poll\", \"choices\", or \"results\" to get the desired data.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/poll/poll/{pollid}/response": { "post": { "tags": [ "PollApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "pollid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned poll ID.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PollCreateResponseFormModel" } ] }, "example": { "choiceId": "", "pollID": "poll-id" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "poll.poll", "id": "662da20fe45ad80a7f2bd950", "appid": "662bb49bf10e9a26a7e8ed92", "ownerid": "u-8842", "title": "Sample Poll 1: Vote for your favorite color", "description": "Vote for your favorite color", "posterurl": "", "embedcontenttop": "", "embedcontentbotton": "", "whenpollpublish": "2024-04-28T01:10:39.5358368Z", "whenpollopens": "2024-04-27T21:10:39.5358872-04:00", "whenpollcloses": null, "whenpollexpires": null, "displayresults": 1, "sortanswers": 0, "customtype": "", "customid": "sample-poll-1-vote", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Create Poll Response (Cast a vote)", "description": "_This method requires authentication._\n\nUse thsi method to respond to a poll or cast a vote.\n\n\\* **pollid**: (required) The id of the poll \n\\* **userid**: (required) The id of the user responding \n\\* **choiceid**: (optional) The selected choice \n| Response Code | Description | \n|---------------|--------------------------------------------------------------| \n| 200 | OK | \n| 400 | Bad Request, not formatted correctly. See response for details | \n| 403 | Forbidden, token doesn't have permission to do this operation | \n| 409 | Conflict, request is formatted OK but violates a rule |", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/poll/poll/{pollid}/standings": { "get": { "tags": [ "PollApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "pollid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned poll ID.", "x-identifier-source": "TalkLabs ID" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": [ { "kind": "poll.poll", "id": "662da20fe45ad80a7f2bd950", "appid": "662bb49bf10e9a26a7e8ed92", "ownerid": "u-8842", "title": "Sample Poll 1: Vote for your favorite color", "description": "Vote for your favorite color", "posterurl": "", "embedcontenttop": "", "embedcontentbotton": "", "whenpollpublish": "2024-04-28T01:10:39.535Z", "whenpollopens": "2024-04-28T01:10:39.535Z", "whenpollcloses": null, "whenpollexpires": null, "displayresults": 1, "sortanswers": 0, "customtype": "", "customid": "sample-poll-1-vote", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Get Standings", "description": "_This method requires authentication._\n\nThis returns a list of all distinct choices selected by poll respondants, with the count of how many responses each choice had, sorted by choice in ascending order by rank. Rank is computed by sorting by count of choices.\n\n## RESPONSE CODES\n\n- **200 | OK** : Sweet, sweet success.\n \n- **400 | BadRequest** : Something is wrong with your request. View response message and errors list for details.\n \n- **403 | Forbidden** : The user doesn't have permission\n \n- **405 | MethodBlocked** : The method was blocked because it contained profanity and filtermode was set to 'block'.\n \n- **412 | PreconditionFailed** : Conditions must be met for standings to be available (depends on the settings of the poll, such as requesting standings while poll is open but poll is configured to only reveal standings when poll is closed)", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/poll/poll/{pollid}/responses/user/{userid}": { "get": { "tags": [ "PollApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "pollid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned poll ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": [ { "kind": "poll.choice", "id": "662da22ee45ad80a7f2bd951", "appid": "662bb49bf10e9a26a7e8ed92", "pollid": "662da20fe45ad80a7f2bd950", "position": 0, "title": "Red", "imageurl": "", "videoid": "", "embedcode": "", "customtype": "", "customid": "", "custompayload": "", "customtags": null, "customfield1": "", "customfield2": "" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Responses by User", "description": "_This method requires authentication._\n\nRooms can be public or private. This method lists all public rooms that everyone can see.\n* **cursor** : (optional) The first time you call list rooms, omit this property to start from the beginning. Call the method again passing in the value returned in the cursor field of the response to get the next page of results. If there are more results available, more will be true.\n* **limit** : (optional) Specify the number of items to return. Default is 200.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/poll/poll/{pollid}/responses/all": { "get": { "tags": [ "PollApi" ], "summary": "List all poll responses", "parameters": [ { "name": "appid", "in": "path", "description": "The TalkLabs application ID assigned to your account.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "pollid", "in": "path", "description": "The TalkLabs-assigned poll ID.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "UserId", "in": "query", "description": "The customer-defined user ID from your application or identity system.", "schema": { "type": "string" }, "x-identifier-source": "customer-defined" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "description": "UserId is the user who is requesting the responses.\nIf the poll doesn't allow responses to come out unless you have responded it needs to be enforced here", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/poll/poll/{pollid}/choice/{choiceid}": { "delete": { "tags": [ "PollApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "pollid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned poll ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "choiceid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned poll choice ID.", "x-identifier-source": "TalkLabs ID" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Delete a poll choice", "description": "Create polls, manage choices, collect votes, and read standings.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/poll/poll/{pollid}/reset": { "put": { "tags": [ "PollApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "pollid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned poll ID.", "x-identifier-source": "TalkLabs ID" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "The specified conversation and all comments were permanently deleted.", "errors": {}, "data": { "kind": "delete.conversation", "conversationid": "api-conversation-demo1", "userid": null, "deletedconversations": 1, "deletedcomments": 17 } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Reset Poll", "description": "## CANNOT BE UNDONE. This deletes all responses for a poll. The purpose of this method is so you can test a poll before opening it to the public.\n\n### URL Arguments\n\n- **pollid** : (required) The ID of the poll to reset.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/poll/poll/{pollid}/lead": { "post": { "tags": [ "PollApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "pollid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned poll ID.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PollCreateLeadFormModel" } ] }, "example": { "email": "potus@test.com", "pollId": "poll-id" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "poll.poll", "id": "662da20fe45ad80a7f2bd950", "appid": "662bb49bf10e9a26a7e8ed92", "ownerid": "u-8842", "title": "Sample Poll 1: Vote for your favorite color", "description": "Vote for your favorite color", "posterurl": "", "embedcontenttop": "", "embedcontentbotton": "", "whenpollpublish": "2024-04-28T01:10:39.5358368Z", "whenpollopens": "2024-04-27T21:10:39.5358872-04:00", "whenpollcloses": null, "whenpollexpires": null, "displayresults": 1, "sortanswers": 0, "customtype": "", "customid": "sample-poll-1-vote", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Create Lead", "description": "_This method requires authentication._\n\nThis is for capturing leads. It can capture name and email address. If the email address is already in use, the name fields will be overwritten.\n\n- **pollid**: (required) The id of the poll\n \n- **firstname**: (optional) The first name of the user responding\n \n- **lastname**: (optional) The last name of the user responding\n \n- **email:** (required) The email address of the user responding\n \n\n| Response Code | Description |\n| --- | --- |\n| 200 | OK |\n| 400 | Bad Request, not formatted correctly. See response for details |\n| 403 | Forbidden, token doesn't have permission to do this operation |\n| 409 | Conflict, request is formatted OK but violates a rule |", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/poll/poll/{pollid}/leads": { "get": { "tags": [ "PollApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "pollid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned poll ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 200 }, "description": "The maximum number of records to return." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The cursor returned by the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List poll leads", "description": "Create polls, manage choices, collect votes, and read standings.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/poll/poll/{pollid}/responses": { "get": { "tags": [ "PollApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "pollid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned poll ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 200 }, "description": "The maximum number of records to return." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The cursor returned by the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List poll responses", "description": "Create polls, manage choices, collect votes, and read standings.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/telemetry/contexts/{contextid}/batch": { "post": { "tags": [ "Telemetry - Batch (submit many actions)" ], "summary": "Submit telemetry in a batch", "description": "Submit multiple telemetry actions in one request.\n\nBuffer counter increments, gauge samples, and presence heartbeats on the client, then flush them together to reduce request overhead. Invalid items are reported without discarding valid items in the same batch.", "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "contextid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A customer-defined ID for the live context being measured.", "x-identifier-source": "customer-defined" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/TelemetryBatchFormModel" } ], "description": "Submits a user's accumulated telemetry actions in one request. Lets a mobile client buffer taps,\r\nloudness samples and presence locally and flush them periodically (e.g. every 1-2s) instead of one\r\nHTTP request per action — the single biggest per-request scaling win at high concurrency." }, "example": { "userId": "u-8842", "ops": [ "" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/telemetry/contexts/{contextid}/gauges/{key}/sample": { "post": { "tags": [ "Telemetry - Gauges (continuous readings)" ], "summary": "Record a gauge sample", "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "contextid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A customer-defined ID for the live context being measured.", "x-identifier-source": "customer-defined" }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A customer-defined name for this telemetry signal.", "x-identifier-source": "customer-defined" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/TelemetrySampleFormModel" } ], "description": "Push for a gauge signal — records a continuous reading such as mic loudness." }, "example": { "userId": "u-8842", "value": 1 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "description": "Record a continuous reading from 0 to 1, such as sound level or interaction intensity.\n\nSend samples while the signal is active. TalkLabs maintains a synchronized aggregate that every viewer of the context can read.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/telemetry/contexts/{contextid}/metrics/{key}/increment": { "post": { "tags": [ "Telemetry - Metrics (counters)" ], "summary": "Increment a counter", "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "contextid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A customer-defined ID for the live context being measured.", "x-identifier-source": "customer-defined" }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A customer-defined name for this telemetry signal.", "x-identifier-source": "customer-defined" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/TelemetryIncrementFormModel" } ], "description": "Push for a metric (counter) signal — records one or more occurrences." }, "example": { "userId": "u-8842", "by": 1 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "description": "Record one or more occurrences in a named counter.\n\nUse customer-defined keys to keep related counters separate. For example, `reaction.primary` and `reaction.secondary` can share a context while producing independent totals.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/telemetry/contexts/{contextid}/presence/{key}/heartbeat": { "post": { "tags": [ "Telemetry - Presence (who is here now)" ], "summary": "Record a presence heartbeat", "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "contextid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A customer-defined ID for the live context being measured.", "x-identifier-source": "customer-defined" }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A customer-defined name for this telemetry signal.", "x-identifier-source": "customer-defined" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/TelemetryHeartbeatFormModel" } ], "description": "Push for a presence signal — marks a user as currently active in the context." }, "example": { "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "description": "Mark a user as active in a live context.\n\nSend heartbeats periodically while the user is present. The active count falls automatically after heartbeats stop.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/telemetry/contexts/{contextid}": { "get": { "tags": [ "Telemetry - Read (live meter)" ], "summary": "Read a live telemetry meter", "description": "Read the synchronized aggregate for every signal in a context.\n\nPoll this endpoint to update live meters and presence displays. Each reading includes a normalized `intensity` from 0 to 1, plus the raw values for its signal type.", "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "contextid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A customer-defined ID for the live context being measured.", "x-identifier-source": "customer-defined" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/users/{userid}/ban": { "post": { "tags": [ "UserApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UserEffectFormModel" } ] }, "example": { "applyEffect": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Set a global user ban", "description": "* **userid**: (required) The applicaiton provided userid of the user to ban\n* **applyeffect**: (required) true or false. If true, user will be set to banned state. If false, will be set to non-banned state.\n* **expireseconds**: (optional) if not specified, the ban is permanent until user is restored. If specified, then the ban will be temporarily applied for the specified number of seconds.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/users/{userid}/shadowban": { "post": { "tags": [ "UserApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UserEffectFormModel" } ] }, "example": { "applyEffect": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Shadow Ban User", "description": "A Shadow Ban user can send messages into a chat room, however those messages are flagged as shadow banned. This enables the application to show those messags only to the shadow banned user, so that that person may not know they were shadow banned. This method shadow bans the user on the global level (or you can use this method to lift the ban). You can optionally specify an expiration time. If the expiration time is specified, then each time the shadow banned user tries to send a message the API will check if the shadow ban has expired and will lift the ban.\n\n* **userid**: (required) The applicaiton provided userid of the user to ban\n* **applyeffect**: (required) true or false. If true, user will be set to shadow banned state. If false, will be set to non-shadow banned state.\n* **expireseconds**: (optional) Duration of shadowban value in seconds. If specified, the shadow ban will be lifted when this time is reached. If not specified, shadowban remains until explicitly lifted. Maximum seconds is a double byte value.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/users/{userid}/mute": { "post": { "tags": [ "UserApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UserEffectFormModel" } ] }, "example": { "applyEffect": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Mute User", "description": "A muted user is in a read-only state. The muted user can join chat rooms and observe but cannot communicate. This method applies mute on the global level (applies to all talk contexts). You can optionally specify an expiration time. If the expiration time is specified, then each time the shadow banned user tries to send a message the API will check if the shadow ban has expired and will lift the ban.\n\n* **userid**: (required) The applicaiton provided userid of the user to ban\n* **applyeffect**: (required) true or false. If true, user will be set to muted state. If false, will be set to non-banned state.\n* **expireseconds**: (optional) Duration of mute in seconds. If specified, the mute will be lifted when this time is reached. If not specified, mute effect remains until explicitly lifted. Maximum seconds is a double byte value.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/users/{userid}/report": { "post": { "tags": [ "UserApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ReportFormModel" } ] }, "example": { "reportType": {}, "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Report User", "description": "### URL Arguments\n\n- **userid** : (required) The ID of the user who is being reported, URL ENCODED.\n \n\n### BODY Parameters\n\n- **userid** : (required) This is the application specific user ID of the user reporting the first user.\n \n- **reporttype:** (required) This is the classification of the reported post. It must be one of the below values (note that 'false' represents information considered false by the reporter:\n \n - abuse\n \n - spam\n \n - selfharm\n \n - hate\n \n - violence\n \n - harassment\n \n - nudity\n \n - illegal\n \n - false\n \n - other\n \n\n### RESPONSES:\n\n| Code | Meaning | Description |\n| --- | --- | --- |\n| 200 | OK | Request completed successfully |\n| 404 | Not Found | The specified user or application could not be found |\n| 409 | Conflict | The request was rejected because user reporting is not enabled for the application. |", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/users/{userid}/globalpurge": { "post": { "tags": [ "UserApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GlobalPurgeUserFormModel" } ] }, "example": { "byUserId": "" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Global Purge User", "description": "#### **This will delete all chat content from this user and will set all the users comments to LOGICALLY DELETED. This means the comments will still be there but the API will return a placeholder instead of the original comment.**\n\n## URL PARAMETERS\n\n- **userid**: (required) The application provided userid of the user to ban\n \n\n## POST PARAMETERS\n\n- **byuserid**: (optional) The userid of the user issuing the purge command.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/users/{userid}/session": { "post": { "tags": [ "UserApi" ], "summary": "Create a user session", "description": "Mint a bearer token for one of your users.\n\nCall this endpoint only from your trusted backend using its API token. Return the minted bearer token to the user's app or browser; never expose the server API token to the client.", "parameters": [ { "name": "appid", "in": "path", "description": "The application the token is for.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "description": "The user the token represents (becomes the token's subject). This sits in the URL path, so the caller\r\nMUST URL-encode it — a userid containing reserved characters (spaces, '/', '%', '#', '?', '+', etc.)\r\nwill otherwise be misread or rejected. ASP.NET Core percent-decodes the value during route binding,\r\nso the method receives the original userid; do not decode it again.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "customer-defined" } ], "requestBody": { "description": "Optional -- send an empty JSON object ({}) to mint with defaults. Fields: displayname and pictureurl\r\nseed or update the user's profile; role is the token's role (\"user\" when omitted); expiresin is a\r\nlifetime in seconds (omit for a non-expiring token).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/MintUserSessionFormModel" } ], "description": "Door B mint request body (docs/specs/features/authentication/door-b-mint-api.md). All fields are\r\noptional -- an empty JSON object ({}) mints a non-expiring \"user\"-role token with no profile seed\r\nfields." }, "example": { "displayName": "Dave M.", "pictureUrl": "https://example.com/avatars/u-8842.jpg", "role": "", "expiresIn": 1 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/users/{userid}/tokens": { "delete": { "tags": [ "UserApi" ], "summary": "Revoke all user tokens", "description": "Revoke every bearer token previously issued for a user.\n\nCall this endpoint from your trusted backend. Tokens issued before the revocation cutoff stop being accepted, including tokens minted by TalkLabs and compatible tokens signed by your own identity system.", "parameters": [ { "name": "appid", "in": "path", "description": "The application the user belongs to.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "description": "The user whose tokens are being revoked.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "customer-defined" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/users/{userid}/role": { "post": { "tags": [ "UserApi" ], "summary": "Set a user role", "description": "Change the role stored on a user.\n\nUse a trusted backend API token, or an authorized administrator user token. In applications that share a user pool, the stored role applies across that pool.", "parameters": [ { "name": "appid", "in": "path", "description": "The application the user belongs to.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "description": "The user whose role is being changed.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "customer-defined" } ], "requestBody": { "description": "The new role in the \"role\" field (\"user\", \"moderator\", or \"admin\").", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UserRoleFormModel" } ], "description": "Role-management request body (claims-profile.md role decision, 2026-07-20)." }, "example": { "role": "" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/moderation/queues/reportedusers": { "get": { "tags": [ "UserApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" }, "description": "The maximum number of records to return." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The cursor returned by the previous page." }, { "name": "filterModerationState", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/ModerationStates" } ] } }, { "name": "filterUserid", "in": "query", "schema": { "type": "string", "default": "" }, "x-identifier-source": "customer-defined" }, { "name": "filterHandle", "in": "query", "schema": { "type": "string", "default": "" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "list.comments", "cursor": "5e9e65f138a285193496316b", "more": false, "conversation": null, "comments": [ { "kind": "comment.comment", "id": "5e9e65f138a285193496316b", "appid": "5e9389ed38a2b10794e271ee", "conversationid": "my_conversation_id", "commenttype": "comment", "added": 1587439089, "modified": 1587439089, "userid": "u-8842", "user": { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "banned": false }, "body": "Hello, World! This is a comment with international characters and emojis. Intl: äöüÄÖÜß | Emojis: 😂🤣❤😍😒", "hashtags": [], "customtype": "my-custom-type", "customid": "/articles/2020-03-01/article1/something-very-important-happened", "custompayload": "{ num : 0 }", "customtags": [ "taga", "tagb" ], "customfield1": "/sample/userdefined1/emojis/😂🤣❤😍😒", "customfield2": "/sample/userdefined2/intl/characters/äöüÄÖÜß", "edited": false, "deleted": false, "parentid": "", "hierarchy": [], "mentions": [], "reactions": [ { "type": "like", "count": 0, "users": [] } ], "likecount": 0, "replycount": 0, "votecount": 0, "votescore": 0, "votes": [], "moderation": "flagged", "active": false, "reports": [ { "userid": "u-8842", "reason": "abuse" } ] } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Users in Moderation Queue", "description": "_This method requires authentication._\n\n* *limit*: (optional) Defaults to 200. This limits how many users to return from the queue\n* *cursor*: (optional) Provide cursor value to get the next page of results.\n* *filterModerationState*: (optional) Filters for users in the specified moderation state.\n * approved: Moderator approved the user\n * rejected: Moderator rejected the user\n * flagged: Enough users reported the user that it is in the flagged state and sent to moderation queue\n* *filterUserId*: (optional) Exact match filter for UserID\n* *filterHandle*: (optional) Substring match for Handle (case-insensitive)", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/moderation/queues/reportedusers/{userid}/applydecision": { "post": { "tags": [ "UserApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ModerateUserFormModel" } ] }, "example": { "approve": "false" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Apply a user moderation decision", "description": "# BODY PROPERTIES\n* **approve** : (required) Pass **true** to approve the comment or **false** to reject the user.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/users/{userid}": { "get": { "tags": [ "Users" ], "summary": "Get User Details", "description": "_This method requires authentication._\n\nThis will return all the information about the user.", "parameters": [ { "name": "appid", "in": "path", "description": "The application the user belongs to.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "description": "The app-specific user ID to look up.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "customer-defined" } ], "responses": { "200": { "description": "OK: success -- `data` is the AppUser.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "BadRequest: the userid parameter is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden: request is not authorized with a valid token, or the token does not match this appid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "NotFound: no user exists for the given userid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] }, "post": { "tags": [ "Users" ], "summary": "Create or Update User", "description": "All users must have a Handle. The display name is optional. If you create a user and don't provide a handle, but you do provide a display name, a handle will be generated for you based on the provided display name. The generated handle will not be able to contain all characters or spaces, and could have numbers appended to the end.\n\nInvoke this API method if you want to create a user or update an existing user. \n\n__Do not use this method to convert an anonymous user into a known user__. Use the **Convert User** api method instead.\n\nWhen users send messages to a room the user ID is passed as a parameter. When you retrieve the events from a room, the user who generated the event is returned with the event data, so it is easy for your application to process and render chat events with minimal code.\n\n* **userid**: _Required_. If the userid is new then the user will be created. If the userid is already in use in the database then the user will be updated.\n* **handle**: (Optional) A unique string representing the user that is easy for other users to type.\n\t* Example @GeorgeWashington could be the handle but Display Name could be \"Wooden Teef For The Win\".\n\t* If you are creating a user and you don't specify a handle, the system will generate one for you (using Display Name as basis if you provide that).\n\t* If you request a handle and it's already in use a new handle will be generated for you by adding a number from 1-99 and returned. \n\t* If the handle can't be generated because all the options 1-99 on the end of it are taken then the request will be rejected with BadRequest status code.\n\t* Only these characters may be used: \"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890_\"\n* **displayname**: _Optional_. This is the desired name to display, typically the real name of the person.\n* **pictureurl**: _Optional_. The URL to the picture for this user.\n* **profileurl**: _Optional_. The profileurl for this user.\n* **role**: _Optional_. Valid roles are \"user\" (default), \"moderator\" and \"admin\".\n* **customtags**: _Optional_. A list of strings to attach to the user object.\n\n\n## RESPONSE CODES\n* **200 | OK** : Sweet, sweet success.\n* **400 | BadRequest** : Something is wrong with your request. View response message and errors list for details.\n* **403 | Forbidden** : Request is not authorized with a valid token.\n* **405 | MethodBlocked** : See the error message, a rule blocked this from completing, such as profanity in the user Display Name (if filtering is enabled), or invalid characters in the handle.\n* **409 | Conflict** : The handle for this user is already in use. System will try up to 20 times to find a variant of your handle with 5 random numbers on the end, for example, \"Harald\" becomes \"Harald12345\".", "parameters": [ { "name": "appid", "in": "path", "description": "The application the user belongs to.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "description": "Required. If this userid is new, the user is created; if it already exists in the database, the user\r\nis updated.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "customer-defined" } ], "requestBody": { "description": "The user fields to create/update -- see UpdateUserFormModel for the full per-field contract\r\n(handle, displayname, pictureurl, profileurl, role, customtags, replaceuserid, isanonymous, expiresat).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateUserFormModel" } ] }, "example": { "handle": "dave_m", "role": "admin", "userId": "u-8842" } } } }, "responses": { "200": { "description": "OK: success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "role": "user", "customtags": [ "optional_custom_tag_1" ], "banned": false, "shadowbanned": false, "shadowbanexpires": "0001-01-01T00:00:00Z", "muted": false, "moderation": "na", "reports": [] } } } } }, "400": { "description": "BadRequest: something is wrong with the request -- see the message and errors list for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden: request is not authorized with a valid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "405": { "description": "MethodNotAllowed: a rule blocked the request, such as profanity in the display name (if filtering is enabled) or invalid characters in the handle.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "409": { "description": "Conflict: the requested handle is already in use. The system retries up to 20 times with a random numeric suffix before giving up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] }, "delete": { "tags": [ "Users" ], "summary": "Delete User", "description": "## All rooms with messages by that user will have the messages from this user purged in the rooms. \n\n_This method requires authentication._\n\n\n* **UserId** is the app specific User ID provided by your application.", "parameters": [ { "name": "appid", "in": "path", "description": "The application the user belongs to.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "description": "Required. The app-specific user ID to delete.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "customer-defined" } ], "responses": { "200": { "description": "OK: success -- `data` is a ResponseDeleteAppUser (kind \"deleted.appuser\") containing the deleted user's last-known record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "BadRequest: the userid parameter was not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden: request is not authorized with a valid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "NotFound: no user exists for the given userid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/users": { "get": { "tags": [ "Users" ], "summary": "List Users", "description": "_This method requires authentication._\n\nUse this method to cursor through a list of users. This method will return users in the order in which they were created, so it is safe to add new users while cursoring through the list.\n\n## ARGUMENTS\n* **cursor**: Each call to ListUsers will return a result set with a 'nextCursor' value. To get the next page of users, pass this value as the optional 'cursor' property. To get the first page of users, omit the 'cursor' argument.\n* **limit**: You can omit this optional argument, in which case the default limit is 200 users to return.", "parameters": [ { "name": "appid", "in": "path", "description": "The application whose users are listed.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "Cursor", "in": "query", "description": "Optional. Pass the `cursor` value from a previous response to fetch the next page; omit to start from the first page.", "schema": { "type": "string", "default": "" } }, { "name": "Limit", "in": "query", "description": "Optional. Maximum number of users to return in this page. Default and maximum are both 200 -- values above 200 are rejected with 400.", "schema": { "type": "integer", "format": "int32", "default": 200 } } ], "responses": { "200": { "description": "OK: success -- `data` is a ResponseCursorListAppUsers (cursor/more/itemcount/users).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Success", "errors": {}, "data": { "kind": "list.users", "cursor": "|5ebbe03d5617e00de4b044c2", "users": [ { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "banned": false }, { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "banned": false }, { "kind": "app.user", "userid": "userid_thomasj", "handle": "TJ", "handlelowercase": "tj", "displayname": "Thomas Jefferson", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTY2NzAyNTE0NTAxMDY3ODMx/thomas-jefferson_editedjpg.jpg", "profileurl": "https://www.biography.com/us-president/thomas-jefferson", "banned": false }, { "kind": "app.user", "userid": "", "handle": "ag_", "handlelowercase": "ag_", "displayname": "", "pictureurl": "", "profileurl": "", "banned": false } ] } } } } }, "400": { "description": "BadRequest: limit exceeds the maximum allowed value of 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden: request is not authorized with a valid token, or the token does not match this appid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/search": { "post": { "tags": [ "Users" ], "summary": "Search Users", "description": "_This method requires authentication._\n\nUse this method to cursor through a list of users. This method will return users in the order in which they were created, so it is safe to add new users while cursoring through the list.\n\n## ARGUMENTS\n* **cursor**: Each call to ListUsers will return a result set with a 'nextCursor' value. To get the next page of users, pass this value as the optional 'cursor' property. To get the first page of users, omit the 'cursor' argument.\n* **limit**: You can omit this optional argument, in which case the default limit is 200 users to return.\n* **name**: Provide part of a name to search the user name field\n* **handle**: Provide part of a handle to search by handle\n* **userid**: Provide part of a userid to search by userid", "parameters": [ { "name": "appid", "in": "path", "description": "The application whose users are searched.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "description": "The search request body -- at least one of userid, handle, or name is required:\r\n`userid` (optional): part of a userid to search by userid (exact-match lookup against the user pool; returns 0 or 1 user).\r\n`handle` (optional): part of a handle to search by handle (partial match, may return many).\r\n`name` (optional): part of a display name to search by name (partial match, may return many).\r\n`cursor` (optional): pass the `cursor` value from a previous response to continue paging a handle/name search.\r\n`limit` (optional): maximum results to return; defaults to 20 if omitted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SearchUserFormModel" } ] }, "example": { "handle": "dave_m", "limit": 100 } } } }, "responses": { "200": { "description": "OK: success -- `data` is `{ kind: \"list.users\", cursor, users }`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "BadRequest: none of userid, handle, or name was provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden: request is not authorized with a valid token, or the token does not match this appid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/users/{userid}/notification/listnotifications": { "get": { "tags": [ "Users" ], "summary": "List User Notifications", "description": "If you see totalunread > 0, but you don't see any notifications, check that you are including valid values for filterNotificationTypes.\n\n# URL PROPERTIES\n* **userid** : (required) Return only notifications for this user\n\n# BODY PROPERTIES\n* **filterNotificationTypes** : (optional) Return only events of the specified type. Pass the argument more than once to fetch multiple types of notifications at once.\n * chatmention\n * chatquote\n * chatreply\n * commentmention\n * commentquote\n * commentreply\n* **includeread** : (optional | default = false) If true, notifications that have already been read are returned\n* **filterChatRoomId** : (optional) If provided, this will only return notifications associated with the specified chat room using the ChatRoom ID (exact match)\n* **filterChatRoomCustomId** : (optional) If provided, this will only return notifications associated with the specified chat room using the Custom ID (exact match)\n* **limit** : (optional) Default is 50, maximum is 200. Limits how many items are returned.\n* **cursor** : (optional) Leave blank to start from the beginning of the result set; provide the value from the previous returned cursor to resume cursoring through the next page of results", "parameters": [ { "name": "appid", "in": "path", "description": "The application the user belongs to.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "description": "Required. Return only notifications for this user.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "customer-defined" }, { "name": "UserId", "in": "query", "description": "Required. Return only notifications for this user (the route's userid; also accepted as a form field).", "schema": { "maxLength": 255, "type": "string" }, "x-identifier-source": "customer-defined" }, { "name": "FilterNotificationTypes", "in": "query", "description": "Optional. Return only events of the specified type(s): chatmention, chatquote, chatreply,\r\ncommentmention, commentquote, commentreply. Pass the argument more than once to fetch multiple types\r\nat once. Omit to return all types.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationTypes" } } }, { "name": "FilterChatRoomId", "in": "query", "description": "Optional. Restrict results to notifications associated with this chat room ID (exact match).", "schema": { "type": "string" } }, { "name": "FilterChatRoomCustomId", "in": "query", "description": "Optional. Restrict results to notifications associated with this chat room custom ID (exact match).", "schema": { "type": "string" }, "x-identifier-source": "customer-defined" }, { "name": "FilterCommentConversationId", "in": "query", "description": "Optional. Restrict results to notifications associated with this comment conversation ID (exact match).", "schema": { "type": "string" } }, { "name": "FilterCommentConversationCustomId", "in": "query", "description": "Optional. Restrict results to notifications associated with this comment conversation custom ID (exact match).", "schema": { "type": "string" }, "x-identifier-source": "customer-defined" }, { "name": "IncludeRead", "in": "query", "description": "Optional, default false. If true, notifications that have already been read are also returned/counted.", "schema": { "type": "boolean" } }, { "name": "Cursor", "in": "query", "description": "Optional. Pass the cursor value from a previous response to resume paging; leave blank to start from the beginning.", "schema": { "type": "string" } }, { "name": "Limit", "in": "query", "description": "Optional. Default 50, maximum 200. Limits how many items are returned per page.", "schema": { "type": "integer", "format": "int32" } }, { "name": "Dieroll", "in": "query", "description": "If non-zero, a die will be rolled with this number of sides. If the roll is not a 1 the request gets a 200 response instantly and no work is done.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK: success -- `data` is a ResponseCursorListUserNotifications (cursor/more/itemcount/totalunread/notifications).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "list.usernotifications", "cursor": "602456795617e108441660da", "more": false, "itemcount": 1, "totalunread": 1, "notifications": [ { "kind": "notification", "id": "602456795617e108441660da", "added": "2021-02-10T21:56:09.9738413Z", "userid": "bobsmith2", "ts": 637485909699738400, "whenread": null, "isread": false, "notificationtype": "chatquote", "chatroomid": "600d78d45617e20e34c39dd5", "chatroomcustomid": "new-york-city-club", "commentconversationid": "", "commentconversationcustomid": "", "chateventid": "602456795617e108441660d9", "commentid": "" } ] } } } } }, "400": { "description": "BadRequest: required fields are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden: request is not authorized with a valid token, or the token does not match this appid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/users/{userid}/notification/countnotifications": { "get": { "tags": [ "Users" ], "summary": "Count User Notifications", "description": "# URL PROPERTIES\n* **userid** : (required) Return only notifications for this user\n\n# BODY PROPERTIES\n* **filterNotificationTypes** : (optional) Return only events of the specified type. Pass the argument more than once to fetch multiple types of notifications at once.\n * chatmention\n * chatquote\n * chatreply\n * commentmention\n * commentquote\n * commentreply\n* **includeread** : (optional | default = false) If true, notifications that have already been read are counted otherwise read notifications are not counted\n* **filterChatRoomId** : (optional) If provided, this will only count notifications associated with the specified chat room using the ChatRoom ID (exact match)\n* **filterChatRoomCustomId** : (optional) If provided, this will only count notifications associated with the specified chat room using the Custom ID (exact match)", "parameters": [ { "name": "appid", "in": "path", "description": "The application the user belongs to.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "description": "Required. Return only the notification count for this user.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "customer-defined" }, { "name": "UserId", "in": "query", "description": "Required. Return only notifications for this user (the route's userid; also accepted as a form field).", "schema": { "maxLength": 255, "type": "string" }, "x-identifier-source": "customer-defined" }, { "name": "FilterNotificationTypes", "in": "query", "description": "Optional. Return only events of the specified type(s): chatmention, chatquote, chatreply,\r\ncommentmention, commentquote, commentreply. Pass the argument more than once to fetch multiple types\r\nat once. Omit to return all types.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationTypes" } } }, { "name": "FilterChatRoomId", "in": "query", "description": "Optional. Restrict results to notifications associated with this chat room ID (exact match).", "schema": { "type": "string" } }, { "name": "FilterChatRoomCustomId", "in": "query", "description": "Optional. Restrict results to notifications associated with this chat room custom ID (exact match).", "schema": { "type": "string" }, "x-identifier-source": "customer-defined" }, { "name": "FilterCommentConversationId", "in": "query", "description": "Optional. Restrict results to notifications associated with this comment conversation ID (exact match).", "schema": { "type": "string" } }, { "name": "FilterCommentConversationCustomId", "in": "query", "description": "Optional. Restrict results to notifications associated with this comment conversation custom ID (exact match).", "schema": { "type": "string" }, "x-identifier-source": "customer-defined" }, { "name": "IncludeRead", "in": "query", "description": "Optional, default false. If true, notifications that have already been read are also returned/counted.", "schema": { "type": "boolean" } }, { "name": "Cursor", "in": "query", "description": "Optional. Pass the cursor value from a previous response to resume paging; leave blank to start from the beginning.", "schema": { "type": "string" } }, { "name": "Limit", "in": "query", "description": "Optional. Default 50, maximum 200. Limits how many items are returned per page.", "schema": { "type": "integer", "format": "int32" } }, { "name": "Dieroll", "in": "query", "description": "If non-zero, a die will be rolled with this number of sides. If the roll is not a 1 the request gets a 200 response instantly and no work is done.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK: success -- `data` is a ResponseCountUserNotifications (itemcount).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "BadRequest: required fields are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden: request is not authorized with a valid token, or the token does not match this appid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/users/{userid}/notification/notifications/{notificationid}/update": { "put": { "tags": [ "Users" ], "summary": "Set Notification Read Status", "description": "**Unless your workflow must support use of read notifications, use DELETE USER NOTIFICATION instead.**\n\nThis marks a notification as being in READ status. \nThat will prevent the notification from being returned in a call to List User Notifications unless the default filters are overridden.\nNotifications that are marked as read will be automatically deleted after some time.\n* Calling this over and over again for an event, or calling it on events where the reader is not the person that the reply is directed to, or calling it against events that are not type ChatReply or ChatQuote is inappropriate use of the API.\n\n### URL Arguments\n* **userid** : (required) The ID of the user marking the notification as read. This is used to ensure a user can't mark another user's notification as read.\n* **notificationid** : (required) The unique ID of the notification being updated.\n* **read** : (required) The read status (true/false) for the notification. You can pass false to mark the notification as unread.", "parameters": [ { "name": "appid", "in": "path", "description": "The application the user belongs to.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "description": "Required. The user marking the notification -- used to ensure a user can't mark another user's notification.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "customer-defined" }, { "name": "notificationid", "in": "path", "description": "Required. The unique ID of the notification being updated.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "read", "in": "query", "description": "Required. The read status (true/false) to set. Pass false to mark the notification unread again.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK: success -- `data` is the updated UserNotification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "notification", "id": "602456795617e108441660da", "added": "2021-02-10T21:56:09.9738413Z", "userid": "bobsmith2", "ts": 637485909699738400, "whenread": "2021-02-10T21:56:26.9429317Z", "isread": true, "notificationtype": "chatquote", "chatroomid": "600d78d45617e20e34c39dd5", "chatroomcustomid": "new-york-city-club", "commentconversationid": "", "commentconversationcustomid": "", "chateventid": "602456795617e108441660d9", "commentid": "" } } } } }, "400": { "description": "BadRequest: the required `read` parameter was not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden: request is not authorized with a valid token, or the token does not match this appid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/users/{userid}/notification/notificationsbyid/chateventid/{chateventid}/update": { "put": { "tags": [ "Users" ], "summary": "Set Notification Read Status (by ChatEventId)", "description": "**Unless your workflow must support use of read notifications, use DELETE USER NOTIFICATION by Chat Event Id instead.**\n\n* This marks a notification as being in READ status. \n* That will prevent the notification from being returned in a call to List User Notifications unless the default filters are overridden.\n* Notifications that are marked as read will be automatically deleted after some time.\n* Only call this once per event. Only call this for events of type ChatReply or ChatQuote.\n\n### URL Arguments\n* **userid** : (required) The ID of the user marking the notification as read. This is used to ensure a user can't mark another user's notification as read.\n* **chateventid** : (required) The unique ID of the chateventid to use to locate the notification being updated.\n* **read** : (required) The read status (true/false) for the notification. You can pass false to mark the notification as unread.", "parameters": [ { "name": "appid", "in": "path", "description": "The application the user belongs to.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "description": "Required. The user marking the notification -- used to ensure a user can't mark another user's notification.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "customer-defined" }, { "name": "chateventid", "in": "path", "description": "Required. The chat event ID used to locate the notification being updated.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "read", "in": "query", "description": "Required. The read status (true/false) to set. Pass false to mark the notification unread again.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK: success -- `data` is the updated UserNotification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "updated", "errors": {}, "data": { "kind": "notification", "id": "602456955617e108441660dc", "added": "2021-02-10T21:56:37.2243706Z", "userid": "bobsmith2", "ts": 637485909972243700, "whenread": "2021-02-10T21:58:01.9942603Z", "isread": true, "notificationtype": "chatquote", "chatroomid": "600d78d45617e20e34c39dd5", "chatroomcustomid": "new-york-city-club", "commentconversationid": "", "commentconversationcustomid": "", "chateventid": "602456955617e108441660db", "commentid": "" } } } } }, "400": { "description": "BadRequest: `chateventid` or `read` was not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden: request is not authorized with a valid token, or the token does not match this appid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/users/{userid}/notification/notifications/{notificationid}": { "delete": { "tags": [ "Users" ], "summary": "Delete User Notification", "description": "Immediately deletes a user notification. Unless your workflow specifically implements access to read notifications, you should delete notifications after they are consumed.\n\n### URL Arguments\n* **userid** : (required) The ID of the user marking the notification as read. This is used to ensure a user can't mark another user's notification as read.\n* **notificationid** : (required) The unique ID of the notification being updated.", "parameters": [ { "name": "appid", "in": "path", "description": "The application the user belongs to.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "description": "Required. The user the notification belongs to -- used to ensure a user can't delete another user's notification.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "customer-defined" }, { "name": "notificationid", "in": "path", "description": "Required. The unique ID of the notification being deleted.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" } ], "responses": { "200": { "description": "OK: success -- `data` is the deleted UserNotification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "notification", "id": "602456955617e108441660dc", "added": "2021-02-10T21:56:37.2243706Z", "userid": "bobsmith2", "ts": 637485909972243700, "whenread": "2021-02-10T21:58:01.9942603Z", "isread": true, "notificationtype": "chatquote", "chatroomid": "600d78d45617e20e34c39dd5", "chatroomcustomid": "new-york-city-club", "commentconversationid": "", "commentconversationcustomid": "", "chateventid": "602456955617e108441660db", "commentid": "" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden: request is not authorized with a valid token, or the token does not match this appid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "404": { "description": "NotFound: no notification with this ID exists for this user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/users/{userid}/notification/notificationsbyid/chateventid/{chateventid}": { "delete": { "tags": [ "Users" ], "summary": "Delete User Notification (By ChatEventId)", "description": "Immediately deletes a user notification. Unless your workflow specifically implements access to read notifications, you should delete notifications after they are consumed.\n\n### URL Arguments\n* **userid** : (required) The ID of the user marking the notification as read. This is used to ensure a user can't mark another user's notification as read.\n* **chateventid** : (required) The unique ID of the chateventid to use to locate the notification to be deleted.", "parameters": [ { "name": "appid", "in": "path", "description": "The application the user belongs to.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "description": "Required. The user the notification belongs to -- used to ensure a user can't delete another user's notification.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "customer-defined" }, { "name": "chateventid", "in": "path", "description": "Required. The chat event ID used to locate the notification to delete.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" } ], "responses": { "200": { "description": "OK: success -- `data` is the deleted UserNotification, or absent if there was nothing to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "deleted", "errors": {}, "data": { "kind": "notification", "id": "602457645617e108441660e8", "added": "2021-02-10T22:00:04.3587267Z", "userid": "bobsmith2", "ts": 637485912043587300, "whenread": null, "isread": false, "notificationtype": "chatquote", "chatroomid": "600d78d45617e20e34c39dd5", "chatroomcustomid": "new-york-city-club", "commentconversationid": "", "commentconversationcustomid": "", "chateventid": "602457645617e108441660e7", "commentid": "" } } } } }, "400": { "description": "BadRequest: `chateventid` was not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden: request is not authorized with a valid token, or the token does not match this appid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/users/{userid}/notification/notifications_all/markread": { "put": { "tags": [ "Users" ], "summary": "Notifications: Mark All Read", "description": "**Unless your workflow must support use of read notifications, notifications should be deleted when read.**\n\nThis marks all notifications for a user as read with one api call. \n### URL Arguments\n* **userid** : (required) The ID of the user marking the notification as read. This is used to ensure a user can't mark another user's notification as read.\n* **delete** : (optional, default: true) The read status (true/false) for the notification. If true, all the notifications for the user are deleted. If false, they are marked read.", "parameters": [ { "name": "appid", "in": "path", "description": "The application the user belongs to.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "description": "Required. The user marking notifications read -- used to ensure a user can't mark another user's notifications.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "customer-defined" }, { "name": "delete", "in": "query", "description": "Optional, default true. If true, all of the user's notifications are deleted. If false, they are marked read (not deleted).", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "OK: success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden: request is not authorized with a valid token, or the token does not match this appid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/user/users/{userid}/setroles": { "post": { "tags": [ "Users" ], "summary": "Set user permissions (not implemented)", "description": "This endpoint is present in the API contract but does not currently apply permission changes.\n\nDo not use it in production. Use **Create or Update User** to change the stored role, or **Set a user role** for the supported role-change operation.", "parameters": [ { "name": "appid", "in": "path", "description": "The application the user belongs to.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "TalkLabs ID" }, { "name": "userid", "in": "path", "description": "The user the permissions would apply to.", "required": true, "schema": { "type": "string" }, "x-identifier-source": "customer-defined" } ], "requestBody": { "description": "Intended shape (see UpdateUserPermissionsForm): a `roles` array of permission records, each with\r\nan entity type (\"room\" or \"application\"), an entity ID (or custom ID), and a role (\"admin\",\r\n\"moderator\", \"user\", or \"none\" to revoke). Currently ignored by the server -- see NOTE above.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateUserPermissionsForm" } ] }, "example": { "roles": [ "" ] } } } }, "responses": { "200": { "description": "OK: request accepted, but no permission change is actually applied (see NOTE above).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "BadRequest: the request body was not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden: request is not authorized with a valid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/webhook/hooks": { "post": { "tags": [ "WebhookApi" ], "summary": "Create or Replace Webhook", "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateWebhookFormModel" } ] }, "example": { "label": "Demonstration Webhook (prepublish)", "url": "https://localhost:443", "enabled": false, "events": [ "commentpublished", "commentreply" ], "webhookType": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "description": "_Requires Authentication._\n\n### Timeouts for Webhooks\n* Webhooks must complete within the allowed time (3 seconds) or it is considered a timeout\n* If your webhook consistently times out or fails to return with a success code then it may be deactivated\n* Your webhook should receive the event and return immediately\n \n### PROPERTIES\n\n* **label** : (required) A unique string for your webhook. It can be anything you want.\n* **url**: (required) A URL to post to when the webhook is activated.\n* **enabled**: (required) Sets the webhook to be in either the enabled or disabled states.\n* **type**: (required) [\"prepublish\"/\"postpublish\"] Sets the type of webhook. See TYPES below.\n* **events**: (required) An array of strings indicating which event types activate your webhook. See events below for allowed values.\n* **requireallcustomtags**: (optional) An array of strings indicating required tags. If any of the required tags are not present as custom tags on the room or conversation triggering the webhook then the webhook will not be fired.\n\n\n## BEHAVIOR: CREATE OR UPDATE\nIf the **label** is already in use by a webhook in the system, this will re-create the webhook, replacing what is in the database with the new settings you passed in.\n\n## WEBHOOK TYPES\n\nThere are two types of webhook: _prepublish_ and _postpublish_. \n\n### Pre-Publish Webhook\nPass \"prepublish\" for the type parameter to create this type of webhook. This webhook will fire before the event is fired. If the remote system responds with 200 then the message will continue through the pipeline to be published. If you have more than one prepublish webhook, if any respond with other than 200 the message will be blocked. An example of when you would use a pre-publish webhook is when you want to perform pre-moderation with an external system.\n\n### Post-Publish Webhook\nPass \"postpublish\" for the type parameter to create this type of webhook. This webhook will fire after an event is published. The reponse from the remote service is ignored. An example of a post publish webhook would be using post moderation with an external system.\n\n## EVENT TYPES\nThe following event types are supported.\n* chatcustom\n* chatspeech\n* chatquote\n* chatreply\n* chatreaction\n* chataction\n* chatenter\n* chatexit\n* chatroomopened\n* chatroomclosed\n* chatpurge\n* commentpublished\n* commentreply", "security": [ { "ApiToken": [] } ] }, "get": { "tags": [ "WebhookApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "Limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 200 }, "description": "The maximum number of records to return." }, { "name": "Cursor", "in": "query", "schema": { "type": "string", "default": "" }, "description": "The cursor returned by the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Webhooks", "description": "_This method requires authentication._\n\nUse this method to get a list of webhooks registered for your application.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/webhook/hooks/{id}": { "put": { "tags": [ "WebhookApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateWebhookFormModel" } ] }, "example": { "label": "Demonstration Webhook Re-Labeled", "url": "https://localhost:443", "enabled": false, "events": [ "speech", "custom", "reply", "reaction", "action", "enter", "exit", "roomopened", "roomclosed", "purge" ], "webhookType": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Update Webhook", "description": "_Requires Authentication._\n\n* **id** : (required) Passed as URL parameter, specifying which webhook to update.\n* **label** : (required) A unique string for your webhook. It can be anything you want.\n* **url**: (required) A URL to post to when the webhook is activated.\n* **enabled**: (required) Sets the webhook to be in either the enabled or disabled states.\n* **type**: (required) [\"prepublish\"/\"postpublish\"] Sets the type of webhook. See TYPES in the description for the \"Create Webhook\" API method.\n* **events**: (required) An array of strings indicating which event types activate your webhook. See events below.\n\n## Additional Details\nSee \"Create or Replace Webhook\" method for details about webhook behavior and settings.", "security": [ { "ApiToken": [] } ] }, "delete": { "tags": [ "WebhookApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "Delete Webhook", "description": "_This method requires authentication._\n\nUse this method to delete a webhook.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/webhook/hooks/{hookid}/logentries": { "get": { "tags": [ "WebhookApi" ], "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "hookid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned webhook ID.", "x-identifier-source": "TalkLabs ID" }, { "name": "Limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 200 }, "description": "The maximum number of records to return." }, { "name": "Cursor", "in": "query", "schema": { "type": "string", "default": "" }, "description": "The cursor returned by the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "Webhooks listed successfully.", "errors": {}, "data": { "kind": "list.webhook.logentries", "cursor": "5eaf47eef20111409006f21d", "more": false, "itemcount": 2, "logentries": [ { "id": "5eaf47d5f20111409006f21b", "appid": "5e921055f2011187885de4e0", "added": "2020-05-03T22:38:12.6864188Z", "ellapsedtimems": 708, "type": "postpublish", "eventtype": "commentpublished", "webhook": { "id": "5eaf22d1f2011166dc4fc50b", "kind": "webhook.webhook", "label": "Demonstration Webhook (postpublish commentreply)", "url": "https://webhook.site/4909b54a-291d-4faa-a4f4-4743fdb84b7a", "enabled": true, "type": "postpublish", "events": [ "commentreply", "commentpublished" ] }, "completedrequest": true, "statuscode": 200, "status": "OK", "payload": { "kind": "webhook.payload.comment", "appid": "5e921055f2011187885de4e0", "conversationid": "api-conversation-demo1", "commentid": "5eaf47d4f20111409006f21a", "comment": { "kind": "comment.comment", "id": "5eaf47d4f20111409006f21a", "appid": "5e921055f2011187885de4e0", "conversationid": "api-conversation-demo1", "commenttype": "comment", "added": "2020-05-03T22:38:12.4026447Z", "modified": "2020-05-03T22:38:12.401645Z", "userid": "u-8842", "user": { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "banned": false }, "body": "Hello, World! This is a comment with international characters and emojis. Intl: äöüÄÖÜß | Emojis: 😂🤣❤😍😒", "hashtags": [], "customtype": "my-custom-type", "customid": "", "custompayload": "{ num : 0 }", "customtags": [ "taga", "tagb" ], "customfield1": "/sample/userdefined1/emojis/😂🤣❤😍😒", "customfield2": "/sample/userdefined2/intl/characters/äöüÄÖÜß", "edited": false, "deleted": false, "parentid": "", "hierarchy": [], "mentions": [], "reactions": [], "likecount": 0, "replycount": 0, "votecount": 0, "votescore": 0, "votes": [], "moderation": "na", "active": true, "reports": [] }, "application": { "id": "5e921055f2011187885de4e0", "name": "Test Application 1", "accountId": "5e921051f2011187885de4df" }, "conversation": { "kind": "comment.conversation", "appid": "5e921055f2011187885de4e0", "owneruserid": null, "conversationid": "api-conversation-demo1", "property": "sportstalk247.com/demo", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "title": "Sample Conversation", "maxcommentlen": 512, "commentcount": 46, "open": true, "added": "2020-05-02T14:41:44.5179063Z", "whenmodified": "2020-05-02T14:41:45.423643Z", "customtype": "", "customid": "/articles/2020-03-01/article1/something-very-important-happened", "customtags": [ "taga", "tagb" ], "custompayload": "{ num : 0 }", "customfield1": "/sample/userdefined1/emojis/😂🤣❤😍😒", "customfield2": "/sample/userdefined2/intl/characters/äöüÄÖÜß" } }, "response": "" }, { "id": "5eaf47eef20111409006f21d", "appid": "5e921055f2011187885de4e0", "added": "2020-05-03T22:38:38.1806982Z", "ellapsedtimems": 680, "type": "postpublish", "eventtype": "commentreply", "webhook": { "id": "5eaf22d1f2011166dc4fc50b", "kind": "webhook.webhook", "label": "Demonstration Webhook (postpublish commentreply)", "url": "https://webhook.site/4909b54a-291d-4faa-a4f4-4743fdb84b7a", "enabled": true, "type": "postpublish", "events": [ "commentreply", "commentpublished" ] }, "completedrequest": true, "statuscode": 200, "status": "OK", "payload": { "kind": "webhook.payload.commentreply", "appid": "5e921055f2011187885de4e0", "conversationid": "api-conversation-demo1", "commentid": "5eaf47edf20111409006f21c", "toplevelcommentid": "5eaf350bf2011158783b2bd1", "parentcommentid": "5eaf358ef2011158783b2bd3", "application": { "id": "5e921055f2011187885de4e0", "name": "Test Application 1", "accountId": "5e921051f2011187885de4df" }, "comment": { "kind": "comment.comment", "id": "5eaf47edf20111409006f21c", "appid": "5e921055f2011187885de4e0", "conversationid": "api-conversation-demo1", "commenttype": "comment", "added": "2020-05-03T22:38:37.8826461Z", "modified": "2020-05-03T22:38:37.8826461Z", "userid": "u-8842", "user": { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "banned": false }, "body": "This is a reply.", "hashtags": [], "customtype": "", "customid": "", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "edited": false, "deleted": false, "parentid": "5eaf358ef2011158783b2bd3", "hierarchy": [ "5eaf350bf2011158783b2bd1", "5eaf358ef2011158783b2bd3" ], "mentions": [], "reactions": [], "likecount": 0, "replycount": 0, "votecount": 0, "votescore": 0, "votes": [], "moderation": "na", "active": true, "reports": [] }, "conversation": { "kind": "comment.conversation", "appid": "5e921055f2011187885de4e0", "owneruserid": null, "conversationid": "api-conversation-demo1", "property": "sportstalk247.com/demo", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "title": "Sample Conversation", "maxcommentlen": 512, "commentcount": 47, "open": true, "added": "2020-05-02T14:41:44.5179063Z", "whenmodified": "2020-05-02T14:41:45.423643Z", "customtype": "", "customid": "/articles/2020-03-01/article1/something-very-important-happened", "customtags": [ "taga", "tagb" ], "custompayload": "{ num : 0 }", "customfield1": "/sample/userdefined1/emojis/😂🤣❤😍😒", "customfield2": "/sample/userdefined2/intl/characters/äöüÄÖÜß" }, "toplevelcomment": { "kind": "comment.comment", "id": "5eaf350bf2011158783b2bd1", "appid": "5e921055f2011187885de4e0", "conversationid": "api-conversation-demo1", "commenttype": "comment", "added": "2020-05-03T21:18:03.9347215Z", "modified": "2020-05-03T21:18:03.9327229Z", "userid": "u-8842", "user": { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "banned": false }, "body": "Hello, World! This is a comment with international characters and emojis. Intl: äöüÄÖÜß | Emojis: 😂🤣❤😍😒", "hashtags": [], "customtype": "my-custom-type", "customid": null, "custompayload": "{ num : 0 }", "customtags": [ "taga", "tagb" ], "customfield1": "/sample/userdefined1/emojis/😂🤣❤😍😒", "customfield2": "/sample/userdefined2/intl/characters/äöüÄÖÜß", "edited": false, "deleted": false, "parentid": "", "hierarchy": [], "mentions": [], "reactions": [], "likecount": 0, "replycount": 1, "votecount": 0, "votescore": 0, "votes": [], "moderation": "na", "active": true, "reports": [] }, "parentcomment": { "kind": "comment.comment", "id": "5eaf358ef2011158783b2bd3", "appid": "5e921055f2011187885de4e0", "conversationid": "api-conversation-demo1", "commenttype": "comment", "added": "2020-05-03T21:20:14.5635324Z", "modified": "2020-05-03T21:20:14.5635324Z", "userid": "u-8842", "user": { "kind": "app.user", "userid": "u-8842", "handle": "dave_m", "handlelowercase": "georgew", "displayname": "Dave M.", "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg", "profileurl": "https://example.com/users/u-8842shington", "banned": false }, "body": "This is a reply.", "hashtags": [], "customtype": "", "customid": null, "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "edited": false, "deleted": false, "parentid": "5eaf350bf2011158783b2bd1", "hierarchy": [ "5eaf350bf2011158783b2bd1" ], "mentions": [], "reactions": [], "likecount": 0, "replycount": 3, "votecount": 0, "votescore": 0, "votes": [], "moderation": "na", "active": true, "reports": [] } }, "response": "" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "summary": "List Webhook Log Entries", "description": "_This method requires authentication._\n\nUse this method to get a list of webhooks registered for your application.", "security": [ { "ApiToken": [] } ] } }, "/api/v3/{appid}/chat/rooms/{roomid}/command": { "post": { "tags": [ "ChatApi" ], "summary": "Execute a chat command", "description": "Publish a normal chat message or execute a configured command.\n\nSend plain text in `command` for an ordinary message. The user identified by `userid` must join the room first. A successful response includes the published speech event, which will also arrive through the room updates stream.", "x-talklabs-source": "Verified against sportstalk-sdk RestfulChatEventService.executeChatCommand", "parameters": [ { "name": "appid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs application ID assigned to your account.", "x-identifier-source": "TalkLabs ID" }, { "name": "roomid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The TalkLabs-assigned room ID returned when the room was created.", "x-identifier-source": "TalkLabs ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCommandFormModel" }, "example": { "command": "", "userid": "u-8842" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" }, "example": { "message": "", "errors": {}, "data": { "kind": "chat.executecommand", "op": "speech", "room": { "kind": "chat.room", "id": "5ec2047286c2921ad07edd39", "appid": "5ec2038a86c2921ad07edd35", "ownerid": "u-8842", "name": "New York City Chat (Post-Moderated)", "description": "Live from the top of the Empire State Building", "customtype": "", "customid": "5th-stand", "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "enableactions": true, "enableenterandexit": true, "open": true, "inroom": 1, "added": "2020-05-18T03:43:46.3198116Z", "whenmodified": "2020-05-18T03:43:46.3198116Z", "moderation": "post", "maxreports": 0, "enableprofanityfilter": true, "delaymessageseconds": 0 }, "speech": { "kind": "chat.event", "id": "5ec204d986c2921ad07edd3d", "roomid": "5ec2047286c2921ad07edd39", "body": "Hello, SportsTalk247.com World!↵", "added": "2020-05-18T03:45:29.3561662Z", "ts": 637253703293561600, "eventtype": "speech", "userid": "userid_abe", "user": { "kind": "app.user", "userid": "userid_abe", "handle": "HonestAbe", "handlelowercase": "honestabe", "displayname": "Abraham Lincoln", "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg", "profileurl": "https://www.biography.com/us-president/abraham-lincoln", "banned": false }, "customtype": "", "customid": null, "custompayload": "", "customtags": [], "customfield1": "", "customfield2": "", "replyto": null, "parentid": "", "hierarchy": [], "edited": false, "deleted": false, "active": true, "mutedby": [], "shadowban": false, "hashtags": [], "likecount": 0, "replycount": 0, "reactions": [], "moderation": "na", "reports": [] }, "action": null } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "412": { "description": "Precondition Failed — the user must join the room first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } }, "418": { "description": "Too many messages were sent in a short interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } } }, "security": [ { "ApiToken": [] } ] } } }, "components": { "schemas": { "AccessRole": { "type": "object", "properties": { "resourceType": { "allOf": [ { "$ref": "#/components/schemas/ResourceTypes" } ], "description": "The kind of entity this permission applies to (\"room\" or \"application\"). Not currently JSON-bindable -- see class remarks." }, "resourceID": { "type": "string", "description": "The ID of the entity this permission applies to. Not currently JSON-bindable -- see class remarks.", "nullable": true } }, "additionalProperties": false, "description": "A single granular permission record: a role granted to a user on one entity (an application or a room).\r\nNOTE: only `Role` currently round-trips through JSON -- `ResourceType`/`ResourceID` (the\r\nentitytype/entityid the API's documented \"Set User Permissions\" contract describes) are marked\r\n[JsonIgnore] below, so a client-supplied entitytype/entityid does not bind onto this model today." }, "ApiResult": { "type": "object", "properties": { "message": { "type": "string", "nullable": true }, "errors": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "errorCode": { "type": "integer", "format": "int32", "readOnly": true }, "data": { "nullable": true }, "statusCode": { "allOf": [ { "$ref": "#/components/schemas/HttpStatusCode" } ] } }, "additionalProperties": false }, "ChatBounceUserFormModel": { "required": [ "bounce", "userId" ], "type": "object", "properties": { "userId": { "minLength": 1, "type": "string", "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" }, "bounce": { "type": "boolean" }, "announcement": { "type": "string", "nullable": true } }, "additionalProperties": false }, "ChatCommandPurgeUserMessagesFormModel": { "required": [ "userid" ], "type": "object", "properties": { "userid": { "minLength": 1, "type": "string", "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" }, "byuserid": { "type": "string", "nullable": true, "x-identifier-source": "customer-defined" } }, "additionalProperties": false }, "ChatEventTypes": { "enum": [ 0, 10, 15, 20, 30, 40, 50, 60, 70, 80, 85, 90, 100, 110, 120, 130, 140, 150, 160, 170, 180, 200 ], "type": "integer", "format": "int32" }, "ChatModerationTypes": { "enum": [ 0, 10, 20 ], "type": "integer", "format": "int32" }, "ChatQuotedReplyFormModel": { "required": [ "body", "userId" ], "type": "object", "properties": { "userId": { "minLength": 1, "type": "string", "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" }, "body": { "minLength": 1, "type": "string" }, "moderationState": { "allOf": [ { "$ref": "#/components/schemas/ModerationStates" } ] }, "customType": { "maxLength": 255, "type": "string", "nullable": true }, "customId": { "maxLength": 1024, "type": "string", "nullable": true, "description": "A customer-defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID.", "x-identifier-source": "customer-defined" }, "customPayload": { "maxLength": 1024, "type": "string", "nullable": true }, "customField1": { "maxLength": 1024, "type": "string", "nullable": true }, "customField2": { "maxLength": 1024, "type": "string", "nullable": true }, "customTags": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "additionalProperties": false }, "ChatResetRoomFormModel": { "type": "object", "properties": { "removeUserEffects": { "type": "boolean" } }, "additionalProperties": false }, "ChatSearchEventsFormModel": { "type": "object", "properties": { "fromUserId": { "type": "string", "description": "If specified, filters the search to only include messages where the user posting the event has this userid as an exact match", "nullable": true, "x-identifier-source": "customer-defined" }, "fromHandle": { "type": "string", "description": "If specified, filters the search to only include messages where the user posting the event has this handle as an exact match", "nullable": true }, "types": { "type": "array", "items": { "$ref": "#/components/schemas/ChatEventTypes" }, "nullable": true }, "roomId": { "type": "string", "description": "If specified, filters the search to only include events from the specified room", "nullable": true, "x-identifier-source": "TalkLabs ID" }, "body": { "type": "string", "description": "If specified, performs a substring match (case insensitive of the body)", "nullable": true }, "limit": { "type": "integer", "format": "int32", "nullable": true, "description": "The maximum number of records to return." }, "cursor": { "type": "string", "nullable": true, "description": "The cursor returned by the previous page." }, "direction": { "allOf": [ { "$ref": "#/components/schemas/CursoringDirections" } ] } }, "additionalProperties": false }, "ChatThreadedReplyFormModel": { "required": [ "body", "userId" ], "type": "object", "properties": { "userId": { "minLength": 1, "type": "string", "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" }, "body": { "minLength": 1, "type": "string" }, "moderationState": { "allOf": [ { "$ref": "#/components/schemas/ModerationStates" } ] }, "customType": { "maxLength": 255, "type": "string", "nullable": true }, "customId": { "maxLength": 1024, "type": "string", "nullable": true, "description": "A customer-defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID.", "x-identifier-source": "customer-defined" }, "customPayload": { "maxLength": 1024, "type": "string", "nullable": true }, "customField1": { "maxLength": 1024, "type": "string", "nullable": true }, "customField2": { "maxLength": 1024, "type": "string", "nullable": true }, "customTags": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "additionalProperties": false }, "ChatUpdateEventFormModel": { "required": [ "body", "userId" ], "type": "object", "properties": { "userId": { "minLength": 1, "type": "string", "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" }, "body": { "minLength": 1, "type": "string" }, "customId": { "type": "string", "nullable": true, "description": "A customer-defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID.", "x-identifier-source": "customer-defined" }, "customPayload": { "type": "string", "nullable": true }, "customField1": { "type": "string", "nullable": true }, "customField2": { "type": "string", "nullable": true }, "customTags": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "additionalProperties": false }, "ChatUserEffectFormModel": { "required": [ "applyEffect", "userId" ], "type": "object", "properties": { "userId": { "minLength": 1, "type": "string", "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" }, "applyEffect": { "type": "boolean" }, "expireSeconds": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false }, "CommentModerationTypes": { "enum": [ 0, 10, 20 ], "type": "integer", "format": "int32" }, "CommentTypes": { "enum": [ 0, 10, 15, 20 ], "type": "integer", "format": "int32" }, "CreateCommentFormModel": { "required": [ "body", "userId" ], "type": "object", "properties": { "userId": { "maxLength": 1024, "minLength": 1, "type": "string", "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" }, "body": { "minLength": 1, "type": "string" }, "added": { "type": "string", "format": "date-time", "nullable": true }, "commentType": { "allOf": [ { "$ref": "#/components/schemas/CommentTypes" } ] }, "customType": { "maxLength": 255, "type": "string", "nullable": true }, "customId": { "maxLength": 1024, "type": "string", "nullable": true, "description": "A customer-defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID.", "x-identifier-source": "customer-defined" }, "customPayload": { "maxLength": 1024, "type": "string", "nullable": true }, "customField1": { "maxLength": 1024, "type": "string", "nullable": true }, "customField2": { "maxLength": 1024, "type": "string", "nullable": true }, "customTags": { "type": "array", "items": { "type": "string" }, "nullable": true }, "handle": { "maxLength": 40, "type": "string", "nullable": true }, "displayName": { "maxLength": 60, "type": "string", "nullable": true }, "pictureUrl": { "maxLength": 1024, "type": "string", "nullable": true }, "profileUrl": { "maxLength": 1024, "type": "string", "nullable": true }, "role": { "allOf": [ { "$ref": "#/components/schemas/UserRoles" } ], "nullable": true }, "userCustomTags": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "additionalProperties": false }, "CreateConversationFormModel": { "required": [ "conversationId", "moderation", "property" ], "type": "object", "properties": { "conversationId": { "maxLength": 250, "minLength": 1, "type": "string", "description": "The TalkLabs-assigned conversation ID.", "x-identifier-source": "TalkLabs ID" }, "ownerUserId": { "maxLength": 1024, "type": "string", "nullable": true, "x-identifier-source": "customer-defined" }, "property": { "maxLength": 1024, "minLength": 1, "type": "string" }, "moderation": { "allOf": [ { "$ref": "#/components/schemas/CommentModerationTypes" } ], "description": "Defaults to postmoderation" }, "maxReports": { "type": "integer", "format": "int32", "nullable": true }, "title": { "maxLength": 1024, "type": "string", "nullable": true }, "maxCommentLen": { "maximum": 1024, "minimum": 0, "type": "integer", "format": "int32", "nullable": true }, "open": { "type": "boolean", "nullable": true }, "enableProfanityFilter": { "type": "boolean", "nullable": true }, "added": { "type": "string", "format": "date-time", "nullable": true }, "customType": { "maxLength": 255, "type": "string", "nullable": true }, "customId": { "maxLength": 1024, "type": "string", "nullable": true, "description": "A customer-defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID.", "x-identifier-source": "customer-defined" }, "customPayload": { "maxLength": 1024, "type": "string", "nullable": true }, "customField1": { "maxLength": 1024, "type": "string", "nullable": true }, "customField2": { "maxLength": 1024, "type": "string", "nullable": true }, "customTags": { "type": "array", "items": { "type": "string" }, "nullable": true }, "replaceConversationId": { "type": "string", "nullable": true } }, "additionalProperties": false }, "CreateRoomFormModel": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "userId": { "type": "string", "nullable": true, "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" }, "description": { "type": "string", "nullable": true }, "pictureUrl": { "type": "string", "nullable": true }, "moderation": { "allOf": [ { "$ref": "#/components/schemas/ChatModerationTypes" } ], "description": "Defaults to postmoderation", "nullable": true }, "maxReports": { "type": "integer", "format": "int32", "nullable": true }, "enableActions": { "type": "boolean", "nullable": true }, "enableEnterAndExit": { "type": "boolean", "nullable": true }, "enableProfanityFilter": { "type": "boolean", "nullable": true }, "enableAutoExpireSessions": { "type": "boolean", "nullable": true }, "delayMessageSeconds": { "type": "integer", "format": "int32", "nullable": true }, "roomIsOpen": { "type": "boolean", "nullable": true }, "privateRoom": { "type": "boolean", "description": "If TRUE set this to a private room, if false make it a public room" }, "customType": { "maxLength": 255, "type": "string", "nullable": true }, "customId": { "maxLength": 1024, "type": "string", "nullable": true, "description": "A customer-defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID.", "x-identifier-source": "customer-defined" }, "customPayload": { "maxLength": 1024, "type": "string", "nullable": true }, "customField1": { "maxLength": 1024, "type": "string", "nullable": true }, "customField2": { "maxLength": 1024, "type": "string", "nullable": true }, "customTags": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "additionalProperties": false }, "CursoringDirections": { "enum": [ 0, 10, 20 ], "type": "integer", "format": "int32" }, "GlobalPurgeUserFormModel": { "required": [ "byUserId" ], "type": "object", "properties": { "byUserId": { "minLength": 1, "type": "string", "x-identifier-source": "customer-defined" } }, "additionalProperties": false }, "HttpStatusCode": { "enum": [ 100, 101, 102, 103, 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 421, 422, 423, 424, 426, 428, 429, 431, 451, 500, 501, 502, 503, 504, 505, 506, 507, 508, 510, 511 ], "type": "integer", "format": "int32" }, "JoinRoomFormModel": { "type": "object", "properties": { "userId": { "maxLength": 255, "minLength": 0, "type": "string", "nullable": true, "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" }, "handle": { "maxLength": 40, "minLength": 0, "type": "string", "nullable": true }, "displayName": { "maxLength": 250, "minLength": 0, "type": "string", "nullable": true }, "pictureUrl": { "maxLength": 1040, "minLength": 0, "type": "string", "nullable": true }, "profileUrl": { "maxLength": 1040, "minLength": 0, "type": "string", "nullable": true }, "limit": { "type": "integer", "format": "int32", "description": "The maximum number of records to return." }, "role": { "allOf": [ { "$ref": "#/components/schemas/UserRoles" } ], "nullable": true }, "customTags": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "additionalProperties": false }, "MintUserSessionFormModel": { "type": "object", "properties": { "displayName": { "type": "string", "description": "Optional -- seeds/updates the auto-provisioned profile's display name (claims-profile.md\r\n `name` rules: <= 64 chars). Oversize is REJECTED (400) by IdentityService.MintUserSessionTokenAsync,\r\n unlike the Bearer path's lenient drop-don't-reject rule -- the mint caller is the customer's own\r\n backend, so bad input should be surfaced, not silently swallowed.", "nullable": true }, "pictureUrl": { "type": "string", "description": "Optional -- seeds/updates the auto-provisioned profile's avatar URL (claims-profile.md\r\n `img` rules: https only, <= 512 chars). Same fail-closed rejection rule as DisplayName above.", "nullable": true }, "role": { "type": "string", "description": "Optional -- \"user\" (default), \"moderator\", or \"admin\". Fail-closed: anything else is a 400,\r\n never silently demoted to \"user\" (claims-profile.md role decision).", "nullable": true }, "expiresIn": { "type": "integer", "description": "Optional, seconds. Absent = non-expiring (Stream model, claims-profile.md §9.1). Must be a\r\n positive integer -- <= 0 is a 400.", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Door B mint request body (docs/specs/features/authentication/door-b-mint-api.md). All fields are\r\noptional -- an empty JSON object ({}) mints a non-expiring \"user\"-role token with no profile seed\r\nfields." }, "ModerateEventFormModel": { "required": [ "approve" ], "type": "object", "properties": { "approve": { "type": "boolean" } }, "additionalProperties": false }, "ModerateUserFormModel": { "required": [ "approve" ], "type": "object", "properties": { "approve": { "type": "boolean" } }, "additionalProperties": false }, "ModerationStates": { "enum": [ 0, 10, 20, 30, 40, 50, 60, 70 ], "type": "integer", "format": "int32" }, "NotificationTypes": { "enum": [ 0, 10, 20, 30, 50, 60, 70 ], "type": "integer", "format": "int32" }, "OptionChoicesSort": { "enum": [ 0, 1 ], "type": "integer", "format": "int32" }, "OptionDisplayResults": { "enum": [ 0, 1, 2 ], "type": "integer", "format": "int32" }, "PollChoiceCreateOrUpdateFormModel": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "readOnly": true }, "pollID": { "type": "string", "nullable": true, "description": "The TalkLabs-assigned poll ID.", "x-identifier-source": "TalkLabs ID" }, "position": { "type": "integer", "format": "int32", "nullable": true }, "title": { "type": "string", "nullable": true }, "subtitle": { "type": "string", "nullable": true }, "imageUrl": { "type": "string", "nullable": true }, "videoID": { "type": "string", "nullable": true }, "embedCode": { "type": "string", "nullable": true }, "customType": { "maxLength": 255, "type": "string", "nullable": true }, "customId": { "maxLength": 1024, "type": "string", "nullable": true, "description": "A customer-defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID.", "x-identifier-source": "customer-defined" }, "customPayload": { "maxLength": 1024, "type": "string", "nullable": true }, "customField1": { "maxLength": 1024, "type": "string", "nullable": true }, "customField2": { "maxLength": 1024, "type": "string", "nullable": true }, "customTags": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "additionalProperties": false }, "PollCreateLeadFormModel": { "required": [ "pollId" ], "type": "object", "properties": { "pollId": { "minLength": 1, "type": "string", "description": "The TalkLabs-assigned poll ID.", "x-identifier-source": "TalkLabs ID" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PollCreateOrUpdateFormModel": { "type": "object", "properties": { "ownerUserId": { "type": "string", "nullable": true, "x-identifier-source": "customer-defined" }, "title": { "type": "string", "nullable": true }, "subtitle": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "pictureUrl": { "type": "string", "nullable": true }, "embedContentTop": { "type": "string", "nullable": true }, "embedContentBottom": { "type": "string", "nullable": true }, "videoId": { "type": "string", "nullable": true }, "displayResults": { "allOf": [ { "$ref": "#/components/schemas/OptionDisplayResults" } ], "nullable": true }, "sortChoices": { "allOf": [ { "$ref": "#/components/schemas/OptionChoicesSort" } ], "nullable": true }, "maxTotalResponsesPerUser": { "type": "integer", "description": "The maximum number of votes an individual can cast", "format": "int32", "nullable": true }, "allowMultipleChoicesPerUser": { "type": "boolean", "description": "Should users be allowed to vote for more than one response choice", "nullable": true }, "maxResponsesPerChoicePerUser": { "type": "integer", "description": "The maximum number of times a user can vote for a single choice", "format": "int32", "nullable": true }, "whenPollPublish": { "type": "string", "format": "date-time", "nullable": true }, "whenPollOpens": { "type": "string", "format": "date-time", "nullable": true }, "whenPollCloses": { "type": "string", "format": "date-time", "nullable": true }, "whenPollExpires": { "type": "string", "format": "date-time", "nullable": true }, "allowAnonymousPolling": { "type": "boolean", "nullable": true }, "leadCaptureEnabled": { "type": "boolean", "nullable": true }, "leadCaptureRequired": { "type": "boolean", "nullable": true }, "leadCaptureName": { "type": "boolean", "nullable": true }, "leadCaptureTitle": { "type": "string", "nullable": true }, "leadCaptureDescription": { "type": "string", "nullable": true }, "leadCapturePrompt": { "type": "string", "nullable": true }, "socialShareEnable": { "type": "boolean", "nullable": true }, "socialHandleFacebook": { "type": "string", "nullable": true }, "socialHandleX": { "type": "string", "nullable": true }, "socialHandleTikTok": { "type": "string", "nullable": true }, "socialHandleWhatsApp": { "type": "string", "nullable": true }, "socialCardTitle": { "type": "string", "nullable": true }, "socialCardImageUrl": { "type": "string", "nullable": true }, "socialCardUrl": { "type": "string", "nullable": true }, "customType": { "maxLength": 255, "type": "string", "nullable": true }, "customId": { "maxLength": 1024, "type": "string", "nullable": true, "description": "A customer-defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID.", "x-identifier-source": "customer-defined" }, "customPayload": { "maxLength": 1024, "type": "string", "nullable": true }, "customField1": { "maxLength": 1024, "type": "string", "nullable": true }, "customField2": { "maxLength": 1024, "type": "string", "nullable": true }, "customTags": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "additionalProperties": false }, "PollCreateResponseFormModel": { "required": [ "choiceId", "pollID" ], "type": "object", "properties": { "pollID": { "minLength": 1, "type": "string", "description": "The TalkLabs-assigned poll ID.", "x-identifier-source": "TalkLabs ID" }, "choiceId": { "minLength": 1, "type": "string", "description": "The TalkLabs-assigned poll choice ID.", "x-identifier-source": "TalkLabs ID" }, "userId": { "type": "string", "nullable": true, "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" } }, "additionalProperties": false }, "ReactionFormModel": { "required": [ "reacted", "reaction", "userId" ], "type": "object", "properties": { "reaction": { "minLength": 1, "type": "string" }, "userId": { "minLength": 1, "type": "string", "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" }, "reacted": { "type": "boolean" } }, "additionalProperties": false }, "ReportFormModel": { "required": [ "reportType", "userId" ], "type": "object", "properties": { "reportType": { "allOf": [ { "$ref": "#/components/schemas/ReportReasonTypes" } ] }, "userId": { "minLength": 1, "type": "string", "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" } }, "additionalProperties": false }, "ReportReasonTypes": { "enum": [ 0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100 ], "type": "integer", "format": "int32" }, "ResourceTypes": { "enum": [ 0, 10, 20, 30, 40 ], "type": "integer", "format": "int32" }, "RoomEntityTypes": { "enum": [ 0, 1, 2 ], "type": "integer", "format": "int32" }, "SearchUserFormModel": { "type": "object", "properties": { "userId": { "type": "string", "description": "Optional. Part of a userid to search by userid. Takes priority over handle and name if more than one is supplied.", "nullable": true, "x-identifier-source": "customer-defined" }, "handle": { "type": "string", "description": "Optional. Part of a handle to search by handle (partial match). Used only if userid is not supplied.", "nullable": true }, "name": { "type": "string", "description": "Optional. Part of a display name to search the name field (partial match). Used only if neither userid nor handle is supplied.", "nullable": true }, "limit": { "type": "integer", "description": "Optional. Maximum number of users to return. Defaults to 20 if omitted.", "format": "int32", "nullable": true }, "cursor": { "type": "string", "description": "Optional. Pass the `cursor` value from a previous response to continue paging a handle/name search; omit to start from the first page.", "nullable": true } }, "additionalProperties": false }, "TelemetryBatchFormModel": { "required": [ "ops", "userId" ], "type": "object", "properties": { "userId": { "minLength": 1, "type": "string", "description": "Default user for items that do not set their own `userid`.", "x-identifier-source": "customer-defined" }, "ops": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/TelemetryBatchItemFormModel" }, "description": "The actions to apply. Capped server-side (see the controller docs)." } }, "additionalProperties": false, "description": "Submits a user's accumulated telemetry actions in one request. Lets a mobile client buffer taps,\r\nloudness samples and presence locally and flush them periodically (e.g. every 1-2s) instead of one\r\nHTTP request per action — the single biggest per-request scaling win at high concurrency." }, "TelemetryBatchItemFormModel": { "required": [ "key", "op" ], "type": "object", "properties": { "op": { "minLength": 1, "type": "string", "description": "The action: `increment` (metric), `sample` (gauge), or `heartbeat` (presence)." }, "key": { "minLength": 1, "type": "string", "description": "The signal key, e.g. `cheer.home`.", "x-identifier-source": "customer-defined" }, "contextId": { "type": "string", "description": "Optional per-item context override. Defaults to the context in the request URL,\r\n which is what enables cross-context batches (e.g. app-wide presence plus an in-game cheer).", "nullable": true, "x-identifier-source": "customer-defined" }, "by": { "type": "integer", "description": "`increment` only: occurrences to add. Defaults to 1.", "format": "int64" }, "value": { "type": "number", "description": "`sample` only: the 0..1 reading. Values outside the range are clamped.", "format": "double" }, "userId": { "type": "string", "description": "Optional per-item user override. Defaults to the batch `userid`.", "nullable": true, "x-identifier-source": "customer-defined" } }, "additionalProperties": false, "description": "One action within a talkapi.Models.TelemetryBatchFormModel." }, "TelemetryHeartbeatFormModel": { "required": [ "userId" ], "type": "object", "properties": { "userId": { "minLength": 1, "type": "string", "description": "The user who is currently present. Distinct users are counted over a sliding window.", "x-identifier-source": "customer-defined" } }, "additionalProperties": false, "description": "Push for a presence signal — marks a user as currently active in the context." }, "TelemetryIncrementFormModel": { "required": [ "userId" ], "type": "object", "properties": { "userId": { "minLength": 1, "type": "string", "description": "The user expressing the reaction. Used for distinct-user weighting and abuse limiting.", "x-identifier-source": "customer-defined" }, "by": { "type": "integer", "description": "How many occurrences to add. Defaults to 1; values <= 0 are treated as 1.", "format": "int64" } }, "additionalProperties": false, "description": "Push for a metric (counter) signal — records one or more occurrences." }, "TelemetrySampleFormModel": { "required": [ "userId" ], "type": "object", "properties": { "userId": { "minLength": 1, "type": "string", "description": "The user contributing the reading. Used to count distinct active participants.", "x-identifier-source": "customer-defined" }, "value": { "maximum": 1, "minimum": 0, "type": "number", "description": "The normalized reading, 0.0 to 1.0 (e.g. mic loudness mapped from dBFS on the client).\r\nValues outside the range are clamped.", "format": "double" } }, "additionalProperties": false, "description": "Push for a gauge signal — records a continuous reading such as mic loudness." }, "UpdateUserFormModel": { "required": [ "userId" ], "type": "object", "properties": { "userId": { "maxLength": 255, "minLength": 1, "type": "string", "description": "Required. If this userid is new, the user is created; if it is already in use, the user is updated.\r\nExample: \"georgew\".", "x-identifier-source": "customer-defined" }, "handle": { "maxLength": 40, "type": "string", "description": "Optional. A unique string representing the user that is easy for other users to type, e.g.\r\n\"@GeorgeWashington\". If omitted when creating a user, one is generated from displayname. If the\r\nrequested handle is already in use, a variant is generated by appending a number (1-99); if all of\r\nthose are also taken the request is rejected with 400 BadRequest. Allowed characters:\r\n\"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890_\". Maximum 40 characters.", "nullable": true }, "displayName": { "maxLength": 250, "type": "string", "description": "Optional. The desired display name, typically the person's real name, e.g. \"Wooden Teef For The Win\". Maximum 250 characters.", "nullable": true }, "pictureUrl": { "maxLength": 1040, "type": "string", "description": "Optional. The URL to this user's picture. Maximum 1040 characters.", "nullable": true }, "profileUrl": { "maxLength": 1040, "type": "string", "description": "Optional. The profile URL for this user. Maximum 1040 characters.", "nullable": true }, "role": { "allOf": [ { "$ref": "#/components/schemas/UserRoles" } ], "description": "Optional. Valid values are \"user\" (default), \"moderator\", and \"admin\".", "nullable": true }, "customTags": { "type": "array", "items": { "type": "string" }, "description": "Optional. A list of free-form strings to attach to the user object.", "nullable": true }, "replaceUserId": { "type": "string", "description": "Optional. Renames an existing user by replacing their stored userid with this value. Leave empty to\r\nleave the userid unchanged. This is NOT a dedicated identity-conversion endpoint -- see the\r\ncontroller action's remarks before using this to promote an anonymous user to a known one.", "nullable": true, "x-identifier-source": "customer-defined" }, "isAnonymous": { "type": "boolean", "description": "Optional. Marks this user as anonymous/throwaway (the customer's own signal -- WE do not decide who is\r\nanonymous). An anonymous user's effective role defaults to the view-only \"readonly\" floor (reads\r\nallowed, writes require ≥ user) unless a token asserts a higher role. Omit to leave unchanged; set true\r\nor false to change it. Requirement: docs/specs/architecture/authentication/identity-architecture.md §2.6.", "nullable": true }, "expiresAt": { "type": "string", "description": "Optional lifecycle expiry (UTC): a time after which a (deferred) cleanup sweep may delete the user and\r\ntheir activity. GENERAL -- not tied to isAnonymous; any user may carry one. Omit to leave unchanged;\r\nsend a timestamp to set it, or send the sentinel `0001-01-01T00:00:00Z` (DateTime.MinValue) to\r\nCLEAR a previously-set expiry. Requirement: identity-architecture.md §2.6.", "format": "date-time", "nullable": true } }, "additionalProperties": false }, "UpdateUserPermissionsForm": { "type": "object", "properties": { "roles": { "type": "array", "items": { "$ref": "#/components/schemas/AccessRole" }, "description": "Required. An array of granular permission records to apply to the user, e.g. admin on one specific\r\nroom while holding the \"user\" role at the application level. NOTE: as of this writing the server\r\naction that binds this form (POST .../setroles) does not yet apply it -- see that action's remarks.", "nullable": true } }, "additionalProperties": false }, "UpdateWebhookFormModel": { "required": [ "enabled", "events", "label", "url", "webhookType" ], "type": "object", "properties": { "label": { "minLength": 1, "type": "string" }, "url": { "minLength": 1, "type": "string" }, "enabled": { "type": "boolean" }, "webhookType": { "allOf": [ { "$ref": "#/components/schemas/WebhookTypes" } ] }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventTypes" } }, "entities": { "type": "array", "items": { "type": "string" }, "nullable": true }, "requiredCustomTags": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "additionalProperties": false }, "UserEffectFormModel": { "required": [ "applyEffect" ], "type": "object", "properties": { "applyEffect": { "type": "boolean" }, "expireSeconds": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false }, "UserIdFormModel": { "required": [ "userId" ], "type": "object", "properties": { "userId": { "minLength": 1, "type": "string", "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" } }, "additionalProperties": false }, "UserRoleFormModel": { "required": [ "role" ], "type": "object", "properties": { "role": { "minLength": 1, "type": "string", "description": "Required -- \"user\", \"moderator\", or \"admin\". Fail-closed: anything else is a 400." } }, "additionalProperties": false, "description": "Role-management request body (claims-profile.md role decision, 2026-07-20)." }, "UserRoles": { "enum": [ 0, 10, 20, 30 ], "type": "integer", "format": "int32" }, "VoteFormModel": { "required": [ "userId", "vote" ], "type": "object", "properties": { "vote": { "minLength": 1, "type": "string" }, "userId": { "minLength": 1, "type": "string", "description": "The customer-defined user ID from your application or identity system.", "x-identifier-source": "customer-defined" } }, "additionalProperties": false }, "WebhookEventTypes": { "enum": [ 0, 10, 15, 20, 30, 40, 50, 60, 70, 80, 85, 90, 100, 110, 120, 200, 210 ], "type": "integer", "format": "int32" }, "WebhookTypes": { "enum": [ 0, 10 ], "type": "integer", "format": "int32" }, "ChatCommandFormModel": { "type": "object", "required": [ "command", "userid" ], "additionalProperties": false, "properties": { "command": { "type": "string", "minLength": 1, "description": "The message or command to publish. Plain text sends a normal chat message; reserved prefixes can invoke configured action or administrator commands." }, "userid": { "type": "string", "minLength": 1, "description": "The customer-defined ID of the user sending the command.", "x-identifier-source": "customer-defined" }, "eventtype": { "type": "string", "enum": [ "announcement", "custom", "ad" ], "nullable": true, "description": "Optional event type override for structured application events." }, "customtype": { "type": "string", "nullable": true, "description": "A customer-defined event type. Use with eventtype custom." }, "customid": { "type": "string", "nullable": true, "description": "A customer-defined ID for the new event.", "x-identifier-source": "customer-defined" }, "custompayload": { "type": "string", "nullable": true, "description": "Customer-defined structured data, commonly serialized JSON." } } } }, "securitySchemes": { "ApiToken": { "type": "apiKey", "in": "header", "name": "x-api-token", "description": "Your TalkLabs application token." } } }, "tags": [ { "name": "Telemetry - Metrics (counters)", "description": "Generic real-time telemetry meter. Push high-frequency samples into an arbitrary `contextid`\r\n(any string you choose, e.g. `game:lakers-celtics`) and poll a live, synchronized aggregate\r\nthat drives meters such as cheer/boo counts, a \"thunder\" loudness meter, floating-reaction\r\nvisualizations, or \"users online now\".\r\n \r\nA signal's kind is chosen by which endpoint you call:\r\nmetric (`/increment`) — counts occurrences. \"How many\".gauge (`/sample`) — averages a 0..1 reading. \"How much / how loud now\".presence (`/heartbeat`) — distinct active users now. \"How many here\".\r\nCounts are best-effort and only need to be directionally correct; they are never used for billing.\r\n \r\n\r\n`contextid` and `key` are customer-owned identifiers used verbatim — the server never\r\ntrims or otherwise rewrites them. They must be URL-encoded in the request path; the decoded value must\r\nbe URL-safe (letters, digits, and `- . _ ~ :`) and at most 256 characters, otherwise the request\r\nis rejected with `400`." }, { "name": "Telemetry - Gauges (continuous readings)", "description": "Generic real-time telemetry meter. Push high-frequency samples into an arbitrary `contextid`\r\n(any string you choose, e.g. `game:lakers-celtics`) and poll a live, synchronized aggregate\r\nthat drives meters such as cheer/boo counts, a \"thunder\" loudness meter, floating-reaction\r\nvisualizations, or \"users online now\".\r\n \r\nA signal's kind is chosen by which endpoint you call:\r\nmetric (`/increment`) — counts occurrences. \"How many\".gauge (`/sample`) — averages a 0..1 reading. \"How much / how loud now\".presence (`/heartbeat`) — distinct active users now. \"How many here\".\r\nCounts are best-effort and only need to be directionally correct; they are never used for billing.\r\n \r\n\r\n`contextid` and `key` are customer-owned identifiers used verbatim — the server never\r\ntrims or otherwise rewrites them. They must be URL-encoded in the request path; the decoded value must\r\nbe URL-safe (letters, digits, and `- . _ ~ :`) and at most 256 characters, otherwise the request\r\nis rejected with `400`." }, { "name": "Telemetry - Presence (who is here now)", "description": "Generic real-time telemetry meter. Push high-frequency samples into an arbitrary `contextid`\r\n(any string you choose, e.g. `game:lakers-celtics`) and poll a live, synchronized aggregate\r\nthat drives meters such as cheer/boo counts, a \"thunder\" loudness meter, floating-reaction\r\nvisualizations, or \"users online now\".\r\n \r\nA signal's kind is chosen by which endpoint you call:\r\nmetric (`/increment`) — counts occurrences. \"How many\".gauge (`/sample`) — averages a 0..1 reading. \"How much / how loud now\".presence (`/heartbeat`) — distinct active users now. \"How many here\".\r\nCounts are best-effort and only need to be directionally correct; they are never used for billing.\r\n \r\n\r\n`contextid` and `key` are customer-owned identifiers used verbatim — the server never\r\ntrims or otherwise rewrites them. They must be URL-encoded in the request path; the decoded value must\r\nbe URL-safe (letters, digits, and `- . _ ~ :`) and at most 256 characters, otherwise the request\r\nis rejected with `400`." }, { "name": "Telemetry - Batch (submit many actions)", "description": "Generic real-time telemetry meter. Push high-frequency samples into an arbitrary `contextid`\r\n(any string you choose, e.g. `game:lakers-celtics`) and poll a live, synchronized aggregate\r\nthat drives meters such as cheer/boo counts, a \"thunder\" loudness meter, floating-reaction\r\nvisualizations, or \"users online now\".\r\n \r\nA signal's kind is chosen by which endpoint you call:\r\nmetric (`/increment`) — counts occurrences. \"How many\".gauge (`/sample`) — averages a 0..1 reading. \"How much / how loud now\".presence (`/heartbeat`) — distinct active users now. \"How many here\".\r\nCounts are best-effort and only need to be directionally correct; they are never used for billing.\r\n \r\n\r\n`contextid` and `key` are customer-owned identifiers used verbatim — the server never\r\ntrims or otherwise rewrites them. They must be URL-encoded in the request path; the decoded value must\r\nbe URL-safe (letters, digits, and `- . _ ~ :`) and at most 256 characters, otherwise the request\r\nis rejected with `400`." }, { "name": "Telemetry - Read (live meter)", "description": "Generic real-time telemetry meter. Push high-frequency samples into an arbitrary `contextid`\r\n(any string you choose, e.g. `game:lakers-celtics`) and poll a live, synchronized aggregate\r\nthat drives meters such as cheer/boo counts, a \"thunder\" loudness meter, floating-reaction\r\nvisualizations, or \"users online now\".\r\n \r\nA signal's kind is chosen by which endpoint you call:\r\nmetric (`/increment`) — counts occurrences. \"How many\".gauge (`/sample`) — averages a 0..1 reading. \"How much / how loud now\".presence (`/heartbeat`) — distinct active users now. \"How many here\".\r\nCounts are best-effort and only need to be directionally correct; they are never used for billing.\r\n \r\n\r\n`contextid` and `key` are customer-owned identifiers used verbatim — the server never\r\ntrims or otherwise rewrites them. They must be URL-encoded in the request path; the decoded value must\r\nbe URL-safe (letters, digits, and `- . _ ~ :`) and at most 256 characters, otherwise the request\r\nis rejected with `400`." }, { "name": "CommentApi", "description": "CommentApiController is the API controller for managing comments and conversations in the Talk API." } ], "servers": [ { "url": "https://api.sportstalk247.com", "description": "Production" } ], "security": [ { "ApiToken": [] } ] }