Client Documentation
Get StartedStatus Page
  • 360Dialog
    • Why you should use 360dialog as Business Solution Provider (BSP)
    • Prices, plans and payment options
  • client hub
    • 360Dialog Client Hub
    • Numbers
      • Manage your WABA
        • Account Statuses
    • Activity
    • Funds
      • Month Closing Invoice (MCI)
    • Payment Management
    • API Keys
    • Template Message Management
    • Partner Change
    • Cancellation
    • Downgrade
  • WhatsApp Marketing
    • Best practices to maintain Account Health and prevent being blocked
    • Driving users to your WhatsApp account
      • WhatsApp Channels
    • Business Search
    • Linking a WABA to a Facebook Page /EN
      • Vinculando uma conta WABA à uma página do Facebook /PT
      • Cómo vincular un WABA a una página de Facebook /ES
    • Linking a WABA to Google Message Ads
    • Ads that Click to WhatsApp (CTWA) /EN
      • Anúncios de Clique para o WhatsApp (CTWA) /PT
        • Como usar o WhatsApp para marketing e vendas? /PT
      • Anuncios que Click to WhatsApp (CTWA) /ES
        • ¿Cómo usar WhatsApp para marketing y ventas? /ES
    • Conversions API (CAPI)
    • Create Ads lookalike audience based on WhatsApp events
    • MM Lite API Beta
      • Onboarding
      • Sending Messages
  • waba basics
    • WhatsApp Business Platform
    • WhatsApp Accounts structure
    • WABA for Government Agencies
    • WABA Policy Enforcement
    • Architecture and Security
    • The Basics (Overview)
    • Webhook Events and Notifications
    • Messaging API
      • Messaging Health Status
      • Step to Step to move to Cloud API
        • [will be deprecated] WABA Integration (On-Premise)
    • Migrating Phone Numbers
      • Migrate number from Meta or alternate BSP to 360dialog Cloud API
      • Migrate a phone number to a new WABA
      • Migrate to alternate BSP
  • waba management
    • Creating new WABA
      • Using a new phone number
      • WhatsApp Coexistence
        • Coexistence Onboarding
        • Coexistence Webhooks
    • Display Name Guidelines
    • Meta Business Verification
    • Official Business Account (OBA) or blue badge
    • WABA Profile Info
    • Capacity, Quality Rating, and Messaging Limits
      • Accelerated Onboarding
    • Hosting type Change
  • waba Messaging
    • Sandbox (Test API Key)
    • Receiving messages
    • Before sending a message
      • Checklist for Message Broadcasts and Campaigns
    • Conversations
    • Messaging
    • Conversational Components
    • Media Messages
      • Upload, retrieve or delete media
    • Template Messages
      • Template Elements
      • Sending Template Messages
      • Authentication Templates
        • Zero-Tap Authentication Templates
        • One-Tap Autofill Authentication Templates
        • Copy Code Authentication Templates
      • Catalog Templates
      • Product Card Carousel Templates
      • Single-Product Message Templates
      • Coupon Code Templates
      • Limited-Time Offer Templates
      • Multi-Product Templates
    • Interactive Messages
      • Single and Multi Product Messages
      • Location Request Message
    • Flows
    • Products & Catalogs
    • Contacts and Location Messages
    • Payments (India Only)
      • Receive WhatsApp Payments via Payments Gateway
      • Receive WhatsApp Payments via Payment Links
      • Order Details Template Message
    • Payments (Singapore only)
      • Receive WhatsApp Payments via Stripe
  • Partners
    • Partner Documentation
  • Support
    • Help and Support
      • Opening Hours & Response Time
      • Status Pages
      • Meta Support
      • Common Issues
      • How to contact Support
    • Error Messages
    • Imprint & Data Privacy
    • FAQ
Powered by GitBook
On this page
  • Send a media message
  • [will be deprecated] If the WABA is registered in On-premise API

Was this helpful?

  1. waba Messaging

Media Messages

Use the media node to upload, retrieve, or delete media.

PreviousConversational ComponentsNextUpload, retrieve or delete media

Last updated 6 months ago

Was this helpful?

If you are using On-Premise API, remember that it is being discontinued by Meta. No new signups will be allowed with this type of integration from May 15, 2024.

Numbers registered before this date will still be supported, but should start planning a as soon as possible.

You can only send a text message up until 24 hours after receiving a message from the user. If you have not received a message from the user within this time, you will need to start a new conversation by .

Use the messages node to send messages containing audio, documents, images, stickers, or videos to your customers.

In essence, when you send a message that includes media, you must provide either the ID of the uploaded media or a link to the media in the request body. You must also specify the type of media that you are sending: audio, document, image, sticker, or video. When the request is received, the media is uploaded to the WhatsApp server and sent to the user indicated in the to field.

When sending messages with media such as images, videos, or audio files, it is important to ensure that they are not heavy, as processing heavy media files at once can cause delays in transmission and lead to issues with message delivery.

For this, we suggest uploading media beforehand using the /media endpoint and then utilizing the media_id obtained from the response when sending messages.

By following this approach, you can ensure that the media file is processed accurately without causing any delays or latencies during send-outs.

Currently, there are two ways to send media messages with the WhatsApp Business API:

  • IDs (recommended) — To use an ID, you must first to obtain the ID required for the messages API call.

  • Links (not recommended) — To use a link, you supply an HTTP(S) link from which the application will download the media, saving you the step of uploading media yourself. Please make sure you are using a mp4 direct link.

