Choice Messages

The Choice Message presents the user with a set of choices to make, and when the user has made their selection, it updates the message’s state for all participants in the Conversation.


This Message, unlike others, depends upon a Message Response Integration Service which you will need to install.

Choice with No Selection
Choice with Selection and allowReselect: false
Name Required Type Description
mime_type Yes String application/vnd.layer.choice+json
label N String A question to ask the user
choices Y Object[] Array of choices for the user to pick from
choices.text Y String Text to show the user within a selection button Y String ID that identifies the selection and distinguishes it from the other choices
allow_reselect N Boolean Default is false; if false then selections may not be changed once made
allow_deselect N Boolean Default is false; if false then selections may not be selected again to deselect them. If true then allowReselect will be set to true
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 set to true.
response_name N String Name that will uniquely identify this response within the Message and differentiate it from other types of responses
enabled_for Y String Identity ID of the user allowed to select these buttons
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
title N String The default title of Choose One can be replaced by providing your own title
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

SAPI payload for creating a Choice Message:

	"sender_id": "layer:///identities/frodo-the-dodo",
	"parts": [
			"id": "layer:///messages/GENERATE_A_UUID/parts/GENERATE_A_UUID",
			"mime_type": "application/vnd.layer.choice+json;role=root",
			"body": JSON.stringify({
        "label": "What is the airspeed velocity of an unladen swallow?",
        "enabled_for": "layer:///identities/sauruman-the-wise-ass",
        "choices": [{
            "id": "zero",
            "text": "Zero, it can not get off the ground!"
        }, {
            "id": "question",
            "text": "Are we using Imperial or Metric units?"
        }, {
            "id": "smartass",
            "text": "What do you mean? African or European swallow?"

The above Choice Message will ask the user the specified question, and provide the specified choices for the user to choose from. When the recipient selects an answer, the following actions will be performed:

  1. A Response Message is sent indicating what the user selected, and providing a textual description of that selection
  2. A Response Message is rendered for all participants, representing that Response Message, and informing all users of the change in the state of the Message. It might say something like “User X has selected Are we using Imperial or Metric units?”.
  3. The Message’s local state is promptly updated for the user who made the selection, providing quick feedback to the user that the selection was accepted.
  4. The Message Response Integration Service receives the Response Message, and updates the original Choice Message with the user’s Selection
  5. All participants receive the update to the Choice Message, and now all users see the selection.

The choices array is designed to have an id so that edits to the text values may eventually be supported, while leaving the id values unchanged. This would leave the user’s selections intact, while allowing for tweaks to the text.

A Choice Message may be sent with an initial selection; for more on sending Messages that contain initial state, see Response Messages.