# 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).