Response Messages

A Response Message consists of:

Field Required Type Description
messageIdToRespondTo Yes String The Message ID of the Message that this response is targeting
partIdToRespondTo Yes String UUID portion of the Message Part’s id for the Message Part being responded to (State change may be for Carousel Item #4 for example, rather than the entire Carousel)
changes Yes List List of Change operations
changes.operation Yes String One of add or remove to add or remove state
changes.type Yes String What behaviors are used when adding or removing state (FWW, LWW, LWWN, Set)
changes.value Yes String, Number, Boolean Value to add. Can be provided when doing remove operations, but is informational only and not used to process the removal
changes.name Yes String Name of the state to be changed (i.e. selected, signature, color)
changes.id Yes String Random 6 character string identifying the add operation, or the operation to undo via remove

Message Part Roles:

Name Required Type Description
status Yes Status Message A Status Message telling users what has changed.

Change Types

The following types can be accessed via the getType() method of each class.

Type Description
StandardORSet Any value that is added via an add operation will be added to the Set of values if not already present; remove operations will similarly be allowed from the Set
FirstWriterWinsRegister Whatever Response Message reaches the server first gets its value accepted; all others are rejected
LastWriterWinsRegister Whatever Response Message reaches the server last gets its value accepted; all others are overwritten. One can not remove values via the remove operation
LastWriterWinsNullableRegister Same as LastWriterWinsRegister, but one can use remove operations to unset the value

Sending a Response Message payload that adds two values to a Set named colors would look like:

{
  "parts": [
    {
      "id": "layer:///messages/GENERATE_A_UUID/parts/UUID1",
      "mime_type": "application/vnd.layer.response-v2+json;role=root",
      "body": JSON.stringify({
        "response_to": "layer:///messages/c2e3449e-b3e7-4a98-a53f-e8fb6d557eb0",
        "response_to_node_id": "1ff726e9-c864-40ce-8409-5bdd52966821",
        "changes":[
          {
            "operation": "add",
            "type": "Set",
            "value": "red",
            "name": "colors",
            "id": "8yFb5j"
          },
          {
            "operation": "add",
            "type": "Set",
            "value": "blue",
            "name": "colors",
            "id": "Zjf8Ac"
          }
        )
      })
    },
    {
      "id": "layer:///messages/GENERATE_A_UUID/parts/GENERATE_A_UUID",
      "mime_type": "application/vnd.layer.status+json;role=status;parent-node-id=UUID1",
      "body": "{\"text\": \"Frodo has added red and blue\"}"
    }
  ]
}

The above operation will update the colors state for that message to ["red", "blue"] so that all participants can see that rendered.

It will also associate the id with each value:

  • {"id": "8yFb5j", "value": "red"}
  • {"id": "Zjf8Ac", "value": "blue"}

To remove the color “red”, perform a remove operation on id=8yFb5j:

{
  "sender_id": "layer:///identities/frodo-the-dodo",
  "parts": [
    {
      "id": "layer:///messages/GENERATE_A_UUID/parts/" + id1,
      "mime_type": "application/vnd.layer.response-v2+json;role=root",
      "body": JSON.stringify({
        "response_to": "layer:///messages/c2e3449e-b3e7-4a98-a53f-e8fb6d557eb0",
        "response_to_node_id": "1ff726e9-c864-40ce-8409-5bdd52966821",
        "changes": [
          {
            "operation": "remove",
            "type": "Set",
            "value": "red",
            "name": "colors",
            "id": "8yFb5j"
          }
        ]
      })
    },
    {
      "id": "layer:///messages/GENERATE_A_UUID/parts/GENERATE_A_UUID",
      "mime_type": "application/vnd.layer.status+json;role=status;parent-node-id=" + id1,
      "body": JSON.stringify({
        "text": "Frodo has removed red"
      })
    }
  ]
}

For this operation, the value is informational; used by other webhook services to understand what value was removed. But the id alone determines what value is actually being removed. How the id works will be discussed in more detail in later sections.

State Management APIs Response Summaries