Add Reel Facebook crosspost payload helper (#2478)

Author: subzeroid

.github/workflows/live-account-tests.yml

@@ -49,7 +49,8 @@ jobs:
         run: |
           pytest -sv \
             tests/live/test_upload.py::ClientFeedMusicUploadLiveTestCase \
-            tests/live/test_upload.py::ClientTrialReelUploadLiveTestCase
+            tests/live/test_upload.py::ClientTrialReelUploadLiveTestCase \
+            tests/live/test_upload.py::ClientFacebookReelCrosspostLiveTestCase
 
       - name: Run direct media test
         if: github.event.inputs.test_target == 'direct' || github.event.inputs.test_target == 'all'

docs/usage-guide/media.md

@@ -308,9 +308,11 @@ Upload medias to your feed. Common arguments:
 | video_upload(path: Path, caption: str, thumbnail: Path, usertags: List[Usertag], location: Location, extra_data: Dict = {})            | Media   | Upload video (Support MP4 files)
 | album_upload(paths: List[Path], caption: str, usertags: List[Usertag], location: Location, extra_data: Dict = {})                      | Media   | Upload Album (Support JPG/MP4 files)
 | igtv_upload(path: Path, title: str, caption: str, thumbnail: Path, usertags: List[Usertag], location: Location, extra_data: Dict = {}) | Media   | Upload IGTV (Support MP4 files)
-| clip_upload(path: Path, caption: str, thumbnail: Path, usertags: List[Usertag], location: Location, extra_data: Dict = {}, trial: bool = False, trial_graduation_strategy: str = "manual") | Media | Upload Reels Clip (Support MP4 files). Set `trial=True` to publish a Trial Reel on eligible accounts
+| clip_upload(path: Path, caption: str, thumbnail: Path, usertags: List[Usertag], location: Location, extra_data: Dict = {}, trial: bool = False, trial_graduation_strategy: str = "manual", share_to_facebook: bool = False) | Media | Upload Reels Clip (Support MP4 files). Set `trial=True` to publish a Trial Reel on eligible accounts. Set `share_to_facebook=True` to cross-post to a linked Facebook destination
 | clip_trial_eligible() | bool | Check whether Reel creation preflight reports Trial Reels enabled before uploading video bytes
 | clip_info_for_creation() | dict | Get Reel creation preflight configuration from the mobile API
+| clip_share_to_fb_config() | dict | Get Reel Facebook sharing configuration from the mobile API
+| clip_share_to_fb_extra_data(config: Dict = None, destination_id: str = None, destination_type: str = None) | dict | Build modern Reel Facebook cross-post configure fields for manual `extra_data`
 | clip_upload_as_reel_with_music(path: Path, caption: str, track: Track, extra_data: Dict = {}) | Media | Upload Reels Clip as reel with music metadata
 | photo_upload_with_music(path: Path, caption: str, track: Track or dict, extra_data: Dict = {}) | Media | Upload feed photo with music metadata
 | album_upload_with_music(paths: List[Path], caption: str, track: Track or dict, extra_data: Dict = {}) | Media | Upload feed album/carousel with music metadata
@@ -333,6 +335,13 @@ Reel composer does not report Trial Reels enabled. Instagram can still reject Tr
 configure, so keep upload-side error handling for backend eligibility decisions. When `trial=True`, `clip_upload` sends
 `trial_params={"graduation_strategy": "manual"}` by default and disables feed preview for the upload.
 
+Facebook Reel sharing requires a Facebook account/page linked in the Instagram app. Modern Android app builds no longer
+use only `{"share_to_facebook": 1}` for Reels; they also send destination and cross-posting fields. Use
+`clip_upload(..., share_to_facebook=True)` to fetch `clip_share_to_fb_config()` and build the configure payload before
+video bytes are uploaded. If the account is not linked or Instagram does not return a Reel Facebook destination,
+instagrapi raises `ClientError` before upload. Advanced callers can pass `fb_destination_id` and `fb_destination_type`,
+or build `extra_data` manually with `clip_share_to_fb_extra_data(...)`.
+
 ### Example:
 
 ``` python
@@ -348,6 +357,22 @@ configure, so keep upload-side error handling for backend eligibility decisions.
 ...         trial=True,
 ...     )
 
+>>> reel = cl.clip_upload(
+...     "/app/reel.mp4",
+...     "Cross-posting this Reel to Facebook",
+...     share_to_facebook=True,
+... )
+
+>>> fb_extra = cl.clip_share_to_fb_extra_data(
+...     destination_id="FACEBOOK_DESTINATION_ID",
+...     destination_type="DESTINATION_TYPE_FROM_APP_CONFIG",
+... )
+>>> reel = cl.clip_upload(
+...     "/app/reel.mp4",
+...     "Cross-posting with explicit Facebook destination",
+...     extra_data=fb_extra,
+... )
+
 >>> media = cl.photo_upload(
     "/app/image.jpg",
     "Test caption for photo with #hashtags and mention users such @example",

instagrapi/mixins/clip.py

@@ -184,6 +184,95 @@ def clip_share_to_fb_config(self, device_status: Optional[Dict[str, object]] = N
             params={"device_status": json.dumps(device_status)},
         )
 
+    def clip_share_to_fb_extra_data(
+        self,
+        config: Optional[Dict[str, object]] = None,
+        destination_id: Optional[str] = None,
+        destination_type: Optional[str] = None,
+        destination_audience_type: Optional[str] = None,
+        xpost_surface: str = "IG_REELS_COMPOSER",
+        validation_check_bypass: Optional[bool] = None,
+    ) -> Dict[str, object]:
+        """
+        Build configure fields for sharing a Reel to Facebook.
+
+        Instagram Android 428 stores Reel Facebook cross-posting in
+        ``XPlatformParams`` fields. The old ``share_to_facebook`` flag alone is
+        not enough for accounts that require an explicit Facebook destination.
+
+        Parameters
+        ----------
+        config: Dict[str, object], optional
+            Response from ``clip_share_to_fb_config()``. When omitted, this
+            method fetches it.
+        destination_id: str, optional
+            Facebook destination id. Overrides config values.
+        destination_type: str, optional
+            Facebook destination type/posting type. Overrides config values.
+        destination_audience_type: str, optional
+            Facebook Reels audience type, e.g. ``PUBLIC``.
+        xpost_surface: str, optional
+            Cross-posting surface reported by the Instagram app.
+        validation_check_bypass: bool, optional
+            Whether to bypass app-side FB validation. Overrides config values.
+
+        Returns
+        -------
+        Dict
+            Extra configure data for ``clip_upload(..., extra_data=...)``.
+        """
+        fb_config = (config if config is not None else self.clip_share_to_fb_config()) or {}
+        if fb_config.get("share_to_fb_unavailable"):
+            raise ClientError("Facebook Reel sharing is unavailable for this account")
+        if fb_config.get("enabled") is False or fb_config.get("is_account_linked") is False:
+            raise ClientError("Facebook Reel sharing is not enabled or no Facebook account is linked")
+
+        destination_id = (
+            destination_id
+            or fb_config.get("share_to_fb_destination_id")
+            or fb_config.get("reels_destination_id")
+            or fb_config.get("destination_id")
+        )
+        destination_type = (
+            destination_type
+            or fb_config.get("share_to_fb_destination_type")
+            or fb_config.get("reels_cross_app_share_type")
+            or fb_config.get("posting_type")
+        )
+        destination_audience_type = (
+            destination_audience_type
+            or fb_config.get("share_to_fb_destination_audience_type")
+            or fb_config.get("reels_destination_audience_type")
+            or fb_config.get("audience_type")
+        )
+        if validation_check_bypass is None:
+            validation_check_bypass = fb_config.get("reels_cross_app_share_fb_validation_check_bypass")
+
+        if not destination_id:
+            raise ClientError(
+                "Facebook Reel sharing configuration has no destination. "
+                "Link a Facebook account/page in the Instagram app or pass destination_id."
+            )
+        if not destination_type:
+            raise ClientError(
+                "Facebook Reel sharing configuration has no destination type. "
+                "Pass destination_type from a linked-account app capture."
+            )
+
+        data = {
+            "share_to_facebook": "1",
+            "is_reel_shared_to_fb": True,
+            "share_to_facebook_reels": True,
+            "share_to_fb_destination_id": destination_id,
+            "share_to_fb_destination_type": destination_type,
+            "xpost_surface": xpost_surface,
+        }
+        if destination_audience_type:
+            data["share_to_fb_destination_audience_type"] = destination_audience_type
+        if validation_check_bypass is not None:
+            data["cross_app_share_fb_validation_check_bypass"] = bool(validation_check_bypass)
+        return data
+
     def clip_upload(
         self,
         path: Path,
@@ -196,6 +285,12 @@ def clip_upload(
         extra_data: Dict[str, object] = {},
         trial: bool = False,
         trial_graduation_strategy: str = "manual",
+        share_to_facebook: bool = False,
+        fb_destination_id: Optional[str] = None,
+        fb_destination_type: Optional[str] = None,
+        fb_destination_audience_type: Optional[str] = None,
+        fb_xpost_surface: str = "IG_REELS_COMPOSER",
+        fb_validation_check_bypass: Optional[bool] = None,
     ) -> Media:
         """
         Upload CLIP to Instagram
@@ -220,11 +315,23 @@ def clip_upload(
             Forced to "0" for Trial Reels.
         extra_data: Dict[str, object], optional
             Dict of extra data, if you need to add your params,
-            like {"share_to_facebook": 1}.
+            like {"disable_comments": 1}.
         trial: bool, optional
             Upload as a Trial Reel for eligible accounts, default is False.
         trial_graduation_strategy: str, optional
             Trial Reel graduation strategy, default is "manual".
+        share_to_facebook: bool, optional
+            Share this Reel to a linked Facebook account/page, default is False.
+        fb_destination_id: str, optional
+            Facebook destination id used when share_to_facebook is True.
+        fb_destination_type: str, optional
+            Facebook destination type used when share_to_facebook is True.
+        fb_destination_audience_type: str, optional
+            Facebook Reels audience type, e.g. ``PUBLIC``.
+        fb_xpost_surface: str, optional
+            Cross-posting surface reported by the Instagram app.
+        fb_validation_check_bypass: bool, optional
+            Override the validation bypass value from share_to_fb_config.
 
         Returns
         -------
@@ -240,6 +347,15 @@ def clip_upload(
             clip_data = fp.read()
             clip_len = str(len(clip_data))
         configure_extra_data = dict(extra_data or {})
+        if share_to_facebook:
+            fb_extra_data = self.clip_share_to_fb_extra_data(
+                destination_id=fb_destination_id,
+                destination_type=fb_destination_type,
+                destination_audience_type=fb_destination_audience_type,
+                xpost_surface=fb_xpost_surface,
+                validation_check_bypass=fb_validation_check_bypass,
+            )
+            configure_extra_data = {**fb_extra_data, **configure_extra_data}
         if trial:
             feed_show = "0"
             configure_extra_data.setdefault(
@@ -439,7 +555,7 @@ def clip_upload_as_reel_with_music(
             use cl.search_music(title)[0].dict()
 
         extra_data: Dict[str, object], optional
-            Dict of extra data, if you need to add your params, like {"share_to_facebook": 1}.
+            Dict of extra data, if you need to add your params, like {"disable_comments": 1}.
 
         Returns
         -------
@@ -549,7 +665,7 @@ def clip_configure(
         location: Location, optional
             Location tag for this upload, default is None
         extra_data: Dict[str, object], optional
-            Dict of extra data, if you need to add your params, like {"share_to_facebook": 1}.
+            Dict of extra data, if you need to add your params, like {"disable_comments": 1}.
 
         Returns
         -------

tests/live/test_upload.py

@@ -348,3 +348,32 @@ def test_clip_upload_trial_live(self):
         if checked:
             self.skipTest(f"Instagram rejected {rejected}/{checked} clip_trial_eligible accounts for trial Clips")
         self.skipTest("No fresh account has Trial Reels enabled")
+
+
+class ClientFacebookReelCrosspostLiveTestCase(_helpers.ClientPrivateTestCase):
+    def __init__(self, *args, **kwargs):
+        self.cl = None
+        return unittest.TestCase.__init__(self, *args, **kwargs)
+
+    def setUp(self):
+        if not TEST_ACCOUNTS_URL:
+            self.skipTest("TEST_ACCOUNTS_URL is required for Reel Facebook crosspost live tests")
+        try:
+            self.cl = self.fresh_account()
+        except RuntimeError as exc:
+            self.skipTest(str(exc))
+
+    def test_clip_share_to_fb_extra_data_live(self):
+        config = self.cl.clip_share_to_fb_config()
+        self.assertEqual(config.get("status"), "ok")
+        try:
+            extra_data = self.cl.clip_share_to_fb_extra_data(config=config)
+        except ClientError as exc:
+            self.skipTest(f"No linked Facebook Reel destination available: {exc}")
+
+        self.assertEqual(extra_data["share_to_facebook"], "1")
+        self.assertTrue(extra_data["share_to_facebook_reels"])
+        self.assertTrue(extra_data["is_reel_shared_to_fb"])
+        self.assertTrue(extra_data["share_to_fb_destination_id"])
+        self.assertTrue(extra_data["share_to_fb_destination_type"])
+        self.assertEqual(extra_data["xpost_surface"], "IG_REELS_COMPOSER")

tests/regression/test_upload.py

@@ -78,6 +78,47 @@ def test_clip_share_to_fb_config_requests_reel_facebook_config(self):
         self.assertFalse(device_status["hw_av1_dec"])
         self.assertEqual(result, expected)
 
+    def test_clip_share_to_fb_extra_data_builds_current_reel_crosspost_payload(self):
+        client = self.build_client()
+        config = {
+            "enabled": True,
+            "is_account_linked": True,
+            "reels_share_to_facebook": True,
+            "reels_destination_id": "fb-destination-id",
+            "reels_cross_app_share_type": "2",
+            "reels_cross_app_share_fb_validation_check_bypass": True,
+            "status": "ok",
+        }
+
+        result = client.clip_share_to_fb_extra_data(config=config)
+
+        self.assertEqual(
+            result,
+            {
+                "share_to_facebook": "1",
+                "is_reel_shared_to_fb": True,
+                "share_to_facebook_reels": True,
+                "share_to_fb_destination_id": "fb-destination-id",
+                "share_to_fb_destination_type": "2",
+                "cross_app_share_fb_validation_check_bypass": True,
+                "xpost_surface": "IG_REELS_COMPOSER",
+            },
+        )
+
+    def test_clip_share_to_fb_extra_data_raises_without_destination(self):
+        client = self.build_client()
+
+        with self.assertRaises(ClientError) as ctx:
+            client.clip_share_to_fb_extra_data(
+                config={
+                    "enabled": True,
+                    "default_share_to_fb_enabled": False,
+                    "status": "ok",
+                }
+            )
+
+        self.assertIn("Facebook Reel sharing configuration has no destination", str(ctx.exception))
+
     def test_clip_info_for_creation_requests_reel_creation_config(self):
         client = self.build_client()
         expected = {
@@ -490,6 +531,56 @@ def test_clip_upload_trial_preserves_explicit_trial_params(self):
             },
         )
 
+    def test_clip_upload_share_to_facebook_adds_crosspost_params_before_upload(self):
+        client = self.build_client()
+        client.last_json = {"media": self.build_media_payload()}
+        ok_response = Mock(status_code=200)
+        extra_data = {"disable_comments": "1"}
+        fb_extra = {
+            "share_to_facebook": "1",
+            "is_reel_shared_to_fb": True,
+            "share_to_facebook_reels": True,
+            "share_to_fb_destination_id": "fb-destination-id",
+            "share_to_fb_destination_type": "2",
+            "cross_app_share_fb_validation_check_bypass": False,
+            "xpost_surface": "IG_REELS_COMPOSER",
+        }
+
+        with mock.patch.object(client, "clip_share_to_fb_extra_data", return_value=fb_extra) as share_to_fb_extra:
+            with mock.patch(
+                "instagrapi.mixins.clip.analyze_video",
+                return_value=(Path("/tmp/thumb.jpg"), 720, 1280, 6.023),
+            ) as analyze_video:
+                with mock.patch.object(client.private, "get", return_value=ok_response):
+                    with mock.patch.object(
+                        client.private,
+                        "post",
+                        side_effect=[ok_response, ok_response],
+                    ):
+                        with mock.patch.object(
+                            client, "clip_configure", return_value={"status": "ok"}
+                        ) as clip_configure:
+                            with mock.patch(
+                                "builtins.open",
+                                mock.mock_open(read_data=b"video-bytes"),
+                            ):
+                                with mock.patch("time.sleep"):
+                                    client.clip_upload(
+                                        Path("example.mp4"),
+                                        "caption",
+                                        share_to_facebook=True,
+                                        extra_data=extra_data,
+                                    )
+
+        share_to_fb_extra.assert_called_once()
+        analyze_video.assert_called_once()
+        self.assertEqual(extra_data, {"disable_comments": "1"})
+        configure_extra = clip_configure.call_args.kwargs["extra_data"]
+        self.assertEqual(configure_extra["disable_comments"], "1")
+        self.assertEqual(configure_extra["share_to_fb_destination_id"], "fb-destination-id")
+        self.assertTrue(configure_extra["share_to_facebook_reels"])
+        self.assertEqual(configure_extra["xpost_surface"], "IG_REELS_COMPOSER")
+
     def test_video_story_upload_raises_clear_error_when_configure_has_no_media(self):
         client = self.build_client()