Container and message states
A container and the message it holds answer two different questions, asked by two different actors, at two different moments. Confusing the two states is the most common integration mistake — this page keeps them apart.
Before this page
This page assumes you already know what a container and a message are. Containers and messages
Two questions, two machines
The container asks your integration’s question: can recording still happen? The message asks the recipient’s question: can they see it? Nothing forces these to change together — a container can stay recording_open for a while after the message inside it has already been released, and a container can close while the message is still pending_release.
Container state: is recording still open?
ContainerState answers a question about the recorder, not about delivery. It has two values.
| State | What it means | What you can do |
|---|---|---|
| recording_open | The container still accepts a recording. | Show the recorder. The sender can still record or re-record. |
| recording_closed | Recording has ended for this container. | Stop offering the recorder. Show playback or a preview instead. |
Message state: can the recipient see it?
MessageState answers a question about delivery to the recipient, independently of whether recording is still open. It has four values.
| State | What it means | What you can do |
|---|---|---|
| pending_release | The message exists but hasn’t been made available to the recipient yet. | Wait, or trigger delivery yourself with notify or unlock. |
| released | The recipient can view the message now. | Treat the message as delivered in your own tracking. |
| delivery_triggered | Delivery has been set in motion — notify or unlock has been called. | Don’t call notify or unlock again; wait rather than re-triggering delivery. |
| unknown | The message state couldn’t be determined. | Don’t assume either way — re-check rather than telling the recipient it’s ready. |
Reading both states from one call
You don’t need two requests to answer both questions. GET /containers/{crid} returns the container’s current state together with the state of the message it holds, in a single call.
curl https://client-api.v5.livstick.com/api/v3/containers/{crid} \
-H "Authorization: Bearer {ACCESS_TOKEN}"