Facebook

Facebook Pages through your Meta app with Facebook Login; every operation acts with the Page's own access token, which Koil obtains when the profile is connected.

The permissions each capability needs are in App Review: Facebook.

Without pages_manage_metadata a Page still connects, but it is never subscribed to webhooks, so no events arrive for it.
Comments and posts emit their whole lifecycle: an edit is updated, a deletion deleted, and a hide or unhide moderated with the resulting hidden state.

Content type	Operations	Events	Backfill
`facebook.media.items`	`list`, `get`, `publish`	`created`, `updated`, `deleted`	yes
`facebook.media.comments`	`list`, `get`, `publish`, `moderate`, `delete`	`created`, `updated`, `deleted`, `moderated`	no
`facebook.media.mentions`	none	`created`	no
`facebook.stories.items`	`list`, `publish`	`created`	yes
`facebook.dm.threads`	`list`, `get`	none	no
`facebook.dm.messages`	`list`, `publish`	`created`	no

`facebook.media.items`

The Page's posts.

`list`

List published Facebook Page posts.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`cursor`	`string`	no	Opaque cursor for fetching the next result page.
`limit`	`number`	no	Maximum number of items to return.
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "cursor": {
      "description": "Opaque cursor for fetching the next result page.",
      "minLength": 1,
      "type": "string"
    },
    "limit": {
      "description": "Maximum number of items to return.",
      "minimum": 1,
      "type": "number"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId"
  ]
}

`get`

Get one Facebook Page post by provider id.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`externalId`	`string`	yes
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "externalId": {
      "minLength": 1,
      "type": "string"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId",
    "externalId"
  ]
}

`publish`

Publish a Facebook Page post: text, a link, photos, a video, or a reel.

Submit through POST /v1/publish-requests with contentType: "facebook.media.items". These fields go in the item's args; connectedProfileId and variant are item fields.

variant: "feed"

Field	Type	Required	Description
`scheduling`	`object`	no	Future operation time and optional wall-clock timezone.
`text`	`string`	yes	Caption/body text for content.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "scheduling": {
      "additionalProperties": false,
      "description": "Future operation time and optional wall-clock timezone.",
      "type": "object",
      "properties": {
        "at": {
          "format": "date-time",
          "description": "Future execution time as an ISO-8601 string.",
          "type": "string"
        },
        "timezone": {
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "at"
      ]
    },
    "text": {
      "description": "Caption/body text for content.",
      "type": "string"
    }
  },
  "required": [
    "text"
  ]
}

variant: "feed"

Field	Type	Required	Description
`scheduling`	`object`	no	Future operation time and optional wall-clock timezone.
`text`	`string`	no	Caption/body text for content.
`link`	`string (uri)`	yes	A URL to attach as a link post; not combinable with media.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "scheduling": {
      "additionalProperties": false,
      "description": "Future operation time and optional wall-clock timezone.",
      "type": "object",
      "properties": {
        "at": {
          "format": "date-time",
          "description": "Future execution time as an ISO-8601 string.",
          "type": "string"
        },
        "timezone": {
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "at"
      ]
    },
    "text": {
      "description": "Caption/body text for content.",
      "type": "string"
    },
    "link": {
      "minLength": 1,
      "format": "uri",
      "description": "A URL to attach as a link post; not combinable with media.",
      "type": "string"
    }
  },
  "required": [
    "link"
  ]
}

variant: "feed"

Field	Type	Required	Description
`scheduling`	`object`	no	Future operation time and optional wall-clock timezone.
`text`	`string`	no	Caption/body text for content.
`media`	`object \| object[]`	yes

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "scheduling": {
      "additionalProperties": false,
      "description": "Future operation time and optional wall-clock timezone.",
      "type": "object",
      "properties": {
        "at": {
          "format": "date-time",
          "description": "Future execution time as an ISO-8601 string.",
          "type": "string"
        },
        "timezone": {
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "at"
      ]
    },
    "text": {
      "description": "Caption/body text for content.",
      "type": "string"
    },
    "media": {
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "anyOf": [
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "mediaId": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "mediaId"
            ]
          },
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "sourceUrl": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "sourceUrl"
            ]
          }
        ]
      }
    }
  },
  "required": [
    "media"
  ]
}

