WebWebNode.jsPhoneGapReact V4JavaScriptJavaScript V4 Objects (BETA) API Reference for Realtime Apps

Go to Mobile Push


Objects provides easy-to-use, serverless storage for data you need to build innovative, reliable, scalable Chat applications. Use Object information across your connected experience features. You can easily save, read, update, and delete information about your application users, shared communication spaces, and their relationships, without the need to stand up a database. Simply build and go.

For more information about Objects, refer to the Objects tutorial.

 Objects is an optional feature, currently in a BETA release—you can use your own user management system, and simply use the usual publish and subscribe. If you'd like to use PubNub's serverless storage, Objects provides a full-featured solution.

Creates a user with the specified properties. Returns the created user object, optionally including the user's custom data object.

To Create a User you can use the following method(s) in the JavaScript V4 SDK:
  1. ParameterTypeRequiredDefaultsDescription
    Operation Arguments HashA hash of arguments.
    id String YesThe user ID. Must be unique, and is limited to 36 characters.
    name String YesDisplay name for the user. Maximum 200 characters.
    externalId String OptionalUser's identifier in an external system
    profileUrl String OptionalThe URL of the user's profile picture
    email String OptionalThe user's email address. Maximum 80 characters.
    custom Object OptionalJSON object of key-value pairs with supported data types. Values must be scalar only; arrays or objects are not supported.
    include Object Optional{ customFields: true}List of additional/complex user attributes to include in response. Currently, customFields is the only supported attribute: set to false to omit the custom data object.
pubnub.createUser(
    {
        id: "user-1",
        name: "John Doe"
    },
    function(status, response) {

    }
);
{
    "status": 200,
    "data": {
        "id": "user-1",
        "name": "John Doe",
        "externalId": null,
        "profileUrl": null,
        "email": null,
        "created": "2019-08-16T00:03:54.689896Z",
        "updated": "2019-08-16T00:03:54.689896Z",
        "eTag": "Ae+lk5mmuf7pLA"
    }
}

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

To Update a User you can use the following method(s) in the JavaScript V4 SDK:
  1. ParameterTypeRequiredDefaultsDescription
    Operation Arguments HashA hash of arguments.
    id StringYesUnique identifier of the user to be updated. You cannot change the user ID.
    name StringYesDisplay name for the user. Maximum 200 characters.
    externalId StringOptionalUser's identifier in an external system
    profileUrl StringOptionalThe URL of the user's profile picture
    email StringOptionalThe user's email address. Maximum 80 characters.
    custom ObjectOptionalJSON object of key-value pairs with supported data types. Values must be scalar only; arrays or objects are not supported.
    include ObjectOptional{ customFields: true}List of additional/complex user attributes to include in response. Currently, customFields is the only supported attribute: set to false to omit the custom data object.
pubnub.updateUser(
    {
        id: "user-1",
        name: "John Updated Doe"
    },
    function(status, response) {}
);
{
    "status": 200,
    "data": {
        "id": "user-1",
        "name": "John Updated Doe",
        "externalId": null,
        "profileUrl": null,
        "email": null,
        "created": "2019-08-16T00:03:54.689896Z",
        "updated": "2019-08-16T00:03:54.689896Z",
        "eTag": "Ae+lk5mmuf7pLA"
    }
}

Deletes the specified user object.

To Delete a User you can use the following method(s) in the JavaScript V4 SDK:
  1. ParameterTypeRequiredDefaultsDescription
    userId StringYesID of the user to delete
pubnub.deleteUser("user-1", function(status, response) {
    
});
{
    "status": 200,
    "data": null
}

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

To Get Users you can use the following method(s) in the JavaScript V4 SDK:
  1. ParameterTypeRequiredDefaultsDescription
    Operation Arguments HashA hash of arguments.
    limit NumberOptional100Maximum number of results to return per page
    page ObjectOptional

    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 ObjectOptional {
    customFields: false,
    totalCount: false
    }
    Specifies whether to include custom fields in the response, and whether to include a total result count.
