Template media headers

When creating or editing a template with a media header (IMAGE, VIDEO, GIF, DOCUMENT), you have four mutually exclusive modes to provide the media. They apply only to non-TEXT headers.

The four modes

Mode	Description	Use case
`url`	Public https URL of the media	The file is already hosted
`base64`	Media base64-encoded in the body	You have the file bytes
`handler`	Existing Meta handler (`4::...`)	You already uploaded the media before
`file`	Multipart with a binary `file` part	Direct upload from the client

header_source and header_handle are mutually exclusive. If you send both, the API returns 400 with header_source and header_handle are mutually exclusive for media headers.

url mode

{
  "name": "test_img",
  "language": "es",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": {
        "header_source": {
          "mode": "url",
          "value": "https://cdn.example.com/banner.jpg"
        }
      }
    },
    {
      "type": "BODY",
      "text": "Check out our new collection {{1}}.",
      "example": { "body_text": [["Spring"]] }
    }
  ]
}

base64 mode

{
  "type": "HEADER",
  "format": "IMAGE",
  "example": {
    "header_source": {
      "mode": "base64",
      "value": "/9j/4AAQSkZJRgABAQAAAQABAAD/..."
    }
  }
}

handler mode

{
  "type": "HEADER",
  "format": "IMAGE",
  "example": {
    "header_source": {
      "mode": "handler",
      "value": "4::1234567890"
    }
  }
}

file mode (multipart)

The request must be multipart/form-data with two parts: template (JSON) and file (binary):

curl --request POST \
  --url 'https://api.chattigo.com/v1/templates/{did}' \
  --header 'Authorization: Bearer <token>' \
  -F 'template={
    "name": "test_img",
    "language": "es",
    "category": "MARKETING",
    "components": [{
      "type": "HEADER",
      "format": "IMAGE",
      "example": { "header_source": { "mode": "file" } }
    }]
  };type=application/json' \
  -F 'file=@/path/banner.jpg'

Validation rules

Rule	Detail
HTTPS required	`mode=url` with `http://` → `400`
No private IPs	`mode=url` pointing to a private/loopback IP → `400` (blocked for security)
Size limits	Each category has a configurable cap (`media.upload.max_bytes`)
TEXT header ignores `header_source`	If the header is TEXT, `header_source` is ignored
`file` requires multipart	`mode=file` with `application/json` → `400`
Missing parts	Multipart without `template` or without `file` part → `400`
Multipart bomb	`file` part exceeding the cap → `413`
GIF	Marketing Messages API only, MP4, max 3.5MB

Media categories and sizes

Format	Max size	MIME
IMAGE	per category (configurable)	`image/*`
VIDEO	per category (configurable)	`video/*`
DOCUMENT	per category (configurable)	`application/*`
GIF	3.5MB	`video/mp4` (Marketing Messages API)

Error format Webhooks