Skip to main content

WhatsApp Cloud API - Media API | Developer Documentation

WhatsApp Cloud API - Media API

Copy for LLM
Version
Retrieve and delete uploaded media files by media ID.
Get media URLs with file metadata including size, MIME type, and SHA256 hash.
Media URLs are valid for 5 minutes after retrieval.

Base

URL
https://graph.facebook.com

Endpoints

GET /{Version}/{Media-ID}

To retrieve your media’s URL, make a GET call to /{{Media-ID}}. Use the returned URL to download the media file. Note that clicking this URL (i.e. performing a generic GET) will not return the media; you must include an access token. For more information, see Download Media.
You can also use the optional query ?phone_number_id for Retrieve Media URL and Delete Media. This parameter checks to make sure the media belongs to the phone number before retrieval or deletion.
Response
A successful response includes an object with a media URL. The URL is only valid for 5 minutes. To use this URL, see Download Media.

Request Syntax

GET /{Version}/{Media-ID}
Try it
Select language
curl --request GET \
  --url 'https://graph.facebook.com/{Version}/{Media-ID}' \
  --header 'Authorization: Bearer <Token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
Select status code
{
  "Retrieve Media URL": {
    "value": {
      "file_size": "303833",
      "id": "2621233374848975",
      "messaging_product": "whatsapp",
      "mime_type": "image/jpeg",
      "sha256": "<HASH>",
      "url": "<URL>"
    }
  }
}
Header Parameters
User-Agentstring
The user agent string identifying the client software making the request.
Authorizationstring·required
Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.
Path Parameters
Versionstring·required
Media-IDstring·required
Query Parameters
phone_number_idstring
Specifies that this action only be performed if the media belongs to the provided phone number.
Responses
To retrieve your media’s URL, make a GET call to /{{Media-ID}}. Use the returned URL to download the media file. Note that clicking this URL (i.e. performing a generic GET) will not return the media; you must include an access token. For more information, see Download Media.
You can also use the optional query ?phone_number_id for Retrieve Media URL and Delete Media. This parameter checks to make sure the media belongs to the phone number before retrieval or deletion.
Response
A successful response includes an object with a media URL. The URL is only valid for 5 minutes. To use this URL, see Download Media.
200
Retrieve Media URL
Content Type: application/json
Schema: object
Show child attributes
file_sizestring
idstring
messaging_productstring
mime_typestring
sha256string
urlstring
Select language
curl --request GET \
  --url 'https://graph.facebook.com/{Version}/{Media-ID}' \
  --header 'Authorization: Bearer <Token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
Select status code
{
  "Retrieve Media URL": {
    "value": {
      "file_size": "303833",
      "id": "2621233374848975",
      "messaging_product": "whatsapp",
      "mime_type": "image/jpeg",
      "sha256": "<HASH>",
      "url": "<URL>"
    }
  }
}

DELETE /{Version}/{Media-ID}

To delete media, make a DELETE call to the ID of the media you want to delete.

Prerequisites

User Access Token with whatsapp_business_messaging permission
Media object ID from either uploading media endpoint or media message Webhooks

Request Syntax

DELETE /{Version}/{Media-ID}
Try it
Select language
curl --request DELETE \
  --url 'https://graph.facebook.com/{Version}/{Media-ID}' \
  --header 'Authorization: Bearer <Token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
Select status code
{
  "Delete Media": {
    "value": {
      "success": true
    }
  }
}
Header Parameters
User-Agentstring
The user agent string identifying the client software making the request.
Authorizationstring·required
Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.
Content-TypeOne of "application/json", "application/x-www-form-urlencoded", "multipart/form-data"·required
Media type of the request body
Path Parameters
Versionstring·required
Media-IDstring·required
Query Parameters
phone_number_idstring
Specifies that deletion of the media only be performed if the media belongs to the provided phone number.
Responses
To delete media, make a DELETE call to the ID of the media you want to delete.

Prerequisites

User Access Token with whatsapp_business_messaging permission
Media object ID from either uploading media endpoint or media message Webhooks
200
Delete Media
Content Type: application/json
Schema: object
Show child attributes
successboolean
Select language
curl --request DELETE \
  --url 'https://graph.facebook.com/{Version}/{Media-ID}' \
  --header 'Authorization: Bearer <Token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
Select status code
{
  "Delete Media": {
    "value": {
      "success": true
    }
  }
}

Authentication

Scheme
Type
Location
bearerAuth
HTTP Bearer
Header: Authorization

Usage Examples

bearerAuth:
Include Authorization: Bearer your-token-here in request headers

Global Authentication Requirements

All endpoints require:
bearerAuth
Back to top