Document multi file upload (#3860)

* Document multi file upload * Review suggestions * Update warning * Filename needs to be unique * Reformatting and new information * Fix link * Add description to attachment structure * Clarify attachments list for patch endpoints * Add footnote for attachments * Add docs for callback data * Review suggestions * Add info block for required fields in attachment structure * Rename file[n] to files[n] * Some rewording
discord · Oct 21, 2021 · 4967eca · 4967eca
1 parent 46b9d00
commit 4967eca
Show file tree

Hide file tree

Showing 4 changed files with 150 additions and 113 deletions.
diff --git a/docs/Reference.md b/docs/Reference.md
@@ -338,3 +338,103 @@ data:image/jpeg;base64,BASE64_ENCODED_JPEG_IMAGE_DATA
 ```
 
 Ensure you use the proper content type (`image/jpeg`, `image/png`, `image/gif`) that matches the image data being provided.
+
+## Uploading Files
+
+Some endpoints support file attachments, indicated by the `files[n]` parameter. To add a file to the request, the standard `application/json` body must be replaced by a `multipart/form-data` body. The otherwise json body can instead be provided using a special `payload_json` parameter in addition to a number of `files[n]` parameters.
+
+All `files[n]` parameters must include a valid `Content-Disposition` subpart header with a `filename` and unique `name` parameter. Each file parameter must be uniquely named in the format `files[n]` such as `files[0]`, `files[1]`, or `files[42]`. The suffixed index `n` is the *snowflake placeholder* for the `attachments` json parameter that is supplied in `payload_json` (or [Callback Data Payloads](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-response-object-interaction-callback-data-structure)).
+
+The file upload limit applies to the entire request, not individual files in a request. This limit depends on the **Boost Tier** of a Guild and is 8 MiB by default.
+
+Images can also be referenced in embeds using the `attachments://filename` URL. An example payload is provided below.
+
+### Editing Message Attachments
+
+All files added to a request, as described above, will be appended to the message in a `PATCH` request. The `attachments` json parameter has a special behavior for edit, as it is used for both removing attachments from the message as well as adding descriptions for new attachments added by the request.
+
+The `attachments` json parameter lists all files that should be attached to the message after the edit, including all new files added and the respective snowflake placeholders. To remove attachments, simply exclude them from this list.
+
+###### Example Request Bodies (multipart/form-data)
+
+Note that these examples are small sections of an HTTP request to demonstrate behaviour of this endpoint - client libraries will set their own form boundaries, `boundary` is just an example. For more information, refer to the [multipart/form-data spec](https://tools.ietf.org/html/rfc7578#section-4).
+
+This example demonstrates usage of the endpoint *without* `payload_json`.
+
+```
+--boundary
+Content-Disposition: form-data; name="content"
+
+Hello, World!
+--boundary
+Content-Disposition: form-data; name="tts"
+
+true
+--boundary--
+```
+
+This example demonstrates usage of the endpoint *with* `payload_json` and all content fields (`content`, `embeds`, `files[n]`) set.
+
+```
+--boundary
+Content-Disposition: form-data; name="payload_json"
+Content-Type: application/json
+
+{
+  "content": "Hello, World!",
+  "embeds": [{
+    "title": "Hello, Embed!",
+    "description": "This is an embedded message.",
+    "thumbnail": {
+      "url": "attachment://myfilename.png"
+    },
+    "image": {
+      "url": "attachment://mygif.gif"
+    }
+  }],
+  "message_reference": {
+    "message_id": "233648473390448641"
+  },
+  "attachments": [{
+      "id": 0,
+      "description": "Image of a cute little cat",
+      "filename": "file.png"
+  }, {
+      "id": 1,
+      "description": "Rickroll gif",
+      "filename": "mygif.gif"
+  }]
+}
+--boundary
+Content-Disposition: form-data; name="files[0]"; filename="file.png"
+Content-Type: image/png
+
+[image bytes]
+--boundary
+Content-Disposition: form-data; name="files[1]"; filename="mygif.gif"
+Content-Type: image/gif
+
+[image bytes]
+--boundary--
+```
+
+###### Using Attachments within Embeds
+
+You can upload attachments when creating a message and use those attachments within your embed. To do this, you will want to upload files as part of your `multipart/form-data` body. Make sure that you're uploading files that contain a filename, as you will need a filename to reference against.
+
+> warn
+> Only filenames with proper image extensions are supported for the time being.
+
+In the embed object, you can then set an image to use an attachment as its url with our attachment scheme syntax: `attachment://filename.png`
+
+For example:
+
+```json
+{
+  "embeds": [{
+    "image": {
+      "url": "attachment://screenshot.png"
+    }
+  }]
+}
+```
diff --git a/docs/interactions/Receiving_and_Responding.md b/docs/interactions/Receiving_and_Responding.md
@@ -172,14 +172,17 @@ There are a number of ways you can respond to an interaction:
 
 Not all message fields are currently supported.
 
-| Name              | Type                                                                | Description                                                                                                                                |
-| ----------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| tts?              | boolean                                                             | is the response TTS                                                                                                                        |
-| content?          | string                                                              | message content                                                                                                                            |
-| embeds?           | array of [embeds](#DOCS_RESOURCES_CHANNEL/embed-object)             | supports up to 10 embeds                                                                                                                   |
-| allowed_mentions? | [allowed mentions](#DOCS_RESOURCES_CHANNEL/allowed-mentions-object) | [allowed mentions](#DOCS_RESOURCES_CHANNEL/allowed-mentions-object) object                                                                 |
-| flags?            | integer                                                             | [interaction callback data flags](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-response-object-interaction-callback-data-flags) |
-| components?       | array of [components](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/)       | message components                                                                                                                         |
+| Name              | Type                                                                             | Description                                                                                                                                |
+| ----------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| tts?              | boolean                                                                          | is the response TTS                                                                                                                        |
+| content?          | string                                                                           | message content                                                                                                                            |
+| embeds?           | array of [embeds](#DOCS_RESOURCES_CHANNEL/embed-object)                          | supports up to 10 embeds                                                                                                                   |
+| allowed_mentions? | [allowed mentions](#DOCS_RESOURCES_CHANNEL/allowed-mentions-object)              | [allowed mentions](#DOCS_RESOURCES_CHANNEL/allowed-mentions-object) object                                                                 |
+| flags?            | integer                                                                          | [interaction callback data flags](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-response-object-interaction-callback-data-flags) |
+| components?       | array of [components](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/)                    | message components                                                                                                                         |
+| attachments? \*   | array of partial [attachment](#DOCS_RESOURCES_CHANNEL/attachment-object) objects | attachment objects with filename and description                                                                                           |
+
+\* See [Uploading Files](#DOCS_REFERENCE/uploading-files) for details.
 
 ###### Interaction Callback Data Flags
 
@@ -311,6 +314,7 @@ We highly recommend checking out our [Community Resources](#DOCS_TOPICS_COMMUNIT
 ## Create Interaction Response % POST /interactions/{interaction.id#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction}/{interaction.token#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object}/callback
 
 Create a response to an Interaction from the gateway. Takes an [interaction response](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-response-object).
+This endpoint also supports file attachments similar to the webhook endpoints. Refer to [Uploading Files](#DOCS_REFERENCE/uploading-files) for details on uploading files and `multipart/form-data` requests.
 
 ## Get Original Interaction Response % GET /webhooks/{application.id#DOCS_RESOURCES_APPLICATION/application-object}/{interaction.token#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object}/messages/@original