megaphone icon Learn how to streamline incident response with Mattermost & ServiceNow on February 16th ยป
Edit on GitHub

Bindings

Bindings (godoc) establish the relationship between call handlers and locations. Whenever the bindings call is executed the App provides a list of bindings based on the request context.

Bindings are refreshed when the App is installed, on every channel switch, and when an OAuth2 process with a third party has completed. Bindings may also be refreshed when the user moves to a different context, such as opening a thread or a post in a search view.

Top level bindings 

Name Type Description
location Location (string) Top level location.
bindings Binding (list) A list of bindings under this location.

Sub-location bindings 

Sub-location bindings use the following data structure:

Name Type Description Locations
location string The name of the binding location. Values must be unique within each top level binding. all locations
icon string The App icon to display, either a fully-qualified URL or a path to an App static asset. Required for web app support. /channel_header
/post_menu
label string The primary text to display at the binding location; defaults to the value of the location field. all locations
hint string Secondary text to display at the binding location /channel_header
/command
description string Extended help text used in modal forms and command autocomplete /command
submit Call Executes an action associated with the binding all locations
form Form The modal form to display /channel_header
/command
/post_menu
bindings Binding (list) Additional sub-location bindings all locations

Call context data 

The following request context fields will be available to calls invoked at each binding location:

Location Context fields
/channel_header user_id
channel_id
team_id
/command user_id
root_post_id
channel_id
team_id
/post_menu user_id
post_id
root_post_id
channel_id
team_id

Slash command bindings 

The slash command (/command) location allows the creation of multiple, nested slash commands. Each slash command can execute a call, display a form, or accept further parameters to trigger a nested command.

The bindings field for this location is used to specify nested commands. If this field is specified, the submit and form fields can’t also be specified; an error will occur.

For example, a slash command binding that returns one day or one week worth of weather information:

{
  "bindings": [
    {
      "location": "/command",
      "bindings": [         
        {
          "location": "weather",
          "label": "Weather conditions",
          "description": "Show the weather conditions for today or the next week",
          "hint": "[day|week]",
          "bindings": [
            {
              "location": "day",
              "label": "Weather for today",
              "description": "Show the weather conditions for today",
              "call": {
                "path": "/weather/day"
              }
            },
            {
              "location": "week",
              "label": "Weather for the next week",
              "description": "Show the weather conditions for the next week",
              "call": {
                "path": "/weather/week"
              }
            }
          ]
        }
      ]
    }
  ]
}

In the Mattermost UI, typing /weather shows the details of the slash command:

image

Typing /weather week shows the details of the nested command:

image

A user could invoke the slash command using /weather day or /weather week to get weather conditions for one day or one week, respectively.

Bindings call response 

The response to the bindings call should take the form of an ok call response where the data field contains the bindings.

For example:

{
	"type": "ok",
	"data": [
		{
			"location": "/channel_header",
			"bindings": [
				{
					"location": "send-button",
					"icon": "icon.png",
					"label":"send hello message",
					"call": {
						"path": "/send-modal"
					}
				}
			]
		},
		{
			"location": "/command",
			"bindings": [
				{
					"icon": "icon.png",
					"label": "helloworld",
					"description": "Hello World app",
					"hint": "[send]",
					"bindings": [
						{
							"location": "send",
							"label": "send",
							"call": {
								"path": "/send"
							}
						}
					]
				}
			]
		}
	]
}

Example request and response 

Client requests bindings from server
GET /plugins/com.mattermost.apps/api/v1/bindings?user_id=ws4o4macctyn5ko8uhkkxmgfur&channel_id=qphz13bzbf8c7j778tdnaw3huc&scope=webapp
Server requests bindings from App

POST /plugins/com.mattermost.apps/example/hello/bindings

{
    "path": "/bindings",
    "context": {
        "app_id": "helloworld",
        "bot_user_id": "i4wzxbk1hbbufq8rnecso96oxr",
        "acting_user_id": "81bqom3kjjbo7bcjcnzs6dc8uh",
        "user_id": "81bqom3kjjbo7bcjcnzs6dc8uh",
        "team_id": "",
        "channel_id": "ytqokpzzcinszf7ywrbdfitusw",
        "mattermost_site_url": "http://localhost:8065",
        "user_agent": "webapp",
        "bot_access_token": "gcn6r3ac178zbxwiw5pc38e8zc"
    }
}
Bindings response from App
{
    "type": "ok",
    "data": [
        {
            "location": "/channel_header",
            "bindings": [
                {
                    "location": "send-button",
                    "icon": "icon.png",
                    "label": "send hello message",
                    "call": {
                        "path": "/send-modal"
                    }
                }
            ]
        },
        {
            "location": "/post_menu",
            "bindings": [
                {
                    "location": "send-button",
                    "icon": "icon.png",
                    "label": "send hello message",
                    "call": {
                        "path": "/send",
                        "expand": {
                            "post": "all"
                        }
                    }
                }
            ]
        },
        {
            "location": "/command",
            "bindings": [
                {
                    "icon": "icon.png",
                    "description": "Hello World app",
                    "hint": "[send]",
                    "bindings": [
                        {
                            "location": "send",
                            "label": "send",
                            "call": {
                                "path": "/send-modal"
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

Did you find what you were looking for?

Thank you! We appreciate your feedback.
ร—

Tell us more

Your feedback helps us improve the Mattermost developer documentation.

Have a feature request? Share it here.

Having issues? Join our Community server.