# Media Uploads

Endpoints for uploading media files

## Upload Media

> Upload media files (images, videos, documents) to Meta's media API for use in messages. More info on media uploads can be found in our documentation: <https://docs.360dialog.com/docs/waba-messaging/media/upload-retrieve-or-delete-media?q=resumable+upload#upload-media>.

```json
{"openapi":"3.1.0","info":{"title":"Messaging API","version":"1.38.1"},"tags":[{"name":"Media Uploads","description":"Endpoints for uploading media files"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"media.ResponsePayload":{"properties":{"id":{"type":"string"}},"type":"object"},"utils.ErrorResp":{"properties":{"error":{"type":"string"}},"type":"object"}}},"paths":{"/media":{"post":{"description":"Upload media files (images, videos, documents) to Meta's media API for use in messages. More info on media uploads can be found in our documentation: https://docs.360dialog.com/docs/waba-messaging/media/upload-retrieve-or-delete-media?q=resumable+upload#upload-media.","operationId":"upload-media","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"oneOf":[{"title":"messaging_product","type":"string"},{"title":"file","type":"file"}]}},"multipart/form-data":{"schema":{"type":"object"}}},"description":"Messaging product (must be 'whatsapp') | Media file to upload","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/media.ResponsePayload"}}},"description":"Media uploaded successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Internal server error"}},"summary":"Upload Media","tags":["Media Uploads"]}}}}
```

## Get Upload Session Status

> Retrieve current status of an upload session to resume interrupted uploads. Returns session ID and current file offset. See Meta docs: <https://developers.facebook.com/docs/graph-api/guides/upload>

```json
{"openapi":"3.1.0","info":{"title":"Messaging API","version":"1.38.1"},"tags":[{"name":"Media Uploads","description":"Endpoints for uploading media files"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"uploads.UploadSessionStatusResponseSchema":{"properties":{"file_offset":{"type":"integer"},"id":{"type":"string"}},"type":"object"},"utils.ErrorResp":{"properties":{"error":{"type":"string"}},"type":"object"}}},"paths":{"/upload:{session_id}":{"get":{"description":"Retrieve current status of an upload session to resume interrupted uploads. Returns session ID and current file offset. See Meta docs: https://developers.facebook.com/docs/graph-api/guides/upload","operationId":"get-upload-session-status","parameters":[{"description":"Upload session ID (the part after 'upload:')","in":"path","name":"session_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/uploads.UploadSessionStatusResponseSchema"}}},"description":"Session status retrieved"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Bad request - missing session ID or authorization header"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Internal server error"}},"summary":"Get Upload Session Status","tags":["Media Uploads"]}}}}
```

## Upload File Data to Session (Resumable Upload API)

> Upload file data to an existing upload session using Meta's Resumable Upload API. The file\_offset header allows resuming interrupted uploads from a specific byte position. Returns file handle on completion. See Meta docs: <https://developers.facebook.com/docs/graph-api/guides/upload>

```json
{"openapi":"3.1.0","info":{"title":"Messaging API","version":"1.38.1"},"tags":[{"name":"Media Uploads","description":"Endpoints for uploading media files"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"uploads.UploadFileHandleResponseSchema":{"properties":{"h":{"type":"string"}},"type":"object"},"utils.ErrorResp":{"properties":{"error":{"type":"string"}},"type":"object"}}},"paths":{"/upload:{session_id}":{"post":{"description":"Upload file data to an existing upload session using Meta's Resumable Upload API. The file_offset header allows resuming interrupted uploads from a specific byte position. Returns file handle on completion. See Meta docs: https://developers.facebook.com/docs/graph-api/guides/upload","operationId":"upload-file-to-session","parameters":[{"description":"Upload session ID (the part after 'upload:')","in":"path","name":"session_id","required":true,"schema":{"type":"string"}},{"description":"Byte offset to resume upload from (default: 0). Use session status endpoint to determine current offset","in":"header","name":"file_offset","schema":{"type":"integer"}}],"requestBody":{"content":{"application/octet-stream":{"schema":{"format":"binary","type":"string"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/uploads.UploadFileHandleResponseSchema"}}},"description":"File uploaded successfully, returns handle"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Bad request - missing session ID or authorization header"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Internal server error"}},"summary":"Upload File Data to Session (Resumable Upload API)","tags":["Media Uploads"]}}}}
```

## Create Upload Session

> Create a new upload session for media files. Returns a session ID for uploading file data. See Meta docs: <https://developers.facebook.com/docs/graph-api/guides/upload>

```json
{"openapi":"3.1.0","info":{"title":"Messaging API","version":"1.38.1"},"tags":[{"name":"Media Uploads","description":"Endpoints for uploading media files"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"uploads.CreateUploadSessionResponseSchema":{"properties":{"id":{"type":"string"}},"type":"object"},"utils.ErrorResp":{"properties":{"error":{"type":"string"}},"type":"object"}}},"paths":{"/uploads":{"post":{"description":"Create a new upload session for media files. Returns a session ID for uploading file data. See Meta docs: https://developers.facebook.com/docs/graph-api/guides/upload","operationId":"create-upload-session","parameters":[{"description":"File name","in":"query","name":"file_name","required":true,"schema":{"type":"string"}},{"description":"File size in bytes","in":"query","name":"file_length","required":true,"schema":{"type":"integer"}},{"description":"MIME type of the file","in":"query","name":"file_type","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/uploads.CreateUploadSessionResponseSchema"}}},"description":"Upload session created successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Bad request - missing or malformed authorization header, or invalid parameters"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Internal server error"}},"summary":"Create Upload Session","tags":["Media Uploads"]}}}}
```

## Upload Media with Session ID

> Upload media using upload: prefixed session ID (e.g., for profile picture uploads via Resumable Upload API).

```json
{"openapi":"3.1.0","info":{"title":"Messaging API","version":"1.38.1"},"tags":[{"name":"Media Uploads","description":"Endpoints for uploading media files"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"media_id.UploadMediaResponse":{"description":"Response payload containing the uploaded file handle","properties":{"h":{"type":"string"}},"type":"object"},"utils.ErrorResp":{"properties":{"error":{"type":"string"}},"type":"object"}}},"paths":{"/{session_id}":{"post":{"description":"Upload media using upload: prefixed session ID (e.g., for profile picture uploads via Resumable Upload API).","operationId":"upload-media-with-session","parameters":[{"description":"Session ID with 'upload:' prefix (e.g. 'upload:1234567890')","in":"path","name":"session_id","required":true,"schema":{"type":"string"}},{"description":"Byte offset to resume upload from. Default 0","in":"header","name":"file_offset","schema":{"type":"integer"}}],"requestBody":{"content":{"application/octet-stream":{"schema":{"format":"binary","type":"string"}},"text/plain":{"schema":{"title":"body","type":"string"}}},"description":"Binary file data","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/media_id.UploadMediaResponse"}}},"description":"File handle returned on successful upload"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Bad request - missing 'upload:' prefix"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Internal server error"}},"summary":"Upload Media with Session ID","tags":["Media Uploads"]}}}}
```