Action Menu API (Draft)

This API represents a method for handling user-facing interactions with agents, allowing for discoverable services and workflows as well as simple data entry. While less flexible than HTML forms or a chat bot, it should be relatively easy to implement and provides a user interface which can be adapted for various platforms, including mobile agents. This initial design is directed toward the IIWBook demo.

Representing a menu

A client application is expected to display only one active menu per connection when action menus are employed by the target agent. This menu may be dismissed or re-requested by the client. A newly received menu is not expected to interrupt a user at the soonest opportunity, but rather be made available for the user to inspect possible actions related to the agent.

As soon as a connection is formed between IIWBook and an agent, a menu message is sent. For example:

{
  "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/action-menu/1.0/menu",
  "@id": "5678876542344",
  "title": "Welcome to IIWBook",
  "description": "IIWBook facilitates connections between attendees by verifying attendance and distributing connection invitations.",
  "errormsg": "No IIWBook names were found.",
  "options": [
    {
      "name": "obtain-email-cred",
      "title": "Obtain a verified email credential",
      "description": "Connect with the BC email verification service to obtain a verified email credential"
    },
    {
      "name": "verify-email-cred",
      "title": "Verify your participation",
      "description": "Present a verified email credential to identify yourself"
    },
    {
      "name": "search-introductions",
      "title": "Search introductions",
      "description": "Your email address must be verified to perform a search",
      "disabled": true
    }
  ]
}

The menu message may have a title string to be shown at the top of the menu, and/or a description to be shown in smaller text below the title bar. Both are plain text. The optional plaintext errormsg is to be presented to the user in the title section and in a style indicating the last request did not work as expected.

A menu must define one or more options. The list of options should be able to scroll in case there are too many for the display.

An option may be marked disabled when certain requirements have not yet been met. An option may have an optional form that enables collecting additional text from the user. See details in the Quick Form section below.

Requesting a menu

In addition to menus being pushed by the agent, the root menu can be re-requested at any time by sending a menu-request.

{
  "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/action-menu/1.0/menu-request",
  "@id": "5678876542345"
}

Selecting a menu option

When the user selects a menu option, a perform message is generated. It should be attached to the same thread as the menu. The active menu should close when an option is selected.

{
  "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/action-menu/1.0/perform",
  "@id": "5678876542346",
  "~thread": {
    "thid": "5678876542344"
  },
  "name": "obtain-email-cred",
  "params": {}
}

The optional params dictionary contains any input parameters (specified below) as key-value pairs.

The response to a perform message can be any type of agent message, including another menu message, a presentation request, an introduction proposal, a credential offer, an acknowledgement, or a problem report. Whatever the message type, it should normally reference the same message thread as the perform message.

Quick forms

Menu options may define a form property, which would direct the user to a client-generated form when the menu option is selected. The menu title should be shown at the top of the form, followed by the form description text if defined, followed by the list of form params in sequence. The form should also include a Cancel button to return to the menu, a Submit button (with an optional custom label defined by submit-label), and optionally a Clear button to reset the parameters to their default values.

{
  "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/action-menu/1.0/menu",
  "@id": "5678876542347",
  "~thread": {
    "thid": "5678876542344"
  },
  "title": "Attendance Verified",
  "description": "",
  "options": [
    {
      "name": "submit-invitation",
      "title": "Submit an invitation",
      "description": "Send an invitation for IIWBook to share with another participant"
    },
    {
      "name": "search-introductions",
      "title": "Search introductions",
      "form": {
        "description": "Enter a participant name below to perform a search.",
        "params": [
          {
            "name": "query",
            "title": "Participant name",
            "default": "",
            "description": "",
            "required": true,
            "type": "text"
          }
        ],
        "submit-label": "Search"
      }
    }
  ]
}

When the form is submitted, a perform message is generated containing values entered in the form. The form block may have an empty or missing params property in which case it acts as a simple confirmation dialog.

Each entry in the params list must define a name and title. The description is optional (should be displayed as help text below the field) and the type defaults to 'text' if not provided (only the 'text' type is supported at this time). Parameters should default to required if not specified. Parameters may also define a default value (used when rendering or clearing the form). For demo purposes, support for only one input parameter is needed.

Sample menu presentation:

When there is no active menu, a Show Menu button should be made available in the client to re-fetch and display the menu. This would generate a new menu-request message.

Sample quick form presentation:

Potential extensions

• Menu 'back' links (to move from the current menu to a previous menu) can be implemented as normal menu options, but it might be desirable to move this functionality up to the top level to allow for alternative interfaces.
• The menu header or options could incorporate icon images.
• Should menus have an expiry time? This way the user could be automatically directed to the top-level menu some time after failing to act on another menu (as a workaround the target agent could just send a new menu after the desired expiry time).