pubnub.getUsers(
    {
        limit: 10
    },
    function(status, response) {
    
    }
);
{
    "status": 200,
    "data": [
        {
            "id": "user-1",
            "name": "John Doe",
            "externalId": "user-1",
            "profileUrl": "http://profile.com/user/john",
            "email": "john@email.com",
            "created": "2019-08-14T19:12:20.653698Z",
            "updated": "2019-08-15T21:16:12.940425Z",
            "eTag": "Ab+Y676I+7SaKw"
        },
        {
            "id": "user-2",
            "name": "Steve Doe",
            "externalId": "user-2",
            "profileUrl": "http://profile.com/user/steve",
            "email": "steve@email.com",
            "created": "2019-08-15T08:24:10.969884Z",
            "updated": "2019-08-15T14:57:51.747819Z",
            "eTag": "AaLS46PS/tOk6gE"
        }
    ],
    "next": "Mw"
}

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

To Get User you can use the following method(s) in the JavaScript V4 SDK:
  1. ParameterTypeRequiredDefaultsDescription
    Operation Arguments HashA hash of arguments.
    userId StringYesThe ID of the user to retrieve
    include ObjectOptional{ customFields: true}Specifies whether to include the user's custom data field
pubnub.getUser(
    {
        userId: "user-1"
    },
    function(status, response) {
    
    }
);
{
    "status": 200,
    "data": {
        "id": "user-1",
        "name": "John Doe",
        "externalId": "user-123",
        "profileUrl": "http://profile.com/user/john",
        "email": "john@email.com",
        "created": "2019-08-14T19:12:20.653698Z",
        "updated": "2019-08-15T21:16:12.940425Z",
        "eTag": "Ab+Y676I+7SaKw"
    }
}

Creates a space with the specified properties. Returns the created space object, optionally including the space's custom data object.

To Create a Space you can use the following method(s) in the JavaScript V4 SDK:
  1. ParameterTypeRequiredDefaultsDescription
    Operation Arguments HashA hash of arguments.
    id StringYesUnique identifier of the space.
    name StringYesDisplay name of the space.
    description StringOptionalDescription of the space.
    custom ObjectOptionalJSON object of key-value pairs with supported data types. Values must be scalar only; arrays or objects are not supported.
    include ObjectOptional{ customFields: true}List of additional/complex space attributes to include in response. Currently, customFields is the only supported attribute: set to false to omit the custom data object.
pubnub.createSpace(
    {
        id: "space-1",
        name: "Demo Space"
    },
    function(status, response) {
    
    }
);
{  
    "status":200,
    "data":{  
        "id":"space-1",
        "name":"Demo space",
        "description":"a space for the engineering team",
        "created":"2019-08-14T19:11:32.300414Z",
        "updated":"2019-08-14T19:16:14.468003Z",
        "eTag":"Ad7+ocehr5nZHw"
    }
}

Updates a space with the specified properties. Returns the updated space object, optionally including the space's custom data object.

To Update a Space you can use the following method(s) in the JavaScript V4 SDK:
  1. ParameterTypeRequiredDefaultsDescription
    Operation Arguments HashA hash of arguments.
    id StringYesUnique identifier of the space to be updated. You cannot change the space ID.
    name StringYesDisplay name of the space.
    description StringOptionalDescription of the space.
    custom ObjectOptionalJSON object of key-value pairs with supported data types. Values must be scalar only; arrays or objects are not supported.
    include ObjectOptional{ customFields: true}List of additional/complex space attributes to include in response. Currently, customFields is the only supported attribute: set to false to omit the custom data object.
pubnub.updateSpace(
    {
        id: "space-1",
        name: "Demo Updated Space"
    },
    function(status, response) {
    
    }
);
{  
    "status":200,
    "data":{  
        "id":"space-1",
        "name":"Demo Updated Space",
        "description":"a space for the engineering team",
        "created":"2019-08-14T19:11:32.300414Z",
        "updated":"2019-08-14T19:16:14.468003Z",
        "eTag":"Ad7+ocehr5nZHw" 
    }
}

Deletes the specified space object.

To Delete a Space you can use the following method(s) in the JavaScript V4 SDK:
  1. ParameterTypeRequiredDefaultsDescription
    spaceId String YesUnique identifier of the space to be deleted
pubnub.deleteSpace("space-1", function(status, response) {

});
{
    "status": 200,
    "data": null
}

Returns the paginated list of space objects, optionally including the space's custom data object.

To Get Spaces you can use the following method(s) in the JavaScript V4 SDK:
  1. ParameterTypeRequiredDefaultsDescription
    Operation Arguments HashA hash of arguments.
    limit NumberOptional100Maximum number of results to return per page
    page ObjectOptional

    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 ObjectOptional {
    customFields: false,
    totalCount: false
    }
    Specifies whether to include custom fields in the response, and whether to include a total result count.
