Users API

Users are entities who connect to the platform via applications. In the case of a chat application, users are actual people, and you may also want to add chatbots.

Users are identified by unique ID which is set by your application. Email addresses are too impermanent to use as user IDs. They also carry the potential for leakage of personal information. Users can also store properties such as a display name, profile URL, and email address. They can also have additional properties that are stored as custom fields.

UUIDs

Each client should pass a uuid that represents the user when it connects to PubNub. The uuid is needed to ensure that your billing is accurate and for other features like Presence and Message Persistence to work as expected.

State Shape​

The data about a user is stored as a slice in a normalized pool of Users. The following example shows the shape of Users in the store:

{
  "byId": {
    "user_53bbe00387004010a8b9ad5f36bdd4a7": {
      "id": "user_53bbe00387004010a8b9ad5f36bdd4a7",
      "name": "Gertie Gibbon",
      "externalId": null,
      "profileUrl": "https://www.gravatar.com/avatar/9e95672bf3246dc07b37f3b8668c5653?s=256&d=identicon",
      "email": null,
      "custom": {
        "title": "Account Representative II"
      },
      "updated": "2019-11-08T21:42:27.247264Z",
      "eTag": "AbvinbGe+7WDIA"
    }
  }
show all 16 lines

Reducers​

The PubNub Redux framework provides reducers your app can implement that respond to various actions that update the store. To track the state of a set of objects in the store, combine the reducers you want into the rootReducer for your app.

createUserDataReducer​

createUserDataReducer instantiates a reducer in the store that responds to actions dispatched to update the state of users in the store.

createUserDataReducer();

createUsersListReducer​

createUsersListReducer instantiates a reducer in the store that responds to actions dispatched to update the list of users in the store.

createUsersListReducer();

Listeners​

The PubNub Redux framework includes listeners that monitor PubNub events from the server and dispatch corresponding actions. All listeners are automatically invoked if your app registers the combined PubNub listener. You can register only specific listeners, or implement your own combine listeners function.

createUserDataListener​

createUserDataListener registers a listener in the store that monitors User events.

A sample implementation of a single listener:

pubnub.addListener(createUserDataListener(store.dispatch));

Commands​

The PubNub Redux framework provides commands that your app can dispatch to the store to be managed by the Thunk middleware. Commands interact with PubNub APIs and dispatch basic actions which are then processed by reducers to update the state in the store.

setUserData​

Sets the data for a user, including the user's custom data object.

setUserData( request, [meta] );

setUserData Arguments​

* required
ParameterDescription
request *
Type: UserRequest
User request parameter object.
[meta]
Type: object
Standard meta options object.

setUserData UserRequest Properties​

PropertyTypeRequiredDescription
uuid
string
Yes
The user ID. Must be unique, and is limited to 92 characters.
data
object
Yes
The data for the user.
[name]
string
Optional
Display name for the user.
[externalId]
string
Optional
User's identifier in an external system.
[profileUrl]
string
Optional
The URL of the user's profile picture.
[email]
string
Optional
The user's email address.
[custom]
object
Optional
JSON object of key-value pairs with supported data types. Values must be scalar only; arrays and objects aren't supported.
API limits

To learn about the maximum length of parameters used to set user metadata, refer to REST API docs.

setUserData Sample Usage​

dispatch(setUserData({
  uuid: 'user_53bbe00387004010a8b9ad5f36bdd4a7',
  data: {
    name: 'Gertie Gibbon',
    profileUrl: 'https://www.gravatar.com/avatar/9e95672bf3246dc07b37f3b8668c5653?s=256&d=identicon',
    custom: {
      title: 'Account Representative II'
    }
  }
}));

removeUserData​

Removes the specified user object.

removeUserData( request, [meta] );

removeUserData Arguments​

* required
ParameterDescription
request *
Type: removeUserDataRequest
Delete user request parameter object.
[meta]
Type: object
Standard meta options object.

removeUserData removeUserDataRequest Properties​

PropertyTypeRequiredDescription
uuid
string
Yes
ID of the user to delete.

removeUserData Sample Usage​

dispatch(removeUserData({
  uuid: 'user_53bbe00387004010a8b9ad5f36bdd4a7'
}));

fetchUserData​

Returns the specified user object, optionally including the user's custom data object.

fetchUserData( request, [meta] );

fetchUserData Arguments​

* required
ParameterDescription
request *
Type: fetchUserDataRequest
Fetch user request parameter object.
[meta]
Type: object
Standard meta options object.

fetchUserData fetchUserDataRequest Properties​

PropertyTypeRequiredDescription
uuid
string
Yes
The ID of the user to retrieve.

fetchUserData Sample Usage​

dispatch(fetchUserData({
  uuid: 'user_53bbe00387004010a8b9ad5f36bdd4a7'
}));

fetchAllUserData​

Returns a paginated list of user objects, optionally including each user's custom data object.

fetchAllUserData( request, [meta] );

fetchAllUserData Arguments​

* required
ParameterDescription
request *
Type: fetchAllUserDataRequest
Fetch users request parameter object.
[meta]
Type: object
Standard meta options object.
[include]
Type: object
Include respective additional fields in the response.
  [customFields]
Type: boolean
Whether to fetch custom fields or not.

fetchAllUserData fetchAllUserDataRequest Properties​

* required
ParameterDescription
limit
Type: number
Default:
100
Maximum number of results to return per page
filter
Type: string
Default:
n/a
Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sort
Type: string
Default:
n/a
Key-value pair of a property to sort by, and a sort direction. Available options are updated, id, and name.
Use asc or desc to specify sort direction, or specify null to take the default sort direction (ascending).
For example: {name: 'asc'}
page
Type: object
Default:
n/a
To get the next set of results, specify next.
To get the previous set of results, specify prev.
If you specify both, prev is ignored.
{
    next: "next-page-id",
    prev: "prev-page-id"
}
include
Type: object
Default:
{
    customFields: false,
    totalCount: false
}
Specifies whether to include custom fields in the response, and whether to include a total result count.

fetchAllUserData Sample Usage​

dispatch(fetchAllUserData({
  limit: 10,
  page: {
    next: 'Mg'
  }
}));

updateUser​

Updates a user with the specified properties, optionally including the user's custom data object.

updateUser( request, [meta] );

updateUser Arguments​

* required
ParameterDescription
request *
Type: UserRequest
Space request parameter object.
[meta]
Type: object
Standard meta options object.

updateUser UserRequest Properties​

PropertyTypeRequiredDescription
uuid
string
Yes
Unique identifier of the user to be updated. You can't change the user ID.
name
string
Yes
Display name for the user.
[externalId]
string
Optional
User's identifier in an external system.
[profileUrl]
string
Optional
The URL of the user's profile picture.
[email]
string
Optional
The user's email address.
[custom]
object
Optional
JSON object of key-value pairs with supported data types. Values must be scalar only; arrays and objects aren't supported.
API limits

To learn about the maximum length of parameters used to set user metadata, refer to REST API docs.

updateUser Sample Usage​

dispatch(updateUser({
  uuid: 'user_53bbe00387004010a8b9ad5f36bdd4a7',
  name: 'Gertrude Gibbon',
  profileUrl: 'https://www.gravatar.com/avatar/9e95672bf3246dc07b37f3b8668c5653?s=256&d=identicon',
  custom: {
    title: 'Sales Manager'
  }
}));
Last updated on
On this page