variant: "reel"

Field	Type	Required	Description
`text`	`string`	no	Caption/body text for content.
`media`	`object \| object[]`	yes
`scheduling`	`object`	no	Future operation time and optional wall-clock timezone.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "text": {
      "description": "Caption/body text for content.",
      "type": "string"
    },
    "media": {
      "minItems": 1,
      "maxItems": 1,
      "type": "array",
      "items": {
        "anyOf": [
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "mediaId": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "pattern": "^video/",
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "mediaId"
            ]
          },
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "sourceUrl": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "pattern": "^video/",
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "sourceUrl"
            ]
          }
        ]
      }
    },
    "scheduling": {
      "additionalProperties": false,
      "description": "Future operation time and optional wall-clock timezone.",
      "type": "object",
      "properties": {
        "at": {
          "format": "date-time",
          "description": "Future execution time as an ISO-8601 string.",
          "type": "string"
        },
        "timezone": {
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "at"
      ]
    }
  },
  "required": [
    "media"
  ]
}

Not offered

update: provider not supported
moderate: provider not supported
delete: provider not supported

Events

Backfill: supported (bounded coverage); see Backfill history.

Item schema

What list and get return and what events carry as data.

Field	Type	Required	Description
`externalId`	`string`	yes	Provider-owned content identifier.
`variant`	`"feed" \| "reel"`	yes
`text`	`string`	no	Caption/body text for content.
`media`	`object[]`	no
`providerPermalink`	`string (uri)`	no	Canonical provider URL for content.
`publishedAt`	`string (date-time)`	no	Provider publish timestamp as an ISO-8601 string.
`providerRaw`	`unknown`	no	Optional provider-native payload included only for transient delivery/debug use.
`contentType`	`"facebook.media.items"`	yes

`facebook.media.comments`

Comments on the Page's posts, replies included.

`list`

List comments on one Facebook Page post, replies included.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`mediaExternalId`	`string`	yes
`cursor`	`string`	no	Opaque cursor for fetching the next result page.
`limit`	`number`	no	Maximum number of items to return.
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "mediaExternalId": {
      "minLength": 1,
      "type": "string"
    },
    "cursor": {
      "description": "Opaque cursor for fetching the next result page.",
      "minLength": 1,
      "type": "string"
    },
    "limit": {
      "description": "Maximum number of items to return.",
      "minimum": 1,
      "type": "number"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId",
    "mediaExternalId"
  ]
}

`get`

Get one Facebook Page comment by provider id.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`externalId`	`string`	yes
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "externalId": {
      "minLength": 1,
      "type": "string"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId",
    "externalId"
  ]
}

`publish`

Publish a Facebook Page comment: a reply to a comment or a top-level comment on a post.

Submit through POST /v1/publish-requests with contentType: "facebook.media.comments". These fields go in the item's args; connectedProfileId and variant are item fields.

Field	Type	Required	Description
`target`	`object`	yes	The provider content this publish targets, identified as events identify it.
`text`	`string`	yes	Caption/body text for content.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "target": {
      "additionalProperties": false,
      "description": "The provider content this publish targets, identified as events identify it.",
      "type": "object",
      "properties": {
        "contentType": {
          "anyOf": [
            {
              "const": "facebook.media.comments",
              "type": "string"
            },
            {
              "const": "facebook.media.items",
              "type": "string"
            }
          ]
        },
        "externalId": {
          "description": "Provider-owned content identifier.",
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "contentType",
        "externalId"
      ]
    },
    "text": {
      "description": "Caption/body text for content.",
      "type": "string"
    }
  },
  "required": [
    "target",
    "text"
  ]
}

`moderate`

Hide or unhide a comment on a Facebook Page post.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`externalId`	`string`	yes
`hidden`	`boolean`	yes

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "externalId": {
      "minLength": 1,
      "type": "string"
    },
    "hidden": {
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId",
    "externalId",
    "hidden"
  ]
}

`delete`

Delete a comment on a Facebook Page post.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`externalId`	`string`	yes

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "externalId": {
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "connectedProfileId",
    "externalId"
  ]
}

Not offered

update: provider not supported

Events

Backfill: not offered — provider no endpoint.

Item schema

