Facebook - API
23 May 2018- FD
- Facebook for Developers
- GAE
- Graph API Explorer
-
user IDs
- UID
- real user ID
- ASID
- app-scoped ID
- PSID
- page-scoped ID
-
access tokens
- AT
- access token
- UAT
- user access token
- AAT
- app access token
- PAT
- page access token
- ATD
- Access Token Debugger
Facebook Login
Graph API
get next bill date
you can get active_billing_date_preference
and next_bill_date
info only if
your token is generated for Ads Manager
App (App ID
field in ATD).
get page conversations
- https://developers.facebook.com/docs/graph-api/reference/page/conversations/
- https://developers.facebook.com/docs/graph-api/reference/v3.1/conversation
first generate long-lived PAT with read_page_mailboxes
permission - see PAT
section below.
this PAT can be now used to fetch page conversations:
UAT scopes: manage_pages,read_page_mailboxes
GET v3.1/me/conversations
filter page conversations by date
https://developers.facebook.com/docs/graph-api/reference/v3.1/page/conversations
Time-based pagination is not available for the conversations endpoint.
filtering conversations by date is removed by Facebook:
https://developers.facebook.com/support/bugs/420363721670492
it appears as if we would have to delete conversations in order to prevent retrieving all conversations all the time.
So if I want to get a message from January I have to paginate all over the object until January?
it’s only possible to limit the number of conversations to fetch using limit
modifier.
Marketing API
get billing events (activities)
billing events:
add_funding_source
(payment method added - say, credit card)funding_event_successful
(money added to balance)ad_account_billing_charge
(ad account billed)
UAT scopes: email,public_profile,ads_management,ads_read,manage_pages
GET v3.1/me/adaccounts?fields=id,account_id,name,activities{event_type,event_time,extra_data}
sample response:
{
"data": [
{
"id": "act_123",
"account_id": "123",
"name": "RS",
"activities": {
"data": [
{
"event_type": "funding_event_successful",
"event_time": "2018-05-25T04:40:16+0000",
"extra_data": "{\"action\":67,\"amount\":3000,\"currency\":\"USD\",\"fee\":0,\"network_id\":0,\"provider_amount\":3000,\"type\":\"\"}"
},
{
"event_type": "add_funding_source",
"event_time": "2018-05-25T04:40:16+0000",
"extra_data": "{\"payment_method\":{\"__html\":\"Credit Card\"}}"
},
{
"event_type": "ad_account_billing_charge",
"event_time": "2018-05-24T14:15:03+0000",
"extra_data": "{\"currency\":\"USD\",\"new_value\":611,\"transaction_id\":\"999\",\"action\":67,\"type\":\"payment_amount\"}"
},
{
"event_type": "funding_event_successful",
"event_time": "2018-05-24T01:44:54+0000",
"extra_data": "{\"action\":67,\"amount\":2000,\"currency\":\"USD\",\"fee\":0,\"network_id\":0,\"provider_amount\":2000,\"type\":\"\"}"
},
{
"event_type": "add_funding_source",
"event_time": "2018-05-24T01:44:54+0000",
"extra_data": "{\"payment_method\":{\"__html\":\"Credit Card\"}}"
},
{
"event_type": "ad_account_billing_charge",
"event_time": "2018-05-23T14:44:39+0000",
"extra_data": "{\"currency\":\"USD\",\"new_value\":984,\"transaction_id\":\"999\",\"action\":67,\"type\":\"payment_amount\"}"
},
{
"event_type": "ad_account_billing_charge",
"event_time": "2018-05-22T14:44:04+0000",
"extra_data": "{\"currency\":\"USD\",\"new_value\":1804,\"transaction_id\":\"999\",\"action\":67,\"type\":\"payment_amount\"}"
},
{
"event_type": "ad_account_billing_charge",
"event_time": "2018-05-21T13:34:11+0000",
"extra_data": "{\"currency\":\"USD\",\"new_value\":100,\"transaction_id\":\"999\",\"action\":67,\"type\":\"payment_amount\"}"
},
{
"event_type": "funding_event_successful",
"event_time": "2018-05-21T05:54:26+0000",
"extra_data": "{\"action\":67,\"amount\":3000,\"currency\":\"USD\",\"fee\":0,\"network_id\":0,\"provider_amount\":3000,\"type\":\"\"}"
},
{
"event_type": "ad_account_billing_charge",
"event_time": "2018-05-20T13:37:46+0000",
"extra_data": "{\"currency\":\"USD\",\"new_value\":933,\"transaction_id\":\"999\",\"action\":67,\"type\":\"payment_amount\"}"
},
{
"event_type": "ad_account_billing_charge",
"event_time": "2018-05-19T13:37:11+0000",
"extra_data": "{\"currency\":\"USD\",\"new_value\":1047,\"transaction_id\":\"999\",\"action\":67,\"type\":\"payment_amount\"}"
},
{
"event_type": "ad_account_billing_charge",
"event_time": "2018-05-18T14:02:07+0000",
"extra_data": "{\"currency\":\"USD\",\"new_value\":728,\"transaction_id\":\"999\",\"action\":67,\"type\":\"payment_amount\"}"
}
]
}
}
]
}
check if account is prepaid or not
https://www.facebook.com/business/help/105373712886516
There are two main payment settings for Facebook ads:
Automatic payments: We’ll automatically charge you whenever you spend a certain amount known as your billing threshold and again on your monthly bill date for any leftover costs. This is how you’ll pay if you use PayPal or most credit and debit cards to purchase ads.
Manual payments: You’ll add money to your account first, and then we’ll deduct from that amount up to once a day as you run ads. This is how you’ll pay if you use a manual payment method (like PayTM or Boleto Bancário) to purchase ads. With manual payments, you won’t have a billing threshold.
UAT scopes: email,public_profile,ads_management,ads_read,manage_pages
GET v3.1/me/adaccounts?fields=id,account_id,name,is_prepay_account
sample response:
{
"data": [
{
"id": "act_123",
"account_id": "123",
"name": "RS",
"is_prepay_account": true
}
]
}
get payment method (funding source) and available balance
UAT scopes: email,public_profile,ads_management,ads_read,manage_pages
GET v3.1/me/adaccounts?fields=id,account_id,name,funding_source_details
sample response:
{
"data": [
{
"id": "act_123",
"account_id": "123",
"name": "RS",
"funding_source_details": {
"id": "345",
"display_string": "Available Balance ($24.52 USD)",
"type": 20
}
}
]
}
available balance in funding_source_details
is decreased every day - on every
ad_account_billing_charge
event, I guess. you can parse this string to predict
when user is close to running out of money.
get campaign insights
UAT scopes: email,public_profile,ads_management,ads_read,manage_pages
GET v3.1/me/adaccounts?fields=campaigns{insights{ctr,cpc,cpm,cpp}}
sample response:
{
"data": [
{
"campaigns": {
"data": [
{
"insights": {
"data": [
{
"ctr": "1.201805",
"cpc": "19.106109",
"cpm": "229.61825",
"cpp": "326.688588",
"date_start": "2018-04-30",
"date_stop": "2018-05-29"
}
]
},
"id": "<campaign_id_1>"
},
{
"insights": {
"data": [
{
"ctr": "1.025733",
"cpc": "34.70614",
"cpm": "355.992442",
"cpp": "361.126323",
"date_start": "2018-04-30",
"date_stop": "2018-05-29"
}
]
},
"id": "<campaign_id_2>"
},
{
"id": "<campaign_id_3>"
}
]
},
"id": "act_<account_id>"
}
]
}
it turns out that read_insights
permission is not required to read insights -
it must be sufficient to have ads_read
permission only.
NOTE: insights are shown/available not for all campaigns - IDK why yet.
user IDs
-
real user ID (UID)
it can be used to open user’s Facebook page (
https://facebook.com/<UID>
). -
app-scoped ID (ASID)
When a person uses Facebook Login on a website or a mobile app, an ID is created for the specific Facebook app, which is called app-scoped ID.
https://developers.facebook.com/docs/messenger-platform/send-messages#recipient_ids
Please note that user ID’s from Facebook Login integrations are app-scoped and will not work with the Messenger platform.
-
page-scoped ID (PSID)
When a person interacts with a business via Messenger, an ID is created for the specific Page associated with the bot in Messenger, which is called Page-scoped ID.
access tokens
- temporary token is called short-lived one
- permanent token is called long-lived one
short-lived token can be extended in ATD - this means it will be turned into long-lived token (in fact it will be a brand new token then).
UAT
User access tokens are generally obtained via a login dialog and require a person to permit your app to obtain one.
AAT
It is generated using a pre-agreed secret between the app and Facebook
PAT
generate long-lived PAT with messenger permissions in FD
FB |
---|
PRODUCTS (section in left menu) → Messenger → Settings |
Token Generation (section) → Select a Page (combobox) |
this PAT is long-lived and has only messenger permissions for selected page
(that is pages_messaging_*
permissions).
UPDATE
new KhLead
PAT generated this way now has not only messenger permissions but
read_page_mailboxes
permission as well (as though it was saved after
generating PAT with read_page_mailboxes
permission in GAE - see below).
generate long-lived PAT with arbitrary permissions in GAE
-
get UAT with required permissions
GAE Facebook App
(combobox):<MY_APP>
GAE User or Page
(dropdown menu) →Get User Access Token
Select Permissions
read_page_mailboxes
Generate Access Token
(button)
-
get short-lived PAT
GAE use UAT generated above to get short-lived PAT:
UAT scopes: manage_pages,read_page_mailboxes GET v3.1/<PAGE_ID>?fields=access_token
see Facebook - Tips on how to find page ID.
=> short-lived PAT is generated (expires in 1 hour) - now it’s necessary to extend it and get a new long-lived PAT in ATD.
-
get long-lived PAT
ATD paste short-lived PAT into ATD and click
Extend Access Token
button at the bottom of the page (you will be prompted to type your FB account password to confirm this action) - a new long-lived PAT will be generated that will never expire.