Facebook (facebook_updated v0.24.2) View Source
Provides API wrappers for the Facebook Graph API
Link to this section Summary
Types
A token which is used to authenticate requests to Facebook's Graph API.
Also referred to as an App ID, this may be found on your app dashboard.
Also referred to as an App Secret, this may be found on your app dashboard.
A reason for settling a payment dispute.
Query values used for supplying or requesting edge attributes. Fields are represented as a string of comma separated values. For example, "id,first_name"
Relative path to media file.
An id composed of a page and post ids separated with an underscore.
Additional attributes for media file uploads
Can be
A reason for refunding a payment.
A type of feed or object.
A base64-encoded JSON string, concatenated to a signature with a single dot. E.g.: "<base64-encoded hmac/sha256 signature>.<base64-encoded JSON payload>"
Functions
Exchange an authorization code for an access token.
Returns metadata about a given access token.
Decodes a signed request from a client SDK (in-app payments), verifies the signature and (if it is valid) returns its decoded contents.
Get the count of fans for the provided page_id/0
Basic Graph object information by object ID
Get Graph object information for the specified params for the provided object ID
Gets an object edge for a specific object ID
Exchange a short lived access token for a long lived one
Basic user infos of the logged in user specified by the access_token/0
Accounts for the logged in user specified by the access_token/0
Likes of the currently logged in user specified by the access_token/0
Gets the number of elements that a scope has in a given object.
Gets the number of reactions that an object has.
Get all the object reactions with single request.
Basic page information for the provided page_id/0
Get page information for the specified fields for the provided page_id/0
Gets the feed of posts (including status updates) and links published by this page, or by others on this page.
Gets payment info about a single payment.
Settle a payment dispute.
Refund a payment.
Retrieves a list of granted permissions
A Picture for a Facebook User
A Picture for a Facebook User with custom dimensions
Publish to a graph edge using the supplied token. Publish to a feed. Author (user or page) is determined from the supplied token.
Publish media to a feed. Author (user or page) is determined from the supplied token.
If you want to use an appsecret proof, pass it into set_app_secret
Callback implementation for Application.start/2
.
Get all test users for an app.
Link to this section Types
Specs
access_token() :: String.t()
A token which is used to authenticate requests to Facebook's Graph API.
A user access token may be generated with Facebook Login. Access tokens for testing purposes may be retrieved from Facebook's Access Token Tool or using the Graph Api Explorer.
Specs
amount() :: Number.t()
Specs
client_id() :: String.t()
Also referred to as an App ID, this may be found on your app dashboard.
Specs
client_secret() :: String.t()
Also referred to as an App Secret, this may be found on your app dashboard.
Specs
currency() :: String.t()
Specs
A reason for settling a payment dispute.
Reasons:
:GRANTED_REPLACEMENT_ITEM
:DENIED_REFUND
:BANNED_USER
Specs
fields() :: String.t()
Query values used for supplying or requesting edge attributes. Fields are represented as a string of comma separated values. For example, "id,first_name"
Specs
file_path() :: String.t()
Relative path to media file.
Specs
limit() :: number()
Specs
num_resp() :: {:ok, number()} | {:error, Map.t()}
Specs
object_id() :: String.t()
An id composed of a page and post ids separated with an underscore.
Specs
Specs
params() :: list()
Additional attributes for media file uploads
Specs
react_type() :: atom()
Can be:
:angry
:haha
:love
:none
:sad
:thankful
:wow
Specs
reaction() :: :reaction
Specs
A reason for refunding a payment.
Reasons:
:MALICIOUS_FRAUD
:FRIENDLY_FRAUD
:CUSTOMER_SERVICE
Specs
resp() :: {:ok, Map.t()} | {:error, Map.t()}
Specs
A type of feed or object.
Feed scopes:
:feed
:posts
:promotabled_posts
(Admin permission needed):tagged
Object scopes:
:likes
:comments
Specs
signed_request() :: String.t()
A base64-encoded JSON string, concatenated to a signature with a single dot. E.g.: "<base64-encoded hmac/sha256 signature>.<base64-encoded JSON payload>"
Specs
using_app_secret() :: boolean()
Link to this section Functions
Specs
access_token(client_id(), client_secret(), String.t(), String.t()) :: resp()
Exchange an authorization code for an access token.
If you are implementing user authentication, the code
is generated from a Facebook
endpoint which is outside of the Graph API. Please see the
Manually Build a Login Flow
documentation for more details.
Examples
iex> Facebook.access_token("client_id", "client_secret", "redirect_uri", "code")
{:ok, %{
"access_token" => access_token,
"expires_in" => 5183976,
"token_type" => "bearer"
}}
See: https://developers.facebook.com/docs/facebook-login/manually-build-a-login-flow#confirm
Specs
debug_token(access_token(), access_token()) :: resp()
Returns metadata about a given access token.
This includes data such as the user for which the token was issued, whether the token is still valid, when it expires, and what permissions the app has for the given user.
This may be used to programatically debug issues with large sets of access tokens.
An app access token or an app developer's user access token for the app associated with the input_token is required to acces.
See:
- https://developers.facebook.com/docs/graph-api/reference/v2.11/debug_token
- https://developers.facebook.com/docs/facebook-login/manually-build-a-login-flow#checktoken
Examples
iex> Facebook.debug_token("INPUT_TOKEN", "ACCESS_TOKEN")
{:ok, %{"data" => [
%{
"app_id": "APP_ID",
"type": "USER",
"application": "APP_NAME",
"expires_at": 1352419328,
"is_valid": true,
"issued_at": 1347235328,
"scopes": [
"email",
"publish_actions"
],
"user_id": "USER_ID"
}
]}
Specs
decode_signed_request(signed_request()) :: resp()
Decodes a signed request from a client SDK (in-app payments), verifies the signature and (if it is valid) returns its decoded contents.
Specs
fan_count(page_id(), access_token()) :: resp()
Get the count of fans for the provided page_id/0
Example
iex> Facebook.fan_count("CocaColaMx", "<Access Token>")
{:ok, %{"fan_count" => fan_count, "id" => id}}
See: https://developers.facebook.com/docs/graph-api/reference/page/
Specs
get_object(object_id :: String.t(), access_token()) :: resp()
Basic Graph object information by object ID
Example
iex> Facebook.get_object("1234567", "<Access Token>")
{:ok, %{"id" => id}}
Specs
get_object(object_id(), access_token(), params()) :: resp()
Get Graph object information for the specified params for the provided object ID
Example
iex> Facebook.get_object("1234567", "<Access Token>", [fields: "id,name"])
{:ok, %{"id" => id, "name" => name}
See: https://developers.facebook.com/docs/graph-api/reference/page
Specs
get_object_edge( edge :: atom() | String.t(), object_id :: String.t(), access_token(), params() ) :: resp()
Gets an object edge for a specific object ID
Examples
iex> Facebook.get_object_edge(:adlabels, "act_12345", "<Access Token>")
iex> Facebook.page_feed(:leads, "1223344332", "<Access Token>", [fields: "created_time,id,ad_id,form_id,field_data"])
{:ok, %{"data" => [...]}}
Specs
long_lived_access_token(client_id(), client_secret(), access_token()) :: resp()
Exchange a short lived access token for a long lived one
Examples
iex> Facebook.long_lived_access_token("client_id", "client_secret", "access_token")
{:ok, %{
"access_token" => access_token,
"expires_in" => 5183976,
"token_type" => "bearer"
}}
See: https://developers.facebook.com/docs/facebook-login/access-tokens/expiration-and-extension
Specs
me(fields(), access_token()) :: resp()
Basic user infos of the logged in user specified by the access_token/0
Examples
iex> Facebook.me("id,first_name", "<Access Token>")
{:ok, %{"first_name" => "...", "id" => "..."}}
See: https://developers.facebook.com/docs/graph-api/reference/user/
Specs
my_accounts(access_token()) :: resp()
Accounts for the logged in user specified by the access_token/0
Examples
iex> Facebook.my_accounts("<Access Token>")
{:ok, %{"data" => [...]}}
See: https://developers.facebook.com/docs/graph-api/reference/user/accounts
Specs
my_likes(access_token()) :: resp()
Likes of the currently logged in user specified by the access_token/0
Example
iex> Facebook.my_likes("<Access Token>")
{:ok, %{"data" => [...]}}
See: https://developers.facebook.com/docs/graph-api/reference/user/likes
Specs
object_count(scope(), object_id(), access_token()) :: num_resp()
Gets the number of elements that a scope has in a given object.
An object stands for: post, comment, link, status update, photo.
If you want to get the likes of a page, please see fan_count/2
.
Expected scopes:
:likes
:comments
Example
iex> Facebook.object_count(:likes, "1326382730725053_1326476257382367", "<Access Token>")
{:ok, 10}
iex> Facebook.object_count(:comments, "1326382730725053_1326476257382367", "<Access Token>")
{:ok, 5}
See:
Specs
object_count(reaction(), react_type(), object_id(), access_token()) :: num_resp()
Gets the number of reactions that an object has.
Expected react_type/0
:
:haha
:wow
:thankful
:sad
:angry
:love
:none
Examples
iex> Facebook.object_count(
:reaction,
:wow,
"769860109692136_1173416799336463",
"<Access Token>"
)
{:ok, 100}
Specs
object_count_all(object_id(), access_token()) :: resp()
Get all the object reactions with single request.
Examples
iex> Facebook.object_count_all("769860109692136_1173416799336463", "<Access Token>")
{:ok, %{"angry" => 0, "haha" => 1, "like" => 0, "love" => 0, "sad" => 0, "wow" => 0}}
Specs
page(page_id(), access_token()) :: resp()
Basic page information for the provided page_id/0
Example
iex> Facebook.page("CocaColaMx", "<Access Token>")
{:ok, %{"id" => id, "name" => name}}
See: https://developers.facebook.com/docs/graph-api/reference/page
Specs
page(page_id(), access_token(), fields()) :: resp()
Get page information for the specified fields for the provided page_id/0
Example
iex> Facebook.page("CocaColaMx", "<Access Token>", "id")
{:ok, %{"id" => id}
See: https://developers.facebook.com/docs/graph-api/reference/page
page_feed(scope, page_id, access_token, limit \\ 25, fields \\ "")
View SourceSpecs
Gets the feed of posts (including status updates) and links published by this page, or by others on this page.
This function can retrieve four scope/0
types:
:feed
:posts
:promotable_posts
(Admin permission needed):tagged
A scope/0
must be provided. It is an atom, which represents the type of feed.
A limit of posts may be given. The maximum number that must be provided is 100.
Examples
iex> Facebook.page_feed(:posts, "CocaColaMx", "<Access Token>")
iex> Facebook.page_feed(:tagged, "CocaColaMx", "<Access Token>", 55)
iex> Facebook.page_feed(:promotable_posts, "CocaColaMx", "<Access Token>")
iex> Facebook.page_feed(:feed, "CocaColaMx", "<Access Token>", 55, "id,name")
{:ok, %{"data" => [...]}}
See: https://developers.facebook.com/docs/graph-api/reference/page/feed
Specs
payment(object_id(), access_token(), fields()) :: resp()
Gets payment info about a single payment.
Examples
iex> Facebook.payment("769860109692136", "<App Access Token>", "id,request_id,actions")
{:ok, %{"request_id" => "abc2387238", "id" => "116397053038597", "actions" => [ %{ "type" => "charge", ... } ] } }
See:
Specs
payment_dispute(object_id(), access_token(), dispute_reason()) :: resp()
Settle a payment dispute.
Examples
iex> Facebook.payment_dispute("769860109692136", "<App Access Token>", :DENIED_REFUND)
{:ok, %{"success" => true}}
See:
payment_refunds(payment_id, access_token, currency, amount, reason)
View SourceSpecs
payment_refunds( object_id(), access_token(), currency(), amount(), refunds_reason() ) :: resp()
Refund a payment.
Examples
iex> Facebook.payment_refunds("769860109692136", "<App Access Token>", "EUR", 10.99, :CUSTOMER_SERVICE)
{:ok, %{"success" => true}}
See:
Specs
permissions(page_id(), access_token()) :: resp()
Retrieves a list of granted permissions
Example
iex> Facebook.permissions("<Some Id>", "<Access Token>")
{:ok, %{"data" => [%{"permission" => "...", "status" => "..."}]}}
See: https://developers.facebook.com/docs/graph-api/reference/user/permissions
Specs
picture(page_id(), type :: String.t(), access_token()) :: resp()
A Picture for a Facebook User
type
may be:
"small"
"normal"
"album"
"large"
"square"
Example
iex> Facebook.picture("<Some Id>", "small", "<Access Token>")
{:ok, %{"data": "..."}}
See: https://developers.facebook.com/docs/graph-api/reference/user/picture/
Specs
picture(page_id(), width :: integer(), height :: integer(), access_token()) :: resp()
A Picture for a Facebook User with custom dimensions
Example
iex> Facebook.picture("<Some Id>", 480, 480, "<Access Token>")
{:ok, %{"data": "..."}}
See: https://developers.facebook.com/docs/graph-api/reference/user/picture/
Specs
publish(edge :: atom(), parent_id :: String.t(), params(), access_token()) :: resp()
Publish to a graph edge using the supplied token. Publish to a feed. Author (user or page) is determined from the supplied token.
The page_id/0
is the id for the user or page feed to publish to.
Apps need both manage_pages
and publish_pages
permissions to be able to publish as a Page.
The publish_actions
permission is required to publish as an individual.
See Facebook's publishing documentation for more info:
- https://developers.facebook.com/docs/pages/publishing
- https://developers.facebook.com/docs/pages/publishing#personal_post
- https://developers.facebook.com/docs/facebook-login/permissions#reference-publish_pages
Examples
iex> # publish a message
iex> Facebook.publish(:feed, "<Feed Id>", [message: "<Message Body"], "<Access Token>")
{:ok, %{"id" => "{page_id}_{post_id}"}}
iex> # publish a link and message
iex> Facebook.publish(:feed, "<Feed Id>", [message: "<Message Body", link: "www.example.com"], "<Access Token>")
{:ok, %{"id" => "{page_id}_{post_id}"}}
iex> # create a Facebook Campaign
iex> Facebook.publish(:campaigns, "act_1234546", [objective: "LINK_CLICKS", name: "a campaign"], "<Access Token>")
{:ok, %{"id" => "{campaign_id}"}}
Specs
publish(:photo, page_id(), file_path(), params(), access_token()) :: resp()
Publish media to a feed. Author (user or page) is determined from the supplied token.
The page_id/0
is the id for the user or page feed to publish to.
Same :feed
publishing permissions apply.
Example
iex> Facebook.publish(:photo, "<Feed Id>", "<Image Path>", [], "<Access Token>")
{:ok, %{"id" => photo_id, "post_id" => "{page_id}_{post_id}"}
iex> Facebook.publish(:video, "<Feed Id>", "<Video Path>", [], "<Access Token>")
{:ok, %{"id" => video_id}
See: https://developers.facebook.com/docs/pages/publishing#fotos_videos
publish(atom, page_id, file_path, params, access_token, options \\ [])
View SourceSpecs
If you want to use an appsecret proof, pass it into set_app_secret:
Example
iex> Facebook.set_app_secret("app_secret")
See: https://developers.facebook.com/docs/graph-api/securing-requests
Callback implementation for Application.start/2
.
Specs
test_users(client_id(), access_token()) :: resp()
Get all test users for an app.
The access token in this case needs to be an app access token. See:
- https://developers.facebook.com/docs/facebook-login/access-tokens#apptokens
- https://developers.facebook.com/docs/graph-api/reference/v2.8/app/accounts/test-users
Examples
iex> Facebook.test_users("appId", "appId|appSecret")
{:ok, %{"data" => [
%{
"access_token" => "ACCESS_TOKEN",
"id" => "USER_ID",
"login_url" => "https://developers.facebook.com/checkpoint/test-user-login/USER_ID/"
}
]}