What list and get return and what events carry as data.

Field	Type	Required	Description
`externalId`	`string`	yes	Provider-owned content identifier.
`mediaExternalId`	`string`	yes
`text`	`string`	yes	Caption/body text for content.
`author`	`object`	no	Provider actor reference for observed content.
`thread`	`object`	no	Parent/root identifiers for threaded contexts.
`hidden`	`boolean`	no
`providerPermalink`	`string (uri)`	no	Canonical provider URL for content.
`publishedAt`	`string (date-time)`	no	Provider publish timestamp as an ISO-8601 string.
`providerRaw`	`unknown`	no	Optional provider-native payload included only for transient delivery/debug use.
`contentType`	`"facebook.media.comments"`	yes

`facebook.media.mentions`

Mentions of the Page in other posts and comments. Delivered as events only: Meta offers no endpoint that lists them.

Not offered

list: provider no endpoint
get: not applicable
publish: provider not supported
update: provider not supported
moderate: provider not supported
delete: provider not supported

Events

content.facebook.media.mentions.created

Backfill: not offered — provider no endpoint.

Item schema

What list and get return and what events carry as data.

Field	Type	Required	Description
`externalId`	`string`	yes	Provider-owned content identifier.
`variant`	`"post" \| "comment"`	yes
`mediaExternalId`	`string`	no
`commentExternalId`	`string`	no
`text`	`string`	no	Caption/body text for content.
`author`	`object`	no	Provider actor reference for observed content.
`providerPermalink`	`string (uri)`	no	Canonical provider URL for content.
`publishedAt`	`string (date-time)`	no	Provider publish timestamp as an ISO-8601 string.
`providerRaw`	`unknown`	no	Optional provider-native payload included only for transient delivery/debug use.
`contentType`	`"facebook.media.mentions"`	yes

`facebook.stories.items`

The Page's stories.

`list`

List the Page's stories.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`cursor`	`string`	no	Opaque cursor for fetching the next result page.
`limit`	`number`	no	Maximum number of items to return.
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "cursor": {
      "description": "Opaque cursor for fetching the next result page.",
      "minLength": 1,
      "type": "string"
    },
    "limit": {
      "description": "Maximum number of items to return.",
      "minimum": 1,
      "type": "number"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId"
  ]
}

`publish`

Publish a Facebook Page story from one photo or video.

Submit through POST /v1/publish-requests with contentType: "facebook.stories.items". These fields go in the item's args; connectedProfileId and variant are item fields.

Field	Type	Required	Description
`media`	`object \| object[]`	yes
`scheduling`	`object`	no	Future operation time and optional wall-clock timezone.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "media": {
      "minItems": 1,
      "maxItems": 1,
      "type": "array",
      "items": {
        "anyOf": [
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "mediaId": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "mediaId"
            ]
          },
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "sourceUrl": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "sourceUrl"
            ]
          }
        ]
      }
    },
    "scheduling": {
      "additionalProperties": false,
      "description": "Future operation time and optional wall-clock timezone.",
      "type": "object",
      "properties": {
        "at": {
          "format": "date-time",
          "description": "Future execution time as an ISO-8601 string.",
          "type": "string"
        },
        "timezone": {
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "at"
      ]
    }
  },
  "required": [
    "media"
  ]
}

Not offered

get: provider no endpoint
update: provider not supported
moderate: provider not supported
delete: provider not supported

Events

content.facebook.stories.items.created

Backfill: supported (bounded coverage); see Backfill history.

Item schema

What list and get return and what events carry as data.

Field	Type	Required	Description
`externalId`	`string`	yes	Provider-owned content identifier.
`variant`	`"photo" \| "video"`	yes
`status`	`"published" \| "archived"`	yes
`mediaExternalId`	`string`	no	Meta's id for the story's photo or video.
`providerPermalink`	`string (uri)`	no	Canonical provider URL for content.
`publishedAt`	`string (date-time)`	no	Provider publish timestamp as an ISO-8601 string.
`providerRaw`	`unknown`	no	Optional provider-native payload included only for transient delivery/debug use.
`contentType`	`"facebook.stories.items"`	yes

`facebook.dm.threads`

The Page's Messenger conversations.

`list`

