Containers and messages
Every Livstick integration manipulates exactly two things: a container, which you create, and a message, which lands inside it. Keeping the two separate in your head is the fastest way to understand the rest of the API.
A container is a slot, not a content
A container does not hold a video, a photo, or any specific media by itself. It is an addressable slot — a place that will receive one, waiting to be filled. You create it before anything has been recorded, often before the recipient even knows it exists.
- You create the container with your own business reference (the crid) — an order id, a card id, a code printed on packaging.
- The container tracks delivery settings: sender, recipient, language, and the code group it belongs to.
- It carries the current state of the recording (whether a message has been released yet) and, from `mode`, how many messages it can hold.
A message is what arrives
A message is the thing your recipient actually records: a video, tied to the container it was recorded into. It has its own id, its own state, and its own data — separate from the container’s own fields.
One container, one or several messages
A container in single mode carries exactly one message: the one most recorded, most released, most delivered. A container in gallery mode can carry several — a running collection contributed to over time, all reachable from the same container.
Why this shape makes the widgets obvious
Once the split is clear, the two Livstick widgets are just the two things you do with it: the Recorder writes a message into a container, and the Viewer reads a message out of one. Nothing else about them needs explaining first.
- The Recorder is handed a container (through its urid) and produces a message inside it.
- The Viewer is handed a container and shows the message — or messages, in gallery mode — that landed inside it.
- Neither widget needs to know your business reference: that mapping lives on your side, through the crid.
Matching a use case to a mode
The mode you choose at creation decides how many messages a container accepts. The concept page on container modes covers the rule in full — here is where the common use cases land.
| Use case | Mode |
|---|---|
| E-commerce gift message | single |
| Gift card | single |
| Collective gift | gallery |
| Stories | gallery |
| Review collection | gallery |
| In-store activation from a pre-printed code | single |
Where to go next
This page only introduces the split. Each of the following pages covers one part of it in full.
- Identifiers
- How the crid, urid and editKey map onto a container.
- Container modes
- The full rule behind single and gallery mode.
- Container and message states
- What a container and a message can be, and when each state applies.
- Choosing an integration mode
- How the Recorder fits into your own recording flow.
- Viewer widget
- How the Viewer reads a message back out of a container.