Skip to main content

Title: Meta Instant Forms: contextCard.coverPhoto is mapped incorrectly and causes form creation to fail

Hello Zernio team,

We found what appears to be an issue with the coverPhoto support for Meta Instant Forms.

According to the Zernio changelog and SDK, contextCard.coverPhoto is supported when creating a Meta Lead Form. However, when we send a form with a cover image, Zernio converts it into:

context_card.cover_photo

Meta then rejects the request with:

Invalid keys "cover_photo" were found in param "context_card".

The full platform error is:

type: OAuthException
code: 100
message: Invalid keys "cover_photo" were found in param "context_card".

We also verified the image upload separately.

The image is successfully uploaded through /v1/ads/images and we receive:

  • a valid Meta Ad Image hash

  • a Meta-hosted image URL

  • an AdImage node ID

So the issue does not appear to be the image upload itself.

The main problem seems to be the mapping of Zernio's public contextCard.coverPhoto field to Meta's Lead Form API.

From our testing, Meta expects the cover image to be handled as the form-level cover_photo parameter during form creation, while context_card.cover_photo is not accepted as a writable field in this request.

At the moment, this means that any Instant Form created through Zernio with a cover image fails completely.

This is important for our use case because we are building an automated Meta advertising platform for Chinese factories. Many of our factory customers need to create complete Instant Forms directly inside our platform, including:

  • cover image

  • introduction/context card

  • questions

  • privacy policy

  • thank-you page

  • lead follow-up

We are trying to avoid requiring factory users to open Meta Ads Manager and manually create or edit forms, since many of them are not familiar with Meta's advertising tools.

Could you please confirm whether this is a Zernio mapping issue and update the Meta Lead Form integration so that contextCard.coverPhoto is sent using the correct Meta form creation parameter?

We have a minimal reproducible example including the sanitized request payload and full Meta platformError, and we can provide it if needed.

Thanks!

Status: Completed1 comment

Log in to comment and vote

Comments1

  • Miquel Palet López

    Team•

    Sep 8

    The cover-image correction is deployed and verified end to end against Meta.

    Send a direct, publicly reachable JPEG or PNG URL, up to 5 MB, in platformSpecificData.contextCard.coverPhoto when creating the form. Zernio uploads it as an unpublished Page photo and attaches its ID through the supported context_card.cover_photo_id field. Use an image URL, not an Ad Image hash or node ID. The legacy top-level contextCard.coverPhoto shape remains accepted when platformSpecificData is absent.

    Reference: https://docs.zernio.com/lead-gen/create-lead-form