List the Page's Messenger threads.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`cursor`	`string`	no	Opaque cursor for fetching the next result page.
`limit`	`number`	no	Maximum number of items to return.
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "cursor": {
      "description": "Opaque cursor for fetching the next result page.",
      "minLength": 1,
      "type": "string"
    },
    "limit": {
      "description": "Maximum number of items to return.",
      "minimum": 1,
      "type": "number"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId"
  ]
}

`get`

Get one Messenger thread by provider id.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`externalId`	`string`	yes
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "externalId": {
      "minLength": 1,
      "type": "string"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId",
    "externalId"
  ]
}

Not offered

publish: provider not supported
update: provider not supported
moderate: provider not supported
delete: provider not supported

Events

None: this content type is read-only.

Backfill: not offered — not implemented.

Item schema

What list and get return and what events carry as data.

Field	Type	Required	Description
`externalId`	`string`	yes	Provider-owned content identifier.
`participantExternalIds`	`string[]`	yes
`updatedAt`	`string (date-time)`	no	Provider update timestamp as an ISO-8601 string.
`providerRaw`	`unknown`	no	Optional provider-native payload included only for transient delivery/debug use.
`contentType`	`"facebook.dm.threads"`	yes

`facebook.dm.messages`

Messages in one Messenger conversation.

`list`

List Messenger messages in one thread.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`threadExternalId`	`string`	yes
`cursor`	`string`	no	Opaque cursor for fetching the next result page.
`limit`	`number`	no	Maximum number of items to return.
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "threadExternalId": {
      "minLength": 1,
      "type": "string"
    },
    "cursor": {
      "description": "Opaque cursor for fetching the next result page.",
      "minLength": 1,
      "type": "string"
    },
    "limit": {
      "description": "Maximum number of items to return.",
      "minimum": 1,
      "type": "number"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId",
    "threadExternalId"
  ]
}

`publish`

Send a Messenger message from the Page to a recipient.

Submit through POST /v1/publish-requests with contentType: "facebook.dm.messages". These fields go in the item's args; connectedProfileId and variant are item fields.

Field	Type	Required	Description
`recipientExternalId`	`string`	yes	Provider actor the message is addressed to, such as a DM event's author.id.
`text`	`string`	yes	Caption/body text for content.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "recipientExternalId": {
      "minLength": 1,
      "description": "Provider actor the message is addressed to, such as a DM event's author.id.",
      "type": "string"
    },
    "text": {
      "description": "Caption/body text for content.",
      "type": "string"
    }
  },
  "required": [
    "recipientExternalId",
    "text"
  ]
}

Not offered

get: provider not supported
update: provider not supported
moderate: provider not supported
delete: provider not supported

Events

content.facebook.dm.messages.created

Backfill: not offered — not implemented.

Item schema

What list and get return and what events carry as data.

Field	Type	Required	Description
`externalId`	`string`	yes	Provider-owned content identifier.
`threadExternalId`	`string`	no	Owning conversation id. Present on messages read through facebook.dm.threads; absent on webhook-observed messages because Messenger webhooks do not identify the conversation.
`text`	`string`	no	Caption/body text for content.
`author`	`object`	no	Provider actor reference for observed content.
`thread`	`object`	no	Parent/root identifiers for threaded contexts.
`publishedAt`	`string (date-time)`	no	Provider publish timestamp as an ISO-8601 string.
`providerRaw`	`unknown`	no	Optional provider-native payload included only for transient delivery/debug use.
`contentType`	`"facebook.dm.messages"`	yes

Facebook

facebook.media.items

list

get

publish

Not offered

Events

facebook.media.comments

list

get

publish

moderate

delete

Not offered

Events

facebook.media.mentions

Not offered

Events

facebook.stories.items

list

publish

Not offered

Events

facebook.dm.threads

list

get

Not offered

Events

facebook.dm.messages

list

publish

Not offered

Events

On this page

`facebook.media.items`

`list`

`get`

`publish`

`facebook.media.comments`

`list`

`get`

`publish`

`moderate`

`delete`

`facebook.media.mentions`

`facebook.stories.items`

`list`

`publish`

`facebook.dm.threads`

`list`

`get`

`facebook.dm.messages`

`list`

`publish`