# TalkLabs developer documentation > Audience engagement and monetization APIs for chat, comments, polls, reactions, moderation, webhooks, and live telemetry. ## Start here - [Developer guide](https://talklabs.ai/docs/): Integration concepts, authentication choices, and task-oriented recipes. - [Experience recipes](https://talklabs.ai/docs/recipes/): End-to-end flows that map complete user experiences to API operations. - [API reference](https://talklabs.ai/docs/reference/): Human-readable REST API reference with runnable requests. - [OpenAPI document](https://talklabs.ai/openapi.json): Current generated OpenAPI 3.0 snapshot. - [Complete AI reference](https://talklabs.ai/llms-full.txt): Every endpoint with parameters and examples in one text file. ## Experience recipes - [Build a complete group chat](https://talklabs.ai/docs/recipes/build-a-complete-group-chat/): Join, initial history, live updates, sending, reply controls, reactions, reporting, reconnects, and exit. - [Add message actions](https://talklabs.ai/docs/recipes/add-message-actions/): Map reply, quote, react, edit, delete, and report controls to chat operations. - [Moderate a live chat](https://talklabs.ai/docs/recipes/moderate-a-live-chat/): User reports, moderation queues, decisions, room effects, and live UI updates. - [Show live audience activity](https://talklabs.ai/docs/recipes/show-live-audience-activity/): Presence, counters, continuous gauges, batching, and synchronized meters. ## API groups - [Chat](https://talklabs.ai/docs/reference/chat/create-room-post): Create rooms, publish messages, subscribe users, and read live activity. - [Comments](https://talklabs.ai/docs/reference/comments/create-update-conversation-post): Create conversations, publish replies, and add reactions or votes. - [Polls](https://talklabs.ai/docs/reference/polls/create-lead-post): Create polls, manage choices, collect votes, and read standings. - [Users & notifications](https://talklabs.ai/docs/reference/users/create-or-update-user-post): Create and find users, update profiles, and deliver notifications. - [User sessions & access](https://talklabs.ai/docs/reference/user-access/create-a-user-session-post): Mint and revoke user tokens, change roles, and inspect access operations. - [Moderate chat](https://talklabs.ai/docs/reference/chat-moderation/list-flagged-users-needing-moderation-get): Review queues, act on reports, and apply room-level user effects. - [Moderate comments](https://talklabs.ai/docs/reference/comment-moderation/list-comments-in-moderation-queue-get): Review reported comments and approve, reject, or flag content. - [Moderate users](https://talklabs.ai/docs/reference/user-moderation/list-users-in-moderation-queue-get): Review reports, ban or mute users, and purge abusive content. - [Live telemetry](https://talklabs.ai/docs/reference/telemetry/read-a-live-telemetry-meter-get): Measure counters, continuous signals, and presence in real time. - [Webhooks](https://talklabs.ai/docs/reference/webhooks/create-or-replace-webhook-post): Send product events to your services and inspect delivery logs. - [Platform status](https://talklabs.ai/docs/reference/platform/get-the-api-version-get): Check service availability and the deployed API version. ## Authentication Send your application token in the `x-api-token` request header. API paths use the application ID as `{appid}`. The production API origin is `https://api.sportstalk247.com`. ## Identifier ownership - A **TalkLabs ID** is assigned and returned by the API. Examples include `roomid`, `conversationid`, and `pollid`. - A **custom ID** (`customid`) is chosen by the customer and can follow the customer's own naming system. - `userid` and telemetry `contextid` are also customer-defined identifiers with specific API roles. # Chat Create rooms, publish messages, subscribe users, and read live activity. ## Create Room `POST /api/v3/{appid}/chat/rooms` _This method requires authentication._ \* **name**: (required) The name of the room \* **description**: (optional) The description of the room \* **pictureurl**: (optional) The URL for a picture for the room \* **moderation**: (optional) \["pre"/"post"\] Defaults to post-moderation. \* **enableactions**: (optional) \[true/false\] Turns action commands on or off \* **enableenterandexit**: (optional) \[true/false\] Turn enter and exit events on or off. Disable for large rooms to reduce noise. \* **enableprofanityfilter**: (optional) \[default=true / false\] Enables profanity filtering. \* **enableautoexpiresessions**: (optional) \[defaulttrue / false\] Enables automatically expiring idle sessions, which removes inactive users from the room. \* **delaymessageseconds**: (optional) \[default=0\] Puts a delay on messages from when they are submitted until they show up in the chat. Used for throttling. \* **roomisopen**: (optional) \[true/false\] If false, users cannot perform any commands in the room, chat is suspended. \* **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. \* **customid**: (optional) A customid for the room. Can be unused, or a unique key. \* **customtype** : (optional) Custom type string. \* **custompayload** : (optional) Custom payload string. \* **customfield1** : (optional) User custom field 1. Store any string value you want here, limit 1024 bytes. \* **customfield2** : (optional) User custom field 2. Store any string value you want here, limit 1024 bytes. \* **customtags** : (optional) A comma delimited list of tags \* **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. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. ### Request example ```json { "name": "New York City Chat (Post-Moderated)", "description": "Live from the top of the Empire State Building", "moderation": "post" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/create-room-post) ## List Event History `GET /api/v3/{appid}/chat/rooms/{roomid}/listeventshistory` * 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. * This method returns a list of events sorted from oldest to newest. * This method returns all events, even those in the inactive state. ## URL PARAMETERS * **limit** : (Optional) Defaults to 100, maximum 2000. * **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. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. - `limit` (query, integer · int32): The maximum number of records to return. - `cursor` (query, string): The cursor returned by the previous page. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/list-event-history-get) ## List Events By Timestamp `GET /api/v3/{appid}/chat/rooms/{roomid}/eventsbytimestamp/list/{ts}` * This method enables you to retrieve an event using a timestamp. * You can optionally retrieve a small number of displayable events before and after the message at the requested timestamp. * This method returns a list of events sorted from oldest to newest. * This method returns only active events. * 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. * The method returns "timestampolder". This can be passed as the timestamp value when calling functions like this which accept a timestamp to retrieve data. * The method returns "timestampnewer". This can be passed as the timestamp value when calling this function again. * The method returns "cursorpolder". This can be passed as the cursor to ethods that accept an events-sorted-by-time cursor. * The method returns "cursornewer". This can be passed as the cursor to methods that accept an events-sorted-by-time cursor. ## LIMITATIONS If 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. If 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. ## URL PARAMETERS * **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. * **limitolder** : (Optional) Defaults to 0, maximum 100. * **limitnewer** : (Optional) Defaults to 0, maximum 100. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. - `ts` (path, integer · int64, required): An ISO 8601 timestamp. - `limitolder` (query, integer · int32): - `limitnewer` (query, integer · int32): ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/list-events-by-timestamp-get) ## List Events By Type `GET /api/v3/{appid}/chat/rooms/{roomid}/listeventsbytype` * 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. * This method returns a list of events sorted from newest to oldest. * This method returns only active events. * If you specify eventtype = customtype, you must pass the customtype value, a string of your choosing for your custom type. ## URL PARAMETERS * **limit** : (Optional) Defaults to 10, maximum 100. * **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. * **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 * **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. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. - `EventType` (query, integer · int32): - `CustomType` (query, string): - `limit` (query, integer · int32): The maximum number of records to return. - `cursor` (query, string): The cursor returned by the previous page. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/list-events-by-type-get) ## List Messages By User `GET /api/v3/{appid}/chat/rooms/{roomid}/messagesbyuser/{userid}` _This method requires authentication._ The 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. ### URL PARAMETERS * **roomid** : (required) The ID of the chatroom to retreive the messages by this user from * **userid** : (required) The ID of the user to fetch messages by * **cursorid** : (optional) If null / "", starts at the first messsage, and if not null, resumes cursoring ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. - `userid` (path, string, required): The customer defined user ID from your application or identity system. - `cursor` (query, string): The cursor returned by the previous page. - `limit` (query, integer · int32): The maximum number of records to return. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/list-messages-by-user-get) ## List Previous Events `GET /api/v3/{appid}/chat/rooms/{roomid}/listpreviousevents` * 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. * This method returns a list of events sorted from newest to oldest. * This method excludes events that are not in the active state (for example if they are removed by a moderator) * This method excludes non-displayable events (reaction, replace, remove, purge) * This method will not return events that were emitted and then deleted before this method was called ## URL PARAMETERS * **limit** : (Optional) Defaults to 100, maximum 500. * **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. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. - `limit` (query, integer · int32): The maximum number of records to return. - `cursor` (query, string): The cursor returned by the previous page. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/list-previous-events-get) ## List Room Participants `GET /api/v3/{appid}/chat/rooms/{roomid}/participants` _This method requires authentication._ Use this method to cursor through the people who have subscribe to the room. To 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. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. - `Cursor` (query, string): The cursor returned by the previous page. - `Limit` (query, integer · int32): The maximum number of records to return. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/list-room-participants-get) ## List Rooms `GET /api/v3/{appid}/chat/rooms` _This method requires authentication._ Rooms can be public or private. This method lists all public rooms that everyone can see. - **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. - **limit** : (optional) Specify the number of items to return. Default is 200. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `limit` (query, integer · int32): The maximum number of records to return. - `cursor` (query, string): The cursor returned by the previous page. - `filterByName` (query, string): - `filterById` (query, string): - `filterByCustomId` (query, string): ### Responses - 200: OK - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/list-rooms-get) ## List User Subscribed Rooms `GET /api/v3/{appid}/chat/user/{userid}/subscriptions` _This method requires authentication._ Use 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. To 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. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `userid` (path, string, required): The customer defined user ID from your application or identity system. - `Cursor` (query, string): The cursor returned by the previous page. - `Limit` (query, integer · int32): The maximum number of records to return. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/list-user-subscribed-rooms-get) ## Get a room by custom ID `GET /api/v3/{appid}/chat/roomsbycustomid/{customid}` _This method requires authentication._ This will return all the settings for the room and the participant count but not the participant list. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `customid` (path, string, required): A customer defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/get-a-room-by-custom-id-get) ## Get an event by custom ID `GET /api/v3/{appid}/chat/rooms/{roomid}/eventsbycustomid/{customid}` Create rooms, publish messages, subscribe users, and read live activity. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. - `customid` (path, string, required): A customer defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/get-an-event-by-custom-id-get) ## Get Event by ID `GET /api/v3/{appid}/chat/rooms/{roomid}/events/{eventid}` The comment time stamp is stored in UTC time. ### URL Arguments * **chat_room_id** : (required) The ID of the comment conversation, URL ENCODED. * **chat_event_id** : (required) The unique ID of the comment, URL ENCODED. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. - `eventid` (path, string, required): The TalkLabs assigned chat event ID. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/get-event-by-id-get) ## Get Room Details `GET /api/v3/{appid}/chat/rooms/{roomid}` _This method requires authentication._ This will return all the settings for the room and the participant count but not the participant list. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. ### Responses - 200: OK - 400: Bad Request - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/get-room-details-get) ## Get Room Extended Details Batch `GET /api/v3/{appid}/chat/rooms/batch/details` 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. You must specify one or more roomid values or customid values. You may optionally provide both roomid and customid values. You may not request more than 20 rooms at once total. You must specify at least one entity type. In the future, each entity requested will count towards your API usage quota, so don't request data you will not be using. The 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. ### URL Parameters * **roomid** : (optional) A list of room IDs. * **customid** : (optional) A list of room customIDs. * **entity** : (required) Specify one or more ENTITY TYPES to include in the response. Use one or more of the types below. * *room* : This returns the room entity. * *numparticipants* : This returns number of active participants / room subscribers. * *lastmessagetime* : This returns the time stamp for the most recent event that is a visible displayable message (speech, quote, threaded reply or announcement). ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (query, string[]): The TalkLabs assigned room ID returned when the room was created. - `customid` (query, string[]): A customer defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID. - `entity` (query, RoomEntityTypes[]): ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/get-room-extended-details-batch-get) ## Get room updates `GET /api/v3/{appid}/chat/rooms/{roomid}/updates/{cursor}` Create rooms, publish messages, subscribe users, and read live activity. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. - `cursor` (query, string): The cursor returned by the previous page. - `limit` (query, integer · int32): The maximum number of records to return. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/get-room-updates-get) ## Search Event History `POST /api/v3/{appid}/chat/searchevents` This method is still operational but its use should be replaced with Search Events. This will be discontinued March 31, 2021. This returns displayable messages (for example speech, quote, threadedreply) that are in the active state (not flagged by moderator or logically deleted). # BODY PROPERTIES * **fromuserid** : (optional) Return ony events from the specified user. * **fromhandle** : (optional) Return only events from a user with the specified handle. Exact match, case insensitive. * **roomid** : (optional) Return only events in the specified room. * **body** : (optional) Returns only messages which contain the specified body substring. * **limit** : (optional) Default is 50, maximum is 200. Limits how many items are returned. * **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 * **direction** : (optional) Defaults to Backward. Pass **forward** or **backward**. Backward is newest to oldest order, forward is oldest to newest order. * **types** : (optional) Default = all. Use this to filter for specific event types. * speech * quote * reply * announcement * custom * reaction * action * enter * exit * ad * roomopened * roomclosed * purge * remove * replace * bounce ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. ### Request example ```json { "types": [ "speech", "quote", "reply" ], "limit": 10 } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/search-event-history-post) ## Search event history with query parameters `GET /api/v3/{appid}/chat/searchevents` Create rooms, publish messages, subscribe users, and read live activity. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `FromUserId` (query, string): If specified, filters the search to only include messages where the user posting the event has this userid as an exact match - `FromHandle` (query, string): If specified, filters the search to only include messages where the user posting the event has this handle as an exact match - `Types` (query, ChatEventTypes[]): - `RoomId` (query, string): If specified, filters the search to only include events from the specified room - `Body` (query, string): If specified, performs a substring match case insensitive of the body - `Limit` (query, integer · int32): The maximum number of records to return. - `Cursor` (query, string): The cursor returned by the previous page. - `Direction` (query, integer · int32): ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/search-event-history-with-query-parameters-get) ## Join a room by custom ID `POST /api/v3/{appid}/chat/roomsbycustomid/{customid}/join` ## This method is the same as Join Room, except you can use your customid The 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. You want your chat experience to open fast. The steps to opening a chat experience are: 1. Create Room 2. Create User 3. Join Room (user gets permission to access events data from the room) 4. Get Recent Events to display in your app If you have already created the room (step 1) then you can perform steps 2 - 4 using join room. When you attempt to join the room, if the userid you provide does not exist then a user will be created for you automatically. You 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. Join may be used to create a new user. Join may not be used to update an existing user. ## DATA PARAMETERS - 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. - You can optionally also provide a URL to an image and a URL to a profile. - If you provide user information and the user already exists in the database, the user will not be updated. - The user will be added to the list of participants in the room and the room participant count will increase. - The user will be removed from the room automatically after some time if the user doesn't perform any operations. - Users can only execute commands in the room if they have joined the room. - When a logged in user joins a room an entrance event is generated in the room. - When a logged in user leaves a room, an exit event is generated in the room. **Creating A New User**: You have the option to create or update an existing user during join. * **limit** : (optional) Defaults to 50. This limits the number of previous messages returned when joining the room. * **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. * **handle**: (Optional) A unique string representing the user that is easy for other users to type. * Example @GeorgeWashington could be the handle but Display Name could be "Wooden Teef For The Win". * 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 by adding a number from 1-99 and returned. * 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. * Only these characters may be used: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890_" * **displayname**: _Optional_. This is the desired name to display, typically the real name of the person. * **pictureurl**: _Optional_. The URL to the picture for this user. * **profileurl**: _Optional_. The profileurl for this user. * **role**: _Optional_. Valid roles are "user" (default), "moderator" and "admin". * **customtags**: _Optional_. A list of strings to attach to the user object. ## RESPONSE CODES * **200 | OK** : Sweet, sweet success. * **400 | BadRequest** : Something is wrong with your request. View response message and errors list for details. * **403 | Forbidden** : Request is not authorized with a valid token. * **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. * **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 - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `customid` (path, string, required): A customer defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID. ### Request example ```json { "limit": 50 } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 405: Method Not Allowed - 409: Conflict - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/join-a-room-by-custom-id-post) ## Join Room `POST /api/v3/{appid}/chat/rooms/{roomid}/join` _Requires Authentication._ You want your chat experience to open fast. The steps to opening a chat experience are: 1. Create Room 2. Create User 3. Join Room (user gets permission to access events data from the room) 4. Get Recent Events to display in your app If you have already created the room (step 1) then you can perform steps 2 - 4 using join room. When you attempt to join the room, if the userid you provide does not exist then a user will be created for you automatically. You 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. Join may be used to create a new user. Join may not be used to update an existing user. ## BODY PARAMETERS - 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. - You can optionally also provide a URL to an image and a URL to a profile. - If you provide user information and the user already exists in the database, the user will be updated with the new information. - The user will be added to the list of participants in the room and the room participant count will increase. - The user will be removed from the room automatically after some time if the user doesn't perform any operations. - Users can only execute commands in the room if they have joined the room. - When a logged in user joins a room an entrance event is generated in the room. - When a logged in user leaves a room, an exit event is generated in the room. - **limit** : (optional) Defaults to 50. This limits the number of previous messages returned when joining the room. **Creating A New User**: You have the option to create or update an existing user during join. - **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. - **handle**: (Optional) A unique string representing the user that is easy for other users to type. - Example @GeorgeWashington could be the handle but Display Name could be "Wooden Teef For The Win". - 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 by adding a number from 1-99 and returned. - 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. - Only these characters may be used: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890_" - **displayname**: _Optional_. This is the desired name to display, typically the real name of the person. - **pictureurl**: _Optional_. The URL to the picture for this user. - **profileurl**: _Optional_. The profileurl for this user. - **role**: _Optional_. Valid roles are "user" (default), "moderator" and "admin". - **usercustomtags**: _Optional_. A list of strings to attach to the user object. ## RESPONSE CODES - **200 | OK** : Sweet, sweet success. - **400 | BadRequest** : Something is wrong with your request. View response message and errors list for details. - **403 | Forbidden** : Request is not authorized with a valid token. - **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. - **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 - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. ### Request example ```json { "handle": "dave_m", "role": "admin" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 405: Method Not Allowed - 409: Conflict - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/join-room-post) ## Update Chat Message Content `PUT /api/v3/{appid}/chat/rooms/{roomid}/events/{eventid}` 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. ### URL Arguments * **roomid** : (required) The ID of the chat room conversation * **eventid** : (required) The unique ID of the chat event to be edited. This must be a messsage type event (speech, quote or reply). ### BODY Properties * **userid** : (required) The application specific user ID updating the chat event. This must be the owner of the comment or moderator / admin. * **body** : (required) The new body contents of the event. * **customid** : (optional) Optionally replace the customid. * **custompayload** : (optional) Optionally replace the payload of the event. * **customfield1** : (optional) Optionally replace the customfield1 value. * **customfield2** : (optional) Optionally replace the customfield2 value. * **customtags** : (optional) Optionaly replace the custom tags. The comment will be flagged to indicate that it has been modified. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. - `eventid` (path, string, required): The TalkLabs assigned chat event ID. ### Request example ```json { "body": "Message has been modified", "userId": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/update-chat-message-content-put) ## Update Room `POST /api/v3/{appid}/chat/rooms/{roomid}` *This method requires authentication.* * __userid__: (optional) The owner of the room * __name__: (optional) The name of the room * __description__: (optional) The description of the room * __moderation__: (optional) [premoderation/postmoderation] Defaults to post-moderation. * __enableactions__: (optional) [true/false] Turns action commands on or off * __enableenterandexit__: (optional) [true/false] Turn enter and exit events on or off. Disable for large rooms to reduce noise. * __enableprofanityfilter__: (optional) [default=true / false] Enables profanity filtering. * **enableautoexpiresessions**: (optional) [defaulttrue / false] Enables automatically expiring idle sessions, which removes inactive users from the room. * __delaymessageseconds__: (optional) [default=0] Puts a delay on messages from when they are submitted until they show up in the chat. Used for throttling. * __roomisopen__: (optional) [true/false] If false, users cannot perform any commands in the room, chat is suspended. * __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. # Creates a new chat room *This method requires authentication.* * **name**: (required) The name of the room * **description**: (optional) The description of the room * **pictureurl**: (optional) The URL for a picture for the room * **moderation**: (optional) ["pre"/"post"] Defaults to post-moderation. * **enableactions**: (optional) [true/false] Turns action commands on or off * **enableenterandexit**: (optional) [true/false] Turn enter and exit events on or off. Disable for large rooms to reduce noise. * **enableprofanityfilter**: (optional) [default=true / false] Enables profanity filtering. * **delaymessageseconds**: (optional) [default=0] Puts a delay on messages from when they are submitted until they show up in the chat. Used for throttling. * **roomisopen**: (optional) [true/false] If false, users cannot perform any commands in the room, chat is suspended. * **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. * **customid**: (optional) A customid for the room. Can be unused, or a unique key. * **customtype** : (optional) Custom type string. * **custompayload** : (optional) Custom payload string. * **customfield1** : (optional) User custom field 1. Store any string value you want here, limit 1024 bytes. * **customfield2** : (optional) User custom field 2. Store any string value you want here, limit 1024 bytes. * **customtags** : (optional) A comma delimited list of tags ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. ### Request example ```json { "name": "ROOM HAS NEW NAME", "description": "Live from the top of the Empire State Building", "moderation": "post" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/update-room-post) ## Execute a chat command `POST /api/v3/{appid}/chat/rooms/{roomid}/command` Publish a normal chat message or execute a configured command. Send 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. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. ### Request example ```json { "command": "", "userid": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 409: Conflict - 412: Precondition Failed — the user must join the room first. - 418: Too many messages were sent in a short interval. [Web reference](https://talklabs.ai/docs/reference/chat/execute-a-chat-command-post) ## Exit a Room `POST /api/v3/{appid}/chat/rooms/{roomid}/exit` _Requires Authentication._ This 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. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. ### Request example ```json { "userId": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/exit-a-room-post) ## Quote a Message `POST /api/v3/{appid}/chat/rooms/{roomid}/events/{eventid}/quote` 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). ## URL PARAMETERS * **appid** : (required) The ID of your application * **chatroomid** : (required) The ID of your chat room * **eventid** : (required) The ID of the event you are quoting ## BODY PARAMETERS * **userid** : (Required) The userid of the user who is publishing the quoted reply * **body** : (Required) The contents of the reply for the quoted reply. Cannot be empty. * **customid**: (Optional) Assigns a custom ID to the quoted reply event. * **custompayload**: (Optional) Attach a custom payload string to the quoted reply such as JSON or XML. * **customfield1**: (Optional) Use this field however you wish * **customfield2**: (Optional) Use this field however you wish * **customtags**: (Optional) An array of strings, use this field however you wish. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. - `eventid` (path, string, required): The TalkLabs assigned chat event ID. ### Request example ```json { "body": "Mind if I quote you?", "userId": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/quote-a-message-post) ## React To A Message ("Like") `POST /api/v3/{appid}/chat/rooms/{roomid}/events/{eventid}/react` 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. ### POST PARAMETERS - **userid**: (required) The ID of the user who is reacting. - **reaction**: (required) A string for the reaction such as "like", or "emoji:{emojid}" which accepts a standard unicode value for an emoji. - **reacted**: (required) true to add reaction or false to remove the reaction. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. - `eventid` (path, string, required): The TalkLabs assigned chat event ID. ### Request example ```json { "reaction": "like", "reacted": "true", "userId": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/react-to-a-message-like-post) ## Reply to a Message (Threaded) `POST /api/v3/{appid}/chat/rooms/{roomid}/events/{eventid}/reply` 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. * Replies do not support admin or action commands ## URL PARAMETERS * **appid** : (required) The ID of your application * **chatroomid** : (required) The ID of your chat room * **eventid** : (required) The ID of the event you are quoting ## BODY PARAMETERS * **userid** : (Required) The userid of the user who is publishing the quoted reply * **body** : (Required) The contents of the reply for the quoted reply. Cannot be empty. * **customid**: (Optional) Assigns a custom ID to the quoted reply event. * **custompayload**: (Optional) Attach a custom payload string to the quoted reply such as JSON or XML. * **customfield1**: (Optional) Use this field however you wish * **customfield2**: (Optional) Use this field however you wish * **customtags**: (Optional) An array of strings, use this field however you wish. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. - `eventid` (path, string, required): The TalkLabs assigned chat event ID. ### Request example ```json { "body": "I spy with my little eye an opportunity to post a reply!", "userId": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/reply-to-a-message-threaded-post) ## Report Message `POST /api/v3/{appid}/chat/rooms/{roomid}/events/{eventid}/report` A reported message is temporarily removed from the chat event stream until it is evaluated by a moderator. ## POST PARAMETERS - **userid** : (optional) The application provided userid of the user who reported the abuse. - **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: - abuse - spam - selfharm - hate - violence - harassment - nudity - illegal - false - other ## RESPONSE CODES - **200 | OK** : Sweet, sweet success. - **400 | BadRequest** : Something is wrong with your request. View response message and errors list for details. - **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. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. - `eventid` (path, string, required): The TalkLabs assigned chat event ID. ### Request example ```json { "reportType": {}, "userId": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/report-message-post) ## Touch Session ("keep alive") `POST /api/v3/{appid}/chat/rooms/{roomid}/sessions/{userid}/touch` 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. You can configure a room to not auto-expire sessions in the settings for that room. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. - `userid` (path, string, required): The customer defined user ID from your application or identity system. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/touch-session-keep-alive-post) ## Event Set Deleted (Logical Delete) `PUT /api/v3/{appid}/chat/rooms/{roomid}/events/{eventid}/setdeleted` 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. ## BODY PARAMETERS - **deleted**: (required) true to delete the event, false to undelete the event. - **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. - 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. ## RESPONSE CODES - **200 | OK** : Sweet, sweet success. - **400 | BadRequest** : Something is wrong with your request. View response message and errors list for details. - **403 | Forbidden** : The userid issuing the request is banned from chatting in this room (or is banned globally). - **405 | MethodBlocked** : The method was blocked because it contained profanity and filtermode was set to 'block'. - **409 | Conflict** : The customid of your event is already in use. - **412 | PreconditionFailed** : User must JOIN the room before executing a chat command. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. - `eventid` (path, string, required): The TalkLabs assigned chat event ID. - `Deleted` (query, boolean, required): - `UserId` (query, string, required): The customer defined user ID from your application or identity system. - `PermanentIfNoReplies` (query, boolean, required): ### Request example ```json { "deleted": true, "permanentifnoreplies": false, "userid": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/event-set-deleted-logical-delete-put) ## Delete all events in a room `DELETE /api/v3/{appid}/chat/rooms/{roomid}/events` Create rooms, publish messages, subscribe users, and read live activity. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/delete-all-events-in-a-room-delete) ## Delete Event `DELETE /api/v3/{appid}/chat/rooms/{roomid}/events/{eventid}` 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. ## URL Parameters - **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. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. - `eventid` (path, string, required): The TalkLabs assigned chat event ID. - `userid` (query, string): The customer defined user ID from your application or identity system. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/delete-event-delete) ## Delete Room `DELETE /api/v3/{appid}/chat/rooms/{roomid}` This cannot be reversed. This command permanently deletes the chat room and all events in it. ## URL Parameters * **roomid** : (required) The room to be deleted. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/delete-room-delete) ## Reset Room `POST /api/v3/{appid}/chat/rooms/{roomid}/reset` ## 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 ### URL Arguments - **roomid** : (required) The ID of the room ### POST BODY Arguments - **removeusereffects** : (optional | false) If true, all effects applied to users in this room are removed from this room only ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `RoomId` (path, string, required): The TalkLabs assigned room ID returned when the room was created. ### Request example ```json {} ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat/reset-room-post) # Comments Create conversations, publish replies, and add reactions or votes. ## Create / Update Conversation `POST /api/v3/{appid}/comment/conversations` If a conversation with the specified ID already exists, this will update it. Custom 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). ### BODY Properties - **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. - **conversationid** : (required) The conversation ID. This must be a URL friendly string (cannot contain / ? or other URL delimiters). Maximum length is 250 characters. - **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. - **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: - _dev_, _uat_, _stage_, _prod_ - _website_, _mobile_ - _site1.com_, _site2.com_ - **moderation** : (required) Specify if _pre_ or _post_ moderation is to be used - **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 - **title** : (optional) The title of the conversation - **maxcommentlen**: (optional) The maximum allowed length of a comment. Default is 256 characters. Maximum value is 10485760 (10 MB) - **open**: (optional, defaults to _true_) If the conversation is open people can add comments. - **enableprofanityfilter**: (optional, defaults to true) Filters comments for known profanities and replaces them with \* chars. - **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" - **customid** : (optional) 250 characters for a custom ID for your app. This field is indexed for high performance object retrieval. - **customtype** : (optional) Custom type string. - **custompayload** : (optional) Custom payload string. - **customfield1** : (optional) User custom field 1. Store any string value you want here, limit 1024 bytes. - **customfield2** : (optional) User custom field 2. Store any string value you want here, limit 1024 bytes. - **customtags** : (optional) A comma delimited list of tags ### Parameters - `appid` (path, string, required): The appid of your app ### Request example ```json { "property": "", "moderation": "post", "title": "Sample Conversation", "open": true, "conversationId": "conversation-id" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comments/create-update-conversation-post) ## Create and Publish Comment `POST /api/v3/{appid}/comment/conversations/{conversationid}/comments` You can optionally make this comment into a reply by passing in the optional replyto field. Custom 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). ### URL Arguments - **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. ### BODY Properties - **userid** : (required) The application's userid representing the user who submitted the comment - **body** : (required) The body of the comment (the message). Supports unicode characters including EMOJIs and international characters. - **replyto** : (optional) The ID of the comment that this is a reply to. - **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" ### OPTIONAL BODY Properties to Create or Update a User If 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 - **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. - **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". - **displayname**: _Optional_. This is the desired name to display, typically the real name of the person. - **pictureurl**: _Optional_. The URL to the picture for this user. - **profileurl**: _Optional_. The profileurl for this user. - **displayname** : (required if creating a new user, otherwise optional) The non-unique name to display when showing the user's name - **pictureurl** : (optional) A URL to the user's photo - **profileurl** : (optional) A URL to the user's profile - **role**: _Optional_. Valid roles are "user" (default), "moderator" and "admin". - **usercustomtags**: _Optional_. A list of strings to attach to the user object. - **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. - **customtype** : (optional) Custom type string. - **custompayload** : (optional) Custom payload string. - **customfield1** : (optional) User custom field 1. Store any string value you want here, limit 1024 bytes. - **customfield2** : (optional) User custom field 2. Store any string value you want here, limit 1024 bytes. - **customtags** : (optional) A comma delimited list of tags ### RESPONSE CODES - **200 | OK** : Sweet, sweet success. - **204 | NoContent** : The content was blocked because it contained profanity and filtermode was set to 'block'. - **400 | BadRequest** : Something is wrong with your request. View response message and errors list for details. - **403 | Forbidden** : The userid issuing the request is banned from commenting. - **409 | Conflict** : The customid of your event is already in use. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `conversationid` (path, string, required): The TalkLabs assigned conversation ID. ### Request example ```json { "body": "Hello, World!", "userId": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 405: Method Not Allowed - 409: Conflict - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comments/create-and-publish-comment-post) ## List Comments `GET /api/v3/{appid}/comment/conversations/{conversationid}/comments` ## GETTING THE RIGHT COMMENTS - If you use ListComments you will get the top level comments. - If you use List Replies you will get comments that are children of another comment. - If you want all replies lower in the tree of comments than the current level use the includechildren property. ## READ THIS: Cursoring Limitations for Offset Cursors 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. ### Cursoring - API Method returns a cursor - Cursor includes a "more" field indicating if there are more results that can be read at the time this call is made - Cursor includes "cursor" field, which can be passed into subsequent calls to this method to get additionaal results - Cursor includes "itemcount" field, which is the number of items returned by the cursor not the total number of items in the database - All LIST methods in the API return cursors and they all work the same way ### URL Arguments - **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED. ### URL Parameters - **cursor** : (optional) If provided, will get the next bundle of comments in the conversation resuming from where the cursor left off. - **limit** : (Optional, default = 200). For cursoring, limit the number of responses for this request. - **direction**: (optional) Default is forward. Must be **forward** or **backward** - **sort** : (optional, defaults to "oldest") Specifies that sort should be done by... - **oldest** : Sort by when added ascending (oldest on top) - **newest** : Sort by when added ascending (newest on top) - **likes** : Sort by number of likes, descending (most liked on top) - **votescore** : Sort by net of adding upvotes and subtracting downvotes, descending - **mostreplies** : Sort by number of replies,descending - **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. - 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. - **filterpostedbyuserid**: (optional) If provided, the list returned will be filtered to only include comments published by the specified userid. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `conversationid` (path, string, required): The TalkLabs assigned conversation ID. - `sort` (query, string): - `cursor` (query, string): The cursor returned by the previous page. - `limit` (query, integer · int32): The maximum number of records to return. - `direction` (query, string): - `includechildren` (query, boolean): - `includeinactive` (query, boolean): - `filterPostedByUserId` (query, string): ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comments/list-comments-get) ## List Conversations `GET /api/v3/{appid}/comment/conversations` ### Cursoring - API Method returns a cursor - Cursor includes a "more" field indicating if there are more results that can be read at the time this call is made - Cursor includes "cursor" field, which can be passed into subsequent calls to this method to get additional results - Cursor includes "itemcount" field, which is the number of items returned by the cursor not the total number of items in the database - All LIST methods in the API return cursors and they all work the same way ### Optional Parameters - **propertyid** : Filters list of conversations by property. Exact match only, case sensitive. - **cursor** : (Optional, default = ""). For cusoring, pass in cursor output from previous call to continue where you left off. - **limit** : (Optional, default = 200). For cursoring, limit the number of responses for this request. - **sort** : (Optional, default = "oldest"). - **newest** : Default. Sorts from newest created conversation to the oldest. - **oldest** : Starts from oldest conversation and cursors towards the newest. - **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). - **filterStartTime** : (Optional, default=""). ISO8601 datetime. When provided, only conversations created on or after this time are returned. Example: "2024-01-26T20:25:37.667Z" - **filterEndTime** : (Optional, default=""). ISO8601 datetime. When provided, only conversations created bn or before this time are returned. Retrieves 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. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `propertyid` (query, string): - `title` (query, string): - `conversationid` (query, string): The TalkLabs assigned conversation ID. - `customid` (query, string): A customer defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID. - `cursor` (query, string): The cursor returned by the previous page. - `limit` (query, integer · int32): The maximum number of records to return. - `sort` (query, string): - `filterStartTime` (query, string · date-time): - `filterEndTime` (query, string · date-time): ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comments/list-conversations-get) ## List Replies `GET /api/v3/{appid}/comment/conversations/{conversationid}/comments/{commentid}/replies` 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. ## GETTING THE RIGHT COMMENTS - If you use ListComments you will get the top level comments. - If you use List Replies you will get comments that are children of another comment. - If you want all replies lower in the tree of comments than the current level use the includechildren property. ## READ THIS - ABOUT CURSORING WITH OFFSET CURSORS - 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. - 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. ### ABOUT CURSORING - API Method returns a cursor - Cursor includes a "more" field indicating if there are more results that can be read at the time this call is made - Cursor includes "cursor" field, which can be passed into subsequent calls to this method to get additionaal results - Cursor includes "itemcount" field, which is the number of items returned by the cursor not the total number of items in the database - All LIST methods in the API return cursors and they all work the same way ### URL Arguments - **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED. ### URL Parameters - **cursor** : (optional) If provided, will get the next bundle of comments in the conversation resuming from where the cursor left off. - **limit** : (Optional, default = 200). For cursoring, limit the number of responses for this request. - **direction**: (optional) Default is forward. Must be **forward** or **backward** - **sort** : (optional, defaults to "oldest") Specifies that sort should be done by... - **oldest** : Sort by when added ascending (oldest on top) - **newest** : Sort by when added ascending (newest on top) - **likes** : Sort by number of likes, descending (most liked on top) - **votescore** : Sort by net of adding upvotes and subtracting downvotes, descending - **mostreplies** : Sort by number of replies,descending - **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. - **includeinactive** : (optional, default is false) If true, return comments that are inactive (for example, disabled by moderation) - **filterpostedbyuserid**: (optional) If provided, the list returned will be filtered to only include comments published by the specified userid. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `conversationid` (path, string, required): The TalkLabs assigned conversation ID. - `commentid` (path, string, required): The TalkLabs assigned comment ID. - `sort` (query, string): - `cursor` (query, string): The cursor returned by the previous page. - `limit` (query, integer · int32): The maximum number of records to return. - `direction` (query, string): - `includechildren` (query, boolean): - `includeinactive` (query, boolean): - `filterpostedbyuserid` (query, string): ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comments/list-replies-get) ## List Replies Batch `GET /api/v3/{appid}/comment/conversations/{conversationid}/repliesbyparentidbatch` 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. You 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: * This method does not support cursoring. * 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. * 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. * This method will return the children that are direct immediate child replies to the parent only, not an entire tree under a parent. * 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. ### URL Arguments * **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED. ### URL Parameters * **childlimit** : (Optional, default = 50). * **parentids** : (Required). A comma delimited list of parentids, up to 30. * **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. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `conversationid` (path, string, required): The TalkLabs assigned conversation ID. - `childlimit` (query, integer · int32): - `parentids` (query, string): - `includeinactive` (query, boolean): ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comments/list-replies-batch-get) ## Find a conversation by custom ID `GET /api/v3/{appid}/comment/find/conversation/bycustomid` 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. ### URL Parameters * **customid** : (Required) Locates a conversation using the custom ID. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `CustomId` (query, string): A customer defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comments/find-a-conversation-by-custom-id-get) ## Get Comment by ID `GET /api/v3/{appid}/comment/conversations/{conversationid}/comments/{commentid}` The comment time stamp is stored in UTC time. ### URL Arguments * **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED. * **comment_comment_id** : (required) The unique ID of the comment, URL ENCODED.* ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `conversationid` (path, string, required): The TalkLabs assigned conversation ID. - `commentid` (path, string, required): The TalkLabs assigned comment ID. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comments/get-comment-by-id-get) ## Get Conversation by ID `GET /api/v3/{appid}/comment/conversations/{conversationid}` Retrieves metadata about a conversation. ### URL Arguments * **comment_conversation_id** : (required) The ID of the conversation which is a context for comments. The ID must be URL ENCODED. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `conversationid` (path, string, required): The TalkLabs assigned conversation ID. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comments/get-conversation-by-id-get) ## Batch Get Conversation Details `GET /api/v3/{appid}/comment/conversations/details/batch` 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. You 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. The API will return a JSON document containing a list of child objects each containing the requested metadata (see entities property). ### URL PARAMETERS - ids: (optional): Include one or more comma delimited Sportstalk conversation IDs. - 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. - entities (optional): By default only the conversation object data is returned. For more data (and deeper queries) provide any of these entities: - **reactions**: Includes user reactions and microprofiles in the response - **likecount**: Includes number of likes on the conversation in the response, otherwise returns -1 for like count. - **commentcount**: Includes the number of comments in the response, otherwise returns -1 for comment count. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `propertyid` (query, string): - `ids` (query, string): - `cid` (query, string[]): - `Entities` (query, string): ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comments/batch-get-conversation-details-get) ## Set Comment Logically Deleted `PUT /api/v3/{appid}/comment/conversations/{conversationid}/comments/{commentid}/setdeleted` * The comment is not actually deleted. The comment is flagged as deleted, and can no longer be read, but replies are not deleted. * If flag "permanentifnoreplies" is true, then it will be a permanent delete instead of logical delete for this comment if it has no children. * 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. ### URL Arguments * **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED. * **comment_comment_id** : (required) The unique ID of the comment, URL ENCODED. ### URL Parameters * **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. * **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. * **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". If 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. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `conversationid` (path, string, required): The TalkLabs assigned conversation ID. - `commentid` (path, string, required): The TalkLabs assigned comment ID. - `userid` (query, string): The customer defined user ID from your application or identity system. - `deleted` (query, boolean): - `permanentifnoreplies` (query, boolean): ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comments/set-comment-logically-deleted-put) ## Update Comment `PUT /api/v3/{appid}/comment/conversations/{conversationid}/comments/{commentid}` ### URL Arguments * **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED. * **comment_comment_id** : (required) The unique ID of the comment, URL ENCODED. ### BODY Properties * **userid** : (required) The application specific user ID of the comment to be updated. This must be the owner of the comment or moderator / admin. * **body** : (required) The new body contents of the comment. The comment will be flagged to indicate that it has been modified. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `conversationid` (path, string, required): The TalkLabs assigned conversation ID. - `commentid` (path, string, required): The TalkLabs assigned comment ID. ### Request example ```json { "body": "Comment has been modified", "userId": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comments/update-comment-put) ## React to a conversation `POST /api/v3/{appid}/comment/conversations/{conversationid}/react` 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. ### BODY Properties - **userid** : (required) The ID of the user reacting to the comment. Anonymous reactions are not supported. - **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. - **reacted** : (required) true or false, to toggle the reaction on or off for this user. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `conversationid` (path, string, required): The TalkLabs assigned conversation ID. ### Request example ```json { "reaction": "like", "reacted": true, "userId": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comments/react-to-a-conversation-post) ## React To Comment `POST /api/v3/{appid}/comment/conversations/{conversationid}/comments/{commentid}/react` A reaction can be added using any reaction string that you wish. ### BODY Properties - **userid** : (required) The ID of the user reacting to the comment. Anonymous reactions are not supported. - **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. - **reacted** : (required) true or false, to toggle the reaction on or off for this user. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `conversationid` (path, string, required): The TalkLabs assigned conversation ID. - `commentid` (path, string, required): The TalkLabs assigned comment ID. ### Request example ```json { "reaction": "like", "reacted": true, "userId": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comments/react-to-comment-post) ## Reply to Comment `POST /api/v3/{appid}/comment/conversations/{conversationid}/comments/{commentid}` 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. See **WEBHOOKS SERVICE API** for information on receiving a notification when someone replies to a comment. See documentation on **Create and Publish Comment** ### URL Arguments - **comment_conversation_id** : (required) The ID of the comment conversation. - **comment_comment_id** : (required) The unique ID of the comment we will reply to. ### BODY Parameters - **userid** : (required) The application's userid representing the user who submitted the comment - **body** : (required) The body of the reply (what the user is saying). Supports unicode characters including EMOJIs and international characters. - **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. ### OPTIONAL BODY Properties to Create or Update a User If 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 - **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. - **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". - **displayname**: _Optional_. This is the desired name to display, typically the real name of the person. - **pictureurl**: _Optional_. The URL to the picture for this user. - **profileurl**: _Optional_. The profileurl for this user. - **displayname** : (required if creating a new user, otherwise optional) The non-unique name to display when showing the user's name - **pictureurl** : (optional) A URL to the user's photo - **profileurl** : (optional) A URL to the user's profile - **customid** : (optional) 250 characters for a custom ID for your app. This field is indexed for high performance object retrieval. - **customtype** : (optional) Custom type string. - **custompayload** : (optional) Custom payload string. - **customfield1** : (optional) User custom field 1. Store any string value you want here, limit 1024 bytes. - **customfield2** : (optional) User custom field 2. Store any string value you want here, limit 1024 bytes. - **customtags** : (optional) A comma delimited list of tags ### RESPONSE CODES - **200 | OK** : Sweet, sweet success. - **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. - **400 | BadRequest** : Something is wrong with your request. View response message and errors list for details. - **403 | Forbidden** : The userid issuing the request is banned from commenting. - **409 | Conflict** : The customid of your event is already in use. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `conversationid` (path, string, required): The TalkLabs assigned conversation ID. - `commentid` (path, string, required): The TalkLabs assigned comment ID. ### Request example ```json { "body": "This is a reply.", "userId": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comments/reply-to-comment-post) ## Vote on Comment `POST /api/v3/{appid}/comment/conversations/{conversationid}/comments/{commentid}/vote` ### URL Arguments * **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED. * **comment_comment_id** : (required) The unique ID of the comment, URL ENCODED. ### BODY Properties * **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. * **userid** : (required) The application specific user id performing the action. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `conversationid` (path, string, required): The TalkLabs assigned conversation ID. - `commentid` (path, string, required): The TalkLabs assigned comment ID. ### Request example ```json { "vote": "up", "userId": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comments/vote-on-comment-post) ## Delete Comment (permanent) `DELETE /api/v3/{appid}/comment/conversations/{conversationid}/comments/{commentid}` ### URL Arguments * **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED. * **comment_comment_id** : (required) The unique ID of the comment, URL ENCODED. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `conversationid` (path, string, required): The TalkLabs assigned conversation ID. - `commentid` (path, string, required): The TalkLabs assigned comment ID. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comments/delete-comment-permanent-delete) ## Delete Conversation `DELETE /api/v3/{appid}/comment/conversations/{conversationid}` ## CANNOT BE UNDONE. This deletes all history of a conversation including all comments and replies within it. ### URL Arguments * **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `conversationid` (path, string, required): The TalkLabs assigned conversation ID. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comments/delete-conversation-delete) ## Reset Conversation `POST /api/v3/{appid}/comment/conversations/{conversationid}/reset` ## CANNOT BE UNDONE. This deletes all history of a conversation including all comments and replies within it. ### URL Arguments - **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `conversationId` (path, string, required): The TalkLabs assigned conversation ID. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comments/reset-conversation-post) # Polls Create polls, manage choices, collect votes, and read standings. ## Create Lead `POST /api/v3/{appid}/poll/poll/{pollid}/lead` _This method requires authentication._ This 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. - **pollid**: (required) The id of the poll - **firstname**: (optional) The first name of the user responding - **lastname**: (optional) The last name of the user responding - **email:** (required) The email address of the user responding | Response Code | Description | | --- | --- | | 200 | OK | | 400 | Bad Request, not formatted correctly. See response for details | | 403 | Forbidden, token doesn't have permission to do this operation | | 409 | Conflict, request is formatted OK but violates a rule | ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `pollid` (path, string, required): The TalkLabs assigned poll ID. ### Request example ```json { "email": "potus@test.com", "pollId": "poll-id" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/polls/create-lead-post) ## Create or Update Choice `POST /api/v3/{appid}/poll/poll/{pollid}/choice` _This method requires authentication._ Use 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 \* **id**: (optional) If specified, the poll choice with this ID will be updated \* **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. \* **title**: (optional) This is the text displayed with the choice. \* **imageurl**: (optional) You can use this field to set the URL for an image \* **videoid**: (optional) A field to store the ID of a video \* **embedcode**: (optional) Store content that can be used to display the choice. \* **vidoeurl**: (optional) This field may be used to store the URL for a video \* **customid**: (optional) A customid for the room. Can be unused, or a unique key. \* **customtype** : (optional) Custom type string. \* **custompayload** : (optional) Custom payload string. \* **customfield1** : (optional) User custom field 1. Store any string value you want here, limit 1024 bytes. \* **customfield2** : (optional) User custom field 2. Store any string value you want here, limit 1024 bytes. \* **customtags** : (optional) A comma delimited list of tags \* **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. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `pollid` (path, string, required): The TalkLabs assigned poll ID. ### Request example ```json { "position": -1, "title": "Red" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/polls/create-or-update-choice-post) ## Create or Update Poll `POST /api/v3/{appid}/poll/poll/create` 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. When 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. #### METADATA - **ownerid**: (required) The userid of the owner of the poll #### DISPLAY PROPERTIES - **title**: (required) The title of the poll. Required on create. Optional on update. - **description**: (optional) The description of the poll - **pictureurl**: (optional) The URL for a picture for the room - **embedcontenttop**: (optional) Content to be displayed at the top of the poll - **embedcontentbottom**: (optional) Content to be displayed at the bottom of the poll - **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. - **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. #### BEHAVIOR SETTINGS - **allowanonymouspolling:** (optional, default=false), if true, allows users to submit responses without a userid value. - **allowmultiplechoicesperuser**: ("true" or default = "false") If true, the user may submit answers for more than one choice. - **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. - **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. #### AUTO PUBLISH SETTINGS - **whenpollpublish**: (optional) \[default=now\] An ISO-8601 date time. Now by default. If specified, poll is hidden until the specified date and time. - **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). - **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. - **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. #### LEAD CAPTURE - **leadcaptureenabled**: (optional, default=false) If true, enables lead capture for the poll. - **leadcapturerequired**: (optional, default=false) If true, makes lead capture required for the poll. - **leadcapturename**: (optional) If true, captures the name of the lead. - **leadcapturetitle**: (optional) The title for the lead capture form. - **leadcapturedescription**: (optional) The description for the lead capture form. - **leadcaptureprompt**: (optional) The prompt for the lead capture form. #### SOCIAL SHARE - **socialshareenable**: (optional, default=false) If true, enables social sharing for the poll. - **socialhandlefacebook**: (optional) The Facebook handle for social sharing. - **socialhandlex**: (optional) The X (formerly Twitter) handle for social sharing. - **socialhandletiktok**: (optional) The TikTok handle for social sharing. - **socialhandlewhatsapp**: (optional) The WhatsApp handle for social sharing. - **socialcardtitle**: (optional) The title for the social card. - **socialcardimageurl**: (optional) The image URL for the social card. - **socialcardurl**: (optional) The URL for the social card. #### CUSTOM FIELDS - **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. - **customtype** : (optional) Custom type string. - **custompayload** : (optional) Custom payload string. - **customfield1** : (optional) User custom field 1. Store any string value you want here, limit 1024 bytes. - **customfield2** : (optional) User custom field 2. Store any string value you want here, limit 1024 bytes. - **customtags** : (optional) A comma delimited list of tags ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. ### Request example ```json { "title": "What is your favorite color?", "description": "Vote for your favorite color" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/polls/create-or-update-poll-post) ## Create Poll Response (Cast a vote) `POST /api/v3/{appid}/poll/poll/{pollid}/response` _This method requires authentication._ Use thsi method to respond to a poll or cast a vote. \* **pollid**: (required) The id of the poll \* **userid**: (required) The id of the user responding \* **choiceid**: (optional) The selected choice | Response Code | Description | |---------------|--------------------------------------------------------------| | 200 | OK | | 400 | Bad Request, not formatted correctly. See response for details | | 403 | Forbidden, token doesn't have permission to do this operation | | 409 | Conflict, request is formatted OK but violates a rule | ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `pollid` (path, string, required): The TalkLabs assigned poll ID. ### Request example ```json { "choiceId": "", "pollID": "poll-id" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/polls/create-poll-response-cast-a-vote-post) ## List all poll responses `GET /api/v3/{appid}/poll/poll/{pollid}/responses/all` UserId is the user who is requesting the responses. If the poll doesn't allow responses to come out unless you have responded it needs to be enforced here ### Parameters - `appid` (path, string, required): - `pollid` (path, string, required): - `UserId` (query, string): ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/polls/list-all-poll-responses-get) ## List Choices for Poll `GET /api/v3/{appid}/poll/poll/{pollid}/choices` _This method requires authentication._ Rooms can be public or private. This method lists all public rooms that everyone can see. * **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. * **limit** : (optional) Specify the number of items to return. Default is 200. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `pollid` (path, string, required): The TalkLabs assigned poll ID. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/polls/list-choices-for-poll-get) ## List poll leads `GET /api/v3/{appid}/poll/poll/{pollid}/leads` Create polls, manage choices, collect votes, and read standings. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `pollid` (path, string, required): The TalkLabs assigned poll ID. - `limit` (query, integer · int32): The maximum number of records to return. - `cursor` (query, string): The cursor returned by the previous page. ### Responses - 200: OK - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/polls/list-poll-leads-get) ## List poll responses `GET /api/v3/{appid}/poll/poll/{pollid}/responses` Create polls, manage choices, collect votes, and read standings. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `pollid` (path, string, required): The TalkLabs assigned poll ID. - `limit` (query, integer · int32): The maximum number of records to return. - `cursor` (query, string): The cursor returned by the previous page. ### Responses - 200: OK - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/polls/list-poll-responses-get) ## List Polls `GET /api/v3/{appid}/poll/poll` _This method requires authentication._ Rooms can be public or private. This method lists all public rooms that everyone can see. - **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. - **limit** : (optional) Specify the number of items to return. Default is 200. - **includeUnpublished**: (optional: false). If set to true, the function will include polls that are not yet published. Requires createpoll permission. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `IncludeUnpublished` (query, boolean): - `limit` (query, integer · int32): The maximum number of records to return. - `cursor` (query, string): The cursor returned by the previous page. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/polls/list-polls-get) ## List Responses by User `GET /api/v3/{appid}/poll/poll/{pollid}/responses/user/{userid}` _This method requires authentication._ Rooms can be public or private. This method lists all public rooms that everyone can see. * **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. * **limit** : (optional) Specify the number of items to return. Default is 200. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `pollid` (path, string, required): The TalkLabs assigned poll ID. - `userid` (path, string, required): The customer defined user ID from your application or identity system. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/polls/list-responses-by-user-get) ## Get a poll by custom ID `GET /api/v3/{appid}/poll/pollbycustomid/{customid}` _This method requires authentication._ Fetches the poll, choices and optionally can return standing / results depending on state of the poll. - **customid**: (required) The customid of the poll to fetch. - **entities:** (optional = "poll"). Provide "poll", "choices", or "results" to get the desired data. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `customid` (path, string, required): A customer defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/polls/get-a-poll-by-custom-id-get) ## Get Poll Details `GET /api/v3/{appid}/poll/poll/{pollid}` _This method requires authentication._ Fetches the poll, choices and optionally can return standing / results depending on state of the poll. - **id**: (required) The ID of the poll to fetch. - **entities:** (optional = "poll"). Provide "poll", "choices", or "results" to get the desired data. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `pollid` (path, string, required): The TalkLabs assigned poll ID. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/polls/get-poll-details-get) ## Get Standings `GET /api/v3/{appid}/poll/poll/{pollid}/standings` _This method requires authentication._ This 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. ## RESPONSE CODES - **200 | OK** : Sweet, sweet success. - **400 | BadRequest** : Something is wrong with your request. View response message and errors list for details. - **403 | Forbidden** : The user doesn't have permission - **405 | MethodBlocked** : The method was blocked because it contained profanity and filtermode was set to 'block'. - **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) ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `pollid` (path, string, required): The TalkLabs assigned poll ID. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/polls/get-standings-get) ## Update Poll `PUT /api/v3/{appid}/poll/poll/{pollid}/update` _This method requires authentication._ When 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. #### METADATA \* **ownerid**: (required) The userid of the owner of the poll #### DISPLAY PROPERTIES \* **title**: (required) The title of the poll. Required on create. Optional on update. \* **description**: (optional) The description of the poll \* **pictureurl**: (optional) The URL for a picture for the room \* **embedcontenttop**: (optional) Content to be displayed at the top of the poll \* **embedcontentbottom**: (optional) Content to be displayed at the bottom of the poll \* **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. \* **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. #### BEHAVIOR SETTINGS \* **allowmultiplechoicesperuser**: ("true" or default = "false") If true, the user may submit answers for more than one choice. \* **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. \* **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. #### AUTO PUBLISH SETTINGS \* **whenpollpublish**: (optional) \[default=now\] An ISO-8601 date time. Now by default. If specified, poll is hidden until the specified date and time. \* **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). \* **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. \* **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. #### CUSTOM FIELDS \* **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. \* **customtype** : (optional) Custom type string. \* **custompayload** : (optional) Custom payload string. \* **customfield1** : (optional) User custom field 1. Store any string value you want here, limit 1024 bytes. \* **customfield2** : (optional) User custom field 2. Store any string value you want here, limit 1024 bytes. \* **customtags** : (optional) A comma delimited list of tags ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `pollid` (path, string, required): The TalkLabs assigned poll ID. ### Request example ```json { "title": "What is your favorite color?", "description": "Vote for your favorite color" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/polls/update-poll-put) ## Delete a poll choice `DELETE /api/v3/{appid}/poll/poll/{pollid}/choice/{choiceid}` Create polls, manage choices, collect votes, and read standings. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `pollid` (path, string, required): The TalkLabs assigned poll ID. - `choiceid` (path, string, required): The TalkLabs assigned poll choice ID. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/polls/delete-a-poll-choice-delete) ## Delete Poll `DELETE /api/v3/{appid}/poll/poll/{pollid}` _This method requires authentication._ When 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. #### URL PARAMETERS \* **pollid**: (required) The ID of the poll to delete ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `pollid` (path, string, required): The TalkLabs assigned poll ID. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/polls/delete-poll-delete) ## Reset Poll `PUT /api/v3/{appid}/poll/poll/{pollid}/reset` ## 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. ### URL Arguments - **pollid** : (required) The ID of the poll to reset. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `pollid` (path, string, required): The TalkLabs assigned poll ID. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/polls/reset-poll-put) # Users & notifications Create and find users, update profiles, and deliver notifications. ## Create or Update User `POST /api/v3/{appid}/user/users/{userid}` 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. Invoke this API method if you want to create a user or update an existing user. __Do not use this method to convert an anonymous user into a known user__. Use the **Convert User** api method instead. When 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. * **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. * **handle**: (Optional) A unique string representing the user that is easy for other users to type. * Example @GeorgeWashington could be the handle but Display Name could be "Wooden Teef For The Win". * 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 by adding a number from 1-99 and returned. * 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. * Only these characters may be used: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890_" * **displayname**: _Optional_. This is the desired name to display, typically the real name of the person. * **pictureurl**: _Optional_. The URL to the picture for this user. * **profileurl**: _Optional_. The profileurl for this user. * **role**: _Optional_. Valid roles are "user" (default), "moderator" and "admin". * **customtags**: _Optional_. A list of strings to attach to the user object. ## RESPONSE CODES * **200 | OK** : Sweet, sweet success. * **400 | BadRequest** : Something is wrong with your request. View response message and errors list for details. * **403 | Forbidden** : Request is not authorized with a valid token. * **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. * **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 - `appid` (path, string, required): The application the user belongs to. - `userid` (path, string, required): Required. If this userid is new, the user is created; if it already exists in the database, the user is updated. ### Request example ```json { "handle": "dave_m", "role": "admin", "userId": "u-8842" } ``` ### Responses - 200: OK: success. - 400: BadRequest: something is wrong with the request see the message and errors list for details. - 403: Forbidden: request is not authorized with a valid token. - 405: MethodNotAllowed: a rule blocked the request, such as profanity in the display name if filtering is enabled or invalid characters in the handle. - 409: Conflict: the requested handle is already in use. The system retries up to 20 times with a random numeric suffix before giving up. - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/users/create-or-update-user-post) ## List User Notifications `GET /api/v3/{appid}/user/users/{userid}/notification/listnotifications` If you see totalunread > 0, but you don't see any notifications, check that you are including valid values for filterNotificationTypes. # URL PROPERTIES * **userid** : (required) Return only notifications for this user # BODY PROPERTIES * **filterNotificationTypes** : (optional) Return only events of the specified type. Pass the argument more than once to fetch multiple types of notifications at once. * chatmention * chatquote * chatreply * commentmention * commentquote * commentreply * **includeread** : (optional | default = false) If true, notifications that have already been read are returned * **filterChatRoomId** : (optional) If provided, this will only return notifications associated with the specified chat room using the ChatRoom ID (exact match) * **filterChatRoomCustomId** : (optional) If provided, this will only return notifications associated with the specified chat room using the Custom ID (exact match) * **limit** : (optional) Default is 50, maximum is 200. Limits how many items are returned. * **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 - `appid` (path, string, required): The application the user belongs to. - `userid` (path, string, required): Required. Return only notifications for this user. - `UserId` (query, string): Required. Return only notifications for this user the route's userid; also accepted as a form field . - `FilterNotificationTypes` (query, NotificationTypes[]): Optional. Return only events of the specified type s : chatmention, chatquote, chatreply, commentmention, commentquote, commentreply. Pass the argument more than once to fetch multiple types at once. Omit to return all types. - `FilterChatRoomId` (query, string): Optional. Restrict results to notifications associated with this chat room ID exact match . - `FilterChatRoomCustomId` (query, string): Optional. Restrict results to notifications associated with this chat room custom ID exact match . - `FilterCommentConversationId` (query, string): Optional. Restrict results to notifications associated with this comment conversation ID exact match . - `FilterCommentConversationCustomId` (query, string): Optional. Restrict results to notifications associated with this comment conversation custom ID exact match . - `IncludeRead` (query, boolean): Optional, default false. If true, notifications that have already been read are also returned/counted. - `Cursor` (query, string): Optional. Pass the cursor value from a previous response to resume paging; leave blank to start from the beginning. - `Limit` (query, integer · int32): Optional. Default 50, maximum 200. Limits how many items are returned per page. - `Dieroll` (query, integer · int32): 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. ### Responses - 200: OK: success data is a ResponseCursorListUserNotifications cursor/more/itemcount/totalunread/notifications . - 400: BadRequest: required fields are missing or invalid. - 403: Forbidden: request is not authorized with a valid token, or the token does not match this appid. - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/users/list-user-notifications-get) ## List Users `GET /api/v3/{appid}/user/users` _This method requires authentication._ Use 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. ## ARGUMENTS * **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. * **limit**: You can omit this optional argument, in which case the default limit is 200 users to return. ### Parameters - `appid` (path, string, required): The application whose users are listed. - `Cursor` (query, string): Optional. Pass the cursor value from a previous response to fetch the next page; omit to start from the first page. - `Limit` (query, integer · int32): Optional. Maximum number of users to return in this page. Default and maximum are both 200 values above 200 are rejected with 400. ### Responses - 200: OK: success data is a ResponseCursorListAppUsers cursor/more/itemcount/users . - 400: BadRequest: limit exceeds the maximum allowed value of 200. - 403: Forbidden: request is not authorized with a valid token, or the token does not match this appid. - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/users/list-users-get) ## Get User Details `GET /api/v3/{appid}/user/users/{userid}` _This method requires authentication._ This will return all the information about the user. ### Parameters - `appid` (path, string, required): The application the user belongs to. - `userid` (path, string, required): The app specific user ID to look up. ### Responses - 200: OK: success data is the AppUser. - 400: BadRequest: the userid parameter is missing or invalid. - 403: Forbidden: request is not authorized with a valid token, or the token does not match this appid. - 404: NotFound: no user exists for the given userid. - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/users/get-user-details-get) ## Search Users `POST /api/v3/{appid}/user/search` _This method requires authentication._ Use 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. ## ARGUMENTS * **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. * **limit**: You can omit this optional argument, in which case the default limit is 200 users to return. * **name**: Provide part of a name to search the user name field * **handle**: Provide part of a handle to search by handle * **userid**: Provide part of a userid to search by userid ### Parameters - `appid` (path, string, required): The application whose users are searched. ### Request example ```json { "handle": "dave_m", "limit": 100 } ``` ### Responses - 200: OK: success data is { kind: "list.users", cursor, users } . - 400: BadRequest: none of userid, handle, or name was provided. - 403: Forbidden: request is not authorized with a valid token, or the token does not match this appid. - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/users/search-users-post) ## Count User Notifications `GET /api/v3/{appid}/user/users/{userid}/notification/countnotifications` # URL PROPERTIES * **userid** : (required) Return only notifications for this user # BODY PROPERTIES * **filterNotificationTypes** : (optional) Return only events of the specified type. Pass the argument more than once to fetch multiple types of notifications at once. * chatmention * chatquote * chatreply * commentmention * commentquote * commentreply * **includeread** : (optional | default = false) If true, notifications that have already been read are counted otherwise read notifications are not counted * **filterChatRoomId** : (optional) If provided, this will only count notifications associated with the specified chat room using the ChatRoom ID (exact match) * **filterChatRoomCustomId** : (optional) If provided, this will only count notifications associated with the specified chat room using the Custom ID (exact match) ### Parameters - `appid` (path, string, required): The application the user belongs to. - `userid` (path, string, required): Required. Return only the notification count for this user. - `UserId` (query, string): Required. Return only notifications for this user the route's userid; also accepted as a form field . - `FilterNotificationTypes` (query, NotificationTypes[]): Optional. Return only events of the specified type s : chatmention, chatquote, chatreply, commentmention, commentquote, commentreply. Pass the argument more than once to fetch multiple types at once. Omit to return all types. - `FilterChatRoomId` (query, string): Optional. Restrict results to notifications associated with this chat room ID exact match . - `FilterChatRoomCustomId` (query, string): Optional. Restrict results to notifications associated with this chat room custom ID exact match . - `FilterCommentConversationId` (query, string): Optional. Restrict results to notifications associated with this comment conversation ID exact match . - `FilterCommentConversationCustomId` (query, string): Optional. Restrict results to notifications associated with this comment conversation custom ID exact match . - `IncludeRead` (query, boolean): Optional, default false. If true, notifications that have already been read are also returned/counted. - `Cursor` (query, string): Optional. Pass the cursor value from a previous response to resume paging; leave blank to start from the beginning. - `Limit` (query, integer · int32): Optional. Default 50, maximum 200. Limits how many items are returned per page. - `Dieroll` (query, integer · int32): 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. ### Responses - 200: OK: success data is a ResponseCountUserNotifications itemcount . - 400: BadRequest: required fields are missing or invalid. - 403: Forbidden: request is not authorized with a valid token, or the token does not match this appid. - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/users/count-user-notifications-get) ## Set Notification Read Status `PUT /api/v3/{appid}/user/users/{userid}/notification/notifications/{notificationid}/update` **Unless your workflow must support use of read notifications, use DELETE USER NOTIFICATION instead.** This marks a notification as being in READ status. That will prevent the notification from being returned in a call to List User Notifications unless the default filters are overridden. Notifications that are marked as read will be automatically deleted after some time. * 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. ### URL Arguments * **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. * **notificationid** : (required) The unique ID of the notification being updated. * **read** : (required) The read status (true/false) for the notification. You can pass false to mark the notification as unread. ### Parameters - `appid` (path, string, required): The application the user belongs to. - `userid` (path, string, required): Required. The user marking the notification used to ensure a user can't mark another user's notification. - `notificationid` (path, string, required): Required. The unique ID of the notification being updated. - `read` (query, boolean): Required. The read status true/false to set. Pass false to mark the notification unread again. ### Responses - 200: OK: success data is the updated UserNotification. - 400: BadRequest: the required read parameter was not provided. - 403: Forbidden: request is not authorized with a valid token, or the token does not match this appid. - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/users/set-notification-read-status-put) ## Set Notification Read Status (by ChatEventId) `PUT /api/v3/{appid}/user/users/{userid}/notification/notificationsbyid/chateventid/{chateventid}/update` **Unless your workflow must support use of read notifications, use DELETE USER NOTIFICATION by Chat Event Id instead.** * This marks a notification as being in READ status. * That will prevent the notification from being returned in a call to List User Notifications unless the default filters are overridden. * Notifications that are marked as read will be automatically deleted after some time. * Only call this once per event. Only call this for events of type ChatReply or ChatQuote. ### URL Arguments * **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. * **chateventid** : (required) The unique ID of the chateventid to use to locate the notification being updated. * **read** : (required) The read status (true/false) for the notification. You can pass false to mark the notification as unread. ### Parameters - `appid` (path, string, required): The application the user belongs to. - `userid` (path, string, required): Required. The user marking the notification used to ensure a user can't mark another user's notification. - `chateventid` (path, string, required): Required. The chat event ID used to locate the notification being updated. - `read` (query, boolean): Required. The read status true/false to set. Pass false to mark the notification unread again. ### Responses - 200: OK: success data is the updated UserNotification. - 400: BadRequest: chateventid or read was not provided. - 403: Forbidden: request is not authorized with a valid token, or the token does not match this appid. - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/users/set-notification-read-status-by-chateventid-put) ## Notifications: Mark All Read `PUT /api/v3/{appid}/user/users/{userid}/notification/notifications_all/markread` **Unless your workflow must support use of read notifications, notifications should be deleted when read.** This marks all notifications for a user as read with one api call. ### URL Arguments * **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. * **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 - `appid` (path, string, required): The application the user belongs to. - `userid` (path, string, required): Required. The user marking notifications read used to ensure a user can't mark another user's notifications. - `delete` (query, boolean): Optional, default true. If true, all of the user's notifications are deleted. If false, they are marked read not deleted . ### Responses - 200: OK: success. - 400: Bad Request - 403: Forbidden: request is not authorized with a valid token, or the token does not match this appid. - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/users/notifications-mark-all-read-put) ## Delete User `DELETE /api/v3/{appid}/user/users/{userid}` ## All rooms with messages by that user will have the messages from this user purged in the rooms. _This method requires authentication._ * **UserId** is the app specific User ID provided by your application. ### Parameters - `appid` (path, string, required): The application the user belongs to. - `userid` (path, string, required): Required. The app specific user ID to delete. ### Responses - 200: OK: success data is a ResponseDeleteAppUser kind "deleted.appuser" containing the deleted user's last known record. - 400: BadRequest: the userid parameter was not provided. - 403: Forbidden: request is not authorized with a valid token. - 404: NotFound: no user exists for the given userid. - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/users/delete-user-delete) ## Delete User Notification `DELETE /api/v3/{appid}/user/users/{userid}/notification/notifications/{notificationid}` Immediately deletes a user notification. Unless your workflow specifically implements access to read notifications, you should delete notifications after they are consumed. ### URL Arguments * **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. * **notificationid** : (required) The unique ID of the notification being updated. ### Parameters - `appid` (path, string, required): The application the user belongs to. - `userid` (path, string, required): Required. The user the notification belongs to used to ensure a user can't delete another user's notification. - `notificationid` (path, string, required): Required. The unique ID of the notification being deleted. ### Responses - 200: OK: success data is the deleted UserNotification. - 400: Bad Request - 403: Forbidden: request is not authorized with a valid token, or the token does not match this appid. - 404: NotFound: no notification with this ID exists for this user. - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/users/delete-user-notification-delete) ## Delete User Notification (By ChatEventId) `DELETE /api/v3/{appid}/user/users/{userid}/notification/notificationsbyid/chateventid/{chateventid}` Immediately deletes a user notification. Unless your workflow specifically implements access to read notifications, you should delete notifications after they are consumed. ### URL Arguments * **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. * **chateventid** : (required) The unique ID of the chateventid to use to locate the notification to be deleted. ### Parameters - `appid` (path, string, required): The application the user belongs to. - `userid` (path, string, required): Required. The user the notification belongs to used to ensure a user can't delete another user's notification. - `chateventid` (path, string, required): Required. The chat event ID used to locate the notification to delete. ### Responses - 200: OK: success data is the deleted UserNotification, or absent if there was nothing to delete. - 400: BadRequest: chateventid was not provided. - 403: Forbidden: request is not authorized with a valid token, or the token does not match this appid. - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/users/delete-user-notification-by-chateventid-delete) # User sessions & access Mint and revoke user tokens, change roles, and inspect access operations. ## Create a user session `POST /api/v3/{appid}/user/users/{userid}/session` Mint a bearer token for one of your users. Call 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 - `appid` (path, string, required): The application the token is for. - `userid` (path, string, required): The user the token represents becomes the token's subject . This sits in the URL path, so the caller MUST URL encode it — a userid containing reserved characters spaces, '/', '%', ' ', '?', '+', etc. will otherwise be misread or rejected. ASP.NET Core percent decodes the value during route binding, so the method receives the original userid; do not decode it again. ### Request example ```json { "displayName": "Dave M.", "pictureUrl": "https://example.com/avatars/u-8842.jpg", "role": "", "expiresIn": 1 } ``` ### Responses - 200: OK - 400: Bad Request - 401: Unauthorized - 409: Conflict - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/user-access/create-a-user-session-post) ## Set a user role `POST /api/v3/{appid}/user/users/{userid}/role` Change the role stored on a user. Use 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 - `appid` (path, string, required): The application the user belongs to. - `userid` (path, string, required): The user whose role is being changed. ### Request example ```json { "role": "" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/user-access/set-a-user-role-post) ## Set user permissions (not implemented) `POST /api/v3/{appid}/user/users/{userid}/setroles` This endpoint is present in the API contract but does not currently apply permission changes. Do 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 - `appid` (path, string, required): The application the user belongs to. - `userid` (path, string, required): The user the permissions would apply to. ### Request example ```json { "roles": [ "" ] } ``` ### Responses - 200: OK: request accepted, but no permission change is actually applied see NOTE above . - 400: BadRequest: the request body was not provided. - 403: Forbidden: request is not authorized with a valid token. - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/user-access/set-user-permissions-not-implemented-post) ## Revoke all user tokens `DELETE /api/v3/{appid}/user/users/{userid}/tokens` Revoke every bearer token previously issued for a user. Call 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 - `appid` (path, string, required): The application the user belongs to. - `userid` (path, string, required): The user whose tokens are being revoked. ### Responses - 200: OK - 400: Bad Request - 401: Unauthorized - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/user-access/revoke-all-user-tokens-delete) # Moderate chat Review queues, act on reports, and apply room-level user effects. ## List Flagged Users Needing Moderation `GET /api/v3/{appid}/chat/moderation/queues/roomflaggedusers` 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. * *limit*: (optional) Defaults to 50. This limits how many items are returned * *roomId*: (optional) Provide the ID for a room to filter for only the queued events for a specific room * *cursor*: (optional) Provide cursor value to get the next page of results. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `limit` (query, integer · int32): The maximum number of records to return. - `roomId` (query, string): The TalkLabs assigned room ID returned when the room was created. - `cursor` (query, string): The cursor returned by the previous page. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat-moderation/list-flagged-users-needing-moderation-get) ## List Messages Needing Moderation `GET /api/v3/{appid}/chat/moderation/queues/events` _This method requires authentication._ * *limit*: (optional) Defaults to 200. This limits how many messages to return from the queue * *roomId*: (optional) Provide the ID for a room to filter for only the queued events for a specific room * *cursor*: (optional) Provide cursor value to get the next page of results. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `limit` (query, integer · int32): The maximum number of records to return. - `roomId` (query, string): The TalkLabs assigned room ID returned when the room was created. - `cursor` (query, string): The cursor returned by the previous page. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat-moderation/list-messages-needing-moderation-get) ## List Room User Effects `GET /api/v3/{appid}/chat/rooms/{roomid}/usereffects` 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). It is possible for the user to appear more than once in the list if there is more than one effect on the user. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat-moderation/list-room-user-effects-get) ## Bounce User (ban user from room) `POST /api/v3/{appid}/chat/rooms/{roomid}/bounce` ## Optionally display a message to people in the room indicating this person was bounced. When 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). * **userid**: (required) The ID of the user to bounce from the room. * **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. * **announcement**: (optional) If provided, this announcement is displayed to the people who are in the room, as the body of a BOUNCE event. ## URL Parameters * **roomid** : The ID of the chat room from which to bounce this user. ### Parameters - `appid` (path, string, required): - `roomid` (path, string, required): ### Request example ```json { "bounce": "true", "announcement": "The bouncer shows dave_m the way out.", "userId": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat-moderation/bounce-user-ban-user-from-room-post) ## Moderator Apply Decision to Flagged User `POST /api/v3/{appid}/chat/rooms/{roomid}/moderation/flaggedusers/{userid}/applydecision` 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. * Invoke this method to either approve or reject the user * In either case the user is no longer flagged * In either case the reports are erased * If apply is true, user gets shadowban effect with no expiration * If apply is false, flag is remove # BODY PROPERTIES * **approve** : (required) Pass **true** to approve the user (indicate the user is not abusive) or **false** to reject the user. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. - `userid` (path, string, required): The customer defined user ID from your application or identity system. ### Request example ```json { "approve": true } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat-moderation/moderator-apply-decision-to-flagged-user-post) ## Moderator Approve / Reject Message `POST /api/v3/{appid}/chat/moderation/queues/events/{eventid}/applydecision` 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. If the room is set to use POST-MODERATION, messages will only be sent to the moderation queue if they are reported. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `eventid` (path, string, required): The TalkLabs assigned chat event ID. ### Request example ```json { "approve": "true" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat-moderation/moderator-approve-reject-message-post) ## Mute User (In Room Only) `POST /api/v3/{appid}/chat/rooms/{roomid}/mute` There is a user level shadow ban (global) and local room level shadow ban. A 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. * **userid**: (required) The applicaiton provided userid of the user to ban * **mute**: (required) true or false. If true, will have the mute affect applied. If false, mute will not be applied. * **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. ### Parameters - `appid` (path, string, required): - `roomid` (path, string, required): ### Request example ```json { "applyEffect": true, "userId": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat-moderation/mute-user-in-room-only-post) ## Purge User Messages `POST /api/v3/{appid}/chat/rooms/{roomid}/commands/purge` - **command**: The command to execute. In this case, "\*purge " ### POST ARGUMENTS - **userid**: (required) The userid of the user owning the messages to be purged - **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 ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. ### Request example ```json { "userid": "u-8842", "byuserid": "admin" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat-moderation/purge-user-messages-post) ## Report User In Room `POST /api/v3/{appid}/chat/rooms/{roomid}/users/{userid}/report` - 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. - 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. - 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. - A user who is flagged will have the _shadowban_ effect applied. ### URL Arguments - **userid** : (required) The ID of the user who is being reported, URL ENCODED. ### BODY Parameters - **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: - abuse - spam - selfharm - hate - violence - harassment - nudity - illegal - false - other ### RESPONSES: | Code | Meaning | Description | | --- | --- | --- | | 200 | OK | Request completed successfully (or duplicate report ignored) | | 404 | Not Found | The specified user or application or room could not be found | | 412 | Precondition Failed | The request was rejected because user reporting is not enabled for the application. | ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `roomid` (path, string, required): The TalkLabs assigned room ID returned when the room was created. - `userid` (path, string, required): The customer defined user ID from your application or identity system. ### Request example ```json { "reportType": {}, "userId": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 409: Conflict - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat-moderation/report-user-in-room-post) ## Shadow Ban User (In Room Only) `POST /api/v3/{appid}/chat/rooms/{roomid}/shadowban` There is a user level shadow ban (global) and local room level shadow ban. A 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. * **userid**: (required) The applicaiton provided userid of the user to ban * **applyeffect**: (required) true or false. If true, user will be set to banned state. If false, will be set to non-banned state. * **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. ### Parameters - `appid` (path, string, required): - `roomid` (path, string, required): ### Request example ```json { "applyEffect": true, "userId": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/chat-moderation/shadow-ban-user-in-room-only-post) # Moderate comments Review reported comments and approve, reject, or flag content. ## List Comments in Moderation Queue `GET /api/v3/{appid}/comment/moderation/queues/comments` _This method requires authentication._ * *limit*: (optional) Defaults to 200. This limits how many messages to return from the queue * *conversationid*: (optional) Provide the ConversationID for a room to filter for only the queued events for a specific room * *cursor*: (optional) Provide cursor value to get the next page of results. * *filterHandle*: (optional) Filters using exact match for a handle of a user * *filterKeyword*: (optional) Filters using substring search for your string * *filterModerationState*: (optional) Filters for comments in the specified moderation state. * approved: Moderator approved the comment * rejected: Moderator rejected the comment * pending: A new comment was posted to a premoderation room, and is pending review, but was never reported as abuse * flagged: Enough users reported the comment that it is in the flagged state and sent to moderation queue ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `limit` (query, integer · int32): The maximum number of records to return. - `conversationId` (query, string): The TalkLabs assigned conversation ID. - `cursor` (query, string): The cursor returned by the previous page. - `filterModerationState` (query, integer · int32): - `filterKeyword` (query, string): - `filterUserid` (query, string): - `filterHandle` (query, string): - `filterTag` (query, string): - `filterHashtag` (query, string): ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comment-moderation/list-comments-in-moderation-queue-get) ## Apply a comment moderation decision `POST /api/v3/{appid}/comment/moderation/queues/comments/{commentid}/applydecision` 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. If the conversation is set to use POST-MODERATION, messages will only be sent to the moderation queue if they are reported. # BODY PROPERTIES * **approve** : (required) Pass **true** to approve the comment or **false** to reject the comment. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `commentid` (path, string, required): The TalkLabs assigned comment ID. ### Request example ```json { "approve": true } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comment-moderation/apply-a-comment-moderation-decision-post) ## Flag Comment `POST /api/v3/{appid}/comment/conversations/{conversationid}/comments/{commentid}/flag` 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. ### URL Arguments - **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED. - **comment_comment_id** : (required) The unique ID of the comment, URL ENCODED. ### BODY Parameters - **reporttype:** ("abuse" or "spam") - **userid** : (optional) This is the application specific user ID of the user reporting the comment. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `conversationId` (path, string, required): The TalkLabs assigned conversation ID. - `commentId` (path, string, required): The TalkLabs assigned comment ID. ### Request example ```json { "reportType": {}, "userId": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comment-moderation/flag-comment-post) ## Report Comment `POST /api/v3/{appid}/comment/conversations/{conversationid}/comments/{commentid}/report` ### URL Arguments - **comment_conversation_id** : (required) The ID of the comment conversation, URL ENCODED. - **comment_comment_id** : (required) The unique ID of the comment, URL ENCODED. ### BODY Parameters - **userid** : (required) This is the application specific user ID of the user reporting the comment. - **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: - abuse - spam - selfharm - hate - violence - harassment - nudity - illegal - false - other ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `conversationId` (path, string, required): The TalkLabs assigned conversation ID. - `commentId` (path, string, required): The TalkLabs assigned comment ID. ### Request example ```json { "reportType": {}, "userId": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 404: Not Found - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/comment-moderation/report-comment-post) # Moderate users Review reports, ban or mute users, and purge abusive content. ## List Users in Moderation Queue `GET /api/v3/{appid}/user/moderation/queues/reportedusers` _This method requires authentication._ * *limit*: (optional) Defaults to 200. This limits how many users to return from the queue * *cursor*: (optional) Provide cursor value to get the next page of results. * *filterModerationState*: (optional) Filters for users in the specified moderation state. * approved: Moderator approved the user * rejected: Moderator rejected the user * flagged: Enough users reported the user that it is in the flagged state and sent to moderation queue * *filterUserId*: (optional) Exact match filter for UserID * *filterHandle*: (optional) Substring match for Handle (case-insensitive) ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `limit` (query, integer · int32): The maximum number of records to return. - `cursor` (query, string): The cursor returned by the previous page. - `filterModerationState` (query, integer · int32): - `filterUserid` (query, string): - `filterHandle` (query, string): ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/user-moderation/list-users-in-moderation-queue-get) ## Set a global user ban `POST /api/v3/{appid}/user/users/{userid}/ban` * **userid**: (required) The applicaiton provided userid of the user to ban * **applyeffect**: (required) true or false. If true, user will be set to banned state. If false, will be set to non-banned state. * **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. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `userid` (path, string, required): The customer defined user ID from your application or identity system. ### Request example ```json { "applyEffect": true } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/user-moderation/set-a-global-user-ban-post) ## Apply a user moderation decision `POST /api/v3/{appid}/user/moderation/queues/reportedusers/{userid}/applydecision` # BODY PROPERTIES * **approve** : (required) Pass **true** to approve the comment or **false** to reject the user. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `userid` (path, string, required): The customer defined user ID from your application or identity system. ### Request example ```json { "approve": "false" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/user-moderation/apply-a-user-moderation-decision-post) ## Global Purge User `POST /api/v3/{appid}/user/users/{userid}/globalpurge` #### **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.** ## URL PARAMETERS - **userid**: (required) The application provided userid of the user to ban ## POST PARAMETERS - **byuserid**: (optional) The userid of the user issuing the purge command. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `userid` (path, string, required): The customer defined user ID from your application or identity system. ### Request example ```json { "byUserId": "" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/user-moderation/global-purge-user-post) ## Mute User `POST /api/v3/{appid}/user/users/{userid}/mute` 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. * **userid**: (required) The applicaiton provided userid of the user to ban * **applyeffect**: (required) true or false. If true, user will be set to muted state. If false, will be set to non-banned state. * **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. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `userid` (path, string, required): The customer defined user ID from your application or identity system. ### Request example ```json { "applyEffect": true } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/user-moderation/mute-user-post) ## Report User `POST /api/v3/{appid}/user/users/{userid}/report` ### URL Arguments - **userid** : (required) The ID of the user who is being reported, URL ENCODED. ### BODY Parameters - **userid** : (required) This is the application specific user ID of the user reporting the first user. - **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: - abuse - spam - selfharm - hate - violence - harassment - nudity - illegal - false - other ### RESPONSES: | Code | Meaning | Description | | --- | --- | --- | | 200 | OK | Request completed successfully | | 404 | Not Found | The specified user or application could not be found | | 409 | Conflict | The request was rejected because user reporting is not enabled for the application. | ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `userid` (path, string, required): The customer defined user ID from your application or identity system. ### Request example ```json { "reportType": {}, "userId": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 409: Conflict - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/user-moderation/report-user-post) ## Shadow Ban User `POST /api/v3/{appid}/user/users/{userid}/shadowban` 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. * **userid**: (required) The applicaiton provided userid of the user to ban * **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. * **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. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `userid` (path, string, required): The customer defined user ID from your application or identity system. ### Request example ```json { "applyEffect": true } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/user-moderation/shadow-ban-user-post) # Live telemetry Measure counters, continuous signals, and presence in real time. ## Read a live telemetry meter `GET /api/v3/{appid}/telemetry/contexts/{contextid}` Read the synchronized aggregate for every signal in a context. Poll 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 - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `contextid` (path, string, required): A customer defined ID for the live context being measured. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/telemetry/read-a-live-telemetry-meter-get) ## Increment a counter `POST /api/v3/{appid}/telemetry/contexts/{contextid}/metrics/{key}/increment` Record one or more occurrences in a named counter. Use customer-defined keys to keep related counters separate. For example, `reaction.primary` and `reaction.secondary` can share a context while producing independent totals. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `contextid` (path, string, required): A customer defined ID for the live context being measured. - `key` (path, string, required): A customer defined name for this telemetry signal. ### Request example ```json { "userId": "u-8842", "by": 1 } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/telemetry/increment-a-counter-post) ## Record a gauge sample `POST /api/v3/{appid}/telemetry/contexts/{contextid}/gauges/{key}/sample` Record a continuous reading from 0 to 1, such as sound level or interaction intensity. Send samples while the signal is active. TalkLabs maintains a synchronized aggregate that every viewer of the context can read. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `contextid` (path, string, required): A customer defined ID for the live context being measured. - `key` (path, string, required): A customer defined name for this telemetry signal. ### Request example ```json { "userId": "u-8842", "value": 1 } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/telemetry/record-a-gauge-sample-post) ## Record a presence heartbeat `POST /api/v3/{appid}/telemetry/contexts/{contextid}/presence/{key}/heartbeat` Mark a user as active in a live context. Send heartbeats periodically while the user is present. The active count falls automatically after heartbeats stop. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `contextid` (path, string, required): A customer defined ID for the live context being measured. - `key` (path, string, required): A customer defined name for this telemetry signal. ### Request example ```json { "userId": "u-8842" } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/telemetry/record-a-presence-heartbeat-post) ## Submit telemetry in a batch `POST /api/v3/{appid}/telemetry/contexts/{contextid}/batch` Submit multiple telemetry actions in one request. Buffer 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 - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `contextid` (path, string, required): A customer defined ID for the live context being measured. ### Request example ```json { "userId": "u-8842", "ops": [ "" ] } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/telemetry/submit-telemetry-in-a-batch-post) # Webhooks Send product events to your services and inspect delivery logs. ## Create or Replace Webhook `POST /api/v3/{appid}/webhook/hooks` _Requires Authentication._ ### Timeouts for Webhooks * Webhooks must complete within the allowed time (3 seconds) or it is considered a timeout * If your webhook consistently times out or fails to return with a success code then it may be deactivated * Your webhook should receive the event and return immediately ### PROPERTIES * **label** : (required) A unique string for your webhook. It can be anything you want. * **url**: (required) A URL to post to when the webhook is activated. * **enabled**: (required) Sets the webhook to be in either the enabled or disabled states. * **type**: (required) ["prepublish"/"postpublish"] Sets the type of webhook. See TYPES below. * **events**: (required) An array of strings indicating which event types activate your webhook. See events below for allowed values. * **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. ## BEHAVIOR: CREATE OR UPDATE If 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. ## WEBHOOK TYPES There are two types of webhook: _prepublish_ and _postpublish_. ### Pre-Publish Webhook Pass "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. ### Post-Publish Webhook Pass "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. ## EVENT TYPES The following event types are supported. * chatcustom * chatspeech * chatquote * chatreply * chatreaction * chataction * chatenter * chatexit * chatroomopened * chatroomclosed * chatpurge * commentpublished * commentreply ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. ### Request example ```json { "label": "Demonstration Webhook (prepublish)", "url": "https://localhost:443", "enabled": false, "events": [ "commentpublished", "commentreply" ], "webhookType": {} } ``` ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/webhooks/create-or-replace-webhook-post) ## List Webhook Log Entries `GET /api/v3/{appid}/webhook/hooks/{hookid}/logentries` _This method requires authentication._ Use this method to get a list of webhooks registered for your application. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `hookid` (path, string, required): The TalkLabs assigned webhook ID. - `Limit` (query, integer · int32): The maximum number of records to return. - `Cursor` (query, string): The cursor returned by the previous page. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/webhooks/list-webhook-log-entries-get) ## List Webhooks `GET /api/v3/{appid}/webhook/hooks` _This method requires authentication._ Use this method to get a list of webhooks registered for your application. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `Limit` (query, integer · int32): The maximum number of records to return. - `Cursor` (query, string): The cursor returned by the previous page. ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/webhooks/list-webhooks-get) ## Update Webhook `PUT /api/v3/{appid}/webhook/hooks/{id}` _Requires Authentication._ * **id** : (required) Passed as URL parameter, specifying which webhook to update. * **label** : (required) A unique string for your webhook. It can be anything you want. * **url**: (required) A URL to post to when the webhook is activated. * **enabled**: (required) Sets the webhook to be in either the enabled or disabled states. * **type**: (required) ["prepublish"/"postpublish"] Sets the type of webhook. See TYPES in the description for the "Create Webhook" API method. * **events**: (required) An array of strings indicating which event types activate your webhook. See events below. ## Additional Details See "Create or Replace Webhook" method for details about webhook behavior and settings. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `id` (path, string, required): ### Request example ```json { "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: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/webhooks/update-webhook-put) ## Delete Webhook `DELETE /api/v3/{appid}/webhook/hooks/{id}` _This method requires authentication._ Use this method to delete a webhook. ### Parameters - `appid` (path, string, required): The TalkLabs application ID assigned to your account. - `id` (path, string, required): ### Responses - 200: OK - 400: Bad Request - 403: Forbidden - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/webhooks/delete-webhook-delete) # Platform status Check service availability and the deployed API version. ## Get the API version `GET /api/v3/version` 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. ### Responses - 200: OK - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/platform/get-the-api-version-get) ## Check API availability `GET /api/v3/monitor` 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. ### Responses - 200: OK - 500: Internal Server Error [Web reference](https://talklabs.ai/docs/reference/platform/check-api-availability-get)