# 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") |
- 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
## 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}} |
- 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}} |
- 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] |
- Return
| key | type |
| ---- | ------------------------ |
| id | product ID |
- 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 |
- 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 |
- 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") |
- 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]] |
- 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 |
- 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#--
Sign in with Wallet
Connect another wallet