---
# System prepended metadata

title: Facebook API
tags: [ShowHue]

---

# Facebook API
###### tags: `ShowHue`
>[name=鍾詔東]

## Facebook

- Current Scopes ([More Scopes])
    | Scope                        | content                             |
    | ---------------------------- | ----------------------------------- |
    | email                        | Get user's email                    |
    | catalog_management           | Get/Set user's catalog and products |
    | business_management          | Get/Set user's business Information |
    | business_creative_management | Get/Set user ads' creative and upload   |

- Use Cases
    - **Login:** email
    - **Connect facebook busniess:** email,business_management,catalog_management 


## Authorization API

- Get Access Token API
    ```
    [GET] https://graph.facebook.com/v12.0/oauth/access_token
    ```
    - Params
        | key           | type   | note                            |
        | ------------- | ------ | ------------------------------- |
        | code          | String | From Frontend                   |
        | client_id     | String | Get From [Facebook developer]   |
        | client_secret | String | Get From [Facebook developer]   |
        | redirect_uri  | String | <FRONTEND_SERVER_HOST>/facebook |

    - Return
        | key          | type              |
        | ------------ | ----------------- |
        | access_token | String            |
        | token_type   | String ("bearer") |
        
        ![](https://i.imgur.com/i2N08ZO.png)

    
- Get User Information API
    ```
    [GET] https://graph.facebook.com/me
    ```
    - Params
        | key           | type   | note                            |
        | ------------- | ------ | ------------------------------- |
        | fields        | String | items seperated by comma [[More User Fields]]        |
        | access_token | String  | The user's access_token|

    - Return
        Depends on Fields
        ![](https://i.imgur.com/6ahroyg.png)


## Catalog API
Management Platform: https://business.facebook.com/commerce/catalogs/1100629960476171/home?business_id=365315497209595
- Get User Business's catalogs API
    ```
    [GET] https://graph.facebook.com/v12.0/<BUSINESS_ID>/owned_product_catalogs
    ```
  
    - Params
        | key           | type   | note                            |
        | ------------- | ------ | ------------------------------- |
        | fields        | String | items seperated by comma        |
        | access_token | String  | The user's access_token|
    - Return
        | key  | type                     |
        | ---- | ------------------------ |
        | data | List(Depends on Fields)         |
        | page | {cursors:{before,after}} |
    ![](https://i.imgur.com/OeC5VKD.png)
    - Refernce
        https://developers.facebook.com/docs/marketing-api/reference/product-catalog

    
- Get User Products API
    ```
    [GET] https://graph.facebook.com/v12.0/<CATALOG_ID>/products
    ```

    - Params
        | key          | type   | note                                           |
        | ------------ | ------ | ---------------------------------------------- |
        | fields       | String | items seperated by comma [[More Product's Fields]]|
        | access_token | String | The user's access_token|
    - Return
        | key  | type                     |
        | ---- | ------------------------ |
        | data | List(Depends on Fields)  |
        | page | {cursors:{before,after}} |
    ![](https://i.imgur.com/jgowjae.png)
    - Reference
        https://developers.facebook.com/docs/marketing-api/reference/product-catalog/products/
- Set User products API (Single)
    ```
    [POST] https://graph.facebook.com/v12.0/<CATALOG_ID>/products
    ```
    - Authorization
        | key           | type   | note         |
        | ------------- | ------ | ------------ |
        | Authorization | Bearer | access_token |
    - Params
        | key                            | type                  | note                              |
        | ------------------------------ | --------------------- | --------------------------------- |
        | retailer_id                    | String                | Our Customized Product ID         |
        | name                           | String                | Default main name                 |
        | categroy                       | String                | [Category of products]            |
        | description                    | String                | "test-content"                    |
        | price                          | int64                 | ```599 => 5.99 USD```             |
        | currency                       | String                | ["TWD", "USD", ...]               |
        | image_url                      | String                | Default main image                |
        | additional_image_urls          | list(String)[Optinal] | Other images of products          |
        | manufacturer_part_number, gtin | String                | "100-440-0.750-3434-A" or "WTF"   |
        | url                            | String                | product related url               |
        | MORE...                        | [optional params]     | [More products create parameters] |
        
        ![](https://i.imgur.com/xodd7wP.png)
    - Return
        | key  | type                     |
        | ---- | ------------------------ |
        | id | product ID  |
        
        ![](https://i.imgur.com/Yzameow.png)
    - Reference
        https://developers.facebook.com/docs/marketing-api/reference/product-catalog/products/#Creating
- Set User products API (Batch)
    ```
    [POST] https://graph.facebook.com/v12.0/<CATALOG_ID>/batch
    ```
    - Authorization
        | key           | type   | note         |
        | ------------- | ------ | ------------ |
        | Authorization | Bearer | access_token |
    - Params
        | key                            | type                  | note                              |
        | ------------------------------ | --------------------- | --------------------------------- |
        |requests|List(ProductRequest)|List of actions to Products|
        -  ProductRequests
            | key         | type        | note                       |
            | ----------- | ----------- | -------------------------- |
            | retailer_id | String      | Our Customized Product ID  |
            | method      | String      | "CREATE","UPDATE","DELETE" |
            | data        | ProductInfo | Product information        |
        - ProductInfo
            | key                            | type                  | note                              |
            | ------------------------------ | --------------------- | --------------------------------- |
            | name                           | String                | Default main name                 |
            | categroy                       | String                | [Category of products]            |
            | description                    | String                | "test-content"                    |
            | price                          | int64                 | ```599 => 5.99 USD```             |
            | currency                       | String                | ["TWD", "USD", ...]               |
            | image_url                      | String                | Default main image                |
            | additional_image_urls          | list(String)[Optinal] | Other images of products          |
            | manufacturer_part_number, gtin | String                | "100-440-0.750-3434-A" or "WTF"   |
            | url                            | String                | product related url               |
            | MORE...                        | [optional params]     | [More products create parameters] |
        
        
    - Return
        | key    | type           |
        | ------ | -------------- |
        | handle | List of tokens |
        
        ![](https://i.imgur.com/Hvu6fVC.png)

    - Refernece
        https://developers.facebook.com/docs/marketing-api/reference/product-catalog/batch/

## Creative API
Management Plaform: https://business.facebook.com/asset_library/business_creatives/?object_id=1151231571951313
- Create user creative folder
    ```
    [POST] https://graph.facebook.com/v12.0/<BUSINESS_ID>/creative_folders
    ```
     - Authorization
        | key           | type   | note         |
        | ------------- | ------ | ------------ |
        | Authorization | Bearer | access_token |
    - Params
        | key  | type   | note        |
        | ---- | ------ | ----------- |
        | name | String | folder name |
    - Return
        | key | type   | note               |
        | --- | ------ | ------------------ |
        | id  | string | business folder id |
    ![](https://i.imgur.com/4DdYmYH.png)
    - Reference
        https://developers.facebook.com/docs/marketing-api/business-creative-asset-management/get-started#create-business-creative-folder

- Upload image to creative folder
    ```
    [POST] https://graph.facebook.com/v12.0/<BUSINESS_ID>/images
    ```
    - Authorization
        | key           | type   | note         |
        | ------------- | ------ | ------------ |
        | Authorization | Bearer | access_token |
    - Params
        | key                | type   | note                          |
        | ------------------ | ------ | ----------------------------- |
        | name               | String | image name                    |
        | creative_folder_id | String | Upload folder ID              |
        | bytes              | Bytes  | image content in bytes format |
        
    - Return
        | key | type   | note               |
        | --- | ------ | ------------------ |
        | id  | string | business folder id |
    - Reference
        https://developers.facebook.com/docs/marketing-api/business-creative-asset-management/get-started#add-images
- Get Folders from User
    ```
    [GET] https://graph.facebook.com/v12.0/<BUSINESS_ID>/creative_folders
    ```
     - Authorization
        | key           | type   | note         |
        | ------------- | ------ | ------------ |
        | Authorization | Bearer | access_token |
    - Params
        | key    | type   | note                                          |
        | ------ | ------ | --------------------------------------------- |
        | fields | string | columns splits by comma ("id,name") |
    ![](https://i.imgur.com/Ab1brcO.png)

    - Reference
        https://developers.facebook.com/docs/marketing-api/business-creative-asset-management/reference#read-endpoints
- Get Images from User
    ```
    [GET] https://graph.facebook.com/v12.0/<BUSINESS_ID>/creatives
    ```
     - Authorization
        | key           | type   | note         |
        | ------------- | ------ | ------------ |
        | Authorization | Bearer | access_token |
    - Params
        | key    | type   | note                                          |
        | ------ | ------ | --------------------------------------------- |
        | fields | string | columns splits by comma [[More Image Fields]] |
    ![](https://i.imgur.com/txrEHbh.png)
    - Reference
        https://developers.facebook.com/docs/marketing-api/business-creative-asset-management/reference#read-endpoints
- Add Tags to Image
    ```
    [POST] https://graph.facebook.com/v12.0/<BUSINESS_IMAGE_ID>/creative_asset_tags
    ```
     - Authorization
        | key           | type   | note         |
        | ------------- | ------ | ------------ |
        | Authorization | Bearer | access_token |
    - Reference 
        https://developers.facebook.com/docs/marketing-api/business-creative-asset-management/guides/creative-asset-tags


## Facebook App setup

Setting Tour: https://developers.facebook.com/docs/graph-api/webhooks/getting-started#configure-webhooks-product

Documents: https://developers.facebook.com/docs/facebook-business-extension/fbe2/guides/get-features#webhook

- Uninstall App
    ```
    [DELETE] https://graph.facebook.com/v12.0/fbe_business/fbe_installs
    ```
     
    - Params
        | key                      | type   | note                 |
        | ------------------------ | ------ | -------------------- |
        | access_token             | string | Users Access Token   |
        | fbe_external_business_id | string | Our assigned User ID |
       
       ![](https://i.imgur.com/rIwuUXf.png)
    - Reference
        https://developers.facebook.com/docs/facebook-business-extension/fbe2/guides/uninstall#uninstall-fbe--v2-for-businesses



### Webhooks

Webhooks Setting Page:
https://developers.facebook.com/apps/174279974792163/webhooks/?business_id=365315497209595

Webhooks Documents:
https://developers.facebook.com/docs/facebook-business-extension/fbe2/guides/get-features#webhook
- App Installed Payload
    ```
    {
      "object": "user",
      "entry": [
        {
          "id": "0",
          "uid": "0",
          "time": 1639368046,
          "changes": [
            {
              "field": "fbe_install",
              "value": {
                "access_token": "sample_access_token",
                "ad_account_id": "sample_ad_account_id",
                "business_id": "sample_business_id",
                "business_manager_id": "sample_business_manager_id",
                "catalog_id": "sample_catalog_id",
                "commerce_merchant_settings_id": "sample_commerce_merchant_settings_id",
                "fbe_event": "INSTALL",
                "flow": "MESSAGING",
                "instagram_profiles": ["sample_instagram_profile_id"],
                "install_time": 1639368045,
                "pixel_id": "sample_pixel_id",
                "pages": ["sample_page_id"],
                "profiles": ["sample_page_id", "sample_instagram_profile_id"],
                "onsite_eligible": true,
                "token_type": "User"
              }
            }
          ]
        }
      ]
    }

    ```
- App Uninstalled Payload
    ```
    {
      "object": "user",
      "entry": [
        {
          "id": "6625272700846725",
          "uid": "6625272700846725",
          "time": 1639547333,
          "changes": [
            {
              "field": "fbe_install",
              "value": {
                "business_id": "showhue-123",
                "fbe_event": "UNINSTALL",
                "install_time": 1639547332
              }
            }
          ]
        }
      ]
    }

    ```


## Disconnected Webhook

Webhooks Setting Page:
https://developers.facebook.com/apps/174279974792163/webhooks/?business_id=365315497209595

Ref: https://developers.facebook.com/docs/graph-api/webhooks/reference/permissions/#connected

 Connected
 ```
 {
  "object": "permissions",
  "entry": [
    {
      "id": "6625272700846725",  //facebook user id
      "uid": "6625272700846725",
      "time": 1641182151,
      "changes": [{ "value": { "verb": "granted" }, "field": "email" }]
    },
    {
      "id": "6625272700846725", //facebook user id
      "uid": "6625272700846725",
      "time": 1641182151,
      "changes": [{ "verb": "granted", "field": "connected" }]
    }
  ]
}

 ```
 Disconnected
 ```
 {
  "object": "permissions",
  "entry": [
    {
      "id": "6625272700846725", //facebook user id
      "uid": "6625272700846725",
      "time": 1641182070,
      "changes": [{ "verb": "revoked", "field": "connected" }]
    }
  ]
}

 ```

## More Potemtial APIs

 - Creative Ads Insight: https://developers.facebook.com/docs/marketing-api/business-creative-asset-management/guides/shared-creative-insights


[Facebook developer]: https://developers.facebook.com/apps/?show_reminder=true
[More Scopes]: https://developers.facebook.com/docs/permissions/reference
[More User Fields]: https://developers.facebook.com/docs/graph-api/reference/user/?locale=en_US
[More Product's Fields]: https://developers.facebook.com/docs/marketing-api/reference/product-item/#fields
[More products create parameters]: https://developers.facebook.com/docs/marketing-api/reference/product-catalog/products/#parameters-2
[Category of products]: https://developers.facebook.com/docs/marketing-api/catalog/guides/product-categories#fb-prod-cat

[Create Creative Folder]: https://developers.facebook.com/docs/marketing-api/business-creative-asset-management/get-started#create-business-creative-folder

[Add Creative to Folders]: https://developers.facebook.com/docs/marketing-api/business-creative-asset-management/get-started#add-images

[Get images/folder from User]: https://developers.facebook.com/docs/marketing-api/business-creative-asset-management/reference#read-endpoints

[Add Tag to Image]: https://developers.facebook.com/docs/marketing-api/business-creative-asset-management/guides/creative-asset-tags
[More Image Fields]: https://developers.facebook.com/docs/marketing-api/reference/ad-image#--