# 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.41.0"},"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.41.0"},"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.41.0"},"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.41.0"},"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.41.0"},"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"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.360dialog.com/docs/messaging-api/api-reference/media-uploads.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.