WhatsApp template image header — format, size and how to add one

A WhatsApp template can show a picture above the message text: a product shot, a boarding-pass banner, a sale graphic. The picture is part of what Meta reviews. This guide covers what the picture must be, the ways to add it, and what to do when a send fails with header_image_missing.

SendFromChat is an independent product and is not affiliated with Meta or WhatsApp. Sizes and formats for SendFromChat come from our templates docs and REST API docs. Meta can change its own rules, so check Meta's documentation before you ship.

The code below was not run against a live key. We ran it only against a mock fetch to check the request shapes, so try it with your own account first.

The short version

• Use a JPG or PNG. Meta reviews the picture together with the rest of the template.
• Size limits depend on how the file gets to us: up to 4 MB from the dashboard or a chat upload link, up to 5 MB from a public https:// link or POST /media.
• Link to the image file itself. A Google Drive or Dropbox share link opens a web page, not the image, so it usually fails.
• Once the template is approved, every message sent from it includes the picture automatically. Your send call passes nothing extra.
• If we don't have the picture, the send returns header_image_missing.

1. What the picture has to be

Rule	Value
Format	JPG or PNG
Dashboard upload	up to 4 MB
Chat upload link	up to 4 MB
Public https:// link	up to 5 MB
POST /media upload	JPEG or PNG, up to 5 MB

The image is reviewed with the rest of the template. Our template approval rules guide covers the text side.

2. Pick a route

Dashboard. In Templates → New template, set Header to Image and choose a file.

From a chat (Claude, ChatGPT). Ask for a template with an image. A file attached to a chat can't reach our MCP tool, so the assistant calls get_template_image_upload_link and gives you a private link. Open it on any device, choose the file and tell the assistant it's done. The link works once and lasts 30 minutes. You can also give the assistant a public https:// link straight to the image.

Claude Code. It gets the same link and can upload the file from your computer itself.

Your own app. Upload the file with POST /media, then pass the returned id as headerImageId to the create_template MCP tool. Section 3 shows the upload.

3. Upload the picture from your own code

POST /media needs a live key. You tell us the file name, type and size, we answer 201 with an id and an uploadUrl, and you PUT the bytes to that URL within two hours with the same Content-Type.

import { readFile } from "node:fs/promises";

const API = "https://sendfromchat.com/api/v1";
const KEY = process.env.SENDFROMCHAT_LIVE_KEY; // sfc_live_… keep it on the server

export async function uploadTemplateImage(path, contentType) {
  if (!["image/jpeg", "image/png"].includes(contentType)) {
    throw new Error("Template pictures must be JPG or PNG");
  }
  const bytes = await readFile(path);
  if (bytes.length > 5 * 1024 * 1024) {
    throw new Error("Picture is over the 5 MB upload limit");
  }

  // 1. Ask for an upload slot
  const slot = await fetch(`${API}/media`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      filename: path.split("/").pop(),
      contentType,
      size: bytes.length,
    }),
  });
  if (slot.status !== 201) {
    throw new Error(`Upload slot failed: ${slot.status} ${await slot.text()}`);
  }
  const { id, uploadUrl } = await slot.json();

  // 2. PUT the bytes within two hours, same Content-Type
  const put = await fetch(uploadUrl, {
    method: "PUT",
    headers: { "Content-Type": contentType },
    body: bytes,
  });
  if (!put.ok) throw new Error(`Upload failed: ${put.status}`);

  return id; // pass this as headerImageId
}

Then hand the id to create_template. In Claude Code, or any assistant connected to the SendFromChat MCP server, say it in words: "Create the template order_shipped with the header image <id>." Per our docs, create_template is an MCP tool, not a REST endpoint, so the REST API does not create templates for you.

4. Sending from the template

Nothing about the picture goes in the send call. An approved template with an image header sends with its picture automatically. Check which templates you can send with GET /templates?status=approved.

Common problems

Symptom	Likely cause	Fix
Link from Google Drive or Dropbox is not accepted	The share link opens a web page, not the image	Upload the file instead, or host it at a direct https:// link to the image file
File rejected	Not a JPG or PNG, or over the size limit	Export as JPG or PNG; stay under 4 MB (dashboard, chat link) or 5 MB (public link, POST /media)
Chat upload link says it has expired	It works once and lasts 30 minutes	Ask the assistant for a new link
Attached the picture to the chat, template has no image	A file attached to a chat can't reach the tool	Use the upload link, or a public https:// link to the image
Send returns header_image_missing	We don't have the picture, for example a template made in WhatsApp Manager without a usable sample	Create the template through SendFromChat with the image, or use a template that has one
Template rejected	Meta reviews the picture with the text	Read the reason Meta gives, fix it and submit again

header_image_missing comes back with status 422, with the other errors that come from WhatsApp's rules (see the REST API docs).

Data and your customers

SendFromChat stores data in Mumbai, India. Transfers from the EU and UK are covered by the Standard Contractual Clauses and the UK Addendum in our Data Processing Agreement, and the sub-processors are listed publicly. Read it before you decide. This is not legal advice.

Try it

Connect a number, make one template with a picture and send it to yourself first.

Connect your number (30-day free trial, no card).