Skip to main content

canvases.edit 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​

This method is used to edit an existing canvas that the actor has write access to.

Different operations may be used to target different kinds of edits to a canvas. Sections may be deleted or replaced. New content can be added to the beginning or end of a canvas, or inserted relative to an existing section.

Formatting the changes argument​

The changes argument is an array of objects that provide instructions on how to edit the canvas. Each element in the changes array contains two properties: operation and document_content.

Operations​

The operation property is a string that can be any of the following:

  • insert_after
  • insert_before
  • insert_at_start
  • insert_at_end
  • replace
  • delete

Using insert_after and insert_before requires also providing a section_id and document_content. These updates are made relative to a section of the canvas, hence the required section_id. For details on how to find a section_id, refer to the canvases.sections.lookup method.

Alternatively, information can be added to the beginning or the end of the canvas using insert_at_start or insert_at_end, respectively. Using these operations requires providing a document_content argument.

Using the replace operation also requires providing a document_content argument. You can optionally specify a section_id or omit it to replace the entire canvas.

Using the delete operation requires providing a section_id, and you can only delete a section with this method. To delete an entire canvas, use the canvases.delete method instead. Once a canvas is deleted, there is no way to get it back.

Document content​

You might recognize document_content from the canvases.create method; it works the same.

The following formatting elements are supported in the document_content object:

  • bold
  • bulleted lists
  • checklist
  • canvas unfurl
  • code block
  • code span
  • divider (horizontal rule)
  • emojis—standard and custom
  • file unfurls
  • hard line break
  • headings h1-h3
  • italic
  • link (in line)
  • link reference
  • message unfurl
  • ordered lists
  • paragraph
  • profile unfurl
  • quote block
  • strikethrough
  • website unfurl
  • @ mentions for users and channels

Examples​

This example shows inserting grocery items in a list format after providing the section_id.

{
    "canvas_id": "F0166DCSTS7",
    "changes": [
      {
        "operation": "insert_after",
        "section_id": "temp:C:VXX8e648e6984e441c6aa8c61173",
        "document_content": {
          "type": "markdown",
          "markdown": "- [ ] asparagus\n- [ ] coffee\n"
        }
      }
    ]
}

Then, we could update that same grocery list to check an item off. First, we would need to look up the item's ID, using the canvases.sections.lookup method. Using the ID that is returned with that, we can check off the item like this:

{
    "canvas_id": "F0166DCSTS7",
    "changes": [
      {
        "operation": "replace",
        "section_id": "temp:C:VXX37d27db7718d44e28803566ae",
        "document_content": {
            "type": "markdown",
            "markdown": "- [x] asparagus\n"
        }
      }
    ]
}

Response​