pubnub.getSpaces(
    {
        limit: 10
    },
    function(status, response) {
    
    }
);
{
    "status": 200,
    "data": [
        {
            "id": "space-1",
            "name": "demo space",
            "description": "demo space",
            "created": "2019-08-14T19:10:59.169062Z",
            "updated": "2019-08-14T19:10:59.169062Z",
            "eTag": "AejRtOqosaX9YQ"
        },
        {
            "id": "space-2",
            "name": "main",
            "description": "main space",
            "created": "2019-08-14T19:11:32.300414Z",
            "updated": "2019-08-14T19:16:14.468003Z",
            "eTag": "Ad7+ocehr5nZHw"
        }
    ],
    "next": "Mw"
}

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

To Get a Space you can use the following method(s) in the JavaScript V4 SDK:
  1. ParameterTypeRequiredDefaultsDescription
    Operation Arguments HashA hash of arguments.
    spaceId String YesThe ID of the space to retrieve
    include Object Optional {customFields: true}Specifies whether to include custom fields in the response
pubnub.getSpace(
    {
        spaceId: "space-1"
    },
    function(status, response) {
    
    }
);
{  
    "status":200,
    "data":{  
        "id":"space-1",
        "name":"Demo space",
        "description":"a space for the engineering team",
        "created":"2019-08-14T19:11:32.300414Z",
        "updated":"2019-08-14T19:16:14.468003Z",
        "eTag":"Ad7+ocehr5nZHw"
    }
}

Get the specified user's space memberships.

To Get Memberships you can use the following method(s) in the JavaScript V4 SDK:
  1. ParameterTypeRequiredDefaultsDescription
    Operation Arguments HashA hash of arguments.
    userId StringYesID of the user whose memberships you wish to retrieve
    limit NumberOptional100Maximum number of results to return per page
    page ObjectOptional

    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 ObjectOptional {
    customFields: false,
    totalCount: false
    }
    Specifies whether to include custom fields in the response, and whether to include a total result count.
pubnub.getMemberships(
    {
        userId: "user-1"
    },
    function(status, response) {
    
    }
);
{
    "status": 200,
    "data": [
        {
            "id": "space-1",
            "created": "2019-08-14T19:41:10.31085Z",
            "updated": "2019-08-14T19:56:24.712691Z",
            "eTag": "AYu9+4jfyfXRaQ"
        }
    ],
    "next": "MQ"
}

Get the specified space’s member users.

To Get Members you can use the following method(s) in the JavaScript V4 SDK:
  1. ParameterTypeRequiredDefaultsDescription
    Operation Arguments HashA hash of arguments.
    spaceId StringYesID of the space whose members you wish to retrieve
    limit NumberOptional100Maximum number of results to return per page
    page ObjectOptional

    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 ObjectOptional {
    customFields: false,
    totalCount: false
    }
    Specifies whether to include custom fields in the response, and whether to include a total result count.
pubnub.getMembers(
    {
        spaceId: "space-1"
    },
    function(status, response) {
    
    }
);
{
    "status": 200,
    "data": [
        {
            "id": "user-1",
            "created": "2019-08-14T19:41:10.31085Z",
            "updated": "2019-08-14T19:56:24.712691Z",
            "eTag": "AYu9+4jfyfXRaQ"
        }
    ],
    "next": "MQ"
}

Join a user to a list of spaces.

To Join Spaces you can use the following method(s) in the JavaScript V4 SDK:
  1. ParameterTypeRequiredDefaultsDescription
    Operation Arguments HashA hash of arguments.
    userId StringYesThe ID of the user to add to the space(s)
    spaces Array of ObjectYes

    Array of objects indicating the space(s) to be joined, along with optional custom data.

    [
    {
    id: "space-id-1"
    custom: { ... }
    },
    {
    id: "space-id-2"
    custom: { ... }
    },
    ]
    limit NumberOptional100Maximum number of results to return per page
    page ObjectOptional

    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 ObjectOptional {
    customFields: false,
    totalCount: false
    }
    Specifies whether to include custom fields in the response, and whether to include a total result count.
pubnub.joinSpaces(
    {
        userId: "user-1",
        spaces: [
            {
                id: "space-1"
            },
            {
                id: "space-2"
            }
        ]
    },
    function(status, response) {
    
    }
);

Update a user's space memberships.

