External page

For some actions it is better to direct the user to an external web page instead of trying to perform them in a dialog or in the sidebar. You can direct your users to an external page by adding an external page element to the addon descriptor and using that page as a target for an action.to

The external page url will include a JWT token that can be used to verify the identity of the user. You can also use template variables in the URL that will be replaced before the user is sent to the page.

Descriptor format

You can declare an external page by adding an 'externalPage' element in the capabilities section of  your addon descriptor. For example:

1
2
{
  "name": "My Integration",
  "description": "An integration that does wonderful things",
  "key": "com.example.myintegration",
  "links": {
    "homepage": "https://example.com/myintegration",
    "self": "https://example.com/myintegration/capabilities"
  },
  "capabilities": {
    "externalPage": [
      {
        "key": "my-page",
        "url": "https://example.com",
        "name": {
          "value": "Example"
        }
      }
    ]
  }
}

URL template

You can add placeholder variables in the "url" attribute of the external page. These variables will be replaced before the user is sent to the page. For example:

https://example.org/page?mid={message.mid}

The variables that can be replaced in the url depend on which action opens the external page.

The following variables are available when your page is opened by a message action:

1
2
metadata.config.isEnabled

1
2
metadata: {
config: {
isEnabled: true
}
}