Attaching media

Attaching media

POST direct_messages/events/new supports media attachments of type image, GIF and video. The process is similar to attaching media to Tweets:

  1. Chunk upload the image, GIF or video.
  2. Send Direct Message with media attachment.

It is possible to attach the same media asset to multiple Direct Messages. However, you must get users’ express consent to set media as “shared,” and must provide them with clear notice that “shared” media will be viewable by anyone with the media’s URL. See the documented process below for how to set media to "shared."

Note: Media for use with Direct Messages should be uploaded using the asynchronous chunked upload process described on this page.

1. Chunk upload media

  • Chunk upload the media file starting with POST media/upload (INIT).
  • Set the media_category to dm_imagedm_gif or dm_video appropriately.
  • If reusing the media asset across multiple Direct Messages, you must set shared to true during the initial upload.
  • If attaching a media asset to a Welcome Message, you must set shared to true during the initial upload.
  • Uploaded media can only be shared across Direct Messages created by the same user.
  • See Uploading Media for subsequent APPEND and FINALIZE steps.
  • The returned media ID will be used when sending the Direct Message. If you did not set shared to true the media ID can only be used in a single Direct Message.

Once a media ID is generated, it must be attached to a Direct Message within 24 hours.


The media category: dm_imagedm_gifdm_video
shared Set to true if media asset will be reused for multiple Direct Messages. Default is false.

See POST media/upload (INIT) documentation for all parameters and full details.

2. Send Direct Message with media attachment

  • Define an attachment object in the message_data object in the Direct Message event json body.
  • Set attachment type property to media.
  • Set the property to the media ID returned in the previous chunk upload process.


Must be set to media.
A media ID to associate with the message. A Direct Message may only reference a single media id.

See POST direct_messages/events/new documentation for all parameters and full details.