Button Messages

Most of the messages described up above are minimally interactive. Except for the Choice Message, the only action they provide is that if you click/select them, they try to open something or trigger an event. The Buttons Message allows you to take any other Message and add Actions to it.

Product Message wrapped in a Button Message. Button Message provides all buttons shown above.
Name Required Type Description
mime_type Yes String application/vnd.layer.choice+json
buttons Yes Object[] Array of objects describing the buttons to add
buttons.type Yes String Currently “action” and “choice” are the only supported values
buttons.text Yes String Label for the Button; used for type=action buttons only
buttons.event No String Event to trigger when the button is clicked
buttons.data No Object Custom parameters to provide with your buttons.event
buttons.choices No Object[] Choices that the user can chose from using the Choice Message structures
custom_data No Object Data that will not be understood by any Layer provided Renderer, but which will allow additional context to be stored in the Message so your server can better understand it when next your server sees the Message

Message Part Roles:

Name Required Type Description
content No Any Message Type A Message Type that is to be have buttons from the parent message rendered below it

SAPI payload for creating a Basic Button Message:

{
	"sender_id": "layer:///identities/frodo-the-dodo",
	"parts": [
		{
			"id": "layer:///messages/GENERATE_A_UUID/parts/" + id1,
			"mime_type": "application/vnd.layer.text+json;role=root",
			"body": JSON.stringify({
        buttons: [
          {"type": "action", "text": "Buy It", "event": "buy", "data": {"one_click_purchasing_enabled": true}},
          {"type": "action", "text": "Like It", "event": "like"},
          {"type": "action", "text": "Discover It", "event": "open-url", "data": {"url": "https://layer.com"}},
        ],
      })
		},
    {
			"id": "layer:///messages/GENERATE_A_UUID/parts/GENERATE_A_UUID",
			"mime_type": "application/vnd.layer.image+json;role=content;parent-node-id="+id1,
			"body": JSON.stringify({
        "source_url": "https://78.media.tumblr.com/1b019b4237ab18f789381941eca98784/tumblr_nlmlir7Lhk1u0k6deo1_400.gif",
        "width": 254,
        "height": 210
      })
		}
	]
}

Button Message with Choice Buttons

The Choice Buttons within the Button Message enables an app to persist a user’s selection and share it with all participants. These selections are designed for a single user only to perform the selection, and for that selection to become a permanent part of that Message. Only a single state name can be set by a given Button Set; you can not set multiple types of state in a single Button Set.

Button Message that does not wrap another message, and which provides 3 choices

The following properties are supported within each Button in the buttons array described in the prior Properties Table.

Name Required Type Description
choices.text Yes String Button text; emoji characters are accepted as well such as “\uD83D\uDC4D”
choices.tooltip No String Button tooltip
choices.id Yes String Value that will be recorded if this Choice is selected
data.response_name No String Unique name associated with this response; needed if more than one Choice or Response may be associated with this message
data.allow_reselect No Boolean Allow users to change their selection once made
data.allow_deselect No Boolean Allow user to deselect a previous selection requires allowReselect
data.allow_multiselect N Boolean Default is false; if false then only a single selection is allowed at a time. If this is true, users may select multiple choices, and allowReselect and allowDeselect are implicitly set to true.
data.enabled_for N String Identity IDs of those allowed to select these buttons (all are enabled if this is empty or omitted)
data.custom_response_data N Object Name value pairs to add to the Message Response data. Allows you to add some context to the Response Messages as well as to the data added to the Choice Model once the Message has been updated

SAPI payload for creating a Button Message with Choice Buttons:

{
	"sender_id": "layer:///identities/frodo-the-dodo",
	"parts": [
		{
			"id": "layer:///messages/GENERATE_A_UUID/parts/" + id1,
			"mime_type": "application/vnd.layer.button+json;role=root",
			"body": JSON.stringify({
        buttons: [
          {
            "type": "choice",
            "choices": [
              {"text": "Love It", "id": "love"},
              {"text": "Like It", "id": "like"},
              {"text": "Hate It", "id": "hate"}
            ],
            "data": {
              "response_name": "likelevel",
              "allow_reselect": true,
              "enabled_for": "layer:///identities/a"
            }
          },
          {
            "type": "choice",
            "choices": [
              {"text": "Favorite", "id": "true"}
            ],
            "data": {
              "response_name": "isfavorite",
              "allow_deselect": true,
              "enabled_for": "layer:///identities/a"
            }
          }
        ],
      })
		},
    {
			"id": "layer:///messages/GENERATE_A_UUID/parts/GENERATE_A_UUID",
			"mime_type": "application/vnd.layer.image+json;role=content;parent-node-id="+id1,
			"body": JSON.stringify({
        "source_url": "https://78.media.tumblr.com/1b019b4237ab18f789381941eca98784/tumblr_nlmlir7Lhk1u0k6deo1_400.gif",
        "width": 254,
        "height": 210
      })
		}
	]
}

Note

  • Failure to set a data.response_name to a unique name could cause your selection state to be overwritten by other Choice Buttons or other state manipulating Messages.
  • Default response_name is selection.
  • A Button Message may contain both Action buttons and Choice Buttons