# Put a Sticker

This endpoint creates one or more Stickers and puts them on a given Twin.
Each Sticker has a "recipients" list. A user whose user, role or account UUID is included on the "recipients" list can view the Sticker in the response to the list_stickers endpoint and remove the Sticker from the Twin through the remove_sticker endpoint.

Method Path Operation*
POST /twins/{twin}/stickers put_sticker

*

In order for a user to perform the "put_sticker" operation, the "put_sticker" permission must be included in the list of allowed actions in the statement of the user's role.

# Request

Parameter Type In Description
{twin}
required
string path Twin UUID of the Twin on which the Sticker is to be put.
message
optional
string body Message for the recipients of the Sticker. The maximum length of a message is 256 characters.
recipients
required
list of strings body List of user UUIDs, role UUIDs, and account UUIDs that should be able to access and remove the sticker. The maximum number of items on the list is 100.
validity_ts
optional*
timestamp body Time at which the Sticker expires. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch (opens new window). The maximum validity of a Sticker is one year after the creation of a Sticker (now() + 1 Year). If the "validity_ts" is not provided in the request, the "validity_ts" is set to its maximum value (now() + 1 Year).
publish
optional**
list of strings, values are "on_put", "on_remove" or "on_expire" body List of events that should trigger a notification message for the Sticker. The event can be one of the following:
- "on_put": A notification message is triggered when a Sticker of the given color is put on a given Twin.
- "on_remove": A notification message is triggered when a Sticker of a given color is removed from the given Twin.
- "on_expire": A notification message is triggered when the "validity_ts" of a Sticker is reached and the Sticker expires. A notification message is triggered up to 60 seconds from the time a Sticker has expired.

*

If "validity_ts" with the value null is provided in the request body, a Sticker will not be created and the request will return an error.
If the request body does not contain "validity_ts", the value of "validity_ts" will be set to its maximum and default value which corresponds one year from now (now() + 1 year).

**

The "publish" parameter is optional. If the "publish" parameter is not provided in the request, a notification will not be set for the Sticker of the given color.

# Response

Attribute Type Description
message string Message for the recipients of the Sticker. The maximum length of a message is 256 characters.
recipients list of strings List of user UUIDs, role UUIDs, and account UUIDs that should be able to access and remove the sticker. The maximum number of items on the list is 100.
validity_ts timestamp Time at which the Sticker expires. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch (opens new window).
created_ts timestamp Time at which the Sticker was created. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch (opens new window).
publish
optional**
set of strings, values are "on_put", "on_remove" or "on_expire" List of events that should trigger a notification message for the Sticker. The event can be one of the following:
- "on_put": A notification message is triggered when a Sticker of the given color is put on a given Twin.
- "on_remove": A notification message is triggered when a Sticker of a given color is removed from the given Twin.
- "on_expire": A notification message is triggered when the "validity_ts" of a Sticker is reached and the Sticker expires. A notification message is triggered up to 60 seconds from the time a Sticker has expired.

# Status codes

Requests to this endpoint result in generic status codes. For a comprehensive list of status codes, please consult the Status codes section.