Set channel members' metadata

Sets the members's metadata in the specified channel. Use the set and delete properties in the request body to perform those operations on one or more memberships.

Returns the list of channel members' metadata, optionally including:

  • Channel's custom properties
  • Custom properties for each UUID's membership in the channel
  • Each UUID's custom properties

Note:

  • You can change all of the membership object's properties except its identifier.

  • Invalid property names are silently ignored and will not cause a request to fail.

  • If you set the custom property, you must completely replace it since partial updates are not supported.

  • The custom object can only contain scalar values.

  • Enabling referential integrity on your app’s keyset in the Admin Portal ensures that memberships can only be created for existing users and channels, and automatically deletes memberships when their associated user or channel is deleted.

    If it’s not enabled, memberships can be created even for the non-existent user and channel entities, while deleting a user or channel entity does not automatically delete any associated membership objects.

Path Parameters
sub_key string — REQUIRED

Your app's subscribe key from Admin Portal.

channel string — REQUIRED

The channel name to perform the operation on. Must not be empty and can contain up to 92 UTF-8 byte sequences.

Prohibited characters are: ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.

Query Parameters
include string[]

Possible values: [custom, status, type, uuid, uuid.custom, uuid.status, uuid.type]

List of additional/complex metadata to include in the response. Omit this query parameter if you don't want to retrieve additional metadata.

limit integer

Possible values: value ≤ 100

Number of objects to return in response. Default is 100, which is also the maximum value.

start string

Random string returned from the server, including a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.

end string

Random string returned from the server, including a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is provided.

count boolean

Request totalCount to be included in the paginated response. By default, totalCount is omitted.

filter string

Expression used to filter the results. Only objects whose properties satisfy the given expression are returned.

For details on App Context Filtering, refer to documentation.

Note the following:

  • Date/time properties, such as updated, must be compared to valid date/time strings formatted according to ISO 8601.
  • Custom properties must have the same type as the value used in the expression; it is an error to compare a custom property of one type to another.
  • Objects that do not have the referenced custom property are excluded regardless of the operator or value used in the expression. The null value can be used to filter out objects that do or do not have the referenced custom property.
  • The LIKE operator supports wildcards denoted by the * character. A wildcard matches any sequence of arbitrary Unicode characters, including the empty sequence. The literal asterisk is matched when escaped using the backslash (\) character.
  • Values used with LIKE must be properly encoded just like any other string value. Thus, to escape an asterisk, the raw value must contain \\*.
  • The entire expression must be properly URL-encoded when used in the query string.

Example (Simple expression): custom.public == true

Example (Date/time comparison): updated >= "2019-08-31T00:00:00Z"

Example (Compound expression): description == null && (custom.label != "" || custom.description != "")

Example (Wildcard): name LIKE 'X*'

Example (Escaped wildcard): name LIKE '*\**'

sort string[]

Possible values: Value must match regular expression ^[^:]+(:(asc|desc))?$

List of properties to sort by. Append :asc or :desc to a property to specify sort direction. The default sort direction is ascending.

Example: updated,status,type,uuid.id,uuid.name,uuid.updated,uuid.status,uuid.type

auth string

String which is either the auth key (PAM v2) or a valid token (Access Manager) used to authorize the operation if access control is enabled. Authorization token with permissions to perform the request.

signature string

Signature used to verify that the request was signed with the secret key associated with the subscribe key.

If Access Manager is enabled, either a valid authorization token or a signature are required. Check Access Manager documentation for details on how to compute the signature.

timestamp integer

Unix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 seconds offset from NTP. Required if signature parameter is supplied.

Request Body — REQUIRED

JSON object with changes to the channel members' list.

set object[]
uuid object — REQUIRED

Object with the UUID identifier.

id string

Possible values: 1 ≤ length ≤ 92

A UTF-8 encoded string used to identify the client. Must not be empty, and may contain up to 92 UTF-8 byte sequences.

Prohibited characters are: ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.

type string

Membership type. Max. 50 characters.

status string

Membership status. Max. 50 characters.

custom object

JSON object of key/value pairs with supported data-types. Values must be scalar only; arrays or objects are not supported.

NOTE: If you set custom fields with integer values, do not specify numbers larger than 9007199254740991 due to precision limitations in JSON implementations. For large integer values, for example PubNub timetoken values, use string values instead of integers.

delete object[]
uuid object — REQUIRED

Object with the UUID identifier.

id string

Possible values: 1 ≤ length ≤ 92

A UTF-8 encoded string used to identify the client. Must not be empty, and may contain up to 92 UTF-8 byte sequences.

Prohibited characters are: ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.

Responses
200

Successfully set the channel members' metadata.

Schema — OPTIONAL
data object[] — OPTIONAL

List of returned objects.

uuid object — OPTIONAL

Object with UUID metadata used in responses.

id string — OPTIONAL

Possible values: 1 ≤ length ≤ 92

A UTF-8 encoded string used to identify the client. Must not be empty, and may contain up to 92 UTF-8 byte sequences.

Prohibited characters are: ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.

name string — OPTIONAL

Possible values: 1 ≤ length

Name of the UUID. Max. 2,048 characters. Must not be empty or consist only of whitespace characters.

