If you're building a WhatsApp flow using a PhotoPicker component and see this error:

INVALID_ON_CLICK_ACTION_PAYLOAD

In the complete action payload, PhotoPicker can only be used if the value of the 'max-uploaded-photos' property doesn't exceed 1.

Or:

PhotoPicker’s 'max-uploaded-photos' property value has to be 1 to be used in top level of on-click-action payload

It means you're trying to use a PhotoPicker in the complete action’s payload, but the configuration doesn’t meet the platform’s strict requirements.

What’s Causing This?

The issue happens when:

  • You're using PhotoPicker in a screen.

  • You're referencing the selected photo(s) directly in the complete action payload.

  • But the max-uploaded-photos property is either not set, or set to more than 1.

WhatsApp Flows only allow the PhotoPicker to be used in this way if it restricts users to uploading a single photo.

Example of the Problem

{
  "children": [
    {
      "type": "PhotoPicker",
      "name": "photo",
      "label": "PASS_CUSTOM_VALUE"
    },
    {
      "type": "Footer",
      "label": "PASS_CUSTOM_VALUE",
      "on-click-action": {
        "name": "complete",
        "payload": {
          "photo": "${screen.FIRST_SCREEN.form.photo}"
        }
      }
    }
  ]
}

Now, the component is restricted to a single image, which satisfies the condition for using the photo value in the payload.

This error is about platform limits on file uploads: if you're collecting more than one photo, you cannot send it in the complete action's payload directly and if you need to include a photo in the payload, set max-uploaded-photos to 1.

This ensures that data passed to the backend or automation flow is clearly structured and limited to a single file, preventing any ambiguity or processing issues.

For more troubleshooting insights related to WhatsApp Business API, check out heltar.com/blogs.