@kody/meta

@kody/meta

Intent

One Meta helpers package for Kody agents: Facebook Pages, Instagram professional accounts, and WhatsApp Cloud API. Auth is a saved Meta OAuth connection (meta / meta-*) or a Business system user token secret — not an API key and not a bot token. Identity and asset ids always come from the connected token. This package never hard-codes a Page, Instagram, or phone-number id.

Do not split WhatsApp Cloud into a separate @kody/whatsapp while this package covers it.

What it does

• List Facebook Pages the token can manage, read posts, and preview a Page publish
• Discover Instagram professional accounts linked to those Pages, list media, and preview a publish
• Discover WhatsApp Business accounts and Cloud phone numbers, list templates, and preview a send
• Call uncommon Graph routes with ./request
• Resolve multi-account OAuth / system-user credentials via ./accounts

Do not use this package to scrape personal Facebook profiles, run a 24/7 bot, or paste access tokens into chat.

Prerequisites / setup

There is no built-in Kody Meta app. Tokens are stored by Kody. Never paste an app secret, user token, or system user token into chat.

Redirect URI (OAuth): https://kody.codes/connect/oauth

Lane A — Facebook Login OAuth (BYO Meta app)

1. Open the Meta App Dashboard → Create app (type Business).
2. Add products you will call: Facebook Login for Business, Instagram, WhatsApp.
3. Facebook Login → Settings → Valid OAuth Redirect URIs: exactly https://kody.codes/connect/oauth.
4. App settings → Basic: copy App ID and App Secret.
5. Permissions / use cases: add the scopes below. App Review is required for assets you do not admin; Development mode works for app admins and testers.
6. Open a prefilled connect URL while signed in to Kody. Paste the App ID and App Secret only on that form.

Smoke test (public_profile + email):

https://kody.codes/connect/oauth?provider=meta&authorizeUrl=https%3A%2F%2Fwww.facebook.com%2Fv26.0%2Fdialog%2Foauth&tokenUrl=https%3A%2F%2Fgraph.facebook.com%2Fv26.0%2Foauth%2Faccess_token&flow=confidential&scopes=public_profile%2Cemail&scopeSeparator=%2C&allowedHosts=graph.facebook.com%2Cgraph.instagram.com%2Cgraph-video.facebook.com&apiBaseUrl=https%3A%2F%2Fgraph.facebook.com%2Fv26.0&dashboardUrl=https%3A%2F%2Fdevelopers.facebook.com%2Fapps&extraAuthorizeParams=%7B%22auth_type%22%3A%22rerequest%22%7D

All products in this package:

https://kody.codes/connect/oauth?provider=meta&authorizeUrl=https%3A%2F%2Fwww.facebook.com%2Fv26.0%2Fdialog%2Foauth&tokenUrl=https%3A%2F%2Fgraph.facebook.com%2Fv26.0%2Foauth%2Faccess_token&flow=confidential&scopes=public_profile%2Cemail%2Cpages_show_list%2Cpages_read_engagement%2Cpages_read_user_content%2Cpages_manage_posts%2Cpages_manage_engagement%2Cpages_manage_metadata%2Cpages_messaging%2Cread_insights%2Cbusiness_management%2Cinstagram_basic%2Cinstagram_content_publish%2Cinstagram_manage_comments%2Cinstagram_manage_insights%2Cinstagram_manage_messages%2Cwhatsapp_business_management%2Cwhatsapp_business_messaging&scopeSeparator=%2C&allowedHosts=graph.facebook.com%2Cgraph.instagram.com%2Cgraph-video.facebook.com&apiBaseUrl=https%3A%2F%2Fgraph.facebook.com%2Fv26.0&dashboardUrl=https%3A%2F%2Fdevelopers.facebook.com%2Fapps&extraAuthorizeParams=%7B%22auth_type%22%3A%22rerequest%22%7D

Reconnect an existing connection:

https://kody.codes/connect/oauth?provider=meta

Decoded connect settings:

• Authorize: https://www.facebook.com/v26.0/dialog/oauth
• Token: https://graph.facebook.com/v26.0/oauth/access_token
• Flow: confidential (App Secret on the token request)
• Extra authorize params: {"auth_type":"rerequest"} so declined permissions can be requested again
• API base: https://graph.facebook.com/v26.0

A 403 / permission error from this package names the missing scope and the next /connect/oauth URL. Page, Instagram, and WhatsApp helpers are not hidden when a token is missing a scope.

Facebook user tokens expire (short-lived, then ~60 days after exchange). Prefer a system user token for unattended jobs.

Lane B — Business system user token

For Pages, Instagram assets, and WhatsApp Cloud that a Business already owns, a system user token is the unattended path.

1. Meta Business Settings → Users → System users → generate a token.
2. Assign the Facebook Page, Instagram professional account, and WhatsApp Business account assets the helpers should see.
3. Save the token on this form (never paste it into chat):

https://kody.codes/account/secrets/new?name=metaSystemUserToken&description=Meta%20Business%20system%20user%20token%20for%20Facebook%20Pages%2C%20Instagram%2C%20and%20WhatsApp%20Cloud.%20Paste%20only%20on%20this%20form.&allowedHosts=graph.facebook.com%2Cgraph.instagram.com%2Cgraph-video.facebook.com&scope=user

Call helpers with authMode: 'system-user' (and tokenSecret only to override the name). Extra accounts use metaSystemUserToken-work.

Wrong path (do not use for Graph access tokens you already have in chat):

https://kody.codes/account/secrets/new?name=metaAccessToken&description=Do%20not%20use%20for%20user%20OAuth.%20%40kody/meta%20prefers%20/connect/oauth%20or%20metaSystemUserToken.&allowedHosts=graph.facebook.com&scope=user

Required hosts

Multiple accounts

Default OAuth name is meta. Extra accounts use meta-<purpose>:

• Connect work: https://kody.codes/connect/oauth?provider=meta-work
• Call with integration: 'meta-work' or account: 'work'
• System user extras: tokenSecret: 'metaSystemUserToken-work' or account: 'work' with authMode: 'system-user'

Omitted integration / account resolve to meta / metaSystemUserToken. There is no reserved personal or brand-page alias.

Scopes

./request uses whatever permissions the saved token already has.

Agents: see AGENTS.md for import paths, smoke checks, and mutation snippets.

Done when

• OAuth meta is connected or metaSystemUserToken is saved; hosts graph.facebook.com, graph.instagram.com, and graph-video.facebook.com are approved
• Smoke test returns { ok: true, … } (or { ok: false, setup } with prefilled URLs when disconnected) and does not post or send
• Mutations preview with dryRun: true and only run live with confirm: true after you approve the exact Page / IG / WhatsApp target

Branding

Official Meta infinity symbol from Meta brand resources. Paths are unmodified. Meta, Facebook, Instagram, WhatsApp, and the Meta logo are trademarks of Meta Platforms, Inc. This package is not affiliated with or endorsed by Meta.

Share https://kody.codes/@kody/meta.

Docs

• Facebook Login (manual flow) — authorize / token URLs
• Permissions
• WhatsApp Cloud API
• OAuth — /connect/oauth query params
• Connect secret — /account/secrets/new