Confirmation prompts for API plugins for Microsoft 365 Copilot

Important

API plugins are only supported as actions within declarative agents. They are not enabled in Microsoft 365 Copilot.

By default, Microsoft 365 Copilot asks the user to confirm sending data to a plugin before it sends it to prevent unintended consequences in external systems. The user is able to see the data to be sent and is given a choice to allow or decline. For some API operations, users are given the option to always allow data to be sent, which prevents future confirmation prompts for that particular operation.

Normally, Microsoft 365 Copilot shows the user the always allow option for HTTP GET operations, and doesn't show the option for POST, PATCH, PUT, and DELETE. API plugin developers can change this behavior for individual operations in their API. Developers can also customize the text that Copilot displays to the user as part of the confirmation prompt.

Overriding prompt behavior

Developers can control whether Microsoft 365 Copilot shows the always allow option for a specific operation by adding the x-openai-isConsequential property in the OpenAPI document for their API. Setting this property to true disables the always allow option, and setting it to false enables it. As a rule, any action with side effects in the external system should be marked with true to ensure the user is in control and prevent unintended consequences for actions with side effects in the external system.

For example, consider an API that creates a reminder: POST /reminders. Because it's a POST operation, Microsoft 365 Copilot asks the user to confirm every time this API is used, and doesn't give the user the option to always allow this operation.

To enable the always allow option, add the x-openai-isConsequential property set to false as shown in the following example.

post:
  x-openai-isConsequential: false
  summary: Create a new reminder
  description: Create a new budget with a specified name and due date
  operationId: CreateReminder
  requestBody:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Reminder'
    required: true

Now imagine a related API that retrieves existing reminders: GET /reminders. Since it's a GET, Microsoft 365 Copilot shows the user the always allow option.

This behavior can be changed by adding x-openai-isConsequential set to true.

get:
  x-openai-isConsequential: true
  summary: Get existing reminders
  description: Gets a list of existing reminders
  operationId: GetReminders

Customizing confirmation text

Developers can specify the confirmation text by setting the body property in the Confirmation object in the function's Function capabilities object in the plugin manifest. The value of body should be indicative of what the function does. If this property isn't present in the manifest, the description property in the Function object is used instead.

{
  "name": "GetBudgets",
  "description": "Returns details including name and available funds of budgets, optionally filtered by budget name",
  "capabilities": {
    "confirmation": {
      "type": "AdaptiveCard",
      "title": "Search budgets",
      "body": "Do you want to allow searching for budgets?"
    }
  }
}