POST Chat
Join a room by custom ID
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 anot…
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:
- Create Room
- Create User
- Join Room (user gets permission to access events data from the room)
- 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".
Request
Parameters
Values in the path and query string.
appid path string TalkLabs ID required
The TalkLabs application ID assigned to your account.
Example:your-app-id customid path string customer-defined required
A customer defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID.
Example:live-event-chat Request
JSON body
Send as application/json.
userId string customer-defined
The customer defined user ID from your application or identity system.
handle string
displayName string
pictureUrl string
profileUrl string
limit integer · int32
The maximum number of records to return.
role integer · int32
customTags string[]
Request example
{
"limit": 50
} Response
Status codes
Every JSON response uses the API result envelope.
200 OK ApiResult 400 Bad Request ApiResult 403 Forbidden ApiResult 404 Not Found ApiResult 405 Method Not Allowed ApiResult 409 Conflict ApiResult 500 Internal Server Error ApiResult Example response · 200
{
"message": "Successfully joined as identified user",
"errors": {},
"data": {
"kind": "chat.joinroom",
"user": {
"kind": "app.user",
"userid": "userid_abe",
"handle": "HonestAbe",
"handlelowercase": "honestabe",
"displayname": "Abraham Lincoln",
"pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg",
"profileurl": "https://www.biography.com/us-president/abraham-lincoln",
"role": "user",
"customtags": [],
"banned": false,
"shadowbanned": false,
"shadowbanexpires": "0001-01-01T00:00:00Z",
"muted": false,
"moderation": "na",
"reports": []
},
"room": {
"kind": "chat.room",
"id": "5ffdaefc86c29a175c6c46fe",
"appid": "5ff89dfb86c2941010796f93",
"ownerid": null,
"name": "New York City Chat (Post-Moderated)",
"description": "Live from the top of the Empire State Building",
"pictureurl": "",
"customtype": "",
"customid": "new-york-city-club",
"custompayload": "",
"customtags": [],
"customfield1": "",
"customfield2": "",
"enableactions": true,
"enableenterandexit": true,
"open": true,
"inroom": 1,
"added": "2021-01-12T14:15:24.8535603Z",
"whenmodified": "2021-01-12T14:15:24.8535603Z",
"moderation": "post",
"maxreports": 0,
"enableprofanityfilter": true,
"delaymessageseconds": 0,
"bouncedusers": [],
"shadowbannedusers": []
},
"eventscursor": {
"kind": "list.chatevents",
"cursor": "637460577330724021",
"more": false,
"itemcount": 1,
"events": [
{
"kind": "chat.event",
"id": "5ffdaf0586c29a175c6c4702",
"roomid": "5ffdaefc86c29a175c6c46fe",
"body": "Message has been modified",
"originalbody": "",
"added": "2021-01-12T14:15:33.0724021Z",
"modified": "2021-01-20T12:53:06.8107428Z",
"ts": 637460577330724000,
"eventtype": "speech",
"userid": "userid_abe",
"user": {
"kind": "app.user",
"userid": "userid_abe",
"handle": "HonestAbe",
"handlelowercase": "honestabe",
"displayname": "Abraham Lincoln",
"pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg",
"profileurl": "https://www.biography.com/us-president/abraham-lincoln",
"role": "user",
"customtags": [],
"banned": false,
"shadowbanned": false,
"shadowbanexpires": "0001-01-01T00:00:00Z",
"muted": false,
"moderation": "na",
"reports": []
},
"mentions": [],
"customtype": "",
"customid": "",
"custompayload": "",
"customtags": [],
"customfield1": "",
"customfield2": "",
"replyto": null,
"parentid": "",
"hierarchy": [],
"depth": 0,
"edited": true,
"editedbymoderator": false,
"censored": false,
"deleted": false,
"active": true,
"mutedby": [],
"shadowban": false,
"hashtags": [],
"likecount": 0,
"replycount": 0,
"reactions": [],
"moderation": "na",
"reports": []
}
]
},
"previouseventscursor": "637460577330724021"
}
}