Rich Media Content Specification

For WhatsApp, rich media content can be used to create visually appealing and interactive messages that can capture the attention of the recipient.

Table of Contents

• Overview
• Type of Rich Media Content
  • Image
  • Audio
  • Video
  • Document
  • Sticker
• Failure Conditions

Overview

Rich media content refers to interactive digital media that uses a combination of text, images, videos, audio and other multimedia elements to provide a more engaging and immersive user experience.

Media of different type, viz. document, audio, video, image are defined as given JSON Structure below. These definitions are in define components with Rich Media. If media type is set to any of the rich-media type, then related JSON Object must be use.

Type of Rich Media Contents

Following type of Rich Media Contents are supported to be sent over WhatsApp Business Platform:

• Image
• Audio
• Video
• Document
• Sticker

The following section discusses specification of each type of media and how they are used while sending message and creating templates.

Rich Media Type: Image

Imagery contents are sent over WhatsApp. Image files are referred in JSON Payload with a publicly accessibly URL hosted over https. Media type is written as “image“.

Specification

• Supported Formats: image/jpeg, image/png. Images must be 8-bit, RGB or RGBA
• Size Limit: 5 MB.

JSON Payload Example: To send message with image

{
  "type": "image",
  "image": {
    "caption": "{caption}",
    "link": "{public image url}"
  }
}

Payload explanation

JSON Payload Example: To send message using a template defined with Image in header component

{
  "template": {
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "{public image url}",
              "caption": "{caption}"
            }
          }
        ]
      }
    ]
  }
}

Payload explanation

Rich Media Type: Audio

Audio contents are sent over WhatsApp. Audio files are referred in JSON Payload with a publicly accessibly URL hosted over https. Media type is written as “audio“.

Specification

• Supported Formats: audio/aac, audio/mp4, audio/mpeg, audio/amr, audio/ogg
• Unsupported Formats: Opus codecs, base audio/ogg
• Size Limit: 16 MB.

JSON Payload Example: To send message with audio

{
  "type": "audio",
  "audio": {
    "link": "{public audio file url}"
  }
}

Payload explanation

JSON Payload Example: To send message using a template defined with Audio in header component

{
  "template": {
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "audio",
            "audio": {
              "link": "{public media url}",
              "filename": "{name of the file}"
            }
          }
        ]
      }
    ]
  }
}

Payload explanation

Rich Media Type: Video

Video contents are sent over WhatsApp. Video files are referred in JSON Payload with a publicly accessibly URL hosted over https. Media type is written as “video“.

Specification

• Supported Formats: video/mp4, video/3gp. Videos with a single audio stream or no audio stream
• Unsupported Formats: Only H.264 video codec and AAC audio codec is supported
• Size Limit: 16 MB.

JSON Payload Example: To send message with video

{
  "type": "video",
  "video": {
    "caption": "{caption}",
    "link": "{public video file url}"
  }
}

Payload explanation

JSON Payload Example: To send message using a template defined with Video in header component

{
  "template": {
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "video",
            "video": {
              "link": "{public media url}",
              "filename": "{name of the file}",
	      "caption": "{caption}"
            }
          }
        ]
      }
    ]
  }
}

Payload explanation

Rich Media Type: Document

Documents are sent over WhatsApp. Document files are referred in JSON Payload with a publicly accessibly URL hosted over https. Media type is written as “document“.

Specification

• Supported Formats: text/plain, application/pdf, application/vnd.ms-powerpoint, application/msword, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.openxmlformats-officedocument.presentationml.presentation, application/vnd.openxmlformats-officedocument.spreadsheetml.shee
• Size Limit: 100 MB.

JSON Payload Example: To send message with document

{
  "type": "document",
  "document": {
    "link": "{public document file url}",
    "caption": "{caption}",
    "filename": "wds"
  }
}

Payload explanation

JSON Payload Example: To send message using a template defined with Document in header component

{
  "template": {
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "document",
            "document": {
              "link": "{public document url}",
              "filename": "{name of the file}",
	      "caption": "{caption}"
            }
          }
        ]
      }
    ]
  }
}

Payload explanation

{
  "type": "sticker",
  "sticker": {
    "link": "{public sticker file url}"
  }
}

Failure Conditions

In case you try to send a Rich Media Content that doesn’t comply to the specification, message will be accepted for processing but it will fail to deliver. In such cases, you get failure notifications posted to your Webhook.

JSON Example: For message failure with Rich Media

{
  "statuses": [
    {
      "id": "{message id}",
      "recipient_id": "{recipient phone}",
      "status": "failed",
      "timestamp": "{unix timestamp}",
      "type": "message",
      "errors": [
        {
          "code": 131053,
          "title": "Image file has size 15483160 bytes but must be atmost 5242880 bytes and non-empty"
        }
      ] 
    }
  ],
  "business_phone": "{business phone}"
}

Notification Payload Explanation