diff --git a/docs/Reference.md b/docs/Reference.md index 46f59e3937..7459fbad79 100644 --- 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" + } + }] +} +``` \ No newline at end of file diff --git a/docs/interactions/Receiving_and_Responding.md b/docs/interactions/Receiving_and_Responding.md index dab081a7fb..ada22de970 100644 --- 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 diff --git a/docs/resources/Channel.md b/docs/resources/Channel.md index 548d3c3f8b..19e1ba0fe6 100644 --- a/docs/resources/Channel.md +++ b/docs/resources/Channel.md @@ -630,10 +630,14 @@ Embed types are "loosely defined" and, for the most part, are not used by our cl ###### Attachment Structure +> info +> For the `attachments` array in Message Create/Edit requests, only the `id` is required. + | Field | Type | Description | |---------------|-----------|-------------------------------------------------------------------------------------| | id | snowflake | attachment id | | filename | string | name of file attached | +| description? | string | description for the file | | content_type? | string | the attachment's [media type](https://en.wikipedia.org/wiki/Media_type) | | size | integer | size of file in bytes | | url | string | source url of file | @@ -873,6 +877,10 @@ Returns a specific message in the channel. If operating on a guild channel, this Post a message to a guild text or DM channel. Returns a [message](#DOCS_RESOURCES_CHANNEL/message-object) object. Fires a [Message Create](#DOCS_TOPICS_GATEWAY/message-create) Gateway event. See [message formatting](#DOCS_REFERENCE/message-formatting) for more information on how to properly format messages. +You may create a message as a reply to another message. To do so, include a [`message_reference`](#DOCS_RESOURCES_CHANNEL/message-reference-object-message-reference-structure) with a `message_id`. The `channel_id` and `guild_id` in the `message_reference` are optional, but will be validated if provided. + +Files must be attached using a `multipart/form-data` body as described in [Uploading Files](#DOCS_REFERENCE/uploading-files). + ###### Limitations - When operating on a guild channel, the current user must have the `SEND_MESSAGES` permission. @@ -881,20 +889,9 @@ Post a message to a guild text or DM channel. Returns a [message](#DOCS_RESOURCE - The referenced message must exist and cannot be a system message. - The maximum request size when sending a message is **8MB** - For the embed object, you can set every field except `type` (it will be `rich` regardless of if you try to set it), `provider`, `video`, and any `height`, `width`, or `proxy_url` values for images. -- **Files can only be uploaded when using the `multipart/form-data` content type.** - -You may create a message as a reply to another message. To do so, include a [`message_reference`](#DOCS_RESOURCES_CHANNEL/message-reference-object-message-reference-structure) with a `message_id`. The `channel_id` and `guild_id` in the `message_reference` are optional, but will be validated if provided. > info -> Note that when sending a message, you must provide a value for at **least one of** `content`, `embeds`, or `file`. - -> info -> For a `file` attachment, the `Content-Disposition` subpart header MUST contain a `filename` parameter. - -> warn -> This endpoint supports both `application/json` and `multipart/form-data` bodies. When uploading files the `multipart/form-data` content type must be used. -> Note that in multipart form data, the `embeds` and `allowed_mentions` fields cannot be used. You can pass a stringified JSON body as a form value as `payload_json` instead. -> **If you supply a `payload_json` form value, all fields except for `file` fields will be ignored in the form data**. +> Note that when sending a message, you must provide a value for at **least one of** `content`, `embeds`, or `files[n]`. ###### JSON/Form Params @@ -902,14 +899,17 @@ You may create a message as a reply to another message. To do so, include a [`me | -------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------- | | content | string | the message contents (up to 2000 characters) | one of content, file, embed(s), sticker_ids | | tts | boolean | true if this is a TTS message | false | -| file | file contents | the contents of the file being sent | one of content, file, embed(s), sticker_ids | | embeds | array of [embed](#DOCS_RESOURCES_CHANNEL/embed-object) objects | embedded `rich` content (up to 6000 characters) | one of content, file, embed(s), sticker_ids | | embed *(deprecated)* | [embed](#DOCS_RESOURCES_CHANNEL/embed-object) object | embedded `rich` content, deprecated in favor of `embeds` | one of content, file, embed(s), sticker_ids | -| payload_json | string | JSON encoded body of non-file params | `multipart/form-data` only | | allowed_mentions | [allowed mention object](#DOCS_RESOURCES_CHANNEL/allowed-mentions-object) | allowed mentions for the message | false | | message_reference | [message reference](#DOCS_RESOURCES_CHANNEL/message-reference-object-message-reference-structure) | include to make your message a reply | false | | components | array of [message component](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/component-object) objects | the components to include with the message | false | | sticker_ids | array of snowflakes | IDs of up to 3 [stickers](#DOCS_RESOURCES_STICKER/sticker-object) in the server to send in the message | one of content, file, embed(s), sticker_ids | +| files[n] \* | file contents | the contents of the file being sent | one of content, file, embed(s), sticker_ids | +| payload_json \* | string | JSON encoded body of non-file params | `multipart/form-data` only | +| attachments \* | array of partial [attachment](#DOCS_RESOURCES_CHANNEL/attachment-object) objects | attachment objects with filename and description | false | + +\* See [Uploading Files](#DOCS_REFERENCE/uploading-files) for details. ###### Example Request Body (application/json) @@ -924,69 +924,7 @@ You may create a message as a reply to another message. To do so, include a [`me } ``` -###### 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`, `file`) 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." - }], - "message_reference": { - "message_id": "233648473390448641" - } -} ---boundary -Content-Disposition: form-data; name="file"; filename="myfilename.png" -Content-Type: image/png - -[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" - } - }] -} -``` +Examples for file uploads are available in [Uploading Files](#DOCS_REFERENCE/uploading-files). ## Crosspost Message % POST /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/messages/{message.id#DOCS_RESOURCES_CHANNEL/message-object}/crosspost @@ -1038,13 +976,11 @@ When the `content` field is edited, the `mentions` array in the message object w Returns a [message](#DOCS_RESOURCES_CHANNEL/message-object) object. Fires a [Message Update](#DOCS_TOPICS_GATEWAY/message-update) Gateway event. -> info -> For a `file` attachment, the `Content-Disposition` subpart header MUST contain a `filename` parameter. +Refer to [Uploading Files](#DOCS_REFERENCE/uploading-files) for details on attachments and `multipart/form-data` requests. +Any provided files will be **appended** to the message. To remove or replace files you will have to supply the `attachments` field which specifies the files to retain on the message after edit. > warn -> This endpoint supports both `application/json` and `multipart/form-data` bodies. When uploading files the `multipart/form-data` content type must be used. -> Note that in multipart form data, the `embeds`, `allowed_mentions`, and `attachments` fields cannot be used. You can pass a stringified JSON body as a form value as `payload_json` instead. -> **If you supply a `payload_json` form value, all fields except for `file` fields will be ignored in the form data**. +> Starting with API v10, the `attachments` array must contain all attachments that should be present after edit, including **retained and new** attachments provided in the request body. > info > All parameters to this endpoint are optional and nullable. @@ -1057,11 +993,13 @@ Returns a [message](#DOCS_RESOURCES_CHANNEL/message-object) object. Fires a [Mes | embeds | array of [embed](#DOCS_RESOURCES_CHANNEL/embed-object) objects | embedded `rich` content (up to 6000 characters) | | embed *(deprecated)* | [embed](#DOCS_RESOURCES_CHANNEL/embed-object) object | embedded `rich` content, deprecated in favor of `embeds` | | flags | integer | edit the [flags](#DOCS_RESOURCES_CHANNEL/message-object-message-flags) of a message (only `SUPPRESS_EMBEDS` can currently be set/unset) | -| file | file contents | the contents of the file being sent/edited | -| payload_json | string | JSON encoded body of non-file params (multipart/form-data only) | | allowed_mentions | [allowed mention object](#DOCS_RESOURCES_CHANNEL/allowed-mentions-object) | allowed mentions for the message | -| attachments | array of [attachment](#DOCS_RESOURCES_CHANNEL/attachment-object) objects | attached files to keep | | components | array of [message component](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/component-object) | the components to include with the message | +| filse[n] \* | file contents | the contents of the file being sent/edited | +| payload_json \* | string | JSON encoded body of non-file params (multipart/form-data only) | +| attachments \* | array of [attachment](#DOCS_RESOURCES_CHANNEL/attachment-object) objects | attached files to keep and possible descriptions for new files | + +\* See [Uploading Files](#DOCS_REFERENCE/uploading-files) for details. ## Delete Message % DELETE /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/messages/{message.id#DOCS_RESOURCES_CHANNEL/message-object} diff --git a/docs/resources/Webhook.md b/docs/resources/Webhook.md index c68f7686bf..098caad563 100644 --- a/docs/resources/Webhook.md +++ b/docs/resources/Webhook.md @@ -155,16 +155,10 @@ Same as above, except this call does not require authentication. ## Execute Webhook % POST /webhooks/{webhook.id#DOCS_RESOURCES_WEBHOOK/webhook-object}/{webhook.token#DOCS_RESOURCES_WEBHOOK/webhook-object} -> info -> Note that when sending a message, you must provide a value for at **least one of** `content`, `embeds`, or `file`. +Refer to [Uploading Files](#DOCS_REFERENCE/uploading-files) for details on attachments and `multipart/form-data` requests. > info -> For a `file` attachment, the `Content-Disposition` subpart header MUST contain a `filename` parameter. - -> warn -> This endpoint supports both `application/json` and `multipart/form-data` bodies. When uploading files the `multipart/form-data` content type must be used. -> Note that in multipart form data, the `embeds` and `allowed_mentions` fields cannot be used. You can pass a stringified JSON body as a form value as `payload_json` instead. -> **If you supply a `payload_json` form value, all fields except for `file` fields will be ignored in the form data**. +> Note that when sending a message, you must provide a value for at **least one of** `content`, `embeds`, or `file`. ###### Query String Params @@ -181,13 +175,15 @@ Same as above, except this call does not require authentication. | username | string | override the default username of the webhook | false | | avatar_url | string | override the default avatar of the webhook | false | | tts | boolean | true if this is a TTS message | false | -| file | file contents | the contents of the file being sent | one of content, file, embeds | | embeds | array of up to 10 [embed](#DOCS_RESOURCES_CHANNEL/embed-object) objects | embedded `rich` content | one of content, file, embeds | -| payload_json | string | JSON encoded body of non-file params | `multipart/form-data` only | | allowed_mentions | [allowed mention object](#DOCS_RESOURCES_CHANNEL/allowed-mentions-object) | allowed mentions for the message | false | -| components\* | array of [message component](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/component-object) | the components to include with the message | false | +| components \* | array of [message component](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/component-object) | the components to include with the message | false | +| files[n] \*\* | file contents | the contents of the file being sent | one of content, file, embeds | +| payload_json \*\*| string | JSON encoded body of non-file params | `multipart/form-data` only | +| attachments \*\* | array of partial [attachment](#DOCS_RESOURCES_CHANNEL/attachment-object) objects | attachment objects with filename and description | false | \* Requires an application-owned webhook +\*\* See [Uploading Files](#DOCS_REFERENCE/uploading-files) for details. > info > For the webhook embed objects, you can set every field except `type` (it will be `rich` regardless of if you try to set it), `provider`, `video`, and any `height`, `width`, or `proxy_url` values for images. @@ -222,13 +218,11 @@ Edits a previously-sent webhook message from the same token. Returns a [message] When the `content` field is edited, the `mentions` array in the message object will be reconstructed from scratch based on the new content. The `allowed_mentions` field of the edit request controls how this happens. If there is no explicit `allowed_mentions` in the edit request, the content will be parsed with _default_ allowances, that is, without regard to whether or not an `allowed_mentions` was present in the request that originally created the message. -> info -> For a `file` attachment, the `Content-Disposition` subpart header MUST contain a `filename` parameter. +Refer to [Uploading Files](#DOCS_REFERENCE/uploading-files) for details on attachments and `multipart/form-data` requests. +Any provided files will be **appended** to the message. To remove or replace files you will have to supply the `attachments` field which specifies the files to retain on the message after edit. > warn -> This endpoint supports both `application/json` and `multipart/form-data` bodies. When uploading files the `multipart/form-data` content type must be used. -> Note that in multipart form data, the `embeds`, `allowed_mentions`, and `attachments` fields cannot be used. You can pass a stringified JSON body as a form value as `payload_json` instead. -> **If you supply a `payload_json` form value, all fields except for `file` fields will be ignored in the form data**. +> Starting with API v10, the `attachments` array must contain all attachments that should be present after edit, including **retained and new** attachments provided in the request body. > info > All parameters to this endpoint are optional and nullable. @@ -239,13 +233,14 @@ When the `content` field is edited, the `mentions` array in the message object w | ---------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------- | | content | string | the message contents (up to 2000 characters) | | embeds | array of up to 10 [embed](#DOCS_RESOURCES_CHANNEL/embed-object) objects | embedded `rich` content | -| file | file contents | the contents of the file being sent/edited | -| payload_json | string | JSON encoded body of non-file params (multipart/form-data only) | | allowed_mentions | [allowed mention object](#DOCS_RESOURCES_CHANNEL/allowed-mentions-object) | allowed mentions for the message | -| attachments | array of [attachment](#DOCS_RESOURCES_CHANNEL/attachment-object) objects | attached files to keep | -| components\* | array of [message component](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/component-object) | the components to include with the message | +| components \* | array of [message component](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/component-object) | the components to include with the message | +| files[n] \*\* | file contents | the contents of the file being sent/edited | +| payload_json \*\*| string | JSON encoded body of non-file params (multipart/form-data only) | +| attachments \*\* | array of partial [attachment](#DOCS_RESOURCES_CHANNEL/attachment-object) objects | attached files to keep and possible descriptions for new files | \* Requires an application-owned webhook +\*\* See [Uploading Files](#DOCS_REFERENCE/uploading-files) for details. # Delete Webhook Message % DELETE /webhooks/{webhook.id#DOCS_RESOURCES_WEBHOOK/webhook-object}/{webhook.token#DOCS_RESOURCES_WEBHOOK/webhook-object}/messages/{message.id#DOCS_RESOURCES_CHANNEL/message-object}