POST Users & notifications

Create or Update User

All users must have a Handle.

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".

Request

Parameters

Values in the path and query string.

appid path

string TalkLabs ID required

The application the user belongs to.

Example: your-app-id

userid path

string customer-defined required

Required. If this userid is new, the user is created; if it already exists in the database, the user is updated.

Example: u-8842

Request

JSON body

Send as application/json.

userId

string customer-defined required

Required. If this userid is new, the user is created; if it is already in use, the user is updated. Example: "georgew".

handle

string

Optional. A unique string representing the user that is easy for other users to type, e.g. "@GeorgeWashington". If omitted when creating a user, one is generated from displayname. If the requested handle is already in use, a variant is generated by appending a number 1 99 ; if all of those are also taken the request is rejected with 400 BadRequest. Allowed characters: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890 ". Maximum 40 characters.

displayName

string

Optional. The desired display name, typically the person's real name, e.g. "Wooden Teef For The Win". Maximum 250 characters.

pictureUrl

string

Optional. The URL to this user's picture. Maximum 1040 characters.

profileUrl

string

Optional. The profile URL for this user. Maximum 1040 characters.

role

integer · int32

Optional. Valid values are "user" default , "moderator", and "admin".

customTags

string[]

Optional. A list of free form strings to attach to the user object.

replaceUserId

string customer-defined

Optional. Renames an existing user by replacing their stored userid with this value. Leave empty to leave the userid unchanged. This is NOT a dedicated identity conversion endpoint see the controller action's remarks before using this to promote an anonymous user to a known one.

isAnonymous

boolean

Optional. Marks this user as anonymous/throwaway the customer's own signal WE do not decide who is anonymous . An anonymous user's effective role defaults to the view only "readonly" floor reads allowed, writes require ≥ user unless a token asserts a higher role. Omit to leave unchanged; set true or false to change it. Requirement: docs/specs/architecture/authentication/identity architecture.md §2.6.

expiresAt

string · date-time

Optional lifecycle expiry UTC : a time after which a deferred cleanup sweep may delete the user and their activity. GENERAL not tied to isAnonymous; any user may carry one. Omit to leave unchanged; send a timestamp to set it, or send the sentinel 0001 01 01T00:00:00Z DateTime.MinValue to CLEAR a previously set expiry. Requirement: identity architecture.md §2.6.

Request example

{
  "handle": "dave_m",
  "role": "admin",
  "userId": "u-8842"
}

Response

Status codes

Every JSON response uses the API result envelope.

200 OK: success. ApiResult

400 BadRequest: something is wrong with the request see the message and errors list for details. ApiResult

403 Forbidden: request is not authorized with a valid token. ApiResult

405 MethodNotAllowed: a rule blocked the request, such as profanity in the display name if filtering is enabled or invalid characters in the handle. ApiResult

409 Conflict: the requested handle is already in use. The system retries up to 20 times with a random numeric suffix before giving up. ApiResult

500 Internal Server Error ApiResult

Example response · 200

{
  "message": "Success",
  "errors": {},
  "data": {
    "kind": "app.user",
    "userid": "u-8842",
    "handle": "dave_m",
    "handlelowercase": "georgew",
    "displayname": "Dave M.",
    "pictureurl": "https://example.com/users/u-8842s/photos/original/a9/c7/a6/44-1-george-washington-18-1549729902.jpg",
    "profileurl": "https://example.com/users/u-8842shington",
    "role": "user",
    "customtags": [
      "optional_custom_tag_1"
    ],
    "banned": false,
    "shadowbanned": false,
    "shadowbanexpires": "0001-01-01T00:00:00Z",
    "muted": false,
    "moderation": "na",
    "reports": []
  }
}

curl --request POST \
  --url "https://api.sportstalk247.com/api/v3/${APP_ID}/user/users/${USER_ID}" \
  --header "Accept: application/json" \
  --header "x-api-token: ${TALKLABS_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "handle": "dave_m",
  "role": "admin",
  "userId": "u-8842"
}'

const appId = process.env.TALKLABS_APP_ID;
const userid = 'u-8842';

const response = await fetch(
  `https://api.sportstalk247.com/api/v3/${appId}/user/users/${userid}`,
{
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'x-api-token': process.env.TALKLABS_API_TOKEN,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "handle": "dave_m",
  "role": "admin",
  "userId": "u-8842"
}),
});

const result = await response.json();

import json
import os
import requests

app_id = os.environ["TALKLABS_APP_ID"]
userid = "u-8842"

response = requests.post(
    f"https://api.sportstalk247.com/api/v3/{app_id}/user/users/{userid}",
    headers={
        "Accept": "application/json",
        "x-api-token": os.environ["TALKLABS_API_TOKEN"],
    },
    json=json.loads(r'''{
  "handle": "dave_m",
  "role": "admin",
  "userId": "u-8842"
}'''),
)
response.raise_for_status()
result = response.json()

Environment variables TALKLABS_APP_ID TALKLABS_API_TOKEN

Response