dialog.open method

Welcome to the new home of Slack developer docs!

We're still building and not all features are available quite yet. Enjoy this peek into the future!

Not ready for the future? Return to the past at api.slack.com.

Usage info

Dialogs are outmoded and are being replaced with modals.

If you are still using dialogs, we recommend upgrading them to modals using Block Kit.

Open a dialog with a user by exchanging a trigger_id received from another interaction. See the legacy dialogs documentation to learn how to obtain triggers define form elements.

As with all of our Web API methods, dialog.open primarily takes URL-encoded parameters as arguments. Similar to chat.postMessage, chat.unfurl, and chat.update this method also includes a parameter that expects a JSON object encoded with application/x-www-form-urlencoded.

A simple form you might create could be modeled in JSON as:

{
  "callback_id": "ryde-46e2b0",
  "title": "Request a Ride",
  "submit_label": "Request",
  "state": "Limo",
  "elements": [
    {
      "type": "text",
      "label": "Pickup Location",
      "name": "loc_origin"
    },
    {
      "type": "text",
      "label": "Dropoff Location",
      "name": "loc_destination"
    }
  ]
}

To prepare that as a HTTP POST to dialog.open, you'd optionally minify and then URL encode that JSON to a single string, displayed below as the value for the dialog POST body parameter.

POST /api/dialog.open
token=xoxb-such-and-such
&trigger_id=13345224609.738474920.8088930838d88f008e0
&dialog=%7B%22callback_id%22%3A%22ryde-46e2b0%22%2C%22title%22%3A%22Request%20a%20Ride%22%2C%22submit_label%22%3A%22Request%22%2C%22state%22%3A%22Limo%22%2C%22elements%22%3A%5B%7B%22type%22%3A%22text%22%2C%22label%22%3A%22Pickup%20Location%22%2C%22name%22%3A%22loc_origin%22%7D%2C%7B%22type%22%3A%22text%22%2C%22label%22%3A%22Dropoff%20Location%22%2C%22name%22%3A%22loc_destination%22%7D%5D%7D

You can avoid this nonsense by posting JSON instead.

Response

Assuming your submitted dialog elements were properly formatted, valid, and the trigger_id was viable, you will receive a minimal success response. If your form was invalid, Slack will try to provide a detailed accounting of why and provide the validation_errors error. Look for the response_metadata node and the messages array contained within for human-readable validation errors.

When we encounter an error with a specific form element, we'll indicate which element by a zero-indexed integer: 0 indicates the first provided element, 1 the second, and so on.