> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wavix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Download received media

> Returns a media file your account received in a WhatsApp message.

The address of the media is the `url` of a media content in a `whatsapp.message.received` event, and the `media_url` of a message from [List WhatsApp messages](https://docs.wavix.com/api-reference/whatsapp/list-whatsapp-messages) or [Retrieve a WhatsApp message](https://docs.wavix.com/api-reference/whatsapp/retrieve-a-whatsapp-message).

**Behavior:** Returns the file itself, with its own media type in the `Content-Type` header. The file stays available at least as long as Wavix keeps the received message.

**Requires:** Your account must have WhatsApp enabled, must have a subscription plan, and must not be blocked or suspended.



## OpenAPI

````yaml https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/whatsapp/media/{media_uuid}
openapi: 3.1.0
info:
  title: Wavix APIs
  description: >-
    Wavix provides robust APIs that let you integrate voice and text messaging
    features directly into your app. Send text, place calls, and access detailed
    reports  programmatically.
  termsOfService: https://wavix.com/terms-and-conditions
  license:
    name: MIT
    identifier: MIT
  contact:
    name: Wavix
    url: https://wavix.com
    email: support@wavix.com
  version: 2.0.0
servers:
  - url: https://api.wavix.com
    description: https://api.wavix.com
    variables: {}
security:
  - bearerAuth: []
tags:
  - name: SIP trunks
    description: SIP trunks
  - name: Buy
    description: Numbers
  - name: Cart
    description: Numbers
  - name: My numbers
    description: Numbers
  - name: Billing
    description: Billing, transactions, and invoices
  - name: Profile
    description: Account profile and customer information
  - name: CDRs
    description: Call detail records and call history
  - name: Speech Analytics
    description: Call transcription and speech analytics
  - name: SMS and MMS
    description: Messaging
  - name: Number Validator
    description: Phone number validation
  - name: Link shortener
    description: Short link and click metrics
  - name: 2FA
    description: Two-factor authentication
  - name: 10DLC
    description: 10DLC Campaigns and Brands
  - name: API Keys
    description: API key management
  - name: Call webhooks
    description: Webhook configuration for call events
  - name: Call control
    description: Programmable Voice
  - name: Call streaming
    description: Real-time call audio streaming over WebSocket
  - name: Call recording
    description: Call recording
  - name: Sub-accounts
    description: Sub-account management
  - name: Voice campaigns
    description: Outbound voice campaigns
  - name: Wavix Embeddable
    description: WebRTC embeddable widget
  - name: WhatsApp
    description: WhatsApp senders, templates, messages, webhooks, and events
  - name: WhatsApp webhook payloads
    description: >-
      Message, template, sender, and marketing preference events Wavix posts to
      your WhatsApp webhooks
paths:
  /v1/whatsapp/media/{media_uuid}:
    get:
      tags:
        - WhatsApp
      summary: Download received media
      description: >-
        Returns a media file your account received in a WhatsApp message.


        The address of the media is the `url` of a media content in a
        `whatsapp.message.received` event, and the `media_url` of a message from
        [List WhatsApp
        messages](https://docs.wavix.com/api-reference/whatsapp/list-whatsapp-messages)
        or [Retrieve a WhatsApp
        message](https://docs.wavix.com/api-reference/whatsapp/retrieve-a-whatsapp-message).


        **Behavior:** Returns the file itself, with its own media type in the
        `Content-Type` header. The file stays available at least as long as
        Wavix keeps the received message.


        **Requires:** Your account must have WhatsApp enabled, must have a
        subscription plan, and must not be blocked or suspended.
      operationId: whatsapp_media_download
      parameters:
        - name: media_uuid
          in: path
          required: true
          description: >-
            ID of the media, as returned in `id` of the media content of a
            `whatsapp.message.received` event or in `media_id` of a received
            message.
          schema:
            type: string
            format: uuid
          example: 7f3e2c1a-5b9d-4e8f-a1c3-2d4e6f8a0b1c
      responses:
        '200':
          description: The media file of the received message.
          headers:
            Content-Type:
              description: >-
                Media type of the file, such as `image/jpeg`, or
                `application/octet-stream` when the type isn't known.
              schema:
                type: string
            Content-Length:
              description: Size of the file in bytes.
              schema:
                type: integer
            Cache-Control:
              description: Always `no-store`.
              schema:
                type: string
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/WhatsAppUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/WhatsAppForbiddenResponse'
        '404':
          description: >-
            WhatsApp isn't available for your account or isn't enabled yet, or
            no media with this ID belongs to your account.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/WhatsAppProblem'
              examples:
                whatsapp-not-available:
                  summary: WhatsApp is not available for this account
                  value:
                    type: https://docs.wavix.com/errors/whatsapp-not-available
                    title: WhatsApp Not Available
                    status: 404
                    detail: WhatsApp is not available for this account.
                    instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                    error_class: permanent
                    error_code: WHATSAPP_NOT_AVAILABLE
                channel-not-enabled:
                  summary: WhatsApp is not enabled yet for this account
                  value:
                    type: https://docs.wavix.com/errors/channel-not-enabled
                    title: Channel Not Enabled
                    status: 404
                    detail: The WhatsApp channel is not enabled for this account.
                    instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                    error_class: permanent
                    error_code: CHANNEL_NOT_ENABLED
                resource-not-found:
                  summary: No media matches the given ID
                  value:
                    type: https://docs.wavix.com/errors/resource-not-found
                    title: Resource Not Found
                    status: 404
                    detail: Resource Not Found
                    instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                    error_class: permanent
                    error_code: RESOURCE_NOT_FOUND
        '429':
          $ref: '#/components/responses/WhatsAppTooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/WhatsAppInternalServerErrorResponse'
        '503':
          $ref: '#/components/responses/WhatsAppServiceUnavailableResponse'
      deprecated: false
      security:
        - bearerAuth:
            - whatsapp:read
components:
  responses:
    WhatsAppUnauthorizedResponse:
      description: >-
        Authentication failed or wasn't provided, or the account is suspended,
        blocked, or has no subscription plan.
      headers: {}
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/WhatsAppProblem'
          examples:
            authentication-required:
              summary: The API key or token is missing or isn't valid
              value:
                type: https://docs.wavix.com/errors/authentication-required
                title: Authentication Required
                status: 401
                detail: Authentication is required to access this resource.
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: permanent
                error_code: AUTHENTICATION_REQUIRED
            account-suspended:
              summary: The account is suspended
              value:
                type: https://docs.wavix.com/errors/authentication-required
                title: Authentication Required
                status: 401
                detail: The account is suspended.
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: permanent
                error_code: AUTHENTICATION_REQUIRED
            account-blocked:
              summary: The account is blocked
              value:
                type: https://docs.wavix.com/errors/authentication-required
                title: Authentication Required
                status: 401
                detail: The account is blocked.
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: permanent
                error_code: AUTHENTICATION_REQUIRED
            account-without-plan:
              summary: The account has no subscription plan
              value:
                type: https://docs.wavix.com/errors/authentication-required
                title: Authentication Required
                status: 401
                detail: The account has no subscription plan.
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: permanent
                error_code: AUTHENTICATION_REQUIRED
    WhatsAppForbiddenResponse:
      description: >-
        Returns when the API key doesn't have the scope the operation needs, or
        the request isn't allowed for the account's region.
      headers: {}
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/WhatsAppProblem'
          examples:
            access-denied:
              value:
                type: https://docs.wavix.com/errors/access-denied
                title: Access Denied
                status: 403
                detail: The API key has no access to this resource.
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: permanent
                error_code: ACCESS_DENIED
    WhatsAppTooManyRequestsResponse:
      description: Returns when the account has exceeded its request rate limit.
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request.
          schema:
            type: integer
            example: 30
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/WhatsAppProblem'
          examples:
            rate-limited:
              value:
                type: https://docs.wavix.com/errors/rate-limited
                title: Rate Limited
                status: 429
                detail: Too many requests. Try again later.
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: rate_limited
                error_code: RATE_LIMITED
    WhatsAppInternalServerErrorResponse:
      description: >-
        Returns when an unexpected error occurs on the server; the request may
        be retried.
      headers: {}
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/WhatsAppProblem'
          examples:
            internal-error:
              value:
                type: https://docs.wavix.com/errors/internal-error
                title: Internal Error
                status: 500
                detail: Internal Error
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: retriable
                error_code: INTERNAL_ERROR
    WhatsAppServiceUnavailableResponse:
      description: >-
        Returns when the service is temporarily unavailable; the request may be
        retried.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/WhatsAppProblem'
          examples:
            service-unavailable:
              value:
                type: https://docs.wavix.com/errors/service-unavailable
                title: Service Unavailable
                status: 503
                detail: The service is temporarily unavailable.
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: retriable
                error_code: SERVICE_UNAVAILABLE
  schemas:
    WhatsAppProblem:
      title: WhatsAppProblem
      description: >-
        An RFC 9457 problem document that describes an error from the WhatsApp
        API. Returned with the `application/problem+json` content type.
      required:
        - type
        - title
        - status
        - detail
        - instance
      type: object
      additionalProperties: false
      properties:
        type:
          type: string
          description: URI that identifies the problem type.
          example: https://docs.wavix.com/errors/whatsapp-not-available
        title:
          type: string
          description: Short, human-readable summary of the problem type.
          example: WhatsApp Not Available
        status:
          type: integer
          format: int32
          description: HTTP status code of the response.
          example: 404
        detail:
          type: string
          description: Human-readable explanation of this occurrence of the problem.
          example: WhatsApp is not available for this account.
        instance:
          type: string
          description: Request ID of this occurrence of the problem.
          example: 3a525ca2-6909-4c72-9399-905adf7f3a74
        error_class:
          type: string
          description: >-
            Machine-readable classification of the error. Possible values:


            - `permanent` — The request can't succeed as sent. Retrying doesn't
            help.

            - `retriable` — The failure is temporary. Retrying can succeed.

            - `rate_limited` — The request was rate limited. Retry later.

            - `invalid_template` — The template content is invalid.
          enum:
            - permanent
            - retriable
            - rate_limited
            - invalid_template
          example: permanent
        error_code:
          type: string
          description: >-
            Stable machine-readable error code. It's the problem type slug in
            upper case, with underscores in place of hyphens.
          example: WHATSAPP_NOT_AVAILABLE
        service_window_closed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Time the 24-hour service window of the recipient closed. Returned
            with `service-window-closed`. It's `null` when the recipient never
            wrote to the sender or the last message is older than the retained
            history.
          example: '2026-01-14T09:15:00.000Z'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        Wavix API key. Pass as `Authorization: Bearer <api_key>`. Keys support
        per-resource scopes (none / read / write). See [Restricted keys and
        scopes](https://docs.wavix.com/api-reference/authentication#restricted-keys-and-scopes).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.