WhatsApp Media API

Upload, retrieve, and delete media files

GitHub OpenAPI

Operations 7

POST /{Version}/{Phone-Number-ID}/media Upload Image #
GET /{Version}/{Media-ID} Retrieve Media URL #
DELETE /{Version}/{Media-ID} Delete Media #
GET /{Version}/{Media-URL} Download Media #
POST /{phone-number-id}/media WhatsApp Upload Media #
GET /{media-id} WhatsApp Get Media URL #
DELETE /{media-id} WhatsApp Delete Media #

Documentation

Specifications

Schemas & Data

Other Resources

🔗
Reference
https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/message-api
🔗
Pricing
https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing
🔗
StatusPage
https://metastatus.com/
🔗
ChangeLog
https://developers.facebook.com/documentation/business-messaging/whatsapp/changelog
🔗
ErrorCodes
https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes
🔗
PostmanCollection
https://www.postman.com/meta/whatsapp-business-platform/collection/wlk6lh4/whatsapp-cloud-api
🔗
Node.js SDK
https://github.com/WhatsApp/WhatsApp-Nodejs-SDK
🔗
Sandbox
https://whatsappbusiness.com/developers/developer-hub/
🔗
Media Reference
https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/media
🔗
Phone Numbers Reference
https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/phone-numbers
🔗
Business Profiles Reference
https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/business-profiles
🔗
Two-Step Verification
https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/two-step-verification
🔗
Versioning
https://developers.facebook.com/docs/graph-api/guides/versioning
🔗
PostmanCollection
https://www.postman.com/meta/whatsapp-business-platform/collection/3kru5r6/whatsapp-business-management-api
🔗
Reference
https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/overview

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/whatsapp:whatsapp-media-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

whatsapp-media-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Whatsapp Media API
  version: '1.0'
  description: 'Operations tagged Media across 2 of this provider''s published API definitions: whatsapp-business-messaging-api-v23.0-openapi.yaml, whatsapp-cloud-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://graph.facebook.com
  description: Production Graph API server
- url: https://graph.facebook.com/v21.0
  description: Meta Graph API Production Server
tags:
- name: Media
paths:
  /{Version}/{Phone-Number-ID}/media:
    parameters:
    - name: Version
      in: path
      required: true
      schema:
        type: string
    - name: Phone-Number-ID
      in: path
      required: true
      schema:
        type: string
    post:
      tags:
      - Media
      summary: Upload Image
      description: This request uploads an image as .jpeg. The parameters are specified as **form-data** in the request **body**.
      operationId: uploadImage
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - name: Version
        in: path
        required: true
        schema:
          type: string
        example: v21.0
      - name: Phone-Number-ID
        in: path
        required: true
        schema:
          type: string
        example: '102290129340398'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                file:
                  type: string
                  example: '@/local/path/file.ogg;type=ogg'
                messaging_product:
                  type: string
                  example: whatsapp
            examples:
              Upload Audio:
                value:
                  file: '@/local/path/file.ogg;type=ogg'
                  messaging_product: whatsapp
              Upload Image:
                value:
                  file: '@/local/path/file.jpg;type=image/jpeg'
                  messaging_product: whatsapp
              Upload Sticker:
                value:
                  file: '@/local/path/file.webp;type=webp'
                  messaging_product: whatsapp
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                messaging_product:
                  type: string
                  example: whatsapp
      responses:
        '200':
          description: Upload Image JSON / Upload Sticker File (form-data) / Upload Sticker File JSON / Upload Audio (form-data) / Upload Audio JSON
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: '4490709327384033'
              examples:
                Upload Audio (form-data):
                  value:
                    id: <MEDIA_ID>
                Upload Audio JSON:
                  value:
                    id: '4490709327384033'
                Upload Image JSON:
                  value:
                    id: '4490709327384033'
                Upload Sticker File (form-data):
                  value:
                    id: <MEDIA_ID>
                Upload Sticker File JSON:
                  value:
                    id: '4490709327384033'
      security:
      - bearerAuth: []
    servers:
    - url: https://graph.facebook.com
      description: Production Graph API server
    - url: https://graph.facebook.com
    - url: https://graph.facebook.com
      description: WhatsApp Business Cloud API
    - url: https://graph.facebook.com
      description: Meta Graph API production server
  /{Version}/{Media-ID}:
    parameters:
    - name: Version
      in: path
      required: true
      schema:
        type: string
    - name: Media-ID
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Media
      summary: Retrieve Media URL
      description: '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.'
      operationId: retrieveMediaUrl
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - name: phone_number_id
        in: query
        schema:
          type: string
          example: <PHONE_NUMBER_ID>
        description: Specifies that this action only be performed if the media belongs to the provided phone number.
      responses:
        '200':
          description: Retrieve Media URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  file_size:
                    type: string
                    example: '303833'
                  id:
                    type: string
                    example: '2621233374848975'
                  messaging_product:
                    type: string
                    example: whatsapp
                  mime_type:
                    type: string
                    example: image/jpeg
                  sha256:
                    type: string
                    example: <HASH>
                  url:
                    type: string
                    example: <URL>
              examples:
                Retrieve Media URL:
                  value:
                    file_size: '303833'
                    id: '2621233374848975'
                    messaging_product: whatsapp
                    mime_type: image/jpeg
                    sha256: <HASH>
                    url: <URL>
      security:
      - bearerAuth: []
    delete:
      tags:
      - Media
      summary: Delete Media
      description: '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'
      operationId: deleteMedia
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/ContentType'
      - name: phone_number_id
        in: query
        schema:
          type: string
          example: <PHONE_NUMBER_ID>
        description: Specifies that deletion of the media  only be performed if the media belongs to the provided phone number.
      responses:
        '200':
          description: Delete Media
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
              examples:
                Delete Media:
                  value:
                    success: true
      security:
      - bearerAuth: []
    servers:
    - url: https://graph.facebook.com
      description: Production Graph API server
    - url: https://graph.facebook.com
    - url: https://graph.facebook.com
      description: WhatsApp Business Cloud API
    - url: https://graph.facebook.com
      description: Meta Graph API production server
  /{Version}/{Media-URL}:
    parameters:
    - $ref: '#/components/parameters/UserAgent'
    - $ref: '#/components/parameters/Authorization'
    - name: Version
      in: path
      required: true
      schema:
        type: string
    - name: Media-URL
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Media
      summary: Download Media
      description: 'Download media files using URLs obtained from media retrieval endpoints.

        Requires User Access Token with whatsapp_business_messaging permission.

        Media URLs expire after 5 minutes and must be re-retrieved if expired.

        Returns binary content with appropriate MIME type headers.'
      operationId: downloadMedia
      responses:
        '200':
          description: Download Media
          content:
            text/plain:
              examples:
                Download Media:
                  value: ''
      security:
      - bearerAuth: []
    servers:
    - url: https://graph.facebook.com
      description: Production Graph API server
    - url: https://graph.facebook.com
    - url: https://graph.facebook.com
      description: WhatsApp Business Cloud API
    - url: https://graph.facebook.com
      description: Meta Graph API production server
  /{phone-number-id}/media:
    post:
      operationId: uploadMedia
      summary: WhatsApp Upload Media
      description: Uploads media to WhatsApp servers. Returns a media ID that can be used when sending media messages. Uploaded media persists for 30 days.
      tags:
      - Media
      parameters:
      - $ref: '#/components/parameters/PhoneNumberId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              - type
              - messaging_product
              properties:
                file:
                  type: string
                  format: binary
                  description: The media file to upload
                type:
                  type: string
                  description: MIME type of the file
                  examples:
                  - image/jpeg
                  - video/mp4
                  - application/pdf
                messaging_product:
                  type: string
                  enum:
                  - whatsapp
      responses:
        '200':
          description: Media uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Media ID for use in messages
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - bearerAuth: []
    servers:
    - url: https://graph.facebook.com/v21.0
      description: Meta Graph API Production Server
  /{media-id}:
    get:
      operationId: getMediaUrl
      summary: WhatsApp Get Media URL
      description: Retrieves a temporary download URL for a media file. The URL expires after 5 minutes. To download the file, make a GET request to the returned URL with the same Bearer token.
      tags:
      - Media
      parameters:
      - $ref: '#/components/parameters/MediaId'
      responses:
        '200':
          description: Media URL retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - bearerAuth: []
    delete:
      operationId: deleteByMediaId
      summary: WhatsApp Delete Media
      description: Deletes a media file from WhatsApp servers.
      tags:
      - Media
      parameters:
      - $ref: '#/components/parameters/MediaId'
      responses:
        '200':
          description: Media deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - bearerAuth: []
      x-operation-id-source: normalized
      x-operation-id-original: deleteMedia
    servers:
    - url: https://graph.facebook.com/v21.0
      description: Meta Graph API Production Server
