fix(instagram-facebook): send private replies via the page node again (#1122)

sendPrivateReplyMessage posted to `{igId}/messages`, which Meta rejects with
`(#3) Application does not have the capability to make this API call.` even when
the app holds instagram_manage_messages, pages_messaging and Human Agent at
Advanced Access. For Instagram via Facebook Login the `messages` edge only
exists on the Page node, so every private reply on that channel failed: the
automation's `text` and `AIAgent` replies, the first message of a `flow` reply,
and the agent's manual private reply from the inbox.

This is the second time the fix has been needed. #875 moved the endpoint to
`pageId`, then #945 moved it back to green a stale test whose fixture carried no
`pageId` at all — so the endpoint silently became `/undefined/messages` and the
assertion on the IG node kept passing. The test is now the guard instead of the
cause: the fixture carries a `pageId` distinct from `igId`, and a new case
asserts the IG node is never called.

Also guards a missing `pageId` explicitly rather than building
`/undefined/messages`, which is the silent failure mode that hid the regression.

Two adjacent error-mapping bugs surfaced while tracing this:

- Code 3 was in neither Instagram mapper, so it fell through to the
  `type === "OAuthException"` fallback and was reported as AUTH_FAILED —
  pointing operators at a reconnect that could never help. It is a capability
  problem, so it now maps to PERMISSION_DENIED (permanent), as messenger
  already does.
- instagram-facebook's isRevokedTokenError matched *any* OAuthException,
  including code 3, making the disconnect flow skip its remote teardown for
  unrelated errors. Narrowed to code 190 plus a revoked subcode, matching the
  Instagram Login variant, which excludes a bare 190 as ambiguous to avoid
  false-positive disconnects.

Unrelated, found in the same log: the getProfile failure in received-message.ts
logged under `error`, so pino dropped the stack trace. Keyed to `err`.

Co-authored-by: Deathgiver <anonymous@users.noreply.github.com>

Author: sung17

.agents/skills/fb-comment-automation/SKILL.md

@@ -108,6 +108,22 @@ Read it before non-trivial changes. This skill is the quick map + the traps.
    instead of disappearing behind a `logger.warn`. Never "fix" that back into an empty
    `{ messageIds: [] }` return.
 
+10. **Instagram-via-Facebook private replies use the Page node, not the IG node.**
+    `sendPrivateReplyMessage` (`integrations/instagram-facebook/src/apis/comment.ts`) must
+    post to `/{pageId}/messages`. `/{igId}/messages` returns `(#3) Application does not
+    have the capability to make this API call.` even with `instagram_manage_messages`,
+    `pages_messaging` and Human Agent at Advanced Access — code 3 means "this edge does
+    not exist on this node", so it is NOT an App-dashboard problem. Already regressed
+    twice (#875 fixed it, #945 reverted it to green a stale test whose fixture had no
+    `pageId`, making the URL `/undefined/messages`). It breaks every private reply on the
+    channel: `text`, `AIAgent`, a `flow` reply's first message, and the agent's manual
+    inbox private reply (which enters via `handlers/comment/outgoing-private-reply`, not
+    the automation loop). Instagram Login is different on purpose — `me/messages` on
+    `graph.instagram.com`. Keep the `send-private-reply.test.ts` guard that asserts the IG
+    node is never called. Also note both Instagram packages log
+    `module=integration-instagram`, so attribute production failures by request host, not
+    module name.
+
 ## Adding a new filter option (recipe)
 
 1. Add the field to `fbCommentOptionsSchema` (partials) + DB default in the schema file

apps/worker/src/integration/handlers/comment-automation/private-reply.ts

@@ -52,8 +52,9 @@ export const PRIVATE_REPLY_TEXT_SENDERS: Record<
   instagram: (auth, commentId, text) =>
     sendInstagramLoginPrivateReply(auth as InstagramAuthValue, commentId, text),
   // Instagram via Facebook Login sends the private DM through the
-  // {igId}/messages endpoint (Page/Business-asset token), addressing the
-  // commenter by comment id.
+  // {pageId}/messages endpoint (Page access token), addressing the commenter
+  // by comment id — Meta exposes the `messages` edge only on the Page node for
+  // this login type; the IG node answers with error #3.
   instagramFacebook: (auth, commentId, text) =>
     sendInstagramFacebookPrivateReply(
       auth as InstagramFacebookAuthValue,

apps/worker/src/integration/handlers/received-message.ts

@@ -1524,7 +1524,11 @@ const createNewContactAndContactInbox = async (props: {
         }
       } catch (error) {
         logger.warn(
-          { error, sourceId: incomingContact.sourceId, channel: inbox.channel },
+          {
+            err: error,
+            sourceId: incomingContact.sourceId,
+            channel: inbox.channel,
+          },
           "detectContactAndConversation: getProfile failed, creating contact without profile data",
         )
         // No `contactId` — the contact does not exist yet at this point.

docs/fb-comment-automation.md

@@ -200,6 +200,31 @@ send), and the comment handler owns the channel routing.
   you add a new filter, add a skip log too — otherwise production debugging is blind
   (`processCommentAutomation` returns `void`, so BullMQ always records `returnValue: null`
   regardless of what happened).
+- **Instagram-via-Facebook private replies go through the Page node, never the IG node.**
+  `sendPrivateReplyMessage`
+  ([`integrations/instagram-facebook/src/apis/comment.ts`](../integrations/instagram-facebook/src/apis/comment.ts))
+  must post to `/{pageId}/messages`. Meta exposes the `messages` edge only on the Page for
+  this login type; `/{igId}/messages` is rejected with `(#3) Application does not have the
+  capability to make this API call.` even when the app holds `instagram_manage_messages`,
+  `pages_messaging` and Human Agent at **Advanced Access** — code 3 means "this edge does
+  not exist here", not "permission missing", so chasing it in the App dashboard is a dead
+  end. This has regressed twice ([#875](https://github.com/ChatbotXIO/ChatbotX/pull/875)
+  moved it to `pageId`; [#945](https://github.com/ChatbotXIO/ChatbotX/pull/945) moved it
+  back to satisfy a stale test whose fixture had no `pageId`, so the endpoint silently
+  became `/undefined/messages`). The blast radius is every private reply on that channel —
+  automation `text`, `AIAgent`, the first message of a `flow` reply, **and** the agent's
+  manual private reply from the inbox, which enters through
+  `handlers/comment/outgoing-private-reply` instead of the automation loop. The Instagram
+  Login variant is different on purpose: it posts to `me/messages` on
+  `graph.instagram.com`. `send-private-reply.test.ts` now pins the node and asserts the IG
+  node is never called — do not "simplify" that away.
+- **The two Instagram packages log under the same module name.** Both
+  `integrations/instagram/src/lib/logger.ts` and
+  `integrations/instagram-facebook/src/lib/logger.ts` call
+  `getChildLogger("integration-instagram")`, so `module=integration-instagram` in
+  production does **not** tell you which login type failed. Use the request host
+  (`graph.facebook.com` = via Facebook, `graph.instagram.com` = Instagram Login) or the
+  stack trace path instead.
 
 ## Testing
 

integrations/instagram-facebook/README.md

@@ -119,6 +119,14 @@ Each message is stamped with `metadata: "SENT_FROM_CHATBOTX"` so echo events can
 | `hideComment` | `POST /<version>/<commentId>?hide=true\|false` | |
 | `likeComment` | `POST /<version>/<igId>/likes` | Toggle via POST/DELETE |
 | `editComment` | — | No-op; Facebook API does not support editing comments |
+| `sendPrivateReply(Message)` | `POST /<version>/<pageId>/messages` | `recipient: { comment_id }`. **Page** node — see below |
+
+Messaging edges use the **Page** node (`<pageId>/messages`, `<pageId>/message_attachments`, `me/messages`);
+Instagram content edges use the **IG** node (`<igId>/media`, `<igId>/stories`, `<igId>/likes`). Posting a
+private reply to `<igId>/messages` fails with `(#3) Application does not have the capability to make this
+API call.` regardless of granted permissions, because Meta does not expose that edge on the IG node for
+Facebook-Login connections. The Instagram Login package (`integrations/instagram`) uses `me/messages` on
+`graph.instagram.com` instead.
 
 ---
 
@@ -128,16 +136,22 @@ All API errors are normalised by `mapToChannelError()` into a typed `ChannelErro
 
 | Category | Trigger |
 |---|---|
-| `AUTH_FAILED` | Error code 190 / `OAuthException` type |
+| `AUTH_FAILED` | Error code 190; `OAuthException` type as a last-resort fallback |
 | `RATE_LIMITED` | Codes 4, 17, 613; subcode 2207051 |
 | `QUOTA_EXCEEDED` | Code 9; subcodes 2018028, 2207042 |
 | `USER_BLOCKED` | Code 551; subcode 1545041 |
-| `PERMISSION_DENIED` | Codes 10, 24, 25, 368; codes 200–299; subcode 2207050 |
+| `PERMISSION_DENIED` | Codes 3, 10, 24, 25, 368; codes 200–299; subcode 2207050 |
 | `PAYLOAD_INVALID` | Codes 1, 100, 352, 9004, 9007, 36000–36004; subcodes 2207020, 2207052 |
 | `NETWORK_ERROR` | Codes −1, −2 |
 | `INVALID_RECIPIENT` | Subcode 2018001 |
 
-`isRevokedTokenError(error)` returns `true` for error code 190 or `type === "OAuthException"`, triggering the upstream re-auth flow.
+Code 3 (`Application does not have the capability to make this API call`) arrives as an
+`OAuthException` but is a capability/endpoint problem, not a token problem — it is mapped to
+`PERMISSION_DENIED` so it is treated as permanent and never sends the operator off to reconnect.
+
+`isRevokedTokenError(error)` returns `true` only for error code 190 **with** a revoked subcode
+(458, 460, 463, 467), triggering the upstream re-auth flow. A bare 190 is ambiguous and is
+deliberately excluded to avoid false-positive disconnects, matching `integrations/instagram`.
 
 ---
 
@@ -181,3 +195,9 @@ src/
 ## API version
 
 Default: `v23.0` (`DEFAULT_API_VERSION` in `constants.ts`). The version is stored in `auth.metadata.version` so it can be pinned per integration instance.
+
+> **Known inconsistency:** `apis/page.ts` (`sendInstagramMessage`, the `messenger_profile` helpers)
+> reads the version off `auth.version`, which the connect flow never writes — it only writes
+> `auth.metadata.version`. Those calls therefore always fall back to `DEFAULT_API_VERSION`, while
+> `apis/comment.ts` and `apis/attachment.ts` (which read `auth.metadata.version`) use the version the
+> UI configured. `integrations/instagram` reads `metadata.version` everywhere and is unaffected.

integrations/instagram-facebook/__tests__/error-mapper.test.ts

@@ -0,0 +1,69 @@
+import { ChannelErrorCategory } from "@chatbotx.io/sdk"
+import { describe, expect, test } from "vitest"
+import { InstagramException } from "../src/exception"
+import { isRevokedTokenError, mapToChannelError } from "../src/lib/error-mapper"
+
+// `(#3) Application does not have the capability to make this API call.` — Meta
+// sends it as an OAuthException, but it is a capability/endpoint problem, not a
+// token problem. Before this was mapped, it fell through to the
+// `type === "OAuthException"` fallback and was reported as AUTH_FAILED, which
+// pointed operators at a reconnect that could never help.
+describe("instagram-facebook error-mapper — code 3 (capability)", () => {
+  const capabilityError = () =>
+    new InstagramException(
+      "#(3) Application does not have the capability to make this API call.",
+      400,
+      3,
+      null,
+      "OAuthException",
+    )
+
+  test("maps to PERMISSION_DENIED, not AUTH_FAILED", () => {
+    const mapped = mapToChannelError(capabilityError())
+
+    expect(mapped.category).toBe(ChannelErrorCategory.PERMISSION_DENIED)
+  })
+
+  test("is permanent, so callers never retry it", () => {
+    const mapped = mapToChannelError(capabilityError())
+
+    expect(mapped.isPermanent).toBe(true)
+    expect(mapped.isRetryable).toBe(false)
+  })
+
+  test("is not treated as a revoked token", () => {
+    expect(isRevokedTokenError(capabilityError())).toBe(false)
+  })
+})
+
+describe("instagram-facebook error-mapper — revoked token detection", () => {
+  test("code 190 with a revoked subcode is a revoked token", () => {
+    const exc = new InstagramException(
+      "Error validating access token",
+      401,
+      190,
+      463,
+      "OAuthException",
+    )
+
+    expect(isRevokedTokenError(exc)).toBe(true)
+  })
+
+  // Ambiguous on purpose: Meta also emits bare 190 for transient session
+  // problems, and treating those as revoked caused false-positive disconnects.
+  test("code 190 without a subcode is not a revoked token", () => {
+    const exc = new InstagramException(
+      "Error validating access token",
+      401,
+      190,
+      null,
+      "OAuthException",
+    )
+
+    expect(isRevokedTokenError(exc)).toBe(false)
+  })
+
+  test("a non-Instagram error is never a revoked token", () => {
+    expect(isRevokedTokenError(new Error("boom"))).toBe(false)
+  })
+})

integrations/instagram-facebook/__tests__/send-private-reply.test.ts

@@ -6,18 +6,28 @@ import type { InstagramAuthValue } from "../src/schemas"
 
 const ACCESS_TOKEN = "IG_TOKEN"
 const IG_ID = "ig-business-account-id"
+const PAGE_ID = "facebook-page-id"
 const COMMENT_ID = "comment-123"
+const MISSING_PAGE_ID_ERROR = /pageId/
 
-const auth = {
+// `pageId` and `igId` are deliberately different values: the old fixture only
+// carried `igId`, so it could not tell the two nodes apart and let the #945
+// regression (posting to the IG node) look correct.
+const auth: InstagramAuthValue = {
   tokens: { accessToken: ACCESS_TOKEN },
-  metadata: { igId: IG_ID, version: DEFAULT_API_VERSION },
-} as unknown as InstagramAuthValue
+  metadata: {
+    igId: IG_ID,
+    igName: "ig-name",
+    pageId: PAGE_ID,
+    version: DEFAULT_API_VERSION,
+  },
+} as InstagramAuthValue
 
 describe("sendPrivateReply", () => {
-  test("addresses the account directly via igId, not the me alias", async () => {
+  test("addresses the Page node, since Meta exposes the messages edge there", async () => {
     server.use(
       http.post(
-        `${API_URL}/${DEFAULT_API_VERSION}/${IG_ID}/messages`,
+        `${API_URL}/${DEFAULT_API_VERSION}/${PAGE_ID}/messages`,
         async ({ request }) => {
           expect(request.headers.get("authorization")).toBe(
             `Bearer ${ACCESS_TOKEN}`,
@@ -38,4 +48,36 @@ describe("sendPrivateReply", () => {
       sendPrivateReply(auth, COMMENT_ID, "Hello from Instagram via Facebook"),
     ).resolves.toEqual({ recipient_id: "recipient-1" })
   })
+
+  // Regression guard for #875 → #945: the IG node returns `(#3) Application
+  // does not have the capability to make this API call.` for this login type,
+  // so a send that reaches it is broken even though the request looks sane.
+  test("never posts to the IG node", async () => {
+    let igNodeCalled = false
+
+    server.use(
+      http.post(`${API_URL}/${DEFAULT_API_VERSION}/${IG_ID}/messages`, () => {
+        igNodeCalled = true
+        return HttpResponse.json({ recipient_id: "wrong-node" })
+      }),
+      http.post(`${API_URL}/${DEFAULT_API_VERSION}/${PAGE_ID}/messages`, () =>
+        HttpResponse.json({ recipient_id: "recipient-1" }),
+      ),
+    )
+
+    await sendPrivateReply(auth, COMMENT_ID, "Hello")
+
+    expect(igNodeCalled).toBe(false)
+  })
+
+  test("throws instead of posting to /undefined/messages when pageId is missing", async () => {
+    const authWithoutPageId = {
+      tokens: { accessToken: ACCESS_TOKEN },
+      metadata: { igId: IG_ID, version: DEFAULT_API_VERSION },
+    } as unknown as InstagramAuthValue
+
+    await expect(
+      sendPrivateReply(authWithoutPageId, COMMENT_ID, "Hello"),
+    ).rejects.toThrow(MISSING_PAGE_ID_ERROR)
+  })
 })

integrations/instagram-facebook/src/apis/comment.ts

@@ -1,5 +1,5 @@
 import { DEFAULT_API_VERSION } from "../constants"
-import { rescue } from "../exception"
+import { InstagramException, rescue } from "../exception"
 import { instagramGraphClient } from "../lib/http-client"
 import {
   INSTAGRAM_MESSAGE_METADATA,
@@ -66,27 +66,55 @@ export const hideComment = (
 /**
  * Sends a private DM reply to the author of a comment with an arbitrary
  * message payload (text, attachment, quick replies, …) — used by flow-based
- * private replies to deliver the *first* outgoing message of the run,
- * addressing the Instagram business account directly via igId rather than the
- * Page node (Meta's Messenger Platform private-reply endpoint also accepts
- * `/<IG_ID>/messages` — see
- * https://developers.facebook.com/docs/messenger-platform/instagram/features/private-replies).
- * The comment_id-anchored Send API bypasses the normal messaging-window
- * requirement.
+ * private replies to deliver the *first* outgoing message of the run, and by
+ * the inbox's manual private reply. The comment_id-anchored Send API bypasses
+ * the normal messaging-window requirement.
+ *
+ * Addresses the **Page** node, not the IG business account. For Instagram via
+ * Facebook Login (Page access token on graph.facebook.com) Meta only exposes
+ * the `messages` edge on the Page:
+ * https://developers.facebook.com/docs/messenger-platform/instagram/features/private-replies
+ * Posting to `/<IG_ID>/messages` is rejected with `(#3) Application does not
+ * have the capability to make this API call.` even when the app holds
+ * `instagram_manage_messages`, `pages_messaging` and Human Agent at Advanced
+ * Access — the code means "this edge does not exist here", not "permission
+ * missing". That matches the rest of this package: messaging edges use the
+ * Page node (`{pageId}/message_attachments`, `me/messages`) while IG content
+ * edges use the IG node (`{igId}/media`, `{igId}/likes`), and it matches
+ * messenger's identical `sendPrivateReplyMessage` (`{pageId}/messages`).
+ *
+ * DO NOT "fix" this back to `igId`. That has already shipped twice: #875 moved
+ * it to `pageId`, then #945 moved it back to make a stale test green (the test
+ * fixture had no `pageId`, so the endpoint silently became `/undefined/…`),
+ * which broke every private reply in production again. The Instagram Login
+ * variant is different on purpose — it uses `me/messages` on
+ * graph.instagram.com.
  *
  * Stamps `message.metadata` like every other Instagram send path so the
  * message_echo webhook (`handlers/webhook.ts`) recognizes and skips our own
  * echo instead of re-ingesting it as an incoming message.
  */
-export const sendPrivateReplyMessage = (
+// `async` so the pageId guard below rejects the returned promise instead of
+// throwing synchronously — callers await it, and a sync throw would escape a
+// `.catch()` attached to the result.
+export const sendPrivateReplyMessage = async (
   auth: InstagramAuthValue,
   commentId: string,
   message: InstagramSendMessage | InstagramMessageAttachmentPayload,
 ): Promise<InstagramSendMessageResponse> => {
   const version = auth.metadata.version ?? DEFAULT_API_VERSION
-  const endpoint = `${version}/${auth.metadata.igId}/messages`
+  const pageId = auth.metadata.pageId
+  // Without this the endpoint becomes `/undefined/messages`, which Meta
+  // answers with a generic error that hides the real cause — exactly how the
+  // #875 → #945 regression went unnoticed.
+  if (!pageId) {
+    throw new InstagramException(
+      "Cannot send an Instagram private reply: the integration has no pageId. Reconnect the Instagram account.",
+    )
+  }
+  const endpoint = `${version}/${pageId}/messages`
 
-  return rescue(endpoint, () =>
+  return await rescue(endpoint, () =>
     instagramGraphClient.post<InstagramSendMessageResponse>(endpoint, {
       headers: {
         "Content-Type": "application/json",

integrations/instagram-facebook/src/lib/error-mapper.ts

@@ -28,6 +28,10 @@ const AUTH_FAILED_CODES = new Set([
 ])
 
 const PERMISSION_DENIED_CODES = new Set([
+  // "Application does not have the capability to make this API call" — the app
+  // lacks a permission/feature, or the edge does not exist on the node being
+  // addressed. Never retryable. Mirrors messenger's mapper.
+  3,
   10, // Permission denied (FB Graph)
   24, // Permission error (IG Content Publishing)
   25, // IG account restricted/checkpointed
@@ -163,13 +167,35 @@ function mapApiFields(fields: ChannelErrorSource): ChannelError {
 }
 
 // === Revoked / invalidated access token detection ===
-// Facebook returns error code 190 (OAuthException) when a page access token is
-// expired or revoked. Returning true triggers the upstream re-auth flow.
+// Facebook signals revoked/expired page tokens via OAuthException + code 190.
+// Sub-codes: 458 = app not installed, 460 = password changed,
+//   463 = access token expired, 467 = invalid access token.
+// Code 190 with no subcode is ambiguous and is NOT treated as revoked, to
+// avoid false-positive channel disconnects. Mirrors the Instagram Login
+// variant (`integrations/instagram`), which already gates this way.
+//
+// Matching on `type === "OAuthException"` alone (as this did before) was wrong:
+// Meta uses that type for unrelated failures such as code 3 ("Application does
+// not have the capability to make this API call"), so a plain endpoint or
+// capability error was reported as a revoked token and made the disconnect flow
+// skip its remote teardown.
+const REVOKED_TOKEN_SUBCODES = new Set([458, 460, 463, 467])
+
 export function isRevokedTokenError(error: unknown): boolean {
-  if (error instanceof InstagramException) {
-    return error.code === 190 || error.type === "OAuthException"
+  if (!(error instanceof InstagramException)) {
+    return false
+  }
+
+  const mappedError = mapToChannelError(error)
+  if (mappedError.subCode === null || mappedError.subCode === undefined) {
+    return false
   }
-  return false
+
+  return (
+    mappedError.category === ChannelErrorCategory.AUTH_FAILED &&
+    mappedError.code === 190 &&
+    REVOKED_TOKEN_SUBCODES.has(Number(mappedError.subCode))
+  )
 }
 
 export function mapToChannelError(rawError: unknown): ChannelError {