To Update Memberships you can use the following method(s) in the JavaScript V4 SDK:
  1. ParameterTypeRequiredDefaultsDescription
    Operation Arguments HashA hash of arguments.
    userId StringYesThe ID of the user whose memberships you wish to update
    spaces Array of ObjectYes

    Array of objects indicating the complete list of space(s) to which the user should belong, along with optional custom data.

    [
    {
    id: "space-id-1"
    custom: { ... }
    },
    {
    id: "space-id-2"
    custom: { ... }
    },
    ]
    limit NumberOptional100Maximum number of results to return per page
    page ObjectOptional

    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 ObjectOptional {
    customFields: false,
    totalCount: false
    }
    Specifies whether to include custom fields in the response, and whether to include a total result count.
pubnub.updateMemberships(
    {
        userId: "user-1",
        spaces: [
            {
                id: "space-1",
                custom: {
                    starred: true
                }
            }
        ]
    },
    function(status, response) {

    }
);

Remove a user from a list of spaces.

To Leave Spaces you can use the following method(s) in the JavaScript V4 SDK:
  1. ParameterTypeRequiredDefaultsDescription
    Operation Arguments HashA hash of arguments.
    userId StringYesThe ID of the user to be removed from the space(s)
    spaces Array of StringYes

    The list of spaces from which to remove the user

    [
    "space-id-1",
    "space-id-2"
    ]
    limit NumberOptional100Maximum number of results to return per page
    page ObjectOptional

    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 ObjectOptional {
    customFields: false,
    totalCount: false
    }
    Specifies whether to include custom fields in the response, and whether to include a total result count.
pubnub.leaveSpaces(
    {
        userId: "user-1",
        spaces: [
            "space-1",
            "space-2"
        ]
    },
    function(status, response) {
    
    }
);

Add a list of users to a space.

To Add Members you can use the following method(s) in the JavaScript V4 SDK:
  1. ParameterTypeRequiredDefaultsDescription
    Operation Arguments HashA hash of arguments.
    spaceId StringYesThe ID of the space to which to add the specified user(s)
    users Array of ObjectYes

    List of users to add to the space, with optional custom data for each

    [
    {
    id: "user-id-1"
    custom: { ... }
    },
    {
    id: "user-id-2"
    custom: { ... }
    },
    ]
    limit NumberOptional100Maximum number of results to return per page
    page ObjectOptional

    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 ObjectOptional {
    customFields: false,
    totalCount: false
    }
    Specifies whether to include custom fields in the response, and whether to include a total result count.
pubnub.addMembers(
    {
        spaceId: "space-1",
        users: [
            {
                id: "user-1"
            },
            {
                id: "user-2"
            }
        ]
    },
    function(status, response) {
    
    }
);

Update a space's user memberships.

To Update Members you can use the following method(s) in the JavaScript V4 SDK:
  1. ParameterTypeRequiredDefaultsDescription
    Operation Arguments HashA hash of arguments.
    spaceId StringYesThe ID of the space whose membership you wish to update
    users Array of ObjectYes

    Array of objects indicating the complete list of user(s) who should belong to the space, along with optional custom data.

    [
    {
    id: "user-id-1"
    custom: { ... }
    },
    {
    id: "user-id-2"
    custom: { ... }
    },
    ]
    limit NumberOptional100Maximum number of results to return per page
    page ObjectOptional

    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 ObjectOptional {
    customFields: false,
    totalCount: false
    }
    Specifies whether to include custom fields in the response, and whether to include a total result count.
pubnub.updateMembers(
    {
        spaceId: "space-1",
        users: [
            {
                id: "user-1",
                custom: {
                    starred: true
                }
            },
            {
                id: "user-2",
                custom: {
                    starred: true
                }
            }
        ]
    },
    function(status, response) {
    
    }
);

Remove a list of users from a space.

To Remove Members you can use the following method(s) in the JavaScript V4 SDK:
  1. ParameterTypeRequiredDefaultsDescription
    Operation Arguments HashA hash of arguments.
    spaceId StringYesThe ID of the space from which to remove the specified user(s)
    users Array of StringYes

    The list of users to be removed from the space

    [
    "user-1",
    "user-2"
    ]
    limit NumberOptional100Maximum number of results to return per page
    page ObjectOptional

    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 ObjectOptional {
    customFields: false,
    totalCount: false
    }
    Specifies whether to include custom fields in the response, and whether to include a total result count.
pubnub.removeMembers(
    {
        spaceId: "space-1",
        users: [
            "user-1",
            "user-2"
        ]
    },
    function(status, response) {
    
    }
);

Go to MISCELLANEOUS