externalId string — OPTIONAL

UUID's identifier in an external system. Max. 2,048 characters.

profileUrl uri — OPTIONAL

URL for the UUID's profile picture. Max. 2,048 characters. Syntax is as defined in RFC 3986.

email email — OPTIONAL

The UUID's email address. Max. 320 characters. Syntax is as defined by RFC 5322 and extended by RFC 6532, with one exception: the display-name part is not allowed (only the addr-spec part is allowed).

type string — OPTIONAL

User type. Max. 50 characters.

status string — OPTIONAL

User status. Max. 50 characters.

custom object — OPTIONAL

JSON object of key/value pairs with supported data-types. Values must be scalar only; arrays or objects are not supported.

NOTE: If you set custom fields with integer values, do not specify numbers larger than 9007199254740991 due to precision limitations in JSON implementations. For large integer values, for example PubNub timetoken values, use string values instead of integers.

updated date-time — OPTIONAL

Date and time the object was last updated.

eTag string — OPTIONAL

Information on the object's content fingerprint.

NOTE: eTag from GET requests can be used alongside the If-Match HTTP header in conditional PATCH requests in users/channels' metadata APIs. This functionality is currently not supported in the membership/members' metadata APIs.

type string — OPTIONAL

Membership type. Max. 50 characters.

status string — OPTIONAL

Membership status. Max. 50 characters.

custom object — OPTIONAL

JSON object of key/value pairs with supported data-types. Values must be scalar only; arrays or objects are not supported.

NOTE: If you set custom fields with integer values, do not specify numbers larger than 9007199254740991 due to precision limitations in JSON implementations. For large integer values, for example PubNub timetoken values, use string values instead of integers.

updated date-time — OPTIONAL

Date and time the object was last updated.

eTag string — OPTIONAL

Information on the object's content fingerprint.

NOTE: eTag from GET requests can be used alongside the If-Match HTTP header in conditional PATCH requests in users/channels' metadata APIs. This functionality is currently not supported in the membership/members' metadata APIs.

status integer — OPTIONAL

HTTP status code.

totalCount integer — OPTIONAL

Total count of objects without pagination.

next string — OPTIONAL

Random string returned from the server, including a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.

prev string — OPTIONAL

Random string returned from the server, including a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.

400

The request body contains invalid data.

Schema — OPTIONAL
status integer — OPTIONAL

HTTP status code.

error object — OPTIONAL

Error response.

message string — OPTIONAL

User-facing error message.

source string — OPTIONAL

Possible values: [metadata, authz]

Internal source of the error.

details object[] — OPTIONAL
message string — OPTIONAL

A user-facing error message.

location string — OPTIONAL

Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.

locationType string — OPTIONAL

Possible values: [path, query, header, body]

403

Disabled - The subscribe key doesn't have App Context API enabled.

Forbidden - The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.

Schema — OPTIONAL
status integer — OPTIONAL

HTTP status code.

error object — OPTIONAL

Error response.

message string — OPTIONAL

User-facing error message.

source string — OPTIONAL

Possible values: [metadata, authz]

Internal source of the error.

details object[] — OPTIONAL
message string — OPTIONAL

A user-facing error message.

location string — OPTIONAL

Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.

locationType string — OPTIONAL

Possible values: [path, query, header, body]

415

The format of the request body you supplied isn't supported. The request body must be in JSON format.

Schema — OPTIONAL
status integer — OPTIONAL

HTTP status code.

error object — OPTIONAL

Error response.

message string — OPTIONAL

User-facing error message.

source string — OPTIONAL

Possible values: [metadata, authz]

Internal source of the error.

details object[] — OPTIONAL
message string — OPTIONAL

A user-facing error message.

location string — OPTIONAL

Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.

locationType string — OPTIONAL

Possible values: [path, query, header, body]

429

Request rate limit exceeded.

Schema — OPTIONAL
status integer — OPTIONAL

HTTP status code.

error object — OPTIONAL

Error response.

message string — OPTIONAL

User-facing error message.

source string — OPTIONAL

Possible values: [metadata, authz]

Internal source of the error.

details object[] — OPTIONAL
message string — OPTIONAL

A user-facing error message.

location string — OPTIONAL

Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.

locationType string — OPTIONAL

Possible values: [path, query, header, body]

500

An internal server error occurred.

Schema — OPTIONAL
status integer — OPTIONAL

HTTP status code.

error object — OPTIONAL

Error response.

message string — OPTIONAL

User-facing error message.

source string — OPTIONAL

Possible values: [metadata, authz]

Internal source of the error.

details object[] — OPTIONAL
message string — OPTIONAL

A user-facing error message.

location string — OPTIONAL

Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.

locationType string — OPTIONAL

Possible values: [path, query, header, body]

503

Request processing exceeded the maximum allowed time.

Schema — OPTIONAL
status integer — OPTIONAL

HTTP status code.

error object — OPTIONAL

Error response.

message string — OPTIONAL

User-facing error message.

source string — OPTIONAL

Possible values: [metadata, authz]

Internal source of the error.

details object[] — OPTIONAL
message string — OPTIONAL

A user-facing error message.

location string — OPTIONAL

Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.

locationType string — OPTIONAL

Possible values: [path, query, header, body]