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:

{
  "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:

Name

Value

Notes
message.body The message body  
message.sender.name The user name of the message sender  
message.sender.id The user id of the message sender Not available for notifications sent by add-ons
message.sender.mention The mention name of the message sender Not available for notifications sent by add-ons
message.mid The XMPP message id of the message  
message.metadata.{x} The value of a card metadata property

Only available for card notifications. Nested properties can be addressed by using the "." delimiter. E.g. use

metadata.config.isEnabled

for metadata of this shape:

metadata: {
  config: {
    isEnabled: true
  }
}
Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport