imageAspectRatio ("square") passthrough on the Facebook generic template

Request: expose Meta's payload-level image_aspect_ratio on the generic template, so Messenger carousel cards can render square images.

Where: in sendInboxMessage (POST /v1/inbox/conversations/{conversationId}/messages), the template object exposes only type and elements - the field would sit between them. Same for CommentAutomationTemplate (it is $ref'd from six operations, so one addition covers all). Checked against docs.zernio.com/api/openapi v1.0.4, sha256 6156f87a..., retrieved 2026-08-27: neither image_aspect_ratio nor imageAspectRatio appears anywhere in the spec.

Meta's definition, a sibling of template_type and elements:

"image_aspect_ratio - String - Optional. The aspect ratio used to render images specified by element.image_url. Must be horizontal (1.91:1) or square (1:1). Defaults to horizontal."

Source (Generic Template reference, before it was folded into the send-messages guide): https://web.archive.org/web/20220704043927/https://developers.facebook.com/docs/messenger-platform/reference/templates/generic/

Still documented today under "Message Attachment Object Reference": https://developers.facebook.com/docs/messenger-platform/marketing-messages

What we observe: sending image_aspect_ratio or imageAspectRatio inside template is accepted - no 400, no warning - but the card still renders horizontal, so the key appears to be dropped in the camelCase to snake_case mapping. That matches the schema, which does not set additionalProperties: false. So this looks like a missing mapping line rather than a validation bug.

Why it matters to us: we sell physical products in Mongolia through Messenger carousels, and our product photography is square. At the 500px card width we measured, a 1.91:1 card shows the photo at 500x261 and a 1:1 card at 500x500 - roughly 1.9x the image area. Meta's current generic-template page says under Best practices: "Use the correct aspect ratio for your image. Messenger scales or crops photos in the generic template that are not 1.91:1." Today every product shot we send is letterboxed.

Before and after:

{ "template": { "type": "generic", "elements": [...] } }

{ "template": { "type": "generic", "imageAspectRatio": "square", "elements": [...] } }

mapping to image_aspect_ratio at payload level, lowercase, not inside each element.

Scope: Facebook only. Meta's Instagram generic template documents just template_type and elements - no image_aspect_ratio, and no sharable either - so the field can simply be ignored on Instagram, the way linkPreview and voiceNote are WhatsApp-only in your spec today.

Support confirmed on 2026-08-28 that the key is accepted and then dropped before the Meta payload is built, and that there is no workaround today. Happy to test a build against a live Page.