Users

Identity

Amity SDKs do not store or manage any user data. This means that you do not have to import or migrate existing user profiles into the system. User management should be handled by your application code. Instead, every user is simply represented by a unique userID, which can be any string that uniquely identifies the user and is immutable throughout its lifetime.
A database primary key would make an ideal userID. Conversely, something like username or emails is not recommended as those values may change overtime.
If you wish to assign additional permissions for a user, for example moderation privileges or different sending limits, you can provide an array of roles to assign to this user. Roles are defined in the admin panel and can be tied to an unlimited number of users. Once again, Amity does not store or manage any user data, which means you do not have to import or migrate existing users into the system. It also means that Amity cannot provide user management functionalities like lists of users, or limit actions of certain users (e.g. user permissions). Instead, these functionalities should be handled by the rest of your application's capabilities and your server.

Descriptions of Users

Name
Data Type
Description
Attributes
userId
string
The id of this user
roles
Array.<string>
A list of user's roles
displayName
string
The display name of the user
flagCount
integer
The number of users that have flagged this user
metadata
Object
The metadata of the user
hashFlag
Object
A hash for checking internally if this user was flagged by the user
createdAt
date
The date/time the user was created at
updatedAt
date
The date/time the user was updated at

User Details

Each User consists of a userId and displayName. The userId is immutable once the account is created, however the displayName can be updated at all times.

Create User

To create a new user into the system, simply register your session:
1
import { connectClient } from '@amityco/ts-sdk';
2
const handleConnect = async (userId: string, displayName: string) => {
3
const userId = 'userId1';
4
const displayName = 'Bob Newton';
5
await connectClient(userId, displayName);
6
};
7
handleConnect();
Copied!
  1. 1.
    If user doesn’t exist, it will be created upon calling this method.
  2. 2.
    If displayName is passed, it will update the user directly.›
  3. 3.
    if displayName is passed, but secured mode is enabled, the values will be ignored.
For more details on connecting client such as secure mode, refer to the Getting Started session.

Delete User

SDK does not have a method for deleting users. You can however ban a user globally. When users are globally banned, they can no longer access Amity's network and will be forcibly removed from all their existing channels.
Refer to our global ban documentation for the instructions on how to global-ban a user.

Observe User

TypeScript SDK provides a convenient way get a single user using observeUser.
1
import { observeUser } from "@amityco/ts-sdk";
2
export default function UserItem({ userId }: { userId: string }) {
3
const [userResult, setUserResult] = useState<Amity.QueryResult<Amity.User | undefined>>(null)
4
const { data: avatar, options] = userResult;
5
const { loading, error } = options;
6
7
useEffect(
8
() => user && observeUser(userId, setUserResult),
9
[user],
10
);
11
return (
12
// Put your code here to display the user
13
);
14
}
Copied!

Get a user

You can also use the code below to get one user:
1
import { getUser, createQuery, runQuery } from '@amityco/ts-sdk';
2
const query = createQuery(getUser, 'userId');
3
runQuery(query, userResult => console.log(userResult));
Copied!

User model

1
type User = {
2
userId: string
3
displayName?: string
4
avatarFileId?: Amity.File<'image'>['fileId']
5
description?: string
6
metadata?: Record<string, any>
7
tags?: string[]
8
flagCount: number
9
hashFlag: {
10
bits: number
11
hashes: number
12
hash: string
13
} | null
14
roles: Amity.Role['displayName'][]
15
permissions: Amity.Permission[]
16
createdAt: timestamp
17
updatedAt?: timestamp
18
localId: string
19
syncedAt: number
20
}
Copied!

Update User Information

You can update information related to current user such as display name, avatar, user description, metadata, etc. amityClient class contains updateCurrentUser: method which allows you to update information about current user.
1
import { updateUser, createQuery, runQuery } from '@amityco/ts-sdk';
2
const query = createQuery(updateUser, 'userId', {
3
displayName: 'newDisplayName',
4
description: 'newDiscription',
5
avatarFileId: 'newAvatarFileId',
6
metadata: {
7
value: 'newValue'
8
}
9
});
10
runQuery(query, updateResult => console.log(updateResult));
Copied!
To flag a user, call the following method:
1
import { createReport, createQuery, runQuery } from '@amityco/ts-sdk';
2
const query = createQuery(createReport, 'user', 'userId');
3
4
runQuery(query, result => console.log(result));
Copied!
To unflag a user, call the following method:
1
import { deleteReport, createQuery, runQuery } from '@amityco/ts-sdk';
2
const query = createQuery(deleteReport, 'user', 'userId');
3
4
runQuery(query, result => console.log(result));
Copied!

Querying users

1
import { queryUser, createQuery, runQuery } from '@amityco/ts-sdk';
2
const query = createQuery(queryUser, {
3
filter: 'all' | 'flagged',
4
sortBy: 'displayName' | 'firstCreated' | 'lastCreated',
5
page: Amity.Page
6
});
7
runQuery(query, queryResult => console.log(queryResult));
Copied!

Search for Users

The queryUser provides a way to search for users by their display name.
1
import { queryUser, createQuery, runQuery } from '@amityco/ts-sdk';
2
const query = createQuery(queryUser, {
3
displayName: 'Test User 1'
4
});
5
runQuery(query, queryResult => console.log(queryResult));
Copied!
The above example searches for all users whose display names start with "Test User 1". Note that the search is case sensitive.

Dealing with avatars

You can easily retrieve the url of a file using observeFile and use it to display in your app later on. Here's an example in React:
1
import { observeFile } from "@amityco/ts-sdk";
2
export default function Avatar(props: Amity.User) {
3
const { avatarFileId } = props
4
const [fileResult, setFileResult] = useState<Amity.QueryResult<Amity.File | undefined>>(null)
5
const { data: avatar, options] = fileResult;
6
const { loading, error } = options;
7
8
useEffect(
9
() => avatar && observeFile(avatarFileId, setFileResult),
10
[avatar],
11
);
12
return (
13
// Put your code here to display the file
14
);
15
}
Copied!
Last modified 25d ago