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
customproperty, 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 — REQUIREDYour app's subscribe key from Admin Portal. |
channel string — REQUIREDThe channel ID to perform the operation on. Must not be empty and can contain up to 92 UTF-8 byte sequences. Prohibited characters are: |
| Query Parameters |
|---|
include string[]Possible values: [ List of additional/complex metadata to include in the response. Omit this query parameter if you don't want to retrieve additional metadata. |
limit integerPossible values: value ≤ 100 Number of objects to return in response. Default is |
start stringRandom 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 stringRandom 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 |
count booleanRequest |
filter stringExpression 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:
Example (Simple expression):
Example (Date/time comparison):
Example (Compound expression):
Example (Wildcard):
Example (Escaped wildcard):
|
sort string[]Possible values: Value must match regular expression List of properties to sort by.
Append Example:
|
auth stringString which is either the auth key (Access Manager legacy) 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 stringSignature 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 integerUnix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 seconds offset from NTP.
Required if |
| Request Body — REQUIRED JSON object with changes to the channel members' list. | |||||
|---|---|---|---|---|---|
set object[]
| |||||
delete object[]
|
| Responses | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200Successfully set the channel members' metadata.
| ||||||||||||||||||||||
400The request body contains invalid data.
| ||||||||||||||||||||||
403Disabled - 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.
| ||||||||||||||||||||||
415The format of the request body you supplied isn't supported. The request body must be in JSON format.
| ||||||||||||||||||||||
429Request rate limit exceeded.
| ||||||||||||||||||||||
500An internal server error occurred.
| ||||||||||||||||||||||
503Request processing exceeded the maximum allowed time.
|
sub_key*channel*Prohibited characters are:
,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.includelimit100, which is also the maximum value.startendstart parameter is provided.counttotalCount to be included in the paginated response. By default, totalCount is omitted.filterFor 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.
sortAppend
:asc or :desc to a property to specify sort direction. The default sort direction is ascending.authsignatureIf 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.
timestampRequired if
signature parameter is supplied.setitems{"uuid":{"id":"uuid-4"}}deleteitems{"uuid":{"id":"uuid-4"}}{
"set": [
{
"uuid": {
"id": "uuid-5"
},
"custom": {
"role": "moderator"
}
}
],
"delete": [
{
"uuid": {
"id": "uuid-0"
}
}
]
}dataitems{"uuid":{"id":"uuid-2","name":"John Doe","externalId":null,"profileUrl":null,"email":"jack@twitter.com","custom":null,"updated":"2019-02-20T23:11:20.893Z","eTag":"MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg=="},"custom":{"role":"admin"},"updated":"2019-02-20T23:11:20.893Z","eTag":"QkRENDA5MjItMUZCNC00REI5LUE4QTktRjJGNUMxNTc2MzE3Cg=="}statustotalCountnextprev{
"status": 200,
"data": [
{
"uuid": {
"id": "uuid-2",
"name": "John Doe",
"externalId": null,
"profileUrl": null,
"email": "jack@twitter.com",
"custom": null,
"updated": "2019-02-20T23:11:20.893Z",
"eTag": "MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg=="
},
"custom": {
"role": "admin"
},
"updated": "2019-02-20T23:11:20.893Z",
"eTag": "QkRENDA5MjItMUZCNC00REI5LUE4QTktRjJGNUMxNTc2MzE3Cg=="
},
{
"uuid": {
"id": "uuid-3",
"name": "Bob Cat",
"externalId": null,
"profileUrl": null,
"email": "bobc@example.com",
"custom": {
"phone": "999-999-9999"
},
"updated": "2019-02-21T03:29:00.173Z",
"eTag": "QkRENDA5MjItMUZCNC00REI5LUE4QTktRjJGNUMxNTc2MzE3Cg=="
},
"updated": "2019-02-20T23:11:20.893Z",
"eTag": "QkRENDA5MjItMUZCNC00REI5LUE4QTktRjJGNUMxNTc2MzE3Cg=="
}
],
"totalCount": 37,
"next": "RDIwQUIwM0MtNUM2Ni00ODQ5LUFGRjMtNDk1MzNDQzE3MUVCCg==",
"prev": "MzY5RjkzQUQtNTM0NS00QjM0LUI0M0MtNjNBQUFGODQ5MTk2Cg=="
}statuserror{
"status": 400,
"error": {
"message": "Request payload contained invalid input.",
"source": "metadata",
"details": [
{
"message": "The email must be a valid email address.",
"location": "uuid.email",
"locationType": "body"
}
]
}
}statuserror{
"status": 403,
"error": {
"message": "Invalid signature",
"source": "authz",
"details": [
{
"message": "Client and server produced different signatures for the same inputs.",
"location": "signature",
"locationType": "query"
}
]
}
}statuserror{
"status": 415,
"error": {
"message": "Request payload must be in JSON format.",
"source": "metadata"
}
}statuserror{
"status": 429,
"error": {
"message": "You have exceeded the maximum number of requests per second allowed for your subscribe key.",
"source": "metadata"
}
}statuserror{
"status": 500,
"error": {
"message": "An unexpected error occurred while processing the request.",
"source": "metadata"
}
}statuserror{
"status": 503,
"error": {
"message": "The server took longer to respond than the maximum allowed processing time.",
"source": "metadata"
}
}