Response Messages

A Response Message consists of:

Field Required Type Description
mime_type Yes String application/vnd.layer.response-v2+json
response_to Yes String The Message ID of the Message that this response is targeting
response_to_node_id 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 Object[] Array 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
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
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

Type Description
Set 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
FWW First Writer Wins: Whatever Response Message reaches the server first gets its value accepted; all others are rejected
LWW Last Writer Wins: Whatever Response Message reaches the server last gets its value accepted; all others are overwritten. One can not remove values via the remove operation
LWWN Last Writer Wins Nullable: Same as LWW, but one can use remove operations to unset the value

SAPI payload for Adding two values to a Set named colors

{
  "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": "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=" + id1,
      "body": JSON.stringify({
        "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.