components:
  parameters:
    Authorization:
      name: Authorization
      in: header
      description: 'Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.

        '
      required: true
      schema:
        type: string
        pattern: ^Bearer\s+[A-Za-z0-9\-_.]+.*$
        example: Bearer EAABwzLixnjYBOzYmNMJJGfHq9DgNh...
    UserAgent:
      name: User-Agent
      in: header
      description: The user agent string identifying the client software making the request.
      required: false
      schema:
        type: string
        default: Meta-Business-Messaging-OpenAPI/1.0.0;spec=2025-10-21
        pattern: ^[a-zA-Z0-9\-_]+\/[0-9]+\.[0-9]+\.[0-9]+(;[a-zA-Z0-9\-=\.]+)?(\s+[a-zA-Z0-9\-_]+\/[0-9\-\.]+)?$
        example: Meta-Business-Messaging-OpenAPI/1.0.0;spec=2025-10-21
    ContentType:
      name: Content-Type
      in: header
      description: Media type of the request body
      required: true
      schema:
        type: string
        enum:
        - application/json
        - application/x-www-form-urlencoded
        - multipart/form-data
        default: application/json
        example: application/json
    MediaId:
      name: media-id
      in: path
      required: true
      description: Media ID returned from upload or webhook
      schema:
        type: string
    PhoneNumberId:
      name: phone-number-id
      in: path
      required: true
      description: Phone Number ID from the WhatsApp Business Account
      schema:
        type: string
  schemas:
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
    MediaResponse:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: Temporary download URL (expires in 5 minutes)
          example: https://example.com/image.jpg
        mime_type:
          type: string
          example: text
        sha256:
          type: string
          example: example_value
        file_size:
          type: integer
          example: 42
        id:
          type: string
          example: wamid.abc123
        messaging_product:
          type: string
          example: example_value
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'System user access token with whatsapp_business_management permission. Format: Bearer YOUR_SYSTEM_USER_ACCESS_TOKEN

        '
externalDocs:
  description: WhatsApp Cloud API Documentation
  url: https://developers.facebook.com/docs/whatsapp/cloud-api
x-refined-from:
- whatsapp-business-messaging-api-v23.0-openapi.yaml
- whatsapp-cloud-api-openapi.yml