Response Messages and State

Some types of messages need to share state changes among all participants. For example:

  • A choice message where one participant is asked a question, and selects an answer should show that user’s selection to all participants.
  • A Like button selected by one user should render to indicate to other users that this thing is “Liked”
  • A Credit Card form that has been validated should show as validated to all users

State is added to a Message using its Response Summary Message Part; this is a Message Part that Layer adds to a Message when the state is changed, and which Layer then updates whenever any further state changes take place.

Note

Do not ever create or directly edit the Response Summary Message Part; this part must be managed using the Message Response Integration Service which you will need to install.

The following steps are used to update Message State:

  1. A new State is calculated for a Message and needs to be shared
  2. A Response Message is sent that contains a description of the change to users, and a separate description in a separate Message Part describing the change to the Message Response Integration Service.
  3. The Message Response Integration Service receives the Response Message via a webhook, and updates the local state of the Message (this is why only this service should ever edit the Response Summary Message Part).
  4. The Message Response Integration Service uses Layer’s Server API to add or update a Response Summary Message Part containing the new state
  5. All clients receive the updated Response Summary and update their local state

Customers wanting to trigger actions on their servers whenever a state change occurs should typically wait for:

  • MessagePart.created Webhook event indicating that a new mime_type: application/vnd.layer.responsesummary-v2+json;role=response_summary Message Part has been created with initial state
  • MessagePart.updated Webhook event indicating that a new mime_type: application/vnd.layer.responsesummary-v2+json;role=response_summary Message Part has been updated with new state

Waiting for the above process to complete and for the Response Summary to show the new data insures that your server will see the same resolved state that all clients will see. Alternatively, listening for the Response Message itself via webhooks will get the state change faster, but without understanding the details of how state changes are resolved on the server, it is possible to incorrectly determine the new Response Summary state solely by looking at one Response Message.

Conflict Free Replicated Datatype (CRDT)

CRDT operations are used to resolve conflicts that can occur when multiple devices send conflicting states, or multiple states are sent in parallel, and a shared resolution needs to be processed and rendered by all clients. This is managed primily via Operation ids that are tracked with their respective values, and flagged as removed once those values are no longer available. This adds some complexity to understanding the datastructures involved, but results in much smoother operation of state changes.