After you upload the media, use the returned ID for the id field in the API call sending the media message.

Alternatively, you can provide a link parameter pointing to the media you want to send. Currently only HTTP/HTTPS links are supported. You will need to use a link that directs to the mp4 file itself, which might not be available if using basic video platforms. Some suggested platforms that offer this type of link are Google Cloud Storage Bucket, AWS S3 Bucket, Streamable.

Either id or link is required, but should not be used at the same time.

Send a media message

POST https://waba-v2.360dialog.io/messages

Request Body

Name
Type
Description

recipient_type

string

individual

SPECIFIC PARAMETERS

String

type

string

to

string

wa_id of the contact you want to message

Object (media ID) is returned.

{
  "id":"<MEDIA_ID>"
}

Example:

The samples below shows a media message with different objects such as URL and Media ID. A valid request body would look like this:

Sending media messages using Image URL:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE-NUMBER",
  "type": "image",
  "image": {
    "link" : "https://IMAGE_URL"
  }
}

Sending media messages using Media ID:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE-NUMBER",
  "type": "image",
  "image": {
    "id" : "MEDIA-OBJECT-ID"
  }
}

In the case of an unsuccessful response, a callback is sent to your Webhook URL even though the response will yield a message ID similar to a successful message send.

Media HTTP Caching

The Cloud API supports media HTTP caching. If you are using a link (link) to a media asset on your server (as opposed to the ID (id) of an asset you have uploaded to Meta's servers), you can instruct them to cache your asset for reuse with future messages by including the headers below in your server response when the asset is requested. If none of these headers are included, Meta will not cache your asset.

Cache-Control: <CACHE_CONTROL>
Last-Modified: <LAST_MODIFIED>
ETag: <ETAG>

Cache-Control

The Cache-Control header tells Meta how to handle asset caching. They support the following directives:

  • max-age=n: Indicates how many seconds (n) to cache the asset. The cached asset will be reused in subsequent messages until this time is exceeded, after which the asset will be requested again, if needed. Example: Cache-Control: max-age=604800.

  • no-cache: Indicates the asset can be cached but should be updated if the Last-Modified header value is different from a previous response. Requires the Last-Modified header. Example: Cache-Control: no-cache.

  • no-store: Indicates that the asset should not be cached. Example: Cache-Control: no-store.

  • private: Indicates that the asset is personalized for the recipient and should not be cached.

Last-Modified

Indicates when the asset was last modified. Used with Cache-Control: no-cache. If the Last-Modified value is different from a previous response and Cache-Control: no-cache is included in the response, Meta updates their cached version of the asset with the asset in the response. Example: Date: Tue, 22 Feb 2022 22:22:22 GMT.

ETag

The ETag header is a unique string that identifies a specific version of an asset. Example: ETag: "33a64df5". This header is ignored unless both Cache-Control and Last-Modified headers are not included in the response. In this case, we will cache the asset according to our own, internal logic (which Meta does not disclose).

Sample Response with Headers

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 1024
Date: Tue, 22 Feb 2022 22:22:22 GMT
ETag: "33a64df5"
Cache-Control: max-age=604800

<IMAGE_PAYLOAD>

[will be deprecated] If the WABA is registered in On-premise API

As announced in November 2023, Meta is transitioning to a fully Cloud-hosted WhatsApp Business Platform and will stop supporting On-Premise API in October 2025.

POST https://waba.360dialog.io/v1/messages

You can send a message using the /v1/messages endpoint.

Headers

Name
Type
Description

D360-API-KEY

string

360dialog API KEY

{
    "messages": [
        {
            "id": "x"
        }
    ],
    "meta": {
        "api_status": "stable",
        "version": "2.35.4"
    }
}

The sample below shows multiple different objects such as audio, document, image, sticker, and video for illustration purposes only. A valid request body contains only one of them.

Example:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "audio" | "contact" | "document" | "image" | "location" | "sticker" | "text" | "video",
  
  "audio": {
    "id": "your-media-id",
  }
  
  "document": {
    "id": "your-media-id",
    "caption": "your-document-caption-to-be-sent",
    "filename": "your-document-filename"
  }
  
  "document": {
    "link": "the-provider-name/protocol://the-url",
    "provider": {
        "name" : "provider-name"
    },
    "caption": "your-document-caption"
  }
  
  "document": {
    "link": "http(s)://the-url.pdf",
    "caption": "your-document-caption"
  }
  
  "video": {
    "id": "your-media-id",
    "caption": "your-video-caption"    
  }
  
  "image": {
    "link": "http(s)://the-url",
    "provider": {
        "name" : "provider-name"
    },
    "caption": "your-image-caption"
  }
  
  "image": {
    "id": "your-media-id",
    "caption": "your-image-caption"
  }
  
  "sticker": {
    "id": "your-media-id"
  }
  
  "sticker": {
    "link": "http(s)://the-url",
    "provider": {
      "name" : "provider-name"
    }
  }
}

Starting from On-Premise client v2.53, all new feature updates will be exclusively delivered to Cloud API. While the On-Premise API client will receive quarterly releases, they will focus solely on bug fixes and security patches. From May 15, 2024, 360dialog will not allow for new numbers to be onboarded with On-Premise API. We will continue supporting already registered On-Premise API throughout 2024, but we strongly recommend to of numbers to Cloud as soon as possible. .

change of hosting type
sending a Template message
upload the media
start changing the hosting type
Learn here how to integrate with Cloud API