Last updatedDec 8, 2017

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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "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:

1
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.bodyThe message body 
message.sender.nameThe user name of the message sender 
message.sender.idThe user id of the message senderNot available for notifications sent by add-ons
message.sender.mentionThe mention name of the message senderNot available for notifications sent by add-ons
message.midThe 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

1
metadata.config.isEnabled

for metadata of this shape:

1
2
3
4
5
metadata: {
  config: {
    isEnabled: true
  }
}