Skip to main content

Users

A user represents an end-user using your application. Users can join channels, chat with other users, receive notifications and perform other actions. Users are identified by a unique name.

Schema​

type
required
string
Enum: "PERSON" "BOT"

Type of user

id
required
integer <int64>

64-bit integer identifier associated with this resource

call_status
string
Enum: "AVAILABLE" "IN_CALL"

Call presence status of this user

display_name
required
string

Human readable name of this user. Shown to other users

display_picture_url
required
string

URL for this user's display picture

isGuest
required
boolean

True if this user was created by a guest user session

name
required
string

The unique name used to identify this user across ChatKitty. Also known as username

required
object (ChatUserPresenceProperties)

Presence status of this user

required
object

Custom data associated with this user

Array of objects (Link)

Hypermedia control links for this resource

{}

Current User​

After starting a ChatKitty user session with a client SDK, you can request the current user anytime:

const result = await chatkitty.getCurrentUser();

const user = result.user; // Handle user

Observing the current user​

Get updates when the current user changes by registering an observer function.

const unsubscribe = chatkitty.onCurrentUserChanged((user) => {
  // handle new current user or current user changes
});

// call when you're no longer interested in updates
unsubscribe();
note

The observer function passed to onCurrentUserChanged is called with the current user value when first registered.

Updating the current user​

Update the current user by passing a function taking the current user and returning a user with the changes to be applied to your ChatKitty client instance.

await chatkitty.updateCurrentUser((user) => {
  // Perform updates
  user.properties = {
    ...user.properties,
    'favorite-number': 42
  };

  return user; // Return updated user
});

Updating the current user's display picture​

Upload a new profile picture for the current user:

await chatkitty.updateCurrentUserDisplayPicture({ file });

Updating the display picture with an externally hosted picture:

await chatkitty.updateCurrentUserDisplayPicture({
  file: {
    url: 'https://example.com/files/jane.png',
    name: 'jane.png',
    contentType: 'image/png',
    size: 123115
  }
});

Guest users​

If a user's isGuest is set to true or the user was implicitly created by a client SDK, the user is a guest user. Guest users can start a user session without authentication. Users with isGuest set to false are native users. Native users are required to be authenticated before starting user sessions.

Secure your user sessions

Guest users makes it easy to get started during development and allows use-cases involving anonymous users. However, we strongly recommend you disable guest users in production for security reasons.

Creating a user​

Create a user using the Platform API

POST /v1/users
curl --location --request 'POST' \
  'https://api.chatkitty.com/v1/users' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "jane@chatkitty.com",
  "displayName": "Jane Doe",
  "isGuest": false,
  "properties": {
    "favoriteNumber": 42
  }
}'

Retrieving a user by ID​

You can retrieve a user using both a client SDK or the Platform API

const result = await chatkitty.retrieveUser(USER-ID);

if (result.succeeded) {
  const user = result.user; // Handle result
}
curl "https://api.chatkitty.com/v1/applications/APP-ID/users/USER-ID" -H  "Authorization: Bearer OAUTH-TOKEN"

Observing user online/presence changes​

You can listen to changes to user presence changes from users who share at least one mutual channel - when users come online or go offline using a client SDK

chatkitty.onUserPresenceChanged(async (user) => {
  const presence = user.presence; // Update online users list
});
import { User, UserPresence } from 'chatkitty';

chatkitty.onUserPresenceChanged(async (user: User) => {
  const presence: UserPresence = user.presence; // Update online users list
});

See also​