{"id":13696682,"url":"https://github.com/facebook/facebook-nodejs-business-sdk","last_synced_at":"2025-12-12T03:44:49.670Z","repository":{"id":37335828,"uuid":"101788376","full_name":"facebook/facebook-nodejs-business-sdk","owner":"facebook","description":"Node.js SDK for Meta Marketing APIs","archived":false,"fork":false,"pushed_at":"2025-05-13T21:02:01.000Z","size":2677,"stargazers_count":535,"open_issues_count":74,"forks_count":233,"subscribers_count":48,"default_branch":"main","last_synced_at":"2025-05-13T22:34:58.505Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://developers.facebook.com/docs/business-sdk","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/facebook.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-08-29T17:30:44.000Z","updated_at":"2025-05-13T21:02:05.000Z","dependencies_parsed_at":"2024-06-14T18:48:24.010Z","dependency_job_id":"1794c67a-faac-407d-9078-3696cb63d6e7","html_url":"https://github.com/facebook/facebook-nodejs-business-sdk","commit_stats":{"total_commits":259,"total_committers":52,"mean_commits":4.980769230769231,"dds":0.7374517374517375,"last_synced_commit":"ef6338d64246515aa5dd6a563bf987c0e08e285f"},"previous_names":["facebook/facebook-nodejs-ads-sdk"],"tags_count":99,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebook%2Ffacebook-nodejs-business-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebook%2Ffacebook-nodejs-business-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebook%2Ffacebook-nodejs-business-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebook%2Ffacebook-nodejs-business-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/facebook","download_url":"https://codeload.github.com/facebook/facebook-nodejs-business-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254039378,"owners_count":22004265,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T18:00:44.854Z","updated_at":"2025-12-12T03:44:49.627Z","avatar_url":"https://github.com/facebook.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Node JS"],"sub_categories":[],"readme":"# Facebook Business SDK for NodeJS\n\n[![npm](https://img.shields.io/npm/v/facebook-nodejs-business-sdk)](https://www.npmjs.com/package/facebook-nodejs-business-sdk)\n[![License](https://img.shields.io/badge/license-Facebook%20Platform-blue.svg?style=flat-square)](https://github.com/facebook/facebook-nodejs-business-sdk/blob/main/LICENSE)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/facebook/facebook-nodejs-business-sdk/ci.yml)](https://github.com/facebook/facebook-nodejs-business-sdk/actions/workflows/ci.yml)\n\n### Introduction\n\nThe Facebook \u003ca href=\"https://developers.facebook.com/docs/business-sdk\" target=\"_blank\"\u003eBusiness SDK\u003c/a\u003e is a one-stop shop to help our partners better serve their businesses. Partners are using multiple Facebook API's to serve the needs of their clients. Adopting all these API's and keeping them up to date across the various platforms can be time consuming and ultimately prohibitive. For this reason Facebook has developed the Business SDK bundling many of its APIs into one SDK to ease implementation and upkeep. The Business SDK is an upgraded version of the Marketing API SDK that includes the Marketing API as well as many Facebook APIs from different platforms such as Pages, Business Manager, Instagram, etc.\n\nThis SDK can be used for both server side as well as client side. It comes with ECMAScript 5 bundled minified distribution with source maps of AMD, CommonJS modules, IIFE, as UMD and as Browser Globals.\n\n## Quick Start\n\nBusiness SDK \u003ca href=\"https://developers.facebook.com/docs/business-sdk/getting-started\" target=\"_blank\"\u003eGetting Started Guide\u003c/a\u003e\n\n## Pre-requisites\n\n### Dependencies\n\n[Gulp](http://gulpjs.com/) and [Bower](http://bower.io/) should be installed globally. Install dependencies:\n\n``` bash\nnpm install\nbower install\n```\n\nCheckout `gulpfile.js` for all available tasks.\n\n### Register An App\n\nTo get started with the SDK, you must have an app\nregistered on \u003ca href=\"https://developers.facebook.com/\" target=\"_blank\"\u003edevelopers.facebook.com\u003c/a\u003e.\n\nTo manage the Marketing API, please visit your\n\u003ca href=\"https://developers.facebook.com/apps/\u003cYOUR APP ID\u003e/dashboard\"\u003e App Dashboard \u003c/a\u003e\nand add the \u003cb\u003eMarketing API\u003c/b\u003e product to your app.\n\n**IMPORTANT**: For security, it is recommended that you turn on 'App Secret\nProof for Server API calls' in your app's Settings-\u003eAdvanced page.\n\n### Obtain An Access Token\n\nWhen someone connects with an app using Facebook Login and approves the request\nfor permissions, the app obtains an access token that provides temporary, secure\naccess to Facebook APIs.\n\nAn access token is an opaque string that identifies a User, app, or Page.\n\nFor example, to access the Marketing API, you need to generate a User access token\nfor your app and ask for the ``ads_management`` permission; to access Pages API,\nyou need to generate a Page access token for your app and ask for the ``manage_page`` permission.\n\nRefer to our\n\u003ca href=\"https://developers.facebook.com/docs/facebook-login/access-tokens\" target=\"_blank\"\u003e\nAccess Token Guide\u003c/a\u003e to learn more.\n\nFor now, we can use the\n\u003ca href=\"https://developers.facebook.com/tools/explorer\" target=\"_blank\"\u003eGraph Explorer\u003c/a\u003e\nto get an access token.\n\n## Installation\n\nNPM\n\n`npm install --save facebook-nodejs-business-sdk`\n\nBower\n\n`bower install --save facebook-nodejs-business-sdk`\n\n## Usage\n\n### Access Token\n\nWhen someone connects with an app using Facebook Login and approves the request for permissions, the app obtains an access token that provides temporary, secure access to Facebook APIs.\n\nAn access token is an opaque string that identifies a User, app, or Page.\n\nFor example, to access the Marketing API, you need to generate a User access token for your app and ask for the ``ads_management`` permission; to access Pages API, you need to generate a Page access token for your app and ask for the ``manage_page`` permission.\nRefer to our \u003ca href=\"https://developers.facebook.com/docs/facebook-login/access-tokens\" target=\"_blank\"\u003eAccess Token Guide\u003c/a\u003e to learn more.\n\nFor now, we can use the \u003ca href=\"https://developers.facebook.com/tools/explorer\" target=\"_blank\"\u003eGraph Explorer\u003c/a\u003e to get an access token.\n\n```javaScript\nconst adsSdk = require('facebook-nodejs-business-sdk');\nconst accessToken = '\u003cVALID_ACCESS_TOKEN\u003e';\nconst api = adsSdk.FacebookAdsApi.init(accessToken);\n```\n\n### Api main class\n\nThe `FacebookAdsApi` object is the foundation of the Business SDK which encapsulates the logic to execute requests against the Graph API.\nOnce instantiated, the Api object will allow you to start making requests to the Graph API.\n\n### Facebook Objects\n\nFacebook Ads entities are defined as classes under the `src/objects` directory.\n\n```javascript\n// instantiating an object\nconst adsSdk = require('facebook-nodejs-business-sdk');\nconst AdAccount = adsSdk.AdAccount;\nconst account = new AdAccount('act_\u003cAD_ACCOUNT_ID\u003e');\nconsole.log(account.id) // fields can be accessed as properties\n```\n\n### Fields\n\nDue to the high number of field names in the existing API objects, in order to facilitate your code maintainability, enum-like field objects are provided within each node class.\nThe fields are stored within node object classes which are stored under the `src/objects` directory.\nYou can access object properties like this:\n\n```javaScript\nconst adsSdk = require('facebook-nodejs-business-sdk');\nconst accessToken = '\u003cVALID_ACCESS_TOKEN\u003e';\nconst api = adsSdk.FacebookAdsApi.init(accessToken);\nconst AdAccount = adsSdk.AdAccount;\nconst Campaign = adsSdk.Campaign;\nconst account = new AdAccount('act_\u003cAD_ACCOUNT_ID\u003e');\n\nconsole.log(account.id) // fields can be accessed as properties\naccount\n  .createCampaign(\n    [Campaign.Fields.Id],\n    {\n      [Campaign.Fields.name]: 'Page likes campaign', // Each object contains a fields map with a list of fields supported on that object.\n      [Campaign.Fields.status]: Campaign.Status.paused,\n      [Campaign.Fields.objective]: Campaign.Objective.page_likes\n    }\n  )\n  .then((result) =\u003e {\n  })\n  .catch((error) =\u003e {\n  });\n```\n\n#### Read Objects\n\n```javascript\nconst adsSdk = require('facebook-nodejs-business-sdk');\nconst accessToken = '\u003cVALID_ACCESS_TOKEN\u003e';\nconst api = adsSdk.FacebookAdsApi.init(accessToken);\nconst AdAccount = adsSdk.AdAccount;\nconst account = new AdAccount('act_\u003cAD_ACCOUNT_ID\u003e');\naccount\n  .read([AdAccount.Fields.name, AdAccount.Fields.age])\n  .then((account) =\u003e {\n    console.log(account);\n  })\n  .catch((error) =\u003e {\n  });\n```\n\nRequesting an high number of fields may cause the response time to visibly increase, you should always request only the fields you really need.\n\n#### Create Objects\n\n```javascript\nconst adsSdk = require('facebook-nodejs-business-sdk');\nconst accessToken = '\u003cVALID_ACCESS_TOKEN\u003e';\nconst api = adsSdk.FacebookAdsApi.init(accessToken);\nconst AdAccount = adsSdk.AdAccount;\nconst Campaign = adsSdk.Campaign;\nconst account = new AdAccount('act_\u003cAD_ACCOUNT_ID\u003e');\naccount\n  .createCampaign(\n    [],\n    {\n      [Campaign.Fields.name]: 'Page likes campaign',\n      [Campaign.Fields.status]: Campaign.Status.paused,\n      [Campaign.Fields.objective]: Campaign.Objective.page_likes\n    }\n  )\n  .then((campaign) =\u003e {\n  })\n  .catch((error) =\u003e {\n  });\n```\n\n#### Update Objects\n\n```javascript\nconst adsSdk = require('facebook-nodejs-business-sdk');\nconst accessToken = '\u003cVALID_ACCESS_TOKEN\u003e';\nconst api = adsSdk.FacebookAdsApi.init(accessToken);\nconst Campaign = adsSdk.Campaign;\nconst campaignId = \u003cCAMPAIGN_ID\u003e;\nnew Campaign(campaignId, {\n  [Campaign.Fields.id]: campaign.id,\n  [Campaign.Fields.name]: 'Campaign - Updated' })\n  .update();\n```\n\n#### Delete Objects\n\n```javascript\nconst adsSdk = require('facebook-nodejs-business-sdk');\nconst accessToken = '\u003cVALID_ACCESS_TOKEN\u003e';\nconst api = adsSdk.FacebookAdsApi.init(accessToken);\nconst Campaign = adsSdk.Campaign;\nconst campaignId = \u003cCAMPAIGN_ID\u003e;\nnew Campaign(campaignId).delete();\n```\n\n### Pagination\n\nSince the release of the Facebook Graph API 2.0, pagination is handled through \u003ca href=\"https://developers.facebook.com/docs/graph-api/using-graph-api/v2.2#paging\" target=\"_blank\"\u003ecursors\u003c/a\u003e.\n\nHere cursors are defined as in `src\\cursor.js`. When fetching nodes related to another (Edges) or a collection in the graph, the results are paginated in a `Cursor` class.\nHere the `Cursor` is a superpowered `Array` (with all it's native helpful operations) with `next` and `previous` methods that when resolved fills itself with the new set of objects.\n\n```javascript\nconst adsSdk = require('facebook-nodejs-business-sdk');\nconst accessToken = '\u003cVALID_ACCESS_TOKEN\u003e';\nconst api = adsSdk.FacebookAdsApi.init(accessToken);\nconst AdAccount = adsSdk.AdAccount;\nconst Campaign = adsSdk.Campaign;\nconst account = new AdAccount('act_\u003cAD_ACCOUNT_ID\u003e');\naccount.getCampaigns([Campaign.Fields.name], { limit: 2 })\n.then((campaigns) =\u003e {\n  if (campaigns.length \u003e= 2 \u0026\u0026 campaigns.hasNext()) {\n    return campaigns.next();\n  } else {\n    Promise.reject(\n      new Error('campaigns length \u003c 2 or not enough campaigns')\n    );\n  }\n})\n.then((campaigns) =\u003e {\n  if (campaigns.hasNext() \u0026\u0026 campaigns.hasPrevious()) {\n    return campaigns.previous();\n  } else {\n    Promise.reject(\n      new Error('previous or next is not true')\n    );\n  }\n  return campaigns.previous();\n})\n.catch((error) =\u003e {\n});\n```\n\nIf you are using cursor to iterate all of your object under your Ad Account, this practice is recommended.\n\n```javascript\nconst adsSdk = require('facebook-nodejs-ads-sdk');\nconst accessToken = '\u003cVALID_ACCESS_TOKEN\u003e';\nconst api = adsSdk.FacebookAdsApi.init(accessToken);\nconst AdAccount = adsSdk.AdAccount;\nconst account = new AdAccount('act_\u003cAD_ACCOUNT_ID\u003e');\n\nvoid async function () {\n    let campaigns = await account.getCampaigns([Campaign.Fields.name], {limit: 20});\n    campaigns.forEach(c =\u003e console.log(c.name));\n    while (campaigns.hasNext()) {\n        campaigns = await campaigns.next();\n        campaigns.forEach(c =\u003e console.log(c.name));\n    }\n}();\n```\n\n\n#### Debugging\n\nA `FacebookAdsApi` object offers a debugging mode that will log all requests. To enable it just call `api.setDebug(true)` on an API instance.\n\n```javascript\nconst adsSdk = require('facebook-nodejs-business-sdk');\nconst accessToken = '\u003cVALID_ACCESS_TOKEN\u003e';\nconst api = adsSdk.FacebookAdsApi.init(accessToken);\napi.setDebug(true);\n```\n\n### Style\n\nThis package uses type safe javascript. \u003ca href=\"https://flow.org/\" target=\"_blank\"\u003eFlow\u003c/a\u003e. Inconsistent code will break builds.\n\n## SDK Codegen\nOur SDK is autogenerated from [SDK Codegen](https://github.com/facebook/facebook-business-sdk-codegen). If you want to learn more about how our SDK code is generated, please check this repository.\n\n## Join the Facebook Marketing Developer community\n* Website: https://www.facebook.com/groups/pmdcommunity\n* Facebook page: https://www.facebook.com/marketingdevelopers/\nSee the CONTRIBUTING file for how to help out.\n\n## License\nFacebook Business SDK for NodeJS is licensed under the LICENSE file in the root directory of this source tree.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacebook%2Ffacebook-nodejs-business-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffacebook%2Ffacebook-nodejs-business-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacebook%2Ffacebook-nodejs-business-sdk/lists"}