Messages and tokens

A message is the video recorded for one purchase or one contribution. You name it with an mrid of your own choosing. Your server mints a short-lived token for that mrid, and the widget uses the token instead of an edit key or a recipient link. Your server never hands a secret key to the browser.

Before you read this

Read the containers reference first: a message always belongs to one container, and the container's mode decides how many messages it can hold. Containers and messages

The mrid

The mrid is your identifier for a message: an order line, a contribution, a donation. It is 1 to 64 characters from letters, digits, colon, underscore and hyphen. Within a container it is unique. A token minted for an mrid that does not exist yet creates that message when the widget records it.

What a message exposes

A message read through v3.1 returns different fields depending on the messageAccess setting of your platform. Livstick sets this value; your key cannot change it. The table lists the fields by level.

Message fields by messageAccess
Field	confidential	admin
messageId, mrid, role, state, held, durationMs, revision	Yes	Yes
createdAt, updatedAt, releasedAt, viewedAt	Yes	Yes
thumbnailUrl, videoUrl (published messages only)	No	Yes
data: firstname, lastname, relation; content	No	Yes
Contact details, sender IP, scoring, moderation state, edit key	Never	Never

Message states

The state field tells you where a message stands. Show only published messages to a public audience.

Message states
State	Meaning
processing	Recorded, not yet encoded.
held	Encoded and held until you release it (payment not yet confirmed).
pending_review	Waiting for a moderator decision.
published	Visible to its audience.
hidden	Hidden by a moderator. It can come back.
rejected	Rejected by moderation. It cannot be deleted through the API.
failed	Encoding failed.

Record tokens

A record token allows the widget to record one message for one mrid, in one container. Your server asks for it, then passes it to the browser as the recordToken property of the widget.

POST /containers/{crid}/record-tokens

curl https://<client-api-host>/api/v3.1/containers/AUB-20481/record-tokens \
  -H "Authorization: Bearer liv_<prefix>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{"mrid": "DON-51873", "role": "contributor", "hold": true, "expiresIn": 3600}'

role is organizer or contributor. A single container accepts only organizer, and a contributor request is refused with 409 MODE_MISMATCH.
hold is false by default. With hold set to true, the message is encoded and then held until you call release. It is not listed anywhere while held, and no e-mail is sent to other participants.
expiresIn is between 60 and 86400 seconds. The default is 3600.
sender.firstName and sender.lastName are optional and are used to pre-fill the widget.
Requesting a token for a closed gallery returns 409 GALLERY_CLOSED.

Hold and release for crowdfunding and e-commerce

Use hold when the video must not be visible before a payment is confirmed. The flow has three steps, and the order of the calls is yours to decide.

Mint a record token with hold set to true, and let the widget record. The widget reports message.held; nothing is listed and nothing is sent to others.
When the payment is confirmed on your side, call POST /containers/{crid}/messages/{mrid}/release. The call is idempotent: a message that is already released returns 200 without change.
The message becomes visible, and Livstick sends message.ready, and gallery.message_added for a gallery contribution.

View tokens

A view token lets the widget read messages and play them. It is the only credential a public page needs, and it grants reading only: no reaction and no seen mark. Reactions still need the urid of the recipient.

POST /containers/{crid}/view-tokens

curl https://<client-api-host>/api/v3.1/containers/AUB-20481/view-tokens \
  -H "Authorization: Bearer liv_<prefix>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{"scope": "viewer", "mrid": "DON-51873", "expiresIn": 900}'

scope is viewer or owner. An owner token also lets the widget show the mrid of each message and the context you pass to it; use it on your back office, not on a public page.
mrid is optional. Without it, the token reads every listed message of the container. With it, the token reads that message only, and the mrid must exist (404 MESSAGE_NOT_FOUND otherwise).
expiresIn is between 60 and 3600 seconds. The default is 900.
The response does not contain the urid. The page that receives the token does not need it.

Delete a message

DELETE /containers/{crid}/messages/{mrid} removes a message for a refund or a withdrawal. It returns 204. The author receives no e-mail: the message.deleted webhook tells your system, and your system decides whether to write.

The main message of a gallery cannot be deleted while other messages remain: 409 GALLERY_NOT_EMPTY.
A message rejected by moderation cannot be deleted through the API: 409 MESSAGE_REJECTED.
The webhook reason is client for a call made by your key.

Listing messages

GET /containers/{crid}/messages lists the messages of a container, main message first, then in the order they were recorded. Filter with mrid for one message, or state for a state from the table above. The page size is 1 to 200, 50 by default.