Share via

root.composeExtensions object

  • Article

Defines a message extension for the app. Currently only one compose extension per app is supported.

Properties that reference this object type:

Syntax

{
  "id": "{string}",
  "botId": "{string}",
  "composeExtensionType": "botBased | apiBased",
  "authorization": {
    "authType": "none | apiSecretServiceAuth | microsoftEntra",
    "microsoftEntraConfiguration": {
      microsoftEntraConfiguration object
    },
    "apiSecretServiceAuthConfiguration": {
      apiSecretServiceAuthConfiguration object
    }
  },
  "apiSpecificationFile": "{string}",
  "canUpdateConfiguration": boolean | null,
  "commands": [
    {
      "id": "{string}",
      "type": "query | action",
      "samplePrompts": [
        {
          samplePrompts object
        }
      ],
      "apiResponseRenderingTemplateFile": "{string}",
      "context": [
        "compose | commandBox | message"
      ],
      "title": "{string}",
      "description": "{string}",
      "initialRun": {boolean},
      "fetchTask": {boolean},
      "parameters": [
        {
          parameters object
        }
      ],
      "taskInfo": {
        taskInfo object
      },
      "semanticDescription": "{string}"
    }
  ],
  "messageHandlers": [
    {
      "type": "link",
      "value": {
        value object
      }
    }
  ],
  "requirementSet": {
    "hostMustSupportFunctionalities": [
      {
        hostFunctionality object
      }
    ]
  }
}

{
  "botId": "{string}",
  "composeExtensionType": "botBased | apiBased",
  "authorization": {
    "authType": "none | apiSecretServiceAuth | microsoftEntra",
    "microsoftEntraConfiguration": {
      microsoftEntraConfiguration object
    },
    "apiSecretServiceAuthConfiguration": {
      apiSecretServiceAuthConfiguration object
    }
  },
  "apiSpecificationFile": "{string}",
  "canUpdateConfiguration": boolean | null,
  "commands": [
    {
      "id": "{string}",
      "type": "query | action",
      "samplePrompts": [
        {
          samplePrompts object
        }
      ],
      "apiResponseRenderingTemplateFile": "{string}",
      "context": [
        "compose | commandBox | message"
      ],
      "title": "{string}",
      "description": "{string}",
      "initialRun": {boolean},
      "fetchTask": {boolean},
      "semanticDescription": "{string}",
      "parameters": [
        {
          parameters object
        }
      ],
      "taskInfo": {
        taskInfo object
      }
    }
  ],
  "messageHandlers": [
    {
      "type": "link",
      "value": {
        value object
      }
    }
  ]
}

Properties

id

A unique identifier for the message extension. Used when defining one-way and mutual app capability dependencies under elementRelationshipSet.

Type
string

Required
—

Constraints
Maximum string length: 64.

Supported values

botId

The unique Microsoft app ID for the bot that powers the message extension, as registered with the Bot Framework. The ID can be the same as the overall app ID.

Type
string

Required
—

Constraints

Supported values
The string value must be a guid.

composeExtensionType

Type of the message extension. Either botBased and apiBased message extension.

Type
string

Required
—

Constraints

Supported values
Allowed values: botBased, apiBased.

authorization

Object capturing authorization information for the API-based message extension.

Type
authorization

Required
—

Constraints

Supported values

apiSpecificationFile

A relative file path to the api specification file in the manifest package.

Type
string

Required
—

Constraints
Maximum string length: 2048.

Supported values

canUpdateConfiguration

A boolean value indicating whether the configuration of a message extension can be updated by the user.

Type
boolean | null

Required
—

Constraints

Supported values

commands

Array of commands the message extension supports.

Type
Array of commands

Required
—

Constraints
Maximum array items: 10.

Supported values

messageHandlers

A list of handlers that allow apps to be invoked when certain conditions are met. Domains must also be listed in validDomains.

Type
Array of messageHandlers

Required
—

Constraints
Maximum array items: 5.

Supported values

requirementSet

Runtime requirements for the message extension to function properly in the Microsoft 365 host application. If one or more of the requirements aren't supported by the runtime host, the host won't load the message extension.

Type
elementRequirementSet

Required
—

Constraints

Supported values

Remarks

Optional – Array

Note

The name of the feature was changed from "compose extension" to "message extension" in November, 2017, but the app manifest name remains the same so that existing extensions continue to function.

The object is an array (maximum of 1 element) with all elements of type object. This block is required only for solutions that provide a message extension.

Examples

{
"composeExtensions": [
        {
            "botId": "%MICROSOFT-APP-ID-REGISTERED-WITH-BOT-FRAMEWORK%",
            "id": "composeExtension-id",
            "canUpdateConfiguration": true,
            "commands": [
                {
                    "id": "exampleCmd1",
                    "title": "Example Command",
                    "description": "Command Description; e.g., Search on the web",
                    "initialRun": true,
                    "type": "search",
                    "context": [
                        "compose",
                        "commandBox"
                    ],
                    "parameters": [
                        {
                            "name": "keyword",
                            "title": "Search keywords",
                            "description": "Enter the keywords to search for"
                        }
                    ]
                }
            ],
            "requirementSet": {
                "hostMustSupportFunctionalities": [
                  {"name": "dialogUrl"},
                  {"name": "dialogUrlBot"}
                ]
            }
        }
    ]
}