Edit on GitHub

Calls

A Call defines an App action that can be invoked, or a request for App data.

Data structure

The data structure of a call (godoc) is described in the following table:

Name	Type	Description
`path`	string	The path of the call. For Apps deployed using HTTP, the path is appended to the App’s `RootURL`.
`expand`	Expand	Specifies additional metadata to include in the call request, such as channel and post information.
`state`	map	A set of elements to be interpreted by the App. Forms and slash commands will also populate these values.

An example call looks like this:

{
    "path": "/my-handler",
    "expand": {
        "app": "all",
        "user": "summary"
    },
    "state": {}
}

Request

When a call is performed, a POST request will be made to the endpoint defined in the call. The call will include a JSON Web Token (JWT) in the Mattermost-App-Authorization header. The Acting User’s ID is included in the request by default.

The data structure of a call request (godoc) is described in the following table:

Name	Type	Description
`path`	string	(See above)
`expand`	Expand	(See above)
`state`	map	(See above)
`values`	map	The pairs of key values present in the call. Can be populated by forms and slash commands.
`context`	Context	The context of the call.
`raw_command`	string	The unparsed command for slash commands.
`selected_field`	string	Specifies the field name to use for lookups and refreshes.
`query`	string	The user-supplied query string to use for lookups and refreshes.

An example call request looks like the following (some context fields omitted for brevity):

{
    "path": "/send",
    "expand": {},
    "context": {
        "app_id": "hello-world",
        "location": "/command/helloworld/send",
        "acting_user": {
            "id": "k86a9cy93f8azx7jjiy5xfq5jc"
        },
        "oauth2": {}
    },
    "raw_command": "/helloworld send"
}

Context

The request context field contains metadata about the request. The data structure of the context (godoc) field is described in the following table:

Name	Type	Description
`subject`	Subject (`string`)	Event subject.
`channel_id`	string	ID from the channel from within which the call was performed.
`team_id`	string	ID from the team from within which the call was performed.
`post_id`	string	ID from the post from within which the call was performed.
`root_post_id`	string	If the call was performed from a post in a thread, the root post ID of that thread.
`app_id`	AppID (`string`)	The app ID.
`location`	Location (`string`)	The location from which the call was performed.
`user_agent`	string	User agent used to perform the call. Valid values are: `mobile`, `webapp`.
`track_as_submit`	bool	Whether the call was caused by a submit action from a binding or form.
`mattermost_site_url`	string	Mattermost base URL.
`developer_mode`	bool	Whether the Apps framework is running in Developer mode.
`app_path`	string	App’s path on the Mattermost instance (appendable to `mattermost_site_url`).
`bot_user_id`	string	Bot user ID.
`bot_access_token`	string	(Expansion)
`app`	App	Details about the installed record of the App.
`acting_user`	User	(Expansion)
`acting_user_access_token`	string	(Expansion)
`locale`	string	(Expansion)
`channel`	Channel	(Expansion)
`channel_member`	ChannelMember	(Expansion)
`team`	Team	(Expansion)
`team_member`	TeamMember	(Expansion)
`post`	Post	(Expansion)
`root_post`	Post	(Expansion)
`user`	User	(Expansion)
`mentioned`	User (list)	(Expansion)
`oauth2`	OAuth2Context	(Expansion)

An example context field looks like this:

{
    "context": {        
        "app_id": "hello-world",
        "location": "/command/helloworld/send",
        "user_agent": "webapp",
        "track_as_submit": true,
        "mattermost_site_url": "http://localhost:8066",
        "developer_mode": true,
        "app_path": "/plugins/com.mattermost.apps/apps/hello-world",
        "bot_user_id": "3sjcm1ztkbfhpnddz389ycq1pe",
        "bot_access_token": "tt59irtaopd7fegi3taamd7dxw",
        "acting_user": {
            "id": "k86a9cy93f8azx7jjiy5xfq5jc",
            "delete_at": 0,
            "username": "",
            "auth_service": "",
            "email": "",
            "nickname": "",
            "first_name": "",
            "last_name": "",
            "position": "",
            "roles": "",
            "locale": "",
            "timezone": null,
            "disable_welcome_email": false
        },
        "oauth2": {}
    }
}

Response

The data structure of a call response is described in the following table:

Name	Type	Description
`type`	CallResponseType	The type of response being returned.
`text`	string	Used by the `ok` and `error` response types to return a markdown message that is sent to the user as an ephemeral post.
`data`	map	Used by the `ok` response type to return additional data.
`navigate_to_url`	string	Used by the `navigate` response type to redirect the user to a specified URL.
`use_external_browser`	bool	Used by the `navigate` response type to indicate the system web browser should be used when redirecting the user to an URL.
`form`	Form	Used by the `form` response type to specify a form to display.
`refresh_bindings`	bool	If `true`, forces App bindings to be refreshed immediately. Does not apply to error responses or responses for bindings calls. For optimal performance, this should be used sparingly.

An example call response looks like this:

{
    "type": "ok",
    "text": "### Success!\n\nThe operation completed successfully."
}

Call response types

There are several types of supported responses (godoc):

Value	Description
`ok`	The action completed successfully.
`error`	An error has occurred.
`form`	Should open a form.
`navigate`	Should navigate the user to an URL.