> ## Documentation Index
> Fetch the complete documentation index at: https://open.manus.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Addon Interaction Cards

> Render Addon form and info cards from task.listMessages, and answer form cards with task.confirmAction

<sup>Questions or issues? Contact us at [api-support@manus.ai](mailto:api-support@manus.ai).</sup>

Addons can show cards in the conversation. Some cards need an answer before the agent continues, for example the Webdev project blueprint (features and design direction). Other cards only show information, for example a saved project version with its screenshot. In the Manus app these are interactive cards. Over the API, Manus returns each card as JSON, and your client renders it. Form cards use the [MCP elicitation](https://modelcontextprotocol.io/specification/draft/client/elicitation) form format.

There are two kinds of card. An `elicitation` card is a form that the user answers. An `info` card only shows information and has no answer.

When a form card makes the agent wait, `status_detail.waiting_for_event_type` is `addonInteraction`. [Confirmation Events](https://open.manus.ai/docs/v2/task-lifecycle/confirmation-events.md#addonInteraction) shows its waiting status and the inputs it accepts. For polling and the general confirmation flow, see [Task Lifecycle](https://open.manus.ai/docs/v2/task-lifecycle).

## Opt in when you create the task

Declare what your client can render in `task.create`:

```json theme={null}
{
  "message": { "content": "Build a portfolio website for a photographer named Lin." },
  "interactive_mode": true,
  "client_capabilities": { "elicitation": { "form": {} }, "info": {} }
}
```

* `{ "elicitation": {} }` also means form support, as in MCP.
* This release supports only `form`. URL mode is not available yet.
* `info: {}` means your client can show display-only cards (`kind: "info"`). Without it, you get no `info` cards.
* Without `client_capabilities`, nothing changes: you get no `addon_interaction` messages. The task can show `waiting` without `confirm_input_schema`, and the Addon continues with its defaults when its own deadline passes (the Webdev blueprint waits about 60 seconds). To steer it, use `task.sendMessage`.
* With `interactive_mode: false`, Addons do not wait for an answer. They continue with their defaults.

## Read the card

The card arrives in `task.listMessages` as an `addon_interaction` message:

```json theme={null}
{
  "id": "Qm3x9VdTq2rL8sN1aB4cZe",
  "type": "addon_interaction",
  "timestamp": "1761740000000",
  "addon_interaction": {
    "event_id": "1XEyM3C6QV9rE4Y7eMOb2A",
    "card_id": "wdo_508aeebc0dc10f2cbb8f860e",
    "kind": "elicitation",
    "card_type": "webdev.blueprint",
    "addon": { "id": "manus-webdev", "display_name": "Webdev" },
    "title": "Project blueprint: Lin — Photography Portfolio",
    "elicitation": {
      "mode": "form",
      "message": "A clean, image-first portfolio for the photographer Lin. Confirm the plan before Manus builds it.",
      "requestedSchema": {
        "type": "object",
        "properties": {
          "style": {
            "type": "string",
            "title": "Design direction",
            "oneOf": [
              { "const": "style_0", "title": "Inspire Me: let Manus choose" },
              { "const": "style_1", "title": "Silver Silence: generous white space, black-and-white layers" }
            ],
            "default": "style_0"
          },
          "features": {
            "type": "array",
            "title": "Features",
            "items": { "anyOf": [
              { "const": "feature_0", "title": "Full-screen hero with Lin's name" },
              { "const": "feature_1", "title": "Gallery by series" }
            ] },
            "minItems": 1,
            "default": ["feature_0", "feature_1"]
          }
        },
        "required": ["style", "features"]
      }
    },
    "expires_at": "1761741800000",
    "expiry_action": "accept_default"
  }
}
```

| Field | Meaning |
| - | - |
| `event_id` | Pass it as `task.confirmAction.event_id`. |
| `card_id` | The card's ID inside the Addon. The Addon can send the same card again as a new message with a new `event_id`, for example after a restart. Keep only the latest message per `card_id`. |
| `kind` | `elicitation` (a form that the user answers) or `info` (display only, see [Info cards](#info-cards)). |
| `card_type` | Optional. The Addon's own name for the card, for example `webdev.blueprint`. Use it if you want to render a card in a special way. If you do not know the value, render the card by `kind`. |
| `elicitation` | MCP `ElicitRequest` params: `mode`, `message`, `requestedSchema`. Field names stay camelCase as in MCP. |
| `display` | Optional images: `media[]` (`id`, `type: "image"`, `url`, `alt`, and optional `width` and `height` in pixels) and `option_media`, which maps a property and option value to a media `id`. |
| `expires_at`, `expiry_action` | Optional. `expires_at` is Unix milliseconds for a countdown, sent as a decimal string like `timestamp` (protobuf JSON encodes 64-bit integers as strings). `expiry_action` is what the Addon does at the deadline: `accept_default` or `cancel`. The Addon runs the deadline. After it, `task.confirmAction` returns `400 failed_precondition`. |
| `sensitive` | Optional, `elicitation` cards only. `true` means the answer contains a secret. See [Sensitive cards](#sensitive-cards). |

`requestedSchema` is always a flat object with at most 32 properties. Each property is one of:

* `string`, optionally with `minLength`, `maxLength`, and `format` (`email`, `uri`, `date`, or `date-time`).
* `number` or `integer`, optionally with `minimum` and `maximum`.
* `boolean`.
* A single choice: `oneOf` with `const` and `title`, or `enum`.
* A multiple choice: `array` with `items.anyOf` or `items.enum`, optionally with `minItems` and `maxItems`.

Every property can have `title`, `description`, and `default`, and the object can have `required`. No other keywords appear. A choice has at most 64 options. Its `default` is one of the options; for a multiple choice it is a subset of the options without duplicates. Check the answer against these rules before you submit it. Manus checks the same rules and returns `400 invalid_argument` when the answer breaks one.

Option values (`const`) are non-empty strings that the Addon chooses, for example `style_0`. Do not depend on their format: show `title` to the user and send back `const`.

The order of keys in `properties` is not guaranteed, so do not depend on it. Arrays keep their order: the options in `oneOf`, `anyOf`, and `enum`, the `required` list, and `display.media`. To lay out the form, see [Render the card](#render-the-card).

When the card makes the agent wait, the waiting `status_update` points at it: `waiting_for_event_type` is `addonInteraction`, `waiting_for_event_id` is the card's `event_id`, and `confirm_input_schema` describes the answer. Some cards do not make the agent wait; you can still answer them until the card is closed (see [Answer the card](#answer-the-card)).

## Render the card

Render a card from its fields. The same rules work for every Addon and every `card_type`, so your client can show cards that did not exist when you built it. The layout, colors, and fonts are your choice.

Show each card in the conversation at its position in `task.listMessages`. When a newer message has the same `card_id`, replace the older card with it.

| Field | How to render it |
| - | - |
| `title` | The card heading. |
| `addon.display_name` | The source of the card, for example "Webdev". |
| `display.media[]` | Images, in array order, above the message. Load `url` directly, and do not send your Manus API key with it. Reserve space with `width` and `height` when they are present. Use `alt` as the text alternative. If an image does not load, leave it out; the card is still complete. |
| `elicitation.message`, `info.message` | The card body. Treat it as plain text: keep line breaks, and do not interpret Markdown or HTML. |
| `info.links[]` | Buttons labeled with `label`. Open `url` in a browser. |
| `info.data` | Do not show it in the generic layout. It is structured data for a `card_type` that you render in a special way. |
| `expires_at`, `expiry_action` | A countdown to `expires_at`. Tell the user what happens at the deadline: with `accept_default`, the Addon continues with the `default` values; with `cancel`, the Addon closes the card without an answer. |

For an `elicitation` card, render one control for each property in `requestedSchema.properties`:

| Property | Control |
| - | - |
| `string` | A single-line text input. Use the input type that matches `format`, and limit the length to `minLength` and `maxLength`. On a `sensitive` card, use a password input. |
| `number`, `integer` | A number input, limited to `minimum` and `maximum`. |
| `boolean` | A switch or a checkbox. |
| Single choice (`oneOf` or `enum`) | Radio buttons or a dropdown. Show the `title` of each `oneOf` option and submit its `const`. An `enum` value is its own label. |
| Multiple choice (`array`) | Checkboxes, limited to `minItems` and `maxItems`. |

* Lay out the controls in a stable order, because the order of keys in `properties` is not guaranteed. We suggest the properties in `required` first, in array order, and then the others by name.
* Use the property's `title` as the control label, and `description` as help text. If there is no `title`, use the property name.
* Preselect `default`. Mark the properties in `required` as required.
* `display.option_media[<property>][<option value>]` is the `id` of an image in `display.media`. Show that image with the option.
* Add a submit button that sends `accept` with the form values, and a decline button that sends `decline`. If your UI lets the user dismiss the card, send `cancel` when they do. Each `card_type` defines what `decline` and `cancel` mean; for example, both mean "Skip all" for `webdev.blueprint`. See [Answer the card](#answer-the-card).

Manus checks each card before it sends it to you. Use these limits to plan your layout. Lengths count UTF-16 code units, as JavaScript `String.length` does.

| Field | Limit |
| - | - |
| `title` | 1 to 120 characters |
| `elicitation.message`, `info.message` | 1 to 4,000 characters |
| `requestedSchema.properties` | At most 32 properties |
| Choice options | 1 to 64 options per property. Each `oneOf` option `title` has 1 to 200 characters. |
| `display.media` | At most 16 images. `alt` has 1 to 200 characters. `url` is an `https` URL of at most 2,048 characters. |
| `info.links` | At most 8 links. `label` has 1 to 80 characters. `url` is an `https` URL of at most 2,048 characters. |
| `info.data` | At most 8 KiB of JSON |
| Your answer: `content` in `task.confirmAction` | At most 32 KiB of JSON. A larger answer returns `400 invalid_argument`. |

Manus removes leading and trailing spaces from `title`, the messages, `alt`, and link labels, and never sends them empty.

## Info cards

An `info` card shows information and has no answer. This Webdev card reports a saved project version with its screenshot:

```json theme={null}
{
  "id": "VKnNEgKIDF1XnvGWrddxUc",
  "type": "addon_interaction",
  "timestamp": "1793693596619",
  "addon_interaction": {
    "event_id": "VKnNEgKIDF1XnvGWrddxUc",
    "card_id": "checkpoint:e09f309be331363606876f03359f3abe0f36a01c",
    "kind": "info",
    "card_type": "webdev.checkpoint",
    "addon": { "id": "manus-webdev", "display_name": "Webdev" },
    "title": "Checkpoint saved: Build minimal Checkpoint Bakery page",
    "display": {
      "media": [
        {
          "id": "screenshot",
          "type": "image",
          "url": "https://<webdev-host>/api/v1/assets/wds_62f3d15089d4b0648511575e/content?token=<signed>&exp=1794355200000",
          "alt": "Screenshot of Build minimal Checkpoint Bakery page"
        }
      ]
    },
    "info": {
      "message": "Manus saved a new version of this website: Build minimal Checkpoint Bakery page",
      "data": {
        "resource_uri": "manus-resource://manus-webdev/project/wdp_132780524ee29992e4b14abd?v=e09f309be331363606876f03359f3abe0f36a01c",
        "version_id": "e09f309be331363606876f03359f3abe0f36a01c",
        "platform": "web",
        "checkpoint_id": "checkpoint-56642",
        "created_at": "2026-11-03T08:13:12.324Z"
      }
    }
  }
}
```

* Render it as described in [Render the card](#render-the-card).
* `info.links` is optional. Each link has `id`, `label`, and an `https` `url`. Open it in a browser.
* `info.data` is optional structured data. Each Addon documents its fields per `card_type`; see [Webdev Cards](https://open.manus.ai/docs/v2/task-lifecycle/addon-interaction-cards/webdev-cards.md). If you do not use them, ignore them.
* An `info` card never makes the agent wait, and it has no `expires_at`. It can arrive at any time while the agent runs, for example right after the agent saves a project version.
* Do not call `task.confirmAction` for an `info` card. Manus rejects it with `400 failed_precondition`.

## Sensitive cards

When `sensitive` is `true`, the answer contains a secret, for example an API key:

* Render the `string` properties as password inputs. Do not log the answer, and do not show it again after the user submits it.
* The card has no `default` values.
* Manus does not store the answer: not in the task history, not in `task.listMessages`, and not in any cache. Manus passes it to the Addon inside the `task.confirmAction` request. If that request fails, the user must enter the secret again, or your client resends it from memory.

## Webdev cards

The Webdev Addon sends these `card_type` values: `webdev.blueprint`, `webdev.secret`, `webdev.hosting_confirmation`, `webdev.publish_confirmation`, `webdev.visibility_confirmation`, `webdev.checkpoint`, and `webdev.unsupported_step`. [Webdev Cards](https://open.manus.ai/docs/v2/task-lifecycle/addon-interaction-cards/webdev-cards.md) describes each one: when it appears, its fields and `info.data`, how to answer it, and how the Manus web app shows the same step.

## Answer the card

Call `task.confirmAction` with an MCP `ElicitResult`:

```bash theme={null}
curl -X POST 'https://api.manus.ai/v2/task.confirmAction' \
  -H 'x-manus-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "task_id": "YOUR_TASK_ID",
    "event_id": "1XEyM3C6QV9rE4Y7eMOb2A",
    "input": {
      "action": "accept",
      "content": { "style": "style_0", "features": ["feature_0", "feature_1"] }
    }
  }'
```

* `accept` requires `content` that matches `requestedSchema`.
* `decline` (the user said no) and `cancel` (the user dismissed the card) take no `content`.

Manus checks the answer against `requestedSchema` and passes it to the Addon inside this request. The request returns after the Addon replies, within about 20 seconds. `confirmed: true` means the Addon accepted the answer. The agent then continues on its own; Manus does not send a status update for the card.

Disable the submit button while the request runs. Treat the card as closed when any of these happens:

* `task.confirmAction` returns `confirmed: true`.
* `task.confirmAction` returns `400 failed_precondition`.
* The card made the agent wait, and the task no longer waits for it: `status` is not `waiting`, or `waiting_for_event_id` points to another event. This happens, for example, when the Addon's deadline passes.
* The user sends a new message, or you stop the task.

`task.confirmAction` errors for these cards:

| Error | Meaning | What to do |
| - | - | - |
| `400 invalid_argument` | `input` does not match the card, `event_id` is not the card's `addon_interaction.event_id`, or the Addon rejected the answer. The message `id` can differ from `event_id`; always pass `addon_interaction.event_id`. | If `event_id` is correct, let the user change the answer. |
| `400 failed_precondition` | The card is closed: the Addon already settled it (deadline, another answer, or the Manus web app), or the user stopped the task. The error message is the same in all these cases, so do not parse it. | Close the card. |
| `404 not_found` | The task or the event does not exist. | Check `task_id` and `event_id`. |
| `503 unavailable` | Manus could not reach the Addon, or the Addon did not reply in time. The answer may or may not have arrived. | Retry with the same input. Sending the same answer again is safe: the Addon accepts it once. |
| `500 internal` | An unexpected error. | Retry with the same input once. If it fails again, close the card and let the user reply in the conversation. |

## Handle what you do not recognize

New card kinds and modes will be added. Your client must not fail on them. If `kind` or `elicitation.mode` has a value you do not handle:

* Show `title` and, if present, `elicitation.message` or `info.message` as plain text.
* Do not render controls, and do not call `task.confirmAction` for that card.
* Let the user reply in the conversation, and send the reply with [task.sendMessage](https://open.manus.ai/docs/v2/task.sendMessage.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.