Creating Messages with Initial State

Note

All APIs in this document are under review and may be removed.

Why would one want to create a Message with Initial State? Consider a Choice Message. These are used to provide Options for a Product, allowing one to specify color, size, and/or any other types of options your product requires.

It should be possible to create such a Product with some or all of these options preselected. We know that the customer wants Product with Option A and Option B; the user may be provided the ability to change those selections, but we do not need the user to select what we already know.

Initial state is set by adding a temporary Message Part that will be removed from the server once its been processed. Lets suppose we are sending a Choice Message:

{
  "sender_id": "layer:///identities/frodo-the-dodo",
  "parts": [
    {
      "id": "layer:///messages/GENERATE_A_UUID/parts/" + id1,
      "mime_type": "application/vnd.layer.choice+json;role=root",
      "body": JSON.stringify({
        "label": "Are you smart?",
        "enabled_for": "layer:///identities/sauruman-the-wise-ass",
        "allow_reselect": true,
        "response_name": "smarts",
        "choices": [{
            "id": "yes",
            "text": "Somewhat"
        }, {
            "id": "no",
            "text": "I'm the smartest!"
        }, {
            "id": "genius",
            "text": "I refuse to answer that!"
        }]
      })
    }
  ]
}

And of course we want to preselect {"id": "yes", "text": "Somewhat"} for the user so that they don’t have to answer unless they want to change that selection. We add the following Message Part to the SAPI request:

{
  "mime_type": "application/vnd.layer.initialresponsestate-v1+json;role=initial_response_state;parent-node-id=" + id1,
  "body": JSON.stringify([
    {
      "operation":"add",
      "type":"FWW",
      "value":"yes",
      "name":"smarts",
      "id":"5J=FKn",
      "identity_id":"layer:///identities/sauruman-the-wise-ass"
    }
  ])
}

To understand this:

  1. The state name is set to smarts by the response_name property in the Choice Message Part; initial state is setting the smarts state
  2. A Response Message operation is added to the Message by adding the initial_response_state Message Part to the Choice Message
  3. The one thing different about this from the Response Message format is that it allows for an identity_id to flag whose state is being set
  4. The Response Message Integration Service on detecting this initial_response_state will add the specified state to the Message, delete the initial_response_state Message Part, and create a response_summary part that contains the new state
  5. Clients will receive this response_summary and be able to render the initial state

Note that apps wanting to preserve the history of state changes to a message will lose any data put into the initial_response_state; and it is therefore recommended that this data also be written to the Message Part being operated upon; this is kept for historical reasons but is not typically processed in any way:

{
  "sender_id": "layer:///identities/frodo-the-dodo",
  "parts": [
    {
      "id": "layer:///messages/GENERATE_A_UUID/parts/" + id1,
      "mime_type": "application/vnd.layer.choice+json;role=root",
      "body": JSON.stringify({
        "label": "Are you smart?",
        "enabled_for": "layer:///identities/sauruman-the-wise-ass",
        "allow_reselect": true,
        "response_name": "smarts",
        "initial_response_state": [
          {
            "operation":"add",
            "type":"FWW",
            "value":"yes",
            "name":"smarts",
            "id":"5J=FKn",
            "identity_id":"layer:///identities/sauruman-the-wise-ass"
          }
        ],
        "choices": [{
            "id": "yes",
            "text": "Somewhat"
        }, {
            "id": "no",
            "text": "I'm the smartest!"
        }, {
            "id": "genius",
            "text": "I refuse to answer that!"
        }]
      })
    },
    {
      "mime_type": "application/vnd.layer.initialresponsestate-v1+json;role=initial_response_state;parent-node-id=" + id1,
      "body": JSON.stringify([
        {
          "operation":"add",
          "type":"FWW",
          "value":"yes",
          "name":"smarts",
          "id":"5J=FKn",
          "identity_id":"layer:///identities/sauruman-the-wise-ass"
        }
      ])